# Announcing the roots/wordpress Composer Package

We are excited to announce our new Composer package for installing WordPress: [`roots/wordpress`](https://packagist.org/packages/roots/wordpress). This is a drop-in replacement for the [`johnpbloch/wordpress`](https://packagist.org/packages/johnpbloch/wordpress) package [Bedrock](https://github.com/roots/bedrock) has used [since November 2014](https://github.com/roots/bedrock/commit/d4fc566ec3461648429a3399860d4f66340c273c#diff-b5d0ee8c97c7abd7e3fa29b9a27d1780). We recommend using [`roots/wordpress`](https://packagist.org/packages/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](https://core.trac.wordpress.org/ticket/23912). `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](https://discourse.roots.io/t/johnpbloch-wordpress-moved-to-a-new-configuration-and-wp-goes-missing/9124).

## 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](https://packagist.org/)

Essentially you need to:

1. Generate a composer.json [that looks like this](https://github.com/roots/wordpress/blob/6a09180aabcc078f88f9be8597e05a002d5c8f18/composer.json)
2. Tag a release
3. The release is picked up by [Packagist](https://packagist.org/)

### 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)](https://github.com/roots/wordpress/blob/6a09180aabcc078f88f9be8597e05a002d5c8f18/composer.json)

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](https://github.com/WordPress/WordPress/releases)
- source: reference to [the `wordpress/wordpress` git repo](https://github.com/WordPress/WordPress).

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](https://discourse.roots.io/t/johnpbloch-wordpress-moved-to-a-new-configuration-and-wp-goes-missing/9124).

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](https://github.com/roots/wordpress/tree/src). [At the time of writing](https://github.com/roots/wordpress/tree/c712842602c5086dcc46677085f10ab13a00501a) 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](https://travis-ci.com/roots/wordpress). 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](https://docs.travis-ci.com/user/cron-jobs/) and a Travis CI build is triggered when a release is published to [the WordPress/WordPress GitHub repo](https://github.com/WordPress/WordPress/releases.atom) via [Zapier](https://zapier.com). 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](https://github.com/roots/wordpress/projects/1). This project has a lot of low-hanging fruit you might be be able to put together a pull-request for!

## Use [`roots/wordpress`](https://packagist.org/packages/roots/wordpress) today

If you are using an older version of [Bedrock](https://github.com/roots/bedrock): using [`roots/wordpress`](https://packagist.org/packages/roots/wordpress) is as simple as [replacing your existing WordPress package with `roots/wordpress`](https://github.com/roots/bedrock/commit/ae063de0b1d9e51817529c0ef6040946fe0f75cb) 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](https://github.com/roots/bedrock) 1.10 and onward already use [`roots/wordpress`](https://packagist.org/packages/roots/wordpress).

Enjoy!