Adding Composer Support to Your Own Themes and Plugins (for developers)

In last chapter, we saw a reason to add composer.json support to your own WordPress themes and plugins. We will see how to do that now.

Note: composer.json in this chapter refers to file in root directory of your theme and plugin repo, and NOT file with same name in WordPress document root (htdocs / public_html) directory.

Adding Composer Support

Let’s start with an example file as below:

{
    "name": "org-name/project-name",
    "type": "wordpress-plugin",
    "require": {
        "composer/installers": "^1.0"
    }
}

Above is bare minimum information needed for a plugin repo.

A detailed version looks like:

{
    "name": "rtcamp/nginx-helper",
    "description": "Cleans nginx's fastcgi/proxy cache or redis-cahce whenever a post is edited/published. Also does few more things.",
    "keywords": ["wordpress", "plugin", "nginx", "nginx-helper", "fastcgi", "redis-cahce", "redis", "cache"],
    "homepage": "https://easyengine.io/nginx-helper/",
    "license": "GPL-2.0+",
    "authors": [{
        "name": "rtCamp",
        "email": "[email protected]",
        "homepage": "https://easyengine.io"
    }],
    "minimum-stability": "dev",
    "prefer-stable": true,
    "type": "wordpress-plugin",
    "support": {
        "issues": "https://github.com/rtCamp/nginx-helper/issues",
        "forum": "https://wordpress.org/support/plugin/nginx-helper",
        "wiki": "https://github.com/rtCamp/nginx-helper/wiki",
        "source": "https://github.com/rtCamp/nginx-helper/"
    },
    "require": {
        "php": ">=5.3.2",
        "composer/installers": "^1.0"
    },
    "require-dev": {
        "wpreadme2markdown/wpreadme2markdown": "*"
    }
}

Meaning of every composer.json field is explained in details in composer documentation.

From WordPress perspective only field important is type field. It can take three values for WordPress projects:

1. wordpress-theme
2. wordpress-plugin
3. wordpress-muplugin

While type field itself is part of composer core, support for above is added via composer-installers package from version 1.0.6.

composer-installers itself is a composer plugin which is needed for WordPress themes and plugins. It’s purpose is to tell composer to download WordPress packages to wp-content subdirectories rather than default vendor directory. Hence we need to declare it as a dependency for our theme/plugin project under require section.

Distributing as Composer Package

Once you add composer.json to your git repo, it will turn your into a composer package.

But in order to use your package, a WordPress project’s composer.json still need to define a new composer repository for your project. Something like:

"repositories": [
    {
        "type": "vcs",
        "url": "[email protected]:rtCamp/nginx-helper.git"
    }
],

But you can make life easy for others by distributing your composer packages via packagist.org. That way other simply need to add one line:

"require": {
    "rtcamp/nginx-helper":"^1.9"
},

Note: require section would have needed even when defining VCS repository.

Adding packages to packagist.org is very easy so we are not covering it here in details.

Duplicate package on packagist.org as well as wpackagist.org

As you may have noticed above, nginx-helper is available via both – official composer repo as well as wpackagist repo. Which one gets picked will be depend on what namespace you use.

Example:

1. rtcamp/nginx-helper – will fetch package from packagist.org (in this case rtcamp/nginx-helper exists as composer package also)
2. wpackagist-plugin/nginx-helper – will fetch package from wpackagist.org

Please do not use both. It may create issues.