Composer Plugin WP Starter for WordPress

A few weeks ago, we published an article in which we explained why we sponsor the further development of WP Starter. We, in fact, mostly Inpsyder Giuseppe rewrites it and creates the Composer Plugin WP Starter. In the 13th Advent Calendar post, he gives an overview of the coming features. WP Starter version 3 is still in alpha status. We will probably release the plugin in the first months of 2019.

Table of Contents

From Library to Composer Plugin
New Features
Simpler Setup
Custom Command
Environment Management
Performance
Enhanced Steps Customization
WP Starter Extensions
Improved Configurations
Extended WP-config.php
WP CLI Integration
Steps improvements
Extensive Documentation
Conclusion

Composer is the de-facto standard dependency management tool for PHP. Pretty much all PHP projects, being them frameworks, applications or libraries, support Composer. All except WordPress. WordPress has no official support for Composer. Creating a website project with centralized dependencies managed by Composer requires some effort and “bootstrap” work.

The main scope of WP Starter is to simplify this process. The idea behind WP Starter is that a folder containing a single composer.json becomes a fully working WordPress website installation after running composer install.

From Library to Composer Plugin

At the moment of writing, the current stable version of WP Starter is 2.4.4.

We worked and changed a lot for the next major release. Many many of a big thanks go to Inpsyde, which decided to sponsor the employees time to work on it.

In its first two major releases WP Starter has been a library, that you required alongside other dependencies. Things are going to change with the next major version. In fact, with version 3, WP Starter will become a Composer plugin. It will improve the integration with Composer, and allows many interesting features.

New Features

Simpler Setup

In WP Starter v2 you need to setup script sections in composer.json to run WP Starter automatically on Composer install (or update). In v3, being a plugin, WP Starter can do that without any setting. Actually, the sole fact of requiring WP Starter could be enough to make everything work: You don’t need to no setup anything at all.

Custom Command

Composer plugins have the possibility to add custom commands to Composer, and WP Starter 3 will do that. There will be a `wpstarter` command you can use to run all the WP Starter workflow or just specific “steps” of it.

Being a Composer plugin will make WP Starter more powerful. But this is just the tip of the iceberg: WP Starter 3 will get a lot of interesting new features.

Environment Management

Besides simplifying the process of having WordPress website dependencies centralized and managed by Composer, there’s a second main goal of WP Starter. Its goal is to make the website configurable via environment variables.

The reason for this additional scope is that in professional development contexts it is more than common to have different environments for the same project. Just think of e.g. “development”, “stage”, and “production”.

The standard “WordPress way” – to do configuration via PHP constants – makes environment-aware configurations more complex than it needs to be. Other projects (not only PHP) have found environment variables to be the current solution for the issue. In fact, the usage of environment variables is one of the Twelve-Factor App (collection of modern practices for web applications).

Configuration via environment variables has been a WP Starter feature since the first release. However, with version 3 there will be a lot of improvements in this field:

• The package that loads and parses .env file will be Symfony Dotenv (it used to be “Dotenv” package by Vance Lucas, in v2). The reason behind the change is the agreement on the reasons explained in the PR by Fabien Potencier that introduced Dotenv in Symfony.
• We built WP Starter 3 keeping in mind that the best (and more performant) way to handle environment variables, especially in production, is to use a real environment. That is to set configuration in the system, e.g. in the webserver config files. For the first time, .env files will not be required at all for WP Starter.
• Environment cache. When using .env files, to load and parse them can be quite expensive for your performance. On top of that, WP Starter needs to setup constants based on env vars … doing this on every request might be quite a waste of resources. WP Starter 3 will use a caching mechanism so that the environment might be computed from .env files only on first request. Via the new custom command it will be possible to “flush” this cache on demand.

Performance

The caching of environment and the support for settings in the actual environment, instead of .env files, is a sign of the care we put in WP Starter 3. We want to make it as less impactful as possible regarding WordPress performance.

Another thing we did in this regard is the optimization of autoloading. WP Starter used to register autoload in Composer. This means that its autoload configuration was part of the application autoload registered at every request to WordPress.

WP Starter 3 changes this. Having more features in WP Starter 3 also means having more code, more classes, more files. By registering them as part of the Composer autoload, the production autoload would be “polluted” by WP Starter configuration that is not needed at all during WordPress requests.

This is why WP Starter 3 only registers a couple of its classes as part of the Composer autoload. For the rest it uses a custom autoload that is only loaded when WP Starter runs.

It’s worth mentioning here that WP Starter 3 will require PHP 7.0 as a minimum version. Using PHP 7 features does not enhance the performance by itself. But PHP 7 has a huge performance gain over PHP 5. So by pushing to the deprecation of PHP 5 we feel we have done good service in the name of the “gods of performance”.

Enhanced Steps Customization

The WP Starter workflow has always been based on a series of “steps”. They could run one after the other on Composer installation or update.

With version 3 this basic principle is still there, but there’s also the possibility to:

• Add custom steps that could be part of the project, but also being shipped as separate packages, making them reusable across projects.
• Replace default steps with custom ones.
• Explicitly exclude some steps.
• Use step scripts: something similar to Composer scripts, that allow running arbitrary callbacks before or after each of the WP Starter steps (including custom ones). Custom scripts, just like custom steps, can be shipped as part of the “project” package or pulled from separate packages.
• Customize step templates. Many of the WP Starter “steps” create files. The most relevant is the step that creates a wp-config.php for the project. All these files are created starting from “templates”: files in which a series of placeholders are replaced by values generated by the related step. With version 3 it is possible to replace the default templates, completely customizing the WP Starter behavior without touching any steps code.

WP Starter extensions

With custom steps, script, and templates, WP Starter offers many different ways to extend its features. Creating packages to re-use them across projects will become a natural way for teams to establish standard practices for their projects. To further support this, WP Starter 3 introduces support for a new Composer package type: “wpstarter-extension”.

By creating packages having this type, it will be possible to declare WP Starter as a dependency without having WP Starter to “jump in” anytime Composer installations or updates runs.

Moreover, by creating packages of type “wpstarter-extension” it will be possible to use a setting in composer.json to extend the WP Starter specific autoload, that will make all extension classes auto-loadable only when WP Starter runs, without affecting application autoload.

Improved configuration

WP Starter v2 already has quite an extensive set of configurations you can use to change its default behavior. In version 3 the possibilities are even more (but none is required). Moreover, we introduced a new way to set them.

Besides having settings in the “extra” section of composer.json it will be possible to put WP Starter specific settings in a separate wpstarter.json file. This helps to keep things more readable, without introducing complexity in the composer.json.

But there’s more. By default, WP Starter looks for a wpstarter.json in the project root. But it is possible to tell it to search in an arbitrary folder. Which means that to share configuration across projects is now possible and very simple.

Extended wp-config.php

Since its first version, the wp-config.php WP Starter is built on top of to the default wp-config.php, by adding the loading of Composer autoload and the code necessary to load environment variables turning them into constants for WordPress configuration.

In version 3 we will add a few more features:

• Early loading of plugin.php. The file that contains the plugin API in recent versions of WordPress has been made “independent” from the rest of the application. This allows loading it very early. WP Starter now loads it before bootstrapping the application. This way, you can easily add hooks before WordPress is loaded. WP Starter offers two entry points for doing that, one generic and one environment-specific.
• There’s now the possibility to load a {$environment}.php file. That is a PHP file named after the current environment (e.g. “production.php”, “staging.php”, etc). This file allows environment-specific operations in WordPress. Thanks to the fact that the plugin API is loaded early, a lot of possibilities are open. Just to name one: imagine having the possibility to disable (or enable) plugins only in specific environments.
• An “early hook file”, whose name can be configured in settings, can be loaded after the plugin API file is loaded, before the rest of WordPress is. This enables the usage of hooks. They have never been possible to use via plugins (not even MU plugins) because they were fired too early in the WordPress bootstrap process.
• Enforcement of admin color scheme. The wp-config.php generated by WP Starter 3 supports an environment variable that can be used to override the admin color scheme defined in user settings. This way it helps to recognize visually which is the current environment and avoid, for example, doing in production operations meant for staging.

WP CLI integration

WP Starter takes care of the file structure of the website and its configuration at the filesystem level. However it does nothing, for example, for the database, and surely WP CLI is the best ally for the ones who want to fully automate website bootstrapping.

WP CLI does not need WP Starter and can work in a WP Starter environment without any particular setting or else. However, WP Starter 3 offers an integrated way to run WP CLI commands that has the benefit to ensure WP CLI is available to run the commands. For example, WP Starter will check if WP CLI is installed via Composer. In case it is, it will do nothing. In case it’s not, it will take care of downloading the WP CLI phar.

By using WP Starter, you can write WP CLI commands in a way that is agnostic of the kind of WP CLI installation (Composer or phar). WP Starter will take care of “translating” them in the appropriate way for the installation type.

The generation of wp-cli.yml file, pointing to the WordPress installation folder, which is there since version 2, has been maintained, and thanks to custom templates can even be extended now.

Steps Improvements

We improved many of the default steps WP Starter makes. We particularly made the handling of drop-ins and MU plugins easier and more effective.

Moreover, with the introduction of custom command and custom steps, a mechanism is now in place to have steps that are meant to run only via the wpstarter command. This makes WP Starter a great help in automating tasks, offering a de-facto framework to interact with the WordPress installation, Composer, and the “bridge” between the two.

Extensive documentation

WP Starter never had a good documentation. Many of its features and behaviors were just undocumented. So, especially people who didn’t know how to use WordPress with Composer had problems in the beginning.

WP Starter 3 will change that. Even if version 3 is still in alpha state, there’s already an extensive documentation available (more than 20.000 words at the moment I’m writing), and during the ongoing development, any change or addition that is made in code is immediately documented and pushed in the same commit that introduces the code change.

Conclusion

WP Starter 3 will arrive after 3 years and a half from the release of version 2.0. Three years and a half in which developers used in a lot of projects (even quite big projects), and it will benefit in many ways from the gained experience.

The Inpsyde sponsorship ensures a more sustainable development. Combined with all the improvements, it will hopefully increase the popularity. And we hope it’ll enlarge the possibility of contributions, feedback, and overall increase the quality and health of the project.

Speaking of help from the community: Version 3 is in alpha state. This means we absolutely don’t recommend to use in production. But any kind of contribution is very welcome. Even just reading the documentation and provide feedback is valuable and we will appreciate that.

I honestly can’t wait the minute I will be able to announce the release of version 3. I hope I was able to get you all intrigued by this article as well. So.. stay tuned!