Create a new Composer-managed Drupal application using Composer, install (download) a Drupal module using Composer, and update a Drupal module using Composer
Composer must be installed on your local machine.
If you use Acquia Cloud IDE, Composer will already be installed.
Creating a new Drupal application with Composer
Acquia recommends using Composer’s create-project command to create a new Drupal application using a predefined template.
When you execute
composer create-project [example/project], it will clone
example/projectfrom Packagist and use it as a template for your new project.
Your new project will not depend on
example/project. Think of it like photocopying the template. You’ll end up with a copy. Any future changes to the original will not affect the copy. It’s just a starting point.
Acquia offers two such templates:
- Acquia Drupal Recommended Project (
acquia/drupal-recommended-project), which provides many Acquia projects for a great out-of-the-box experience
- Acquia Drupal Minimal Project (
acquia/drupal-minimal-project), which provides only the bare minimum configuration to start a project on Acquia Cloud
Both of these templates follow the best practices outlined in How to Structure Your Drupal Repository.
Try it yourself
To create a new Drupal application that uses
acquia/drupal-recommended-projectas a template, execute the following commands in your terminal:
drupal-projectwith the name of the project directory you want to use)
composer create-project acquia/drupal-recommended-project drupal-project --no-interaction cd drupal-project
For more information, see Using Composer to Install Drupal and Manage Dependencies.
Using Acquia CLI
If you have Acquia CLI installed on your machine (it’s already installed in all Acquia Cloud IDEs) you can alternatively use the
acli newcommand to create a new Drupal application with Composer. The
newcommand will simply prompt you to choose one of Acquia’s Composer templates and run the
composer create-projectcommand for you "under the hood."
acli new drupal-project cd drupal-project
- Acquia Drupal Recommended Project (
Push your new code upstream
Now that you have a new project, you can push your “first commit” upstream to a Git remote. Use the typical process of adding a Git remote to your local Git repository and pushing code. E.g.,
git init git remote add [remote-name] [remote-url] git push [remote-name] [branch-name]
[remote-name]is whatever you’d like to name your remote (often this is origin) and
[remote-url]is the remote URL of your remote Git repository.
For example, if you’re using Acquia Code Studio, you can find the remote URL of your Code Studio project here:
To add this Git remote (named codestudio) and push your code, you’d run:
git remote add codestudio [url] git push codestudio main
Note that the Acquia project templates configure Git to ignore Composer-provided files by default. For instance, the
docroot/coredirectory will not be committed to your Git repository because of the following line in the
/docroot/core. For more information see How to Structure Your Drupal Repository.
Download a new Drupal module, theme, or distro via Composer
All of the modules, themes, and distributions hosted on Drupal.org are made available as Composer packages. You can use Composer to download and update these packages for your Drupal application.
First, ensure that your application follows Acquia’s best practices as defined in How to structure your Drupal repository. At minimum, your composer.json file must:
- Include the
drupalkey in the repositories array so that Composer is able to locate the Drupal packages hosted on Drupal.org
- Have a properly configured installer-paths key in order to ensure that Drupal projects are downloaded to the correct directories in your local repository
Composer and Drush use the same words to mean different things. Notably, the word "install" means one thing in Composer parlance and something very different in Drupal parlance.
Terminology Composer Meaning Drupal & Drush Meaning Install Download to local repository and make available via Composer Autoloader Install to Drupal database Package A Composer package, inclusive of Drupal modules, themes, distros, etc. A group of modules listed on the Drupal admin "Extend" page. Project A type of package. A module, theme, distro, or other repository hosted on Drupal.org.
Composer allows you to "require" a set of dependencies that it "installs." Again, in Composer parlance, “install” simply means that the Composer package will be downloaded and correctly loaded (made available to PHP classes) by the Composer autoloader.
To use Composer to "install" a new Drupal project (module, theme, profile, etc.), execute:
composer require drupal/[project-name]
[project-name]is the machine name of the project (module, theme, distro, etc.) on Drupal.org. You can always find the machine name of a Drupal project on it’s project page on Drupal.org:
For instance, to require token, execute:
composer require drupal/token
This will add
requirearray in your
composer.json. It will choose a default version constraint based on your
composer.jsonconfiguration. E.g., if you have specified
"prefer-stable": "true"then this will download the latest stable version of the package.
You may also specify the version constraint by adding second argument:
composer require drupal/token ^1.1.0
Make sure to commit the changes to
composer.lockafter requiring the new module. As mentioned above and in How to Structure Your Drupal Repository, the Drupal module files will not be committed to Git. Rather, Composer will read the contents of
composer.lockwhen installing or deploying your site to another environment in order to install the expected packages.
- Include the
Update a single Composer package
To update any Composer package, execute:
composer update [org]/[package]
For instance, to update
composer update drupal/token
This will update the package within the bounds of the version constraint defined in
composer.json. E.g., if
composer.jsondefines the constraint for
composer updatewill update to the latest 1.x release. It will never update
drupal/tokento a 2.x version. To learn more about Composer version constraints, read Versions and constraints - Composer.
drupal/tokenand also all of the packages that
drupal/tokendepends on, execute:
composer update drupal/token --with-all-dependencies
--with-all-dependenciesoption is useful not only because it updates packages which
drupal/tokendepends on, but because the newer version of
requirenewer versions of those packages. And unless you explicitly tell Composer that it’s OK to update those packages with the
--with-all-dependenciesoption, it will give you an error saying that the new version of
drupal/tokenis incompatible with your other already-installed packages.
drupal/tokenand require a new version constraint (such as 1.10), execute:
composer require drupal/token:^1.10 --update-with-all-dependencies
Update all Composer packages
To update all Composer packages (within the bounds of your version constraints), run: