Integrated Composer is a Pantheon platform feature that extends Composer functionality to WordPress and Drupal's core files, and treats them as a managed dependency. Integrated Composer enables one-click updates from the Dashboard for upstream updates and Composer dependencies on your Composer-managed Pantheon site.
Follow the Drupal 9 doc to create a new Drupal 9 site with Integrated Composer built in.
To upgrade or migrate an existing site to Drupal 9 with Integrated Composer, visit the Migrate to Drupal 9 guide.
To convert an existing Drupal 8 site to a Composer-managed site with Integrated Composer, visit the Composer Convert doc.
Add a new Custom Upstream on the Pantheon Dashboard.
Create a new WordPress site from the Upstream. Do not customize the upstream as yet.
In the Dev environment, click Visit Development Site and follow the prompts to complete the CMS installation.
Clone the site locally and run
Clone the Git repository from the Pantheon site's dashboard.
Add a new dependency locally:
composer require drupal/pkg-name
- Pantheon will run Composer, generate build artifacts, and deploy it to your Dev or Multidev environment.
You can remove site dependencies if they are no longer needed.
Remove the dependency locally:
composer remove drupal/pkg-name
- Pantheon will run Composer, generate build artifacts, etc.
Navigate to Code in the Dev tab of the site's Dashboard.
Click Check Now.
If updates are available, click Apply Updates.
The upstream has the following directory structure:
code/ ├─ .gitignore ├─ composer.json └─ pantheon.upstream.yml ├─ README.md └─ upstream-configuration/ or upstream-config/ for WordPress └─ composer.json
.gitignore: Prevents build artifacts generated by Composer from being committed to the upstream or site code repositories.
composer.json: The two different
composer.jsonfiles allow customization of individual sites without inherent merge conflicts and enable one-click updates.
- Root-level: Site-level customizations.
composer.json: Composer automatically updates
composer.jsonwith customizations for the upstream. Avoid manually modifying this file.
build_step: truedirective in
pantheon.upstream.ymlenables the build step.
When a site is created, Pantheon runs
composer install, generates a
composer.lock file and commits it back to the site’s code repository.
Build artifacts are stored in a Git tag like
$BRANCHNAME is the name of the environment or Multidev feature branch).
Clone the Git repository from the Pantheon site's Dashboard.
Change into the Upstream's configuration directory:
composer requirefor each dependency:
composer require drupal/pkg-name --no-update
--no-updatetells Composer to disable automatic updates of the dependency. This makes Composer faster when adding dependencies to the Upstream as shown here.
--no-updateshould not be included when adding dependencies to a site.
Set or increment the current configuration version:
If this is your first time setting the config version:
Confirm the version:
composer config version 1.0.0
Increment the config version number when you update dependencies. If you don't increment the version number, Composer will ignore updated dependencies.
1.0.1in this example with another number:
composer config version 1.0.1
Commit and push.
The version of Composer on the platform is Composer 2.
Some packages are not compatible with Composer 2. If you encounter a build error that instructs you to contact Support, validate the package version's compatibility locally first, and check Drupal's Preparing your site for Composer 2 documentation for packages that have already been identified.
Pantheon supports the version of Composer integrated into the Pantheon platform and available for use with all Drupal 8+ and WordPress sites. Pantheon’s support for Composer is limited to the application level, and any Composer scripts or modifications made with a Composer script are outside the Pantheon Scope of Support.
Do not remove
composer.json. If it's removed,
terminus drush commands will fail with errors related to Twig.
If you encounter an error during a code sync or if the site is missing files that should be added by Integrated Composer, the Build Log may contain information that can help you troubleshoot:
Navigate to the Code in the Dev tab of your Site Dashboard.
In the Commit Log section, find the most recent commit and click View Log to view the Composer command that was run and the output that was given by that command.
If there is an error in the output, it may be due to an error in the site's
composer.lock file, or there may be an issue with a Composer library the site uses.
To resolve, examine the error in the log. It may be a syntax or parse error of the JSON files, or some sort of error loading a library via Composer. You can also try running the same command on your local Git checkout of the site's code and see if you can update the
composer.lock files to run the command successfully.
When you click Apply Updates, the process completes with the error,
Something went wrong when applying updates. View log. Click View log to view the output of the log:
We were not able to perform the merge safely. See the Applying Upstream Updates doc (https://pantheon.io/docs/core-updates) for further debugging tips. Conflicts: [ "CONFLICT (content): Merge conflict in composer.json" ]
Issue 1: The site might use a Custom Upstream.
Solution 1: Copy the Upstream URL and then follow Solution 2:
From the Site Dashboard, navigate to the Dev environment.
Click Settings, then About site.
Copy the Upstream URL and use it instead of the Pantheon Upstream URL in Solution 2.
Issue 2: The upstream updates and your Composer changes to the site, are in a conflict that cannot be automatically merged by Git.
- We do not recommend using Auto-resolve updates in this case since it will cause your changes to the site's
composer.jsonfile to be lost.
Merge the changes manually:
Create a local Git clone of the Pantheon site repository.
Merge in the upstream changes:
git pull https://github.com/pantheon-upstreams/drupal-project main
You will get a message that there are conflicts in
composer.jsonthat cannot be merged automatically:
Auto-merging composer.json CONFLICT (content): Merge conflict in composer.json Automatic merge failed; fix conflicts and then commit the result.
Resolve the conflict and follow the instructions to commit the merged changes.
To verify that the merge was successful, run
composer installon your local branch to verify that the
composer.jsonparses correctly, and that the correct libraries are installed or updated. If the command fails, then the merge was not made correctly and the error message may point to how
composer.jsonneeds to change.
Push the changes to Pantheon. Integrated Composer will run again with the updated
When Auto-Resolve Updates is selected and the
composer.json contents are changed in the upstream, all changes the site's developers made to
composer.json will be removed if Git cannot automatically merge the changes.
To resolve, there are two potential solutions:
If you have a copy of the
composer.jsonfrom before the updates were applied, add the changes from that file back to the updated
Use of the
wikimedia/composer-merge-plugin is deprecated within Drupal.
When using Pantheon's Integrated Composer, this plugin often tries to run a "composer update" during the "composer install," which is not allowed and will cause errors. We recommend removing
composer-merge-plugin from your Composer toolchain.
All Composer commands are available through the Commit Log in the Site Dashboard's development environment.
Composer build logs are only available after the task or action completes (or fails).
git diff to view changes, excluding
git diff d94d1a1179 -- . ':(exclude)composer.lock'
Try composer-lock-diff to see what packages have changed after
Pantheon does not offer support for Composer GUIs or any conflicts that might be caused by one.
Integrated Composer needs to consider the use case where a site might already have non-Composer-managed modules in the standard
/modules/contrib directory. To support this, we create the
/modules/composer directory for modules added by Integrated Composer.
If your site does not fall into this category, it is safe to rename the
composer directory back to the standard
Pantheon's devs are working hard to make the Integrated Composer experience on Pantheon better.
Features that are still in development:
- Integrated Composer and Build Tools