PHPackages villfa/composer-substitution-plugin - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. villfa/composer-substitution-plugin ActiveComposer-plugin villfa/composer-substitution-plugin =================================== Composer plugin replacing placeholders in the scripts section by dynamic values 1.4.0(4y ago)5148.7k—0%4[1 issues](https://github.com/villfa/composer-substitution-plugin/issues)1MITPHPPHP >=5.3.2 Since Apr 5Pushed 1mo ago4 watchersCompare [ Source](https://github.com/villfa/composer-substitution-plugin)[ Packagist](https://packagist.org/packages/villfa/composer-substitution-plugin)[ Docs](https://github.com/villfa/composer-substitution-plugin)[ RSS](/packages/villfa-composer-substitution-plugin/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (4)Versions (14)Used By (1) Composer Substitution Plugin ============================ [](#composer-substitution-plugin) The [Composer](https://getcomposer.org/) 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](https://github.com/villfa/composer-substitution-plugin/workflows/Build/badge.svg)](https://github.com/villfa/composer-substitution-plugin/actions)[![AppVeyor Build Status](https://camo.githubusercontent.com/234d4a5d22e93551c35dabb117a1ffb7b7536369ed08eecee512f3facbca4eab/68747470733a2f2f63692e6170707665796f722e636f6d2f6170692f70726f6a656374732f7374617475732f6769746875622f76696c6c66612f636f6d706f7365722d737562737469747574696f6e2d706c7567696e3f6272616e63683d6d61696e267376673d74727565)](https://ci.appveyor.com/project/villfa/composer-substitution-plugin)[![Latest Stable Version](https://camo.githubusercontent.com/4fb6e23603475ac8312f50cbf7a0ccbbf2af0ec2e1670582812755dbf2999696/68747470733a2f2f706f7365722e707567782e6f72672f76696c6c66612f636f6d706f7365722d737562737469747574696f6e2d706c7567696e2f762f737461626c65)](https://packagist.org/packages/villfa/composer-substitution-plugin)[![Minimum PHP Version](https://camo.githubusercontent.com/ed01d9ed58eeae6546ad914dfe36ffe4d8686fd4e56440892018169df0f3b5ec/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344253230352e332e322d3838393242462e7376673f7374796c653d666c61742d737175617265)](https://php.net/)[![License](https://camo.githubusercontent.com/295bd4f5fd5d6211beaf9a77555d3875816bdb815c6acbdef49be2a0e0e2cacf/68747470733a2f2f706f7365722e707567782e6f72672f76696c6c66612f636f6d706f7365722d737562737469747574696f6e2d706c7567696e2f6c6963656e7365)](./LICENSE) Installation ------------ [](#installation) ``` composer require villfa/composer-substitution-plugin ``` Requirements ------------ [](#requirements) - PHP >= 5.3.2 - Composer >= 1.0.0 Usage ----- [](#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) Configuration keyMandatoryTypeDefault valueDescriptionextra.substitution.enablenobooltrue with Composer 2.2+, false otherwiseDisables the plugin when falseextra.substitution.mappingyesobjectempty objectMapping between placeholders (the keys) and substitution rules (the values). There is no restriction with the placeholders format.extra.substitution.mapping.\*.typeyesstringn/aSubstitution type (see [the related section](#substitution-types) below)extra.substitution.mapping.\*.valueyesstringn/aSubstitution value (depends on the type)extra.substitution.mapping.\*.cachednoboolfalseIndicates whether the value provided after the first substitution must be cachedextra.substitution.mapping.\*.escapenostringnullEscaping function that will receive the substitute value as argumentextra.substitution.prioritynointeger0Plugin's event handler priority (see [Composer documentation](https://getcomposer.org/doc/articles/plugins.md#event-handler))⚠️ **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 ### Substitution types [](#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 ------------------ [](#real-life-examples) ### [PHPUnit Extra Constraints](https://github.com/villfa/phpunit-extra-constraints) [](#phpunit-extra-constraints) This library defines a Composer script which uses [PHP\_CodeSniffer](https://github.com/PHPCSStandards/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](https://github.com/jrgp/linfo)(See also the tiny script [nproc.php](https://github.com/villfa/phpunit-extra-constraints/blob/a2c8e5a6f5079f4a2c9d83f45283ad25330ae16b/scripts/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. ### Health Score 46 — FairBetter than 93% of packages Maintenance58 Moderate activity, may be stable Popularity40 Moderate usage in the ecosystem Community17 Small or concentrated contributor base Maturity58 Maturing project, gaining track record Bus Factor1 Top contributor holds 98.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~53 days Recently: every ~156 days Total 13 Last Release 1595d ago PHP version history (2 changes)1.0.0PHP ^5.3.2 || ^7.0 1.0.1PHP >=5.3.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/1c1769d6e1862cba100fc2e8c3651e54a26f24bf8506c16d39f9e729a31cc339?d=identicon)[villfa](/maintainers/villfa) --- Top Contributors [![villfa](https://avatars.githubusercontent.com/u/2891564?v=4)](https://github.com/villfa "villfa (175 commits)")[![szepeviktor](https://avatars.githubusercontent.com/u/952007?v=4)](https://github.com/szepeviktor "szepeviktor (2 commits)")[![rodrigoprimo](https://avatars.githubusercontent.com/u/77215?v=4)](https://github.com/rodrigoprimo "rodrigoprimo (1 commits)") --- Tags composercomposer-plugincomposer-scriptsphpplugincomposerreplacementscriptssubstitution ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/villfa-composer-substitution-plugin/health.svg) ``` [![Health](https://phpackages.com/badges/villfa-composer-substitution-plugin/health.svg)](https://phpackages.com/packages/villfa-composer-substitution-plugin) ``` ### Alternatives [dealerdirect/phpcodesniffer-composer-installer PHP\_CodeSniffer Standards Composer Installer Plugin 598161.9M1.9k](/packages/dealerdirect-phpcodesniffer-composer-installer)[ergebnis/composer-normalize Provides a composer plugin for normalizing composer.json. 1.1k37.3M2.1k](/packages/ergebnis-composer-normalize)[pyrech/composer-changelogs Display changelogs after each composer update 5904.0M25](/packages/pyrech-composer-changelogs)[sllh/composer-versions-check Checks if packages are up to date to last major versions after update 2352.4M16](/packages/sllh-composer-versions-check)[ffraenz/private-composer-installer A composer install helper for private packages 2331.7M5](/packages/ffraenz-private-composer-installer)[automattic/jetpack-autoloader Creates a custom autoloader for a plugin or theme. 525.5M69](/packages/automattic-jetpack-autoloader) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)