Configuration reference
このコンテンツはまだ日本語訳がありません。
The consumer configuration lives under extra.scaffold in the root composer.json of the project. Only the root
package is read: the extra.scaffold block of a provider describes what it ships (see
Creating Providers), and its own allowed-packages has no effect on the projects that install it.
allowed-packages
Section titled “allowed-packages”An ordered list of the Composer packages allowed to write files into the project. Packages that are not listed are never read, even when they ship a manifest.
{ "extra": { "scaffold": { "allowed-packages": ["php-forge/baseline", "php-forge/coding-standard"] } }}- Order matters. When two providers ship the same destination, the provider listed later wins, and the run prints
[scaffold] "<file>" from "<later>" overrides "<earlier>" (last provider in allowed-packages wins). - A listed package that is not installed produces a warning that names the fix:
[scaffold] Provider "<name>" is allowed but not installed; check extra.scaffold.allowed-packages or require it. - Entries that are not strings are ignored with
[scaffold] Non-string entry in allowed-packages ignored. - Without
extra.scaffold, or with an empty or missing list, Composer runs print[scaffold] No extra.scaffold configuration found. Skipping scaffold.or[scaffold] No allowed-packages configured. Skipping scaffold.and write nothing.
Optional, defaults to true. Controls whether the plugin scaffolds on Composer events.
{ "extra": { "scaffold": { "auto": false, "allowed-packages": ["php-forge/baseline", "php-forge/coding-standard"] } }}With auto: false, Composer runs print
[scaffold] Auto-scaffold disabled via "extra.scaffold.auto"; run "vendor/bin/scaffold" manually. and write nothing.
The console commands keep working, and sync applies the providers on demand, creating scaffold-lock.json when it
does not exist yet:
vendor/bin/scaffold status # every provider file is listed as pendingvendor/bin/scaffold sync --dry-run --exit-code # review what applying the providers would changevendor/bin/scaffold sync # apply them, as composer install wouldUse it when every change to the shared files must be reviewed before it lands. Only an explicit false disables the
Composer hooks; any other value, including a missing key or null, keeps them enabled, so a typo never disables
scaffolding silently.
Full example
Section titled “Full example”{ "require-dev": { "php-forge/baseline": "^0.2", "php-forge/coding-standard": "^0.3", "php-forge/scaffold": "^0.3" }, "config": { "allow-plugins": { "php-forge/scaffold": true } }, "extra": { "scaffold": { "allowed-packages": ["php-forge/baseline", "php-forge/coding-standard"] } }}scaffold-lock.json
Section titled “scaffold-lock.json”Every run that applies files writes scaffold-lock.json at the project root. It records which provider owns each file,
how it was written, and the hashes that scaffold compares against on the next run. Commit it: status, diff, prune
and the user-modified detection of every clone and CI job read it.
Excerpt from a project that installed php-forge/baseline and php-forge/coding-standard with an existing ecs.php:
{ "providers": { "php-forge/baseline": { "version": "0.2.0", "path": "vendor/php-forge/baseline" }, "php-forge/coding-standard": { "version": "0.3.4", "path": "vendor/php-forge/coding-standard" } }, "files": { ".gitignore": { "hash": "sha256:4d07dd19f50ed675620f5a2f2d3abc9d2d3df9fe4ffbf70efc7a7efabfdbdc7c", "provider": "php-forge/baseline", "source": "metadata/.gitignore", "mode": "append", "stub-hash": "sha256:7d7753b2cc6184d74fb22f78c6b351b6c9c9dc04bcabe5481a0ed64b06858597" }, ".styleci.yml": { "hash": "sha256:825f8c744ffbd2bc2369712e7192b8694129a8ecbc3fd91dc9300fccecf827bd", "provider": "php-forge/baseline", "source": "metadata/.styleci.yml", "mode": "replace", "stub-hash": "sha256:825f8c744ffbd2bc2369712e7192b8694129a8ecbc3fd91dc9300fccecf827bd" }, "ecs.php": { "hash": "sha256:50b842500050094116202088109abfac734d2fd9341eb14b25dd870fc63936f3", "provider": "php-forge/coding-standard", "source": "src/config/ecs.php", "mode": "preserve", "stub-hash": "sha256:7c054b397506c1a4d4ab2d1197e9536b44f114e2721a0e9f8c46f362efcc7bae", "adopted": true } }}providers.<name>:
| Key | Meaning |
|---|---|
version | Pretty version of the provider at the last run, as Composer reports it. |
path | Install path of the provider, relative to the project root, or absolute when it lies outside the project. |
files.<destination>:
| Key | Meaning |
|---|---|
hash | sha256:<hex> of the destination as scaffold last left it (see Hash tracking). |
provider | Package that owns the destination. |
source | Path of the stub inside the provider. |
mode | replace, preserve, append or prepend. |
stub-hash | sha256:<hex> of the stub at the last apply. Entries written by 0.2.x lack it until a run applies them again. |
merge | Merge strategy (ini, list or text) selected by the manifest merge map; absent when the name decides it. |
ejected | true after vendor/bin/scaffold eject <file> --yes: no run writes the file until reapply <file> --force. |
adopted | true for a preserve file that existed before scaffold tracked it. |
The file is written atomically with providers and files sorted by key and a trailing newline, so diffs stay small.
Keys that scaffold does not know are kept. A lock with Git conflict markers is rejected with a message that names them;
resolve the conflict and run Composer again.
Composer events
Section titled “Composer events”| Composer event | Behavior |
|---|---|
post-install-cmd | Applies every allowed and installed provider: every mode on every destination, ejected files skipped. |
post-update-cmd | Same as post-install-cmd. |
post-create-project-cmd | Same, unless post-install-cmd or post-update-cmd already ran in the same Composer process, so a template is applied once. |
There is no partial run: append and prepend files are re-evaluated on every event, so new provider entries reach
existing projects on the next composer install or composer update.
The plugin subscribes to these events as a Composer plugin, not as a script:
composer install --no-scriptsstill scaffolds.composer install --no-pluginsdoes not load the plugin (The "php-forge/scaffold" plugin was not loaded as plugins are disabled.); runvendor/bin/scaffold syncafterwards, or a later plaincomposer installcatches up.- With the plugin in
require-dev, a freshcomposer install --no-dev, such as a production build, does not install it and writes no scaffold file.
Output and failure policy
Section titled “Output and failure policy”A Composer run that writes a file or needs attention ends with one summary line on stdout, such as
[scaffold] 2 files written, 7 unchanged, 1 conflict, 1 orphan, 1 warning.; a run that changes nothing prints nothing.
Warnings and errors go to stderr, prefixed with [scaffold].
The run fails (Composer exits with 1) when:
scaffold-lock.jsoncannot be read: invalid JSON or Git conflict markers. Nothing is applied.- The manifest of an allowed and installed provider is invalid: unknown key, invalid mode or merge strategy, unsafe
path, missing
copypath. The message names the provider; nothing is applied. - A file cannot be applied (unsafe path, unreadable stub, write failure). The other files are applied and recorded
first, then the run fails with
[scaffold] 1 file failed while scaffolding; see the messages above.
Warnings keep the run successful:
- An allowed provider that is not installed, or that produced no file mapping.
- A
replacefile that overwrote an untracked file with different content. - A user-modified
replacefile that was skipped, with theconflictline when its stub changed (see File Modes). - Orphaned files that no allowed provider ships anymore, listed with the
vendor/bin/scaffold prunehint. Composer runs never delete them.