Install Drupal with Composer

Goal

Create a new Composer-managed Drupal application using Composer, install (download) a Drupal module using Composer, and update a Drupal module using Composer

Prerequisites

• Composer must be installed on your local machine.

• If you use Acquia Cloud IDE, Composer will already be installed.

Overview

Learn how to create a new Drupal project using Composer with this step-by-step tutorial. Master Drupal setup and development with Composer for a streamlined workflow.

• 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/project from 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

  Using Composer

  To create a new Drupal application that uses acquia/drupal-recommended-project as a template, execute the following commands in your terminal:

  (replace drupal-project with the name of the project directory you want to use)

  copy

   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 new command to create a new Drupal application with Composer. The new command will simply prompt you to choose one of Acquia’s Composer templates and run the composer create-project command for you "under the hood."

  copy

   acli new drupal-project cd drupal-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.,

  copy

   git initgit remote add [remote-name] [remote-url]git push [remote-name] [branch-name]

  Where [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:

  copy

   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/core directory will not be committed to your Git repository because of the following line in the .gitignore file: /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 drupal key 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

  Terminology

  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.

• Update a single Composer package

  To update any Composer package, execute:

  copy

   composer update [org]/[package] 

  For instance, to update drupal/token, execute:

  copy

   composer update drupal/token

  This will update the package within the bounds of the version constraint defined in composer.json. E.g., if composer.json defines the constraint for drupal/token as ^1.0.0, composer update will update to the latest 1.x release. It will never update drupal/token to a 2.x version. To learn more about Composer version constraints, read Versions and constraints - Composer.

  To update drupal/token and also all of the packages that drupal/token depends on, execute:

  copy

   composer update drupal/token --with-all-dependencies

  Note

  The --with-all-dependencies option is useful not only because it updates packages which drupal/token depends on, but because the newer version of drupal/token might require newer versions of those packages. And unless you explicitly tell Composer that it’s OK to update those packages with the --with-all-dependencies option, it will give you an error saying that the new version of drupal/token is incompatible with your other already-installed packages.

  To update drupal/token and require a new version constraint (such as 1.10), execute:

  copy

   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:

  copy

   composer update

Additional Resources

• How to structure your Drupal repository
• Using Composer to Install Drupal and Manage Dependencies
• https://github.com/acquia/drupal-recommended-project
• Minimal Drupal project for use on Acquia Cloud