Composer Substitution Plugin

The Composer Substitution plugin replaces placeholders in the scripts section by dynamic values.

It also permits to cache these values during the command execution and adds the ability to escape them with the function of your choice.

Installation

composer require villfa/composer-substitution-plugin

Requirements

• PHP >= 5.3.2
• Composer >= 1.0.0

Usage

You need to configure the plugin in the extra section of composer.json.

Here an example:

"extra": {
    "substitution": {
        "enable": true,
        "mapping": {
            "{MY_NAME}": {
                "type": "literal",
                "value": "John Doe",
                "escape": "addslashes"
            },
            "{PHP_VERSION}": {
                "type": "callback",
                "value": "phpversion"
            },
            "{DB_STATUS}": {
                "type": "include",
                "value": "./scripts/db.php",
                "cached": true
            },
            "{HOME}": {
                "type": "env",
                "value": "HOME"
            },
            "{COMPOSER_VERSION}": {
                "type": "constant",
                "value": "Composer\\Composer::VERSION"
            },
            "{NPROC}": {
                "type": "process",
                "value": "nproc"
            }
        }
    }
}

Then you can add the configured placeholders in the scripts section:

"scripts": {
    "welcome": "echo 'Hi {MY_NAME}, the database is {DB_STATUS}.'"
}

And now if you run the command:

$ composer run-script welcome
Hi John Doe, the database is OK.

Configuration

Configuration key	Mandatory	Type	Default value	Description
extra.substitution.enable	no	bool	true with Composer 2.2+, false otherwise	Disables the plugin when false
extra.substitution.mapping	yes	object	empty object	Mapping between placeholders (the keys) and substitution rules (the values). There is no restriction with the placeholders format.
extra.substitution.mapping.*.type	yes	string	n/a	Substitution type (see the related section below)
extra.substitution.mapping.*.value	yes	string	n/a	Substitution value (depends on the type)
extra.substitution.mapping.*.cached	no	bool	false	Indicates whether the value provided after the first substitution must be cached
extra.substitution.mapping.*.escape	no	string	null	Escaping function that will receive the substitute value as argument
extra.substitution.priority	no	integer	0	Plugin's event handler priority (see Composer documentation)

⚠️ From Composer 2.2+ you'll have to configure your composer.json file to allow the plugin to run

Example:

{
    "config": {
        "allow-plugins": {
            "villfa/composer-substitution-plugin": true
        }
    }
}

You can just execute this command:

composer config allow-plugins.villfa/composer-substitution-plugin true

For more details, see https://getcomposer.org/doc/06-config.md#allow-plugins

Substitution types

For each type of substitution the value replacing the placeholder comes from a different source.

• literal: The value in configuration is used directly.
• callback: The value is the string returned by a callback.
• include: The value is the string returned by a PHP file.
• env: The value is an ENV variable.
• constant: The value comes from a constant or a class constant.
• process: The value is the output of the processed command.

Real-life examples

PHPUnit Extra Constraints

This library defines a Composer script which uses PHP_CodeSniffer this way:

"scripts": {
    "phpcs": "phpcs --standard=PSR12 --parallel=$(nproc) src/ tests/",

Unfortunately it is not cross-platform because of the usage of nproc.

This is solved by the substitution plugin in combination with Linfo (See also the tiny script nproc.php). Here how it is configured:

"extra": {
    "substitution": {
        "enable": true,
        "mapping": {
            "$(nproc)": {
                "cached": true,
                "type": "include",
                "value": "./scripts/nproc.php"
            }
        }
    }
}

So now it also works on Windows without even touching the scripts section.