README

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

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.

villfa / composer-substitution-plugin

Maintainers

Details