As of Drupal 8.8.0, we now have a core-composer-scaffold project in core. This is detailed here: https://www.drupal.org/docs/develop/using-composer/using-drupals-composer-scaffold, and a great presentation by Greg Anderson on this is available here: https://www.videodrupal.org/video/20191005/composer-core-initiative-what-it-will-mean-you.

This is a great new tool, and opens up some new possibilities to Drupal developers using composer, more and more the standard in the Drupal developer community.

In this article, we're going to explore using this new tool by adding a local development scaffolding to a Drupal 8 project. This means that when we do a pull of the project, we can scaffold the Docksal local development files right in, the same as if we were adding any other composer dependency. We'll be using Docksal (https://docksal.io), which if you want to follow along, you should get installed. We're also basing this work on setting up the site on Pantheon (https://pantheon.io), a Drupal and Wordpress PaaS. We'll be using their "flavor" of Drupal in this example.

I already published a repository on Packagist called tylerfahey/docksal-pack. You can take a look at the source for it here: https://github.com/twfahey1/docksal-pack. If you take a look at the composer.json, you can see where the scaffolding is defined:

"extra": {
        "drupal-scaffold": {
          "file-mapping": {
            "[project-root]/.docksal/docksal.env": "docksal.env",
            "[project-root]/.docksal/docksal.yml": "docksal.yml",
            "[project-root]/.vscode/settings.json": "vscode/default.settings.json",
            "[web-root]/sites/default/settings.local.php": {
                "mode": "replace",
                "path": "drupal/default.settings.local.php",
                "overwrite": false
            }
          }
        }
      }

This instructs the composer scaffold tool to put files from this repository into a specific location on the project it's being included in. You can see how the handy [project-root] and [web-root] allow for flexibility, in the case where you have a Drupal site that has an identical project-root and web-root, or one that has a nested docroot, meaning the actual web served files are inside of /web or /docroot folder, as is common in many Drupal architectures.

Now, we can grab Pantheon's Drops 8 Composer repository, which is nearly identical to the Drupal 8 standard repository, apart from some bits for running on the Pantheon platform, and is configured with a /web docroot - https://github.com/pantheon-systems/example-drops-8-composer. Here's what that might look like in the terminal:

➜  Sites git clone https://github.com/pantheon-systems/example-drops-8-composer test-drops8
Cloning into 'test-drops8'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 2733 (delta 0), reused 1 (delta 0), pack-reused 2730
Receiving objects: 100% (2733/2733), 1.39 MiB | 2.93 MiB/s, done.
Resolving deltas: 100% (1459/1459), done.

Once the drops-8 is cloned down, we need to allow the package to scaffold, which is a quick addition in the composer.json, in the "extra" section, adding the tylerfahey/docksal-pack package to the "allowed-packages":

"extra": {
        "drupal-scaffold": {
            "allowed-packages": [
                "pantheon-systems/drupal-integrations",
                "tylerfahey/docksal-pack"
            ],

Now, we can simply require the package like we would with any Drupal module or library. Because I haven't tagged any releases, we can just use dev-master to pull the latest master branch. You should see the scaffold indicate when it starts scaffolding this package:

➜  test-drops8 (default) ✗ composer require tylerfahey/docksal-pack:dev-master
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Installing tylerfahey/docksal-pack (dev-master 0aefb08): Cloning 0aefb086d0 from cache
(... other output)
Scaffolding files for tylerfahey/docksal-pack:
  - Copy [project-root]/.docksal/docksal.env from docksal.env
  - Copy [project-root]/.docksal/docksal.yml from docksal.yml
  - Copy [project-root]/.vscode/settings.json from vscode/default.settings.json
  - Copy [web-root]/sites/default/settings.local.php from drupal/default.settings.local.php
➜  test-drops8 (default) ✗

You can see that we now have the .docksal folder in the root, where it needs to be. You should be able to run fin up, and it will initialize the project. At this point, we are just using standard Docksal. But, the specific settings.local.php has been copied in, along with the VS Code settings we need for running xDebug. We could also run a fin drush si -y && fin addon install uli && fin uli to install Drupal, and get us an admin login link:

➜  test-drops8 (master) ✗ fin drush si -y
You are about to DROP all tables in your 'default' database. Do you want to continue? (y/n): y
Starting Drupal installation. This takes a while. Consider using the --notify global option.                                                      [ok]
Installation complete.  User name: admin  User password: FKQsHEsTDj                                                                               [ok]
Congratulations, you installed Drupal!                                                                                                            [status]
➜  test-drops8 (master) ✗ fin addon install uli
Downloading addon main script
  uli/uli
Addon uli was installed
➜  test-drops8 (master) ✗ fin uli
http://test-drops8.docksal/user/reset/1/1581633238/ZOjdjtP6fg3dIL5uAKeJHmGES4g705w-VuL0tbE4Q0I/login
[+] Copied to clipboard

This is a really great new tool to have with Drupal. Scaffolding files is something that can be handled a lot of different ways, but it's really fantastic to have it standardized via composer and Drupal core, rather than one-off bash scripts or other non-standard ways of getting it done.