PhpStorm for Composer Managed Drupal 8 Sites

Learn how to configure JetBrains PhpStorm for Pantheon sites managed with Composer using a GitHub Pull Request workflow.

Contributors: Lukas Rosenstock, Rachel Whitton


JetBrains PhpStorm is a commercial PHP IDE that you can configure to work with your Pantheon sites. This guide explains how to use the Composer integration of JetBrains PhpStrom to install Drupal 8 dependencies.

Before You Begin

Be sure that you:

Create A New Project

  1. Open PhpStorm, and in the "Welcome to PhpStorm" screen, select Check out from Version Control > Git:

    Welcome to PhpStorm

  2. Open the GitHub project page for the site you created following the Build Tools guide. Copy the repository's SSH URL to your clipboard:

    GitHub clone repo link

  3. In PhpStorm, paste the repository's SSH URL in the Git Repository URL field (the Directory Name field will automatically populate after pasting the URL):

    Clone repository

  4. Click the Clone button and wait for PhpStorm to download your repository from GitHub.

  5. Reply Yes when PhpStorm asks whether you want to open the project.

Initialize Composer

  1. After opening the project, check the event log by clicking the message icon from the lower right side of the window. Click Initialize:

    Composer init PhpStorm

  2. PhpStorm should catch the settings correctly, so you can simply confirm with OK:

    Composer

  3. Open composer.json and select Install from the top right:

    Composer install

    If this is the first time you use PhpStorm's Composer integration, you'll see the "Composer Settings" window in which you need to set or confirm your local Composer installation. PhpStorm needs to know where it can find this tool on your computer and you can point it either to the composer executable or a composer.phar archive. Confirm your local installation then click OK:

    Composer Settings

Enable Drupal Support

  1. After installing Drupal using Composer in the previous section, you should get a message to Enable Drupal Support. Click Enable:

    Enable Drupal Support

  2. Add a check to Enable Drupal integration then click the ... button to browse your local filesystem:

    Enable Drupal Support browse

  3. Navigate to the project's installation path, then select the web subdirectory and click Open:

    Enable Drupal Support select subdir

  4. Select 8 for Drupal version, then click Ok:

    Enable Drupal Support select version

  5. After enabling Drupal Support, check your messages for a prompt to set Drupal-style formatting. Click Set it:

    Set Drupal-style formatting

Install Dependencies via Composer

PhpStorm's Composer integration has a search interface available at Tools > Composer > Manage Dependencies .... You can type the name of any package hosted on the PHP Package Repository in the search field.

Unfortunately, this interface cannot be used to install dependencies from custom repositories defined in composer.json:

"repositories": [
  {
    "type": "composer",
    "url": "https://packages.drupal.org/8"
  }
],

This means that if your Composer extension is not on the PHP Package Repository, you have to add it manually to the composer.json file. Dependencies are added to the require section and for each package you need to specify either an exact version number or a version constraint.

  1. Click Git:Master from the bottom right corner, then click + New Branch:

    Checkout new branch

  2. Checkout a new branch for your specific task, in this example we name it pathauto since that's the name of the module we're adding:

    Checkout pathauto branch

  3. Determine the latest available stable version from the Pathauto project page:

    Drupal Pathauto

  4. Add drupal/panthauto your composer.json file with a version constraint of ~1.0, then click Update to start the download and installation process:

    Composer with Pathauto

    Composer package names always follow a "vendor/name" convention. All packages in the Drupal repositories have "drupal" as the vendor and the Drupal project name as their package name (e.g., drupal/pathauto).

  5. Wait for a confirmation message from Composer.

Open PR and Deploy to Multidev

Now it's time to deploy and test the newly installed module. The Pull Request workflow demonstrated in the Build Tools guide encourages the mental model where only files unique to the project are tracked as part of the project's main "source" repository.

For this example, that means we only care about changes made to the composer.json file and the composer.lock file. We don't want to track the actual code of the Pathauto module within our repository, we want Composer to build it for us based on our version constraints.

  1. Navigate to VCS > Commit.. Note only two files are listed as changed:
  2. Disable default options to perform a code analysis and check TODOs. Enter a commit message and then select Commit and Push..:

    Commit Changes Window

  3. Click Push:

    Push Changes Window

  4. Go to the project page on GitHub. Select Compare & pull request:

    New branch pushed

  5. Open a Pull Request from the pathauto branch to master, suggesting edits to two files:

    Open PR

  6. The commit will be built by CircleCI and deployed to a new Multidev environment on Pantheon. Check the PR for a new comment containing links to the Multidev environment and site.

Follow your teams standard review process for accepting changes into master, which is built and deployed to Dev.