Composer-suggest, JuxtaLearn, LACE & Open Media Player

Over the course of a number of recent development phases in different software projects, I’ve been working to simplify installation and dependency management, while leaving room for the sort of experimentation required in research projects (indeed, many software projects?)

Way back in November 2013, I was working for Gill Clough on the Tricky Topic tool, for the JuxtaLearn European funded project. Initial work for the tool was done by Martin Hawksey, and built on WordPress. When I took over, I decided to use Git submodules to manage the dependencies on WordPress, third-party plugins, and custom plugins being developed for the project.

You can see what this looks like on GitHub in the first screen-shot …

A screen shot of submodules as they appear on GitHub - OER research hub & JuxtaLearn

Some potential benefits to note about Git submodules – you can see the dependencies, and their Git SHA-1 sums directly in GitHub, as the above screen shot shows. However, as anyone who has tried submodules tends to realise, their are a number of drawbacks.

There are alternatives, built to work fairly closely with Git. However, these would all require evaluation, and would probably prove difficult to support in our small, busy team. So, after some experimentation, I concluded it was safer to adopt the de facto standard dependency-manager for PHP, Composer, in my next project. This was the LACE Evidence Hub, for Rebecca Ferguson and Doug Clow.

The LACE Evidence Hub was also built on WordPress, and grew in part out of the work on the OER Research Hub. Discoveries that helped me decide on Composer were this 2013 post, and the WordPress Packagist repository.

A requirement that became apparent, during the work for LACE, and later Open Media Player, was the ability to enable (and disable), optional packages in the composer.json manifest. The composer.json schema allows for the inclusion of suggestions, however by default, these are merely displayed to the developer – they aren’t used by Composer.

So, over the course of LACE and Open Media Player, I developed the composer-suggest plugin.

The modified use of Composer suggestions involves JSON containing a package name on the left (eg. wpackagist-plugin/wp-postratings), and on the right a string that starts with a precise version constraint and a semi-colon (1.82;), followed by free text that can optionally contain tags (eg. postratings, [LACE]…).

Here’s a short JSON example:

"suggest": {
    "wpackagist-plugin/wp-postratings": "1.82; postratings [LACE] & [OERRH]"
}

Here is a longer example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"require": {
    "php": ">=5.3.3",
    "fancyguy/webroot-installer": "1.1.0",
    "nfreear/composer-suggest": "^1.1",

    "wordpress/wordpress": "4.1",

    "wpackagist-plugin/google-universal-analytics": "2.4.2",
},
"suggest": {
    "wordpress/wordpress": "4.3; WP-4.3.x",
    "wordpress/wordpress": "4.3.1; WP-4.3.1 / LAC-E only for now!",

    "wpackagist-plugin/facetious": "1.1.4; wp-facet [LAC-E] & [OERR-H] projects",
    "cftp/facetious": "dev-master; cftp-facet-1.2 [LAC-E] project",
    "wpackagist-plugin/wp-postratings": "1.82; postratings [LACE] & [OERRH]"
}

Some points worth noting:

The package ../google-universal-analytics is always required;
Their are two optional WordPress versions, which can override the default version (4.1);
Almost all the suggestions use a precise version constraint – this is safer!
The composer.json validates – if the composer-suggest plugin is not used Composer falls back to its default behaviour.

After earlier false starts, the keywords mentioned above are used in a .env, which is loaded via phpdotenv. The NF_COMPOSER_SUGGEST environment variable can either contain a single keyword, eg. LACE, or a preg_match-compatible regular expression.

A simple example of a single keyword in the .env file:

# LACE Evidence Hub - single keyword.
NF_COMPOSER_SUGGEST = "LACE"

And, a more complex example of a regular expression in the .env file – all suggestions containing the pipe-separated keywords will be installed:

# LACE - regular expression.
NF_COMPOSER_SUGGEST = "(LACE|Exp-LA|CFTP-Facet-1.2|WP-4.3.1)"

Referring back, you can see that the WP-4.3.1 in the regular expression, equates to line 12 of the composer.json example above.

The only potential drawbacks to the use of composer-suggest:

You probably can’t commit the composer.lock file to your code repository;
You need to specify quite tight version constraints to reduce the effect of the point 1.

In conclusion, the composer-suggest plugin provides a light-weight, simple to use method to enable and disable optional packages to fine-tune your Composer-based project.

In the case of LACE, this enables us to try third-party WordPress plugins on the test server, and then deploy them to the live server at our leisure all with the same code base. In Open Media Player, it enables us to present a core of requirements, and then a simple means to allow some options, for example adding more oEmbed providers.

All this within a conventional Composer-based workflow.