How to install custom / private Wordpress plugins and themes with Composer

[aloys-dillar]

Goal

Add custom/private plugins or themes that are not publicly available to your Wordpress installation on Platform.sh using composer.

Assumptions

• A WordPress installation on Platform.sh that uses Composer, for example one that uses the WordPress Template.
• An SSH key configured on the project account
• Composer installed locally

Problems

The file system on Platform.sh is read-only starting at the deploy phase. While this makes Wordpress sites more secure, adding and updating custom themes and plugins at runtime will fail.

Steps

0. Project structure

Let’s assume both cases; you are trying to add a custom theme and plugin to Wordpress, both of which are not available on the Wordpress Composer-based package management resource wpackagist. This will be the case whether you paid for these packages, or if you have developed them yourself.

To start, we’re going to assume a particular project structure for where we can keep and access these kinds of packages. First, add a custom subdirectory to the repository that contains two additional subdirectories for keeping our plugins and themes:

.
└── custom
    ├── plugins
    │   └── my_custom_plugin
    └── themes
        └── my_custom_theme

Within Platform.sh’s WordPress Template, you would then have something like:

.
├── README.md
├── composer.json
├── composer.lock
├── custom
│   ├── plugins
│   │   └── my_custom_plugin
│   └── themes
│       └── my_custom_theme
├── example.wp-config-local.php
├── wp-cli.yml
└── wp-config.php

Where my_custom_plugin is the name of your plugin and my_custom_theme is the name of your theme.

1. Add the external and local repositories

Edit the composer.json file (located at the root of the repository) to add wpackagist and the path object.
The wpackagist repository will allow you to install publicly available plugins or themes.
More details can be found in this how-to guide.

In this example, we will use two path package sources. Each path object will look up the path indicated with "url": "/the/path/to/your/packages/*" in your repository. It may be required to adapt that path to your project’s settings. If other options of installation (such as version control, zip, …) are needed please consult the composer documentation

We chose to specify both themes and plugins separately on two path directives for several reasons. We decided it would be easier to follow the example with a clear folder structure, and as a good workaround for how composer handles sub-directories. More details can be found here

"repositories":[
    {
       "type":"composer",
       "url":"https://wpackagist.org"
    },
    {
      "type": "path",
      "url": "custom/themes/*",
      "options": {
        "symlink": false
        }
    },
    {
      "type": "path",
      "url": "custom/plugins/*",
      "options": {
        "symlink": false
        }
    }
],

2. Ensure your plugins and themes have their own composer.json file

For a custom plugin or theme to be recognized by Composer, you will need to have a composer.json file in its subdirectory. If your plugin or theme doesn’t have such a file, you will need to create one.

Here’s a minimal working example for a plugin :

{
    "name": "me/my_custom_plugin",
    "description": "Custom Plugin",
    "version": "1.0",
    "type": "wordpress-plugin",
    "require": {
        "composer/installers": "~1.0",
        "johnpbloch/wordpress-core": "5.4.2"
    }
}

Note:

It is mandatory to require both composer/installers and johnpbloch/wordpress-core. This will force composer to load your plugins or themes after Wordpress was installed. Otherwise, your plugins or themes would get overwritten by the Wordpress installation.
The "type" has to be set accordingly to either wordpress-plugin or wordpress-theme depending on what is supposed to be installed.

Your folder structure would then become something like:

.
└── custom
    ├── plugins
    │   └── my_custom_plugin
    │      └── composer.json
    └── themes
        └── my_custom_theme
           └── composer.json

3. Add the plugin or theme via Composer

You can then use composer require to add the plugin or theme as a dependency.

To that purpose, use the plugin or theme name you would like to install (it is case sensitive).

• For plugins: composer require me/my_custom_plugin
• For themes: composer require me/my_custom_theme

You can also specify a version for either (e.g. composer require me/my_custom_plugin:version). Composer will then update your composer.json and composer.lock files accordingly.

4. Enable plugins/themes in the WP-Admin Dashboard

The admin interface will show the plugins/themes and will allow you to enable them directly via the interface.

Conclusion

As we saw, adding custom/private themes and plugins into Composer without the use of an external VCS or private packagist can be done, however, the process could be easier to set up. By using Composer to install 3rd party plugins and themes, you get a reliable and repeatable build process and make sure the code is deployed safely.

It also makes it easy to keep plugins and themes up to date. You can follow this guide on how to keep your Wordpress site updated.