villfa/composer-substitution-plugin

Composer plugin replacing placeholders in the scripts section by dynamic values

1.4.0 2022-01-04 10:53 UTC

This package is auto-updated.

Last update: 2024-03-01 00:19:47 UTC


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.

Build Status AppVeyor Build Status Latest Stable Version Minimum PHP Version License

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.