Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

Mattias Noback:
How to make Sculpin skip certain sources
Jun 21, 2017 @ 10:41:28

For those Sculpin users out there Matthias Noback has posted a tip showing how to make the tool skip certain sources so it's not included in the build. This is useful for removing files that may not be needed in the final result. In his case, he wanted to slim down his Docker image and only include exactly what was needed for the site it hosts.

Whenever I run the Sculpin generate command to generate a new version of the static website that is this blog, I notice there are a lot of useless files that get copied from the project's source/ directory to the project's output/ directory. All the files in the output/ directory will eventually get copied into a Docker image based on nginx (see also my blog series on Containerizing a static website with Docker). And since I'm on a hotel wifi now, I realized that now was the time to shave off any unnecessary weight from this Docker image.

After some searching around he found the best solution for his needs - a custom hook into Sculpin's own events system with a "before run" event. He includes the code he used to create a SkipSources event that uses pattern matches to exclude the requested sources. Then, using the fnmatch function he generated a listing of files to pass in to be skipped. After working up this solution, a bit more research also lead to another possible, more built-in way: the ignore configuration key that also uses pattern matching.

tagged: sculpin skip source ignore event static site generator tutorial

Link: https://php-and-symfony.matthiasnoback.nl/2017/06/how-to-make-sculpin-skip-certain-sources/

Matthias Noback:
Creating virtual pages with Sculpin
Dec 14, 2016 @ 09:28:58

Matthias Noback has continued his series looking at using Sculpin to create static pages for "in-project documentation" with this second post focusing more on the creation of "virtual pages". These pages allow the insertion of dynamic content into pages pulled from other sources (in this case, from the source of the project).

Previously we looked at how to use the static site generator Sculpin to generate in-project documentation. When Sculpin builds the HTML files and assets it looks at what files are in the source/ directory and processes them based on certain rules (e.g. "parse Markdown files", "format HTML files with Twig", etc.). The purpose for my "living documentation" project is to also dynamically generate documentation based on PHP and configuration files from the main project.

[...] The Sculpin documentation mentions several ways to generate dynamic content for a static site, as opposed to the standard way of adding static Markdown or HTML files. [...] So, I dug into the source code of Sculpin to find out what would be a reasonable extension point. It turned out that the best way to approach this was to create a custom data source (which is currently not documented).

He then walks you through the creation of a custom data source with "dataSourceId" and "refresh" methods the tool uses to pull in the dynamic data. He shows how to set up the script to be called at any time and have the same effect (Sculpin does this when the "server" is running) and defining the service in your Sculpin configuration.

tagged: sculpin static site generator virtual page dynamic content tutorial

Link: http://php-and-symfony.matthiasnoback.nl/2016/12/creating-virtual-pages-with-sculpin/

Mattias Noback:
Project documentation with Sculpin
Dec 12, 2016 @ 09:43:43

Matthias Noback has a recent post to his site sharing some advice and examples of how to use Sculpin for your project's documentation to make it a quick and pretty painless process.

One of the key ideas is to generate documentation instead of writing it. This should help prevent duplication and outdated information that is not trust-worthy and would therefore be neglected. I'm currently looking for ways to technically accomplish such a thing with PHP projects. This should result in reusable tools which will make it easier and more fun to document future projects while writing the code.

[...] I wanted to use Sculpin to document another project, the main project. So I started figuring out how to run Sculpin and generate a static subsite (not a blog) based on files in a subdirectory of another project. It wasn't all that hard, but I'll share the steps here anyway.

He walks you through the creation of a new Sculpin-based site and how to test and ensure it's all working correctly with simple content, a layout and configuration. He finishes out the post mentioning the themes available for Scuplin applications and links to the Bootstrap 3 theme as an example.

tagged: project documentation sculpin static generator tutorial introduction

Link: http://php-and-symfony.matthiasnoback.nl/2016/12/project-documentation-with-sculpin/

Understanding PHP Generators
Oct 28, 2016 @ 11:20:44

