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 about 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 the 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 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 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 of 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 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 real environment. That is to set configuration in the system, e.g. in the web server 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 autoload. 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 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 a 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 re-usable across projects.
  • Replace default steps with custom ones.
  • Explicitly exclude some steps.
  • Use step scripts: something similar to Composer scripts, that allow to run 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” will be possible to use a setting in composer.json to extend the WP Starter specific autoload, that will make all extension classes autoloadable only when WP Starter runs, without affecting application autoload.

Improved configuration

WP Starter v2 already has a quite 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 to load 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 to have 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 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 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 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 dropins 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 in 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 introduce 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 with this article as well. So.. stay tuned!

Comments

  1. Leho Kraav @lkraav1

    Hi Giuseppe. Thanks for writing this update.

    Could you alos comment on WP Starter vs Bedrock, which afaict is the only other advanced project WP boilerplate tool on the market.

    1 month ago, I got the discussion started here https://discourse.roots.io/t/research-bedrock-vs-wp-starter-by-gmazzap/14044 but basically forgot to send you a feedback ping email 🙂 I apologize.

    My questions (WP Starter: v3+):

    * does either project do anything significantly better than the other?

    * does either project plan to do anything significantly better/different in short term future? How much real non-bikeshedding value opportunity area is there in the WP boilerplate challenge space, to warrant multiple projects?

    * do these projects perhaps have merge potential? Is there a good reason to keep scarce development resource fragmented and slow both projects down from their (merged) potential?

    Tyvm.

  2. Giuseppe Mazzapica2

    Hi Leho,
    thanks for your comment.

    Regarding WP Starter and Bedrock: the latter is more a “boilerplate” for your project, the previous is more a library that you require in your project. It is a different approach, and one is not necessarily better or worse than the other.

    As a boilerplate Bedrock is more opinionated on several decisions, e.g. folder structure or some libraries to use (see the list of Bedrock “require” https://github.com/roots/bedrock/blob/master/composer.json#L39-L42).

    Being a boilerplate, you need to clone Bedrock and edit its source if you really want to customize something (but probably you loose one of biggest pros of a boilerplate: a standardized setup).

    If you use WP Starter, you require it and use its configuration if you want to change something, like folder structure, and in case you want to use Bedrock/Roots libraries… (or anything else) you just require them.

    If we consider WP Starter 2, beside of this difference there was no much more to say. Maybe that WP Starter 2 has better support for dropins and that Bedrock has a better support to use regular plugin as MU plugin.

    Being a boilerplate, getting started in Bedrock is easier than WP Starter 2, because in the latter you had to configure your Composer “scripts” manually, in Bedrock you get them already when you clone the project.

    With WP Starter 3, and the conversion to a Composer plugin, this latter point is not true anymore: as written in the article being a Composer plugin allows to run scripts without them being configured by end user on project composer.json.

    The end goal of Bedrock is to have a standardized (and so, opinionated) way to use WP + Composer + ENV + a set of libraries.

    The end goal of WP Starter is to provide tools to build a different WP + Composer + ENV setup per project, based on project needs and requirements, or why not, build a standardized boilerplate to reuse (company-wide, team-wide..), if wanted.

    In theory, people at Roots could use WP Starter 3 to build Bedrock: they would require it, their additional libraries and would ship the WP Starter configuration that would setup the site like Bedrock do it now.

    Would they find any value in doing that? Well, this is not a question for me 🙂 I can say that if they would express the will to do so, I could offer my effort to make this as smooth as possible.

    With WP Starter v3 some additional technical differences are there e.g. the usage of Symfony Dotenv component to parse .env files instead of vlucas/phpdotenv that is used in Bedrock (and was used in v2) and minimum PHP version that, as of now, is PHP 7.0 for WP Starter v3 and 5.6 for Bedrock.

    Moreover, WP Starter v3 explicitly supports packages of type “WP Starter Extension”, so you can expect that in future some extensions will be created to enable more features on WP Starter, but always in a way that is end-users call to add them, if they wish. Spoiler: the first of them will handle installation of translation files for plugin and themes.

    I think you can find an answer to all your questions in what’s written above, if not… let me know, I will try some more explicit answer.

    PS: thanks to let me know about the discussion at discourse.roots.io, I will also comment there.

Leave a reply

Your email address will not be published. Required fields are marked *