Problem/Motivation
The current Scaffold plugin allows append operations to happen only to files that were scaffolded by a previous stage. For example, drupal/core provides a scaffolded robots.txt file, and an individual Drupal site may provide additional scaffold operations to append more directives to the end of the robots.txt file. Every time that the scaffold operation runs, the pristine robots.txt file is copied from the drupal/core asset file, and then the append data is added to the fresh copy. The fact that we always start with a fresh file ensures that append data will not keep piling up in the target file.
In some cases, though, we might want to append to a file that is NOT scaffolded on every run. An example of this would be a Profile that needs code in the user's settings.php file. We can potentially use scaffolding to place this code. The best way to do this is to scaffold a settings.profile.php file, and include said file via include __DIR__ . '/settings.profile.php'; in settings.php. If we require that the Composer Project Template for the site scaffold the settings.php file, then the profile could use a scaffold append op to meet this use-case. If settings.php is not being scaffolded (probably common, since most people are currently used to owning their settings.php files), we would still like to be able to append our include statement to it in a way that works whether or not it is being scaffolded.
For files that are not being scaffolded, then the data will not be rewritten on subsequent scaffold runs. This means that the second and subsequent times that the scaffold operation runs, the append data will already exist in the target file. We must therefore take care to not append the additional content again, as otherwise it will build up and create a separate copy on every scaffold run.
Proposed resolution
We would like the AppendOp to be able to flexibly append to either scaffolded or non-scaffolded files.
- By default, we will skip the append with an error message if appending to a non-scaffolded file.
- If the file being appended specifically allows it, then the scaffold plugin will allow append content to be added to a non-scaffolded file, as long as the target file does not yet contain the contents.
- If the target file does not exist at all, we will allow the AppendOp to contain default data for creating the base form of the file from scratch.
Remaining tasks
- Tests
- Documentation
- Change record
User interface changes
None.
API changes
None.
Data model changes
An "append" operation now has two more attributes, apply-once and default.
apply-once: This attribute indicates that it is acceptable to append to a target file that was not scaffolded. Default is 'false'
default: This attribute specifies the relative path to a default file to use in instances where the target file was not scaffolded and does not initially exist.
Example:
"composer-scaffold": {
"file-mapping": {
"[web-root]/sites/default/settings.php": {
"apply-once": true,
"default": "assets/initial-default-settings.txt",
"append": "assets/include-local-settings.txt"
}
}
Release notes snippet
Scaffold "append" operations may now append to files that were not themselves scaffolded.