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
andjohnpbloch/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 eitherwordpress-plugin
orwordpress-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.