The build process on Pantheon is done with Composer, the build prioritizes the composer.json and composer.lock file in the root of the repo, and builds out based on those two files.
After checking out a site repo from the Pantheon dashboard under the 'connection info' button, composer can be used to to install and uninstall modules via the command line from with the site repo directory, some useful commands are below:
Adding a module
composer drupal/admin_toolbar
Advanced example:
composer --ignore-platform-reqs -W require drupal/admin_toolbar:^3
- --ignore-platform-reqs allows you to avoid local platform compatibility, the site will be built on Pantheon so this allows you to avoid any local issues
- -W is a shortcut for --with-all-dependencies, this pulls in all dependencies and requirements for a module, not just the module itself
drupal/admin_toolbartells composer what repository the package is in, in this case drupal, and what exactly to install, in this example admin_toolbar- :^3 is a version constraint. Without a number listed, composer will get the latest version available. In this example, ^3 tells composer to get the lastest version on the 3.x branch, but not anything above the major version 3. In most cases, letting composer install the latest version is best practice, but in some cases it may be necessary to limit the versioning. Do note, limiting the versioning with a :^x means composer will never update the module past x automatically. When an update is eventually desired, composer.json must be edited to remove the constraint.
Removing a module
composer remove drupal/admin_toolbar
- With composer remove, the code for a module will be removed from the site code-base. NOTE: any module configuration will remain as config is stored in the site database. It is best to uninstall a module from the site web console by utilizing the 'uninstall' menu under the 'Extend' top menu item within the site to remove all database config before uninstalling a module via composer. Not removing the configuration can cause errors as the site will still be expecting the module to be present based on the config.
Adding libraries via composer
Adding libraries is possible via composer, this allows composer to download and install the library files, freeing you from having to manage them. Adding libraries to the composer.json is a bit more complicated then adding a module, detailed documentation can be found on the Drupal.org page.
Composer update
Once all needed additions and removals have been done via composer, the update command should be run via:
composer update
This command will run the composer.json file, and build out the composer.lock file, downloading and installing all specific modules and dependencies that are listed as needed for the site. If you do not wish to install all the files locally, you can run composer update --no-install.
Commit and push
After installing and/or removing all modules with composer, and running composer update, you are now ready to commit your changes to the site repo and push them back to the Pantheon server to be build. From your git repo on the command line, or from your git GUI, you should see two files that have been changed, composer.json and composer.lock (if you see other files being changed, please see the pitfalls section below). Adding your changes with "git add file_name" or "git add ." Commit the changes to composer.json and composer.lock with git commit -m "your message here", and give the commit a message describing what changes were done between the "". Once you have committed them, you can push your changes to Pantheon with git push.
Once you push your changes, Pantheon will run the composer.json on their servers, and the changes will be deployed to the dev version of your site for review.
Quick version
- check out or update the site repo
- run "
composer --ignore-platform-reqs -W require drupal/admin_toolbar" or "composer remove drupal/admin_toolbar" as needed to install or remove modules - run "
composer update" to build out the local site composer files - add, commit and push the changes (which should only be to composer.json and composer.lock) to the Pantheon repo.
Potential pitfalls and ways to avoid
The Pantheon build process can balk anywhere it encounters files that it 'expects' to be from Composer being committed in the git repo itself. Changing and committing files in directories where Composer puts files, especially force commits with git -f force, can cause problems. It is best to avoid using git -f force as a general rule.
If you have custom code for themes or modules, they should be added to the directories below:
/web/sites/default/modules/custom
/web/sites/default/themes/custom
/web/sites/default/libraries
Pantheon also does not change its build restrictions based on changes to the .gitignore file. Removing lines from the .gitignore and committing files in those now tracked directories can still lead to the Pantheon build process issues. We recommand avoiding making changes to the .gitignore file.
Resources: