Last Reviewed: October 15, 2024

Manage Dependencies

Learn how to add or remove an individual site dependency.

Edit this page on GitHub Report an issue with this doc

This sections provides information on dependency requirements and how to add or remove individual site dependencies.

Composer `require` and `require dev` Sections

It's important to understand how require and require dev are used on the Pantheon platform.

Composer `require` Section

Drupal modules / themes and WordPress plugins / themes should always be in the require section, not the require-dev section. Dependencies in the require section are pushed to all Pantheon environments.

Composer `require dev` Section

You should use the require-dev section for dependencies that are not a part of the web application but are necessary to build or test your project. Some examples are php_codesniffer and phpunit. Dev dependencies are deployed to Pantheon Dev and Multidev environments, but not to Test and Live environments.

Third-party dependencies, such as modules / plugins and themes, are added to the project via composer.json. The composer.lock file keeps track of the exact version of dependency. Composer installer-paths are used to ensure the dependencies are downloaded into the appropriate directory.

Select Dependencies Locally

When running composer install on a local clone of your Pantheon site's repository, you can use the --no-dev option to install the dependencies that will be installed on the Pantheon Test and Live environments. Do not include this option to install the dependencies that will be installed on Dev and Multidev environments on Pantheon. The --no-dev option has no effect on what is written to the composer.lock file, and therefore does not change the behavior of your site on Pantheon. This option is only relevant to local testing.

Add a Module, Plugin, or Theme

Clone the Git repository from the Pantheon site's dashboard.
Run composer install:
```
composer install
```
Add a new dependency locally:
```
composer require drupal/pkg-name
```
Commit composer.json and composer.lock and push the changes.
```
git add composer.json composer.lock && git commit -m "added composer.json and composer.lock" && git push
```
- Pantheon will run Composer, build artifacts, and deploy the changes to your Dev or Multidev environment. You can now deploy the changes from the updated Dev environment to the Test and Live environments.
Complete the steps to commit Dev changes to Test and Live through your Pantheon dashboard or with Terminus env:deploy.

Using Composer to manage plugins and themes

Packagist is a repository of Composer packages that are available by default to projects managed by Composer. Packagist libraries receive updates from their source GitHub repositories automatically.

WPackagist is a Packagist-like mirror of the WordPress.org plugin and theme repositories and is included with Bedrock out of the box.

You can install packages from Packagist or WPackagist without any additional configuration using composer require.

Require a Package from Packagist

Some WordPress developers push their packages to Packagist in addition to the WordPress plugin and theme repositories. In this way, it may be beneficial to pull those packages directly from Packagist to get the latest code directly from the source.

composer require yoast/wordpress-seo

Packages that are flagged as wordpress-plugin, wordpress-theme or wordpress-muplugin in their composer.json files will be installed automatically in the appropriate web/app/ directory by Composer.

Requiring a package from WPackagist

For all other plugins and themes that are not managed on Packagist, you can use composer require as well, using wpackagist-plugin or wpackagist-theme as the vendor and the plugin or theme slug as the package name.

composer require wpackagist-theme/twentytwentytwo

composer require wpackagist-plugin/advanced-custom-fields

Check first

It's generally a good idea when using either Packagist or WPackagist to check the repository before requireing the package. If you search Packagist for a WordPress plugin or theme and don't see it, you can be sure that if it exists in the WordPress plugin or theme repository, it will be available on WPackagist. Checking WPackagist for the package can be beneficial if you want to check what versions are available.

Add a Package from a Private Repository

Note

Pantheons Secrets Manager is currently in Early Access (EA). You can also use the Terminus plugin to manage your secrets for private repositories in Integrated Composer builds without committing your credentials to the repository. If you use it, follow the instructions in the Terminus plugin README instead of the steps presented on this page.

The steps below outline a method for adding a package from a private GitHub, GitLab, or Bitbucket repository. Refer to the official Composer documentation for additional information on handling private packages.

A token will be added to your code repository for this procedure. This allows anyone with the token to read and write to private repositories associated with the issuing account. You can explore workarounds to limit the scope of the token access. For example, you can create a new GitHub user and restrict that user's permission to only the private repositories needed for your Composer packages. This ensures your site repository code is not published publicly.

Your repository should contain a composer.json file that declares a package name in its name field. If it is a WordPress plugin or a Drupal module, it should specify a type of wordpress-plugin or drupal-module respectively. For these instructions, we will assume your package name is mycompany/my-private-repo.

Generate a GitHub Personal Access Tokens page. The Github token must have all repo permissions selected.

Add the private repository to composer.json, replacing <token> with your newly generated token.

composer.json

"repositories": [
     {
         "type": "vcs",
         "url": "https://<token>@github.com/mycompany/my-private-repo"
     }
 ],

Run the command below to require the package (you may specify any needed version constraint in this step):
```
composer require mycompany/my-private-repo
```
Run the commands below to commit the updated Composer files and add them to your environment only if the above command update works locally.
```
git add composer.json composer.lock
git commit -m "Adding private package <your-package>"
git push
```

Generate a GitLab token. Ensure that read_repository scope is selected for the token.

Add the private repository to composer.json, replacing <token> with your newly generated token.

composer.json

"repositories": [
    {
        "type": "vcs",
        "url": "https://oauth2:<token>@gitlab.com/mycompany/my-private-repo.git"
    }
],

Run the command below to require the package (you may specify any needed version constraint in this step):
```
composer require mycompany/my-private-repo
```
Run the commands below to commit the updated Composer files and add them to your environment only if the above command update works locally.
```
git add composer.json composer.lock
git commit -m "Adding private package <your-package>"
git push
```

Generate a Bitbucket oauth consumer. Ensure that Read repositories permission is selected for the consumer. Also, set the consumer as private and put a (dummy) callback URL.
Use the consumer key and consumer secret to create an auth.json file in your repo root like this:
```
composer config bitbucket-oauth.bitbucket.org consumer-key consumer-secret
```

Add your private repository to the repositories section of composer.json:

composer.json

"repositories": [
    {
        "type": "vcs",
        "url": "https://bitbucket.org/vendor/package-name.git"
    }
],

Run the command below to require the package (you may specify any needed version constraint in this step):
```
composer require mycompany/my-private-repo
```
Run the commands below to commit the updated Composer files and add them to your environment only if the above command update works locally.
```
git add auth.json composer.json composer.lock
git commit -m "Adding private package <your-package>"
git push
```

Remove Individual Site Dependencies

You can remove site dependencies if they are no longer needed. You should use caution when removing individual site dependencies. You can cause problems with your site if you decide you no longer need a module but leave it installed, and then remove site dependencies.

Clone the database from Live to all other environments before continuing.
Ensure that all modules in the package have been uninstalled. You can uninstall modules in the Drupal admin dashboard, or from the command line with Terminus:
```
terminus drush site.live -- pm:uninstall module1 module2
```
Remove the dependency locally:
```
composer remove drupal/pkg-name
```
Commit composer.json and composer.lock and push the changes.
- Pantheon will run Composer, generate build artifacts, etc.

Updating Dependencies

Integrated Composer on Pantheon runs Composer operations on the server level. Which operations are run depends on what you are doing with your code.

Pushing Code to Pantheon

When you push code to Pantheon, a composer install operation is run. This operation installs the dependencies listed in the composer.lock file. This ensures that the same versions of dependencies are installed on all environments.

Update all dependencies

When you check for an upstream update, the composer update operation is run. This operation updates all Composer-managed packages according to the version constraints in your composer.json file. This ensures that your site is up-to-date with the latest versions of all Composer-managed packages. Refer to the Composer Versions documentation for more information on version constraints.

When you click to apply these upstream updates, the composer update operation is run on the Pantheon server. This updates the composer.lock file with the new versions of the packages. The composer.lock file is then committed to the repository and pushed to Pantheon.

Site Dashboard

Go to the Site Dashboard, Dev tab, and click Code.
Click Check Now.
Switch your Development Mode from SFTP to Git if you have not done so already.
Click Apply Updates if updates are available.

Terminus

Run the command below to apply available updates to your site development environment:

terminus upstream:updates:apply --updatedb --accept-upstream -- <site>.<env>

Update a specfic package

To update a specific package, run:

composer update vendor/package

Replace vendor/package with the package name you want to update. This will update only the named package to the latest version that matches the version constraints in your composer.json file.

Manage Dependencies

Composer `require` and `require dev` Sections

Composer `require` Section

Composer `require dev` Section

Select Dependencies Locally

Add a Module, Plugin, or Theme

Using Composer to manage plugins and themes

Require a Package from Packagist

Requiring a package from WPackagist

Check first

Add a Package from a Private Repository

Remove Individual Site Dependencies

Updating Dependencies

Pushing Code to Pantheon

Update all dependencies

Site Dashboard

Terminus

Update a specfic package

More Resources

Topics

Help

Community

Composer require and require dev Sections

Composer require Section

Composer require dev Section

Select Dependencies Locally

Add a Module, Plugin, or Theme

Using Composer to manage plugins and themes

Require a Package from Packagist

Requiring a package from WPackagist

Check first

Add a Package from a Private Repository

Remove Individual Site Dependencies

Updating Dependencies

Pushing Code to Pantheon

Update all dependencies

Site Dashboard

Terminus

Update a specfic package

More Resources

Composer `require` and `require dev` Sections

Composer `require` Section

Composer `require dev` Section