Skip to main content
Log inGet free account

Manage Some Dependencies with Composer

Get your feet wet with Composer on WordPress or Drupal before going all in.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

In this guide, you'll learn how to use Composer in small doses with WordPress and Drupal so you can work towards best practices achieved by more advanced implementations. This allows you to continue using Pantheon's one-click core updates in the Site Dashboard while managing non-core dependencies with Composer.

Before You Begin

Partial Composer adoption for Drupal sites is not supported since Composer is used by core, meaning any change to composer.json or the vendor directory would result in massive merge conflicts when trying to update core via one-click updates in the Pantheon Site Dashboard. Composer with Drupal is an all or nothing proposition. To use Composer to manage Drupal sites, use the Build Tools or convert an existing Drupal site to Integrated Composer on Pantheon methods.

  • Set the site's connection mode to Git within the Site Dashboard or via Terminus:

    terminus connection:set <site>.<env> git

  • Create a local clone of your site code, and navigate to it in your terminal

Initialize and Configure Composer

Use the init command to create a composer.json file that includes the appropriate package repository, then configure installation paths for dependencies like plugins and modules:

  1. If you haven't done so already, clone your Pantheon site repository and navigate to the project's root directory. Replace <site_name> with your site's name (e.g., your-awesome-site):

    SITE=<site_name>
`terminus connection:info $SITE.dev --fields='Git Command' --format=string`
cd $SITE

  2. Initialize composer to create a composer.json file with the WordPress package repository:

    composer init --repository=https://wpackagist.org --no-interaction

  3. Edit the composer.json to add extra configuration that specifies installation paths for WordPress plugins and themes.

    Note

    Since Pantheon does not support Git submodules

    , we recommend using the provided script remove-git-submodules to remove any .git directories upon install and update.

    composer.json
    {
  "repositories": [
    {
      "type": "composer",
      "url": "https://wpackagist.org"
    }
  ],
  "require": {},
  "extra": {
    "installer-paths": {
      "wp-content/plugins/{$name}/": ["type:wordpress-plugin"],
      "wp-content/themes/{$name}/": ["type:wordpress-theme"]
    }
  },
  "scripts": {
    "remove-git-submodules": "find . -mindepth 2 -type d -name .git | xargs rm -rf",
    "post-install-cmd": [
      "@remove-git-submodules"
    ],
    "post-update-cmd": [
      "@remove-git-submodules"
    ]
  }
}

  4. Commit the composer.json file to version control with Git:

    git add composer.json
    git commit -m "Create composer.json with WP repo and install paths"

  5. Push your new file to Pantheon:

    git push origin master

Anything you aren't managing with Composer is installed and maintained using the standard techniques such as using the WordPress or Drupal admin interfaces. Continue applying one-click core updates from Pantheon in the Site Dashboard.

Require Dependencies

Use the require command to add new dependencies to your project, such as libraries or themes. This command modifies your composer.json file by including the specified dependency and it's compatible version.

Note that Pantheon does not run composer install on the platform, so you need to install and commit the dependencies.

Install a Plugin

  1. Require the plugin, Pantheon Advanced Page Cache for example, with Composer:

    composer require wpackagist-plugin/pantheon-advanced-page-cache

  2. Review modified files using git status, you should see the module has been installed in the wp-content/plugins directory like so:

    Require wpackagist-plugin/pantheon-advanced-page-cache output

    Notice a missing dependency was also installed, composer/installers. This package is needed to support the installation paths configured in the previous section, and needs to be tracked in version control.

  3. Commit your work to version control with Git:

    git add .
    git commit -m "Require pantheon-advanced-page-cache ^0.3.0 "

  4. Push your changes to Pantheon:

    git push origin master

  5. Navigate to the Dev environment of the Site Dashboard.

  6. Click the Site Admin button and login.

  7. Navigate to Plugins and activate Pantheon Advanced Page Cache.

Next Steps

If your use case doesn't require the more advanced Build Tools method, continue using Composer to manage any number of your non-core dependencies while preserving Pantheon's one-click core updates. This is only supported for Drupal and WordPress.

If you're ready to learn best practices for Composer on Pantheon, follow the Build Tools guide.