The Scotch.io blog has posted a tutorial that wants to introduce you to and help you understand a feature recently added to the PHP language: generators. In this new article author Samuel Oloruntoba walks you through some of the basics and offers advice on when to use this helpful feature.

When it comes to driving, speed is not everything. But on the web, speed makes all the difference. The faster your application, the better the user experience. Well, this article is on PHP Generators, so why are we talking about speed? As you are soon about to find out, generators make a huge difference on speed and memory management.

He starts off by explaining what generators are and gives a simple code example showing how they can replace a standard loop (without some of the memory overhead). He uses a for and foreach loop to show a memory overflow caused by it trying to reach the highest integer allowed in the config. To help solve this, he makes use of generators, a much more memory efficient method that only returns the latest value requested and doesn't keep the remainder in memory. He then answers the question of why you might need to even use generators, how to return keys and send values into the generator. He also offers a word of advice on using them - mostly to not overuse them as it's still possible to have issues (like the memory one above).

tagged: generator example introduction tutorial memory yield

Link: https://scotch.io/tutorials/understanding-php-generators

Mark Baker:
PHP Generators – Sending “Gotchas”
Oct 11, 2016 @ 11:54:52

In this post to his site Mark Baker has shared some "sending gotchas" when generators are used in you PHP code. The focus of the article is on the "sending" part, pushing data into the generator for evaluation and use.

If you’re reading this, you’re probably already aware of just how useful PHP’s Generators are for improving performance and/or reducing memory overheads while keeping your code clean and easy to read.

Unlike their equivalent in some programming languages, PHP’s Generators allow you to send data into the Generator itself; not simply at initialisation (the arguments that we pass to the Generator when instantiating it); but also between iterations. This has its own uses, and again, allows us to move code from our main blocks and methods into the Generator itself. [...] However, there are a few “gotchas” when we combine Generators that both return and accept data in this way, and it really helps to be aware of them when we’re developing, otherwise it can create problems.

He starts simple, showing a generator that uses integers passed in as the starting number and addition interval for each loop. He gets a bit more complex in his next example, having a method called inside the loop. While the first instance of this behaves as expected, the second (after minor modification) yields unexpected results. He walks you through what's happening to produce those results and one possibility on how to get it corrected.

tagged: generator gotcha issue unexpected results debugging workaround

Link: https://markbakeruk.net/2016/10/08/php-generators-sending-gotchas/

Laravel News:
Improved model generation with Laracademy Generators
Sep 08, 2016 @ 11:18:24

The Laravel News site has a quick tutorial posted showing you how using smarter generators to make model classes can help reduce your development time in Laravel applications (using a package to help adds the "smarts" needed).

Laravel provides the Artisan command line tool that allows you to save time by including several generators. Some examples include make:controller, make:model, and make:migration.

Building on top of this idea is a third party package named Laracademy Generators that will automatically generate your models based on your database structure.

They show first the normal process for creating a model and matching migration with the "artisan" command. Once this migration is run and the table is created, they can show how to automagically enhance the model with the generators package, using it to read from the table in the database and update the model with "fillable", "casts" and "dates" properties filled in.

tagged: model generator laracademy package improved database migration

Link: https://laravel-news.com/2016/09/improved-model-generation-with-laracademy-generators/

Sculpin Blog:
Deprecating Phar Distribution and Embedded Composer
Sep 02, 2016 @ 12:18:29

On the Sculpin blog Beau Simensen has posted an update about a change in how the project will be released in the future, most notably deprecating the phar release and switching to an embedded Composer installation.

If you are currently using a globally installed phar distribution for Sculpin you should migrate to a per-project Composer installed version of Sculpin as soon as you can. [...] Any plans for Sculpin 3 would have required reworking the phar build and distribution process

In typical programmer fashion, I let myself get bogged down in the details of eventually needing to deploy Sculpin 3 phar builds rather than working on Sculpin 3. What little time I had to spend on Sculpin last year was sunk on solving this problem. [...] The last officially available Sculpin phar is not compatible with PHP 7.

He talks about his earlier goals to make v3 of Sculpin PHP 7-only but, in the process of the work to get to that point, several roadblocks came up preventing it. He talks about self-updating phars and finally realizing that, for the good of the project, a move to the embedded Composer setup is the best method for keeping dependencies in sync. He ends the post with the steps you'll need to take to migrate from the phar release to the managed version and an example commit of how the Sculpin site itself was migrated.

tagged: sculpin static generator project phar embedded composer update

Link: https://blog.sculpin.io/2016/08/31/deprecating-phar-distribution-and-embedded-composer

Introducing Jigsaw, a Static Site Generator for Laravel Developers
Apr 20, 2016 @ 13:33:40

On the Tighten.co blog there's a new post introducing Jigsaw, a static site generator for Laravel developers they've created in the course of their own work.

That's right, Tighten has created a Laravel-based static site generator named Jigsaw, and we think it's pretty great.

Before I write another line of this post, I want to address the looming question: Why create another static site generator? In PHP alone there are two, and since we soft-launched Jigsaw there's already been another Blade-based static site generator launched.

The first part of the article lists three reasons for making the tool, pointing out the ecosystem they used (different from others), the focus on Laravel developers and the easy transition from a Jigsaw site to a full Laravel one. From there the post talks about what Jigsaw is and how you can get started using it (installation and configuration guide included). It also includes examples of "first pages" to help you get started and the result. The post finishes with a look at variable handling, custom front matter values, deployment and how to convert the site from Jigsaw to Laravel should the need arise.

tagged: jigsaw static site generator laravel introduction installation tutorial

Link: http://blog.tighten.co/introducing-jigsaw-a-static-site-generator-for-laravel-developers

SitePoint PHP Blog:
Building an Spress Svbtle Theme – Responsive Static Blogs!
Feb 11, 2016 @ 12:47:11

On the SitePoint blog there's a tutorial posted showing you how to create a responsive site template in Spress, a static site generator written in PHP.

You may have heard of Sculpin – a static site generator for PHP. [...] While easy to use and fast to set up, Sculpin’s development has stagnated a bit and the documentation leaves much to be desired. Spress is, in a way, its spiritual successor. Much better documentation, much more flexible configuration, much easier to extend, and just as easy to use with almost the same API and commands.

He starts by helping you set up a basic site to work with on a Homestead Improved instance. Once that's up and running (including an install of Spress) he creates the simple site and starts in on the rebuild of the Svbtle theme. He briefly explains how Spress themes work and then includes the code/layouts you'll need to reproduce the theme. The post includes a screenshot of what the end result should look like in two different browser sizes (responsive, remember).

tagged: spress static site generator responsive theme svbtle tutorial

Link: http://www.sitepoint.com/building-an-spress-svbtle-theme-responsive-static-blogs/

Mark Baker:
A Functional Guide to Cat Herding with PHP Generators
Jan 19, 2016 @ 10:05:13

In this post to his blog Mark Baker looks at a feature added in PHP 5.5 - generators - and how to use them with some of the array handling functionality PHP provides.

When working with arrays in PHP, three of the most useful functions available to us are array_map(), array_filter() and array_reduce().

[...] However, these functions only work with standard PHP arrays; so if we are using Generators as a data source instead of an array, then we can’t take advantage of the functionality that they provide. Fortunately, it’s very easy to emulate that functionality and apply it to Generators (and also to other Traversable objects like SPL Iterators), giving us access to all of the flexibility and power that mapping, filtering and reducing can offer.

He starts with a more "real world" example of using a generator in a handler for GPX files, XML files storing GPS data. He gives an example of the typical file contents and shows a simple generator script (class) that he uses to grab chunks of the file at a time instead of reading it all in and parsing it from there. He then uses this generator along with a bit of extra handling to mimic array filtering, transformation and reducing the data being returned.

tagged: functional generator tutorial array filter reduce transformation

Link: http://markbakeruk.net/2016/01/19/a-functional-guide-to-cat-herding-with-php-generators/