Integrated Composer

Learn how to deploy a site with Integrated Composer

Contributors: Ari Gold, Edward Angert.

Discuss in our Forum Discuss in Slack

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.

Get Started With Integrated Composer

Drupal 9 with Integrated Composer

  • 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.

WordPress with Integrated Composer

  1. Fork the Pantheon-maintained repository from https://github.com/pantheon-upstreams/wordpress-project.

  2. Add a new Custom Upstream on the Pantheon Dashboard.

  3. Create a new WordPress site from the Upstream. Do not customize the upstream as yet.

  4. In the Dev environment, click Visit Development Site and follow the prompts to complete the CMS installation.

  5. Clone the site locally and run composer install.

Add a Dependency to an Individual Site

  1. Clone the Git repository from the Pantheon site's dashboard.

  2. Run composer install:

     composer install
  3. Add a new dependency locally:

     composer require drupal/pkg-name
  4. Commit composer.json and composer.lock and push.

    • Pantheon will run Composer, generate build artifacts, and deploy it to your Dev or Multidev environment.

Remove Individual Site Dependencies

You can remove site dependencies if they are no longer needed.

  1. Remove the dependency locally:

     composer remove drupal/pkg-name
  2. Commit composer.json and composer.lock and push.

    • Pantheon will run Composer, generate build artifacts, etc.

Apply One-click Updates

  1. Navigate to Code in the Dev tab of the site's Dashboard.

  2. Click Check Now.

  3. If updates are available, click Apply Updates.

Upstream

Upstream refers to the source code that is hosted in the Pantheon code repository and includes the core code for Drupal, WordPress, and some customizations for the Pantheon platform.

Upstream and Site Structure

The upstream has the following directory structure:

code/
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.json files allow customization of individual sites without inherent merge conflicts and enable one-click updates.
    • Root-level: Site-level customizations.
    • Drupal: upstream-configuration/ or WordPress: upstream-config/:
      • composer.json: Composer automatically updates composer.json with customizations for the upstream. Avoid manually modifying this file.
  • pantheon.upstream.yml: The build_step: true directive in pantheon.upstream.yml enables 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 pantheon_build_artifacts_$BRANCHNAME (where $BRANCHNAME is the name of the environment or Multidev feature branch).

How to Add Dependencies to Your Upstream

  1. Clone the Git repository from the Pantheon site's Dashboard.

  2. Change into the Upstream's configuration directory:

    • Drupal:

      cd upstream-config
    • WordPress:

      cd upstream-configuration
  3. Run composer require for each dependency:

    composer require drupal/pkg-name --no-update
    • --no-update tells Composer to disable automatic updates of the dependency. This makes Composer faster when adding dependencies to the Upstream as shown here.
    • --no-update should not be included when adding dependencies to a site.
  4. 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.

    • Replace 1.0.1 in this example with another number:

       composer config version 1.0.1
  5. Commit and push.

Support

Pantheon Supports Composer 2

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's Scope of Support for Composer

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.

Troubleshooting Code Syncs and Upstream Updates

Site-local Drush Is Required for Drupal 9 Sites

Do not remove drush/drush from composer.json. If it's removed, terminus drush commands will fail with errors related to Twig.

View the Output of the Commit Log First

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:

  1. Navigate to the Code in the Dev tab of your Site Dashboard.

  2. 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.

Dashboard Workflow Shows an Error During Sync Code or Deploying to a New Environment

If there is an error in the output, it may be due to an error in the site's composer.json or 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.json and composer.lock files to run the command successfully.

Upstream Updates Cannot Be Applied

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:

  1. From the Site Dashboard, navigate to the Dev environment.

  2. Click Settings, then About site.

  3. 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.json file to be lost.

Solution 2:

Merge the changes manually:

  1. Create a local Git clone of the Pantheon site repository.

  2. Merge in the upstream changes:

    git pull https://github.com/pantheon-upstreams/drupal-project main
  3. You will get a message that there are conflicts in composer.json that 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.
  4. Resolve the conflict and follow the instructions to commit the merged changes.

  5. To verify that the merge was successful, run composer install on your local branch to verify that the composer.json parses 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.json needs to change.

  6. Push the changes to Pantheon. Integrated Composer will run again with the updated composer.json.

Changes Lost During Upstream Updates

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:

Issues using wikimedia/composer-merge-plugin

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.

FAQ

What Composer commands does Pantheon run?

All Composer commands are available through the Commit Log in the Site Dashboard's development environment.

Can I view live logs?

Composer build logs are only available after the task or action completes (or fails).

How do I view Composer's changes?

Use git diff to view changes, excluding composer.lock:

git diff d94d1a1179 -- . ':(exclude)composer.lock'

Try composer-lock-diff to see what packages have changed after composer update.

Can I use a Composer GUI?

Pantheon does not offer support for Composer GUIs or any conflicts that might be caused by one.

Why are contrib modules placed in /modules/composer instead of /modules/contrib?

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 contrib.

What features are planned for Integrated Composer on Pantheon?

Pantheon's devs are working hard to make the Integrated Composer experience on Pantheon better.

Features that are still in development: