Announcing the roots/wordpress Composer Package

We are excited to announce our new Composer package for installing WordPress: roots/wordpress. This is a drop-in replacement for the johnpbloch/wordpress package Bedrock has used since November 2014. We recommend using roots/wordpress going forward.

Why a new package?

First of all, it’s disappointing that any non-official WordPress package is still needed. These packages exist because WordPress.org will not add a composer.json to their project root. roots/wordpress isn’t just a copy of johnpbloch/wordpress either. We had some specific goals we wanted to accomplish to justify this new package:

• Use an official source
  
  When requiring our package the downloaded WordPress code must come from an official source (such as https://github.com/WordPress/WordPress or https://wordpress.org/download/releases/).
  
  
• No source modifications
  
  The WordPress source code must be left untouched without any modifications.
  
  
• Fully automated releases
  
  Our package must have automated releases whenever a new version of WordPress is released in a timely fashion (johnpbloch/wordpress has been mostly good historically, but there have been issues with delays and missing versions).
  
  
• Publicly auditable
  
  The code, run status, and output of the automated update process must be public facing and easy to contribute to.
  
  
• Seamless transition process
  
  The wordpress-core-installer should be future-proof.

Implementation

We accomplished all these goals and ended up with a pretty elegant solution.

What’s in a WordPress package?

Ideally, any WordPress core composer package is as minimal as possible. It should really only require two things:

1. Composer metadata (composer.json)
2. Package published to Packagist

Essentially you need to:

1. Generate a composer.json that looks like this
2. Tag a release
3. The release is picked up by Packagist

Anatomy of composer.json generated from roots/wordpress

The following is an example of the composer.json generated for the WordPress 5.0 release:

{
    "name": "roots/wordpress",
    "description": "WordPress is web software you can use to create a beautiful website or blog.",
    "keywords": [
        "wordpress",
        "blog",
        "cms"
    ],
    "homepage": "http://wordpress.org/",
    "license": "GPL-2.0-or-later",
    "authors": [
        {
            "name": "WordPress Community",
            "homepage": "http://wordpress.org/about/"
        }
    ],
    "support": {
        "issues": "http://core.trac.wordpress.org/",
        "forum": "http://wordpress.org/support/",
        "wiki": "http://codex.wordpress.org/",
        "irc": "irc://irc.freenode.net/wordpress",
        "source": "http://core.trac.wordpress.org/browser"
    },
    "type": "wordpress-core",
    "version": "5.0",
    "require": {
        "php": ">=5.3.2",
        "roots/wordpress-core-installer": ">=1.0.0"
    },
    "dist": {
        "url": "https://api.github.com/repos/WordPress/WordPress/zipball/5.0",
        "type": "zip"
    },
    "source": {
        "url": "https://github.com/WordPress/WordPress.git",
        "type": "git",
        "reference": "5.0"
    }
}

(source)

The important bits of the composer.json schema that make up our package are:

• type: wordpress-core
• dist: direct URL to download a WordPress release zip
• source: reference to the wordpress/wordpress git repo.

Unlike normal Composer packages, WordPress core needs to be installed to a non-standard directory which requires a custom installer. We’ve forked https://github.com/johnpbloch/wordpress-core-installer to https://github.com/roots/wordpress-core-installer. The installer picks up on the fact that you have a package with the type wordpress-core and installs it in the proper location. Our installer lets you easily replace an existing WordPress package without throwing an error like the original.

The dist and source keys tell composer where to grab the package’s content. Our package is essentially a meta-package that just tells composer to grab WordPress from the official source. The benefits are clear if you take a look at the composer.lock after switching over to roots/wordpress. You’ll get official source URLs and proper reference versions:

-  "name": "johnpbloch/wordpress-core",
-  "version": "4.9.8",
+  "name": "roots/wordpress",
+  "version": "5.0",
   "source": {
       "type": "git",
-      "url": "https://github.com/johnpbloch/wordpress-core.git",
-      "reference": "50323f9b91d7689d615b4af02caf9d80584b1cfc"
+      "url": "https://github.com/WordPress/WordPress.git",
+      "reference": "5.0"
   },
   "dist": {
       "type": "zip",
-      "url": "https://api.github.com/repos/johnpbloch/wordpress-core/zipball/50323f9b91d7689d615b4af02caf9d80584b1cfc",
-      "reference": "50323f9b91d7689d615b4af02caf9d80584b1cfc",
-      "shasum": ""
+      "url": "https://api.github.com/repos/WordPress/WordPress/zipball/5.0",
+      "reference": "5.0",

Publicly auditable automated releases

The source for our automated release process is available on the src branch of github.com/roots/wordpress. At the time of writing you will find a straightforward set of PHP scripts that orchestrate fetching new versions, generating composer files, and tagging releases. We chose to write these in PHP for the following reasons:

• Lower barrier to contribution. I assume if you are reading this article you understand how to write and debug PHP.
• Safety and reliability of a fully featured programming language environment. Bash scripts can be powerful but can get pretty insane pretty fast.
• Our code can be reused as a library outside of this project if you have different ideas about how this should be run/implemented.

The main place this automated release process will be run is Travis CI. We chose this because:

• The build history and build output are publicly available for maximum transparency. If our automation has errors, you can inspect and perhaps even fix them yourself.
• Travis is free for open source. Anyone with a copy of our code and a GitHub account can run on the same infrastructure we do without setting up and maintaining their own servers.
• Travis has a great track record and lots of mindshare. You will spy a .travis.yml in most of the popular repos you rely on daily.

The release process is run daily by Travis CI cron jobs and a Travis CI build is triggered when a release is published to the WordPress/WordPress GitHub repo via Zapier. The goal here is that you don’t have to trust us to keep our infrastructure running to get reliable releases.

We encourage anyone who is interested in contributing to look at the “Second Pass” project on GitHub. This project has a lot of low-hanging fruit you might be be able to put together a pull-request for!

Use roots/wordpress today

If you are using an older version of Bedrock: using roots/wordpress is as simple as replacing your existing WordPress package with roots/wordpress and then running composer update.

  "require": {
    "php": ">=5.6",
    "composer/installers": "^1.4",
    "vlucas/phpdotenv": "^2.0.1",
    "oscarotero/env": "^1.1.0",
-   "johnpbloch/wordpress": "5.0",
+   "roots/wordpress": "5.0",
    "roots/wp-config": "1.0.0",
    "roots/wp-password-bcrypt": "1.0.0"
  },

Projects created with Bedrock 1.10 and onward already use roots/wordpress.

Enjoy!