Lando Drupal 7

Posted onby admin

The question I get asked most often when discussing my Lando development environment with other Drupal Web Developers is, “How do you setup Lando and PhpStorm to debug Drupal using Xdebug?” This blog post will help you do exactly that.

Acquia BLT with Lando generally works as expected, but to achieve a better integration, add the following code to your.lando.yml file, and then rebuild the containers. Tooling: blt: service: appserver cmd: /app/vendor/bin/blt. You can also update your BLT config (blt.yml) with the Lando host name syntax:project: machinename: abc prefix: ABC humanname: 'A website' profile: name: standard. I would open Hyper-v Manager and make sure the crc vm is not there. Then delete your.crc directory completely. Next run crc setup after then is down run crc start -p C: Users jim crc-windows-1.4.0-amd64 pull-secret.txt -m 9192 -n 8.8.8.8 Please note you will need to change the path from C: Users jim crc-windows-1.4.0-amd64 pull-secret.txt to where to stored your pull-secret fie.

Before you start, you should have a Drupal website up-and-running in Lando. Even a freshly-installed, blank Drupal website will do.

Once you finish, you will be able to use PhpStorm to:

  • Debug Drupal 8 (and 7) in Lando: a Docker-based development environment
  • Debug drush commands for Drupal in Lando
  • Debug phpunit tests for Drupal in Lando
    • because if you had just written your unit test before you wrote that snazzy method, like you were supposed to,…😉

Tested using:

  • OSX
    • v10.12.6
    • v10.13.6
  • PhpStorm v2018.2.2
  • Xdebug v2.6.1
  • Lando v3.0.0-beta.47
  • Docker v18.06.1-ce-mac73 (26764)
  • Drupal
    • v8.6.0
    • v7.59
  • drush v8.1.17
    • NOTE: drush 9 is currently NOT supported in PhpStorm
  • phpunit
    • v6.5.12 for Drupal 8
    • v6.5.3 for Drupal 7

Prerequisites:

  • PhpStorm is installed
  • Xdebug is installed
  • Lando is installed (includes Docker)
  • Drupal is installed in Lando
  • drush 8.x.x is installed
    • NOTE: drush 9 is currently NOT supported in PhpStorm
  • phpunit 6.5.x is installed
    • Drupal 8: included with install
    • Drupal 7: https://phpunit.de/manual/6.5/en/phpunit-book.html#installation
  • You should be reasonably familiar with the command line, as well as with the above software.

Prepare your Drupal in Lando for PhpStorm:

Create a custom php.ini for your Drupal in Lando website:

In the root directory of your lando project, create a “config” directory.

  • For example, on OSX this might be: ~/Sites/yourdrupal.lndo.site/config/

Inside this config directory, create a php.ini file with the following:

Edit the .lando.yml file for your Drupal in Lando website:

Add the following to the “config” key of the .lando.yml file, so that Lando will include your new php.ini.

Add the following to the “services” key of the .lando.yml file, so that Lando will include a PHP_IDE_CONFIG for PhpStorm.

Change “yourdrupal.lndo.site” above to match the domain name of your Drupal in Lando website.

Add the following to the “tooling” key of the .lando.yml file, so Lando will recognize “lando phpunit” commands.

If Drupal 8:

Change “web” above to match the webroot directory of your Drupal 8 in Lando website.

If Drupal 7:

Examples of complete Drupal 8 and Drupal 7 .lando.yml files:

A complete but basic Drupal 8 .lando.yml configured for PhpStorm would look like the following:

A complete but basic Drupal 7 .lando.yml configured for PhpStorm would look like the following:

In fact, you could use either of the above .lando.yml files as written, just to test things out. If you plan on spinning-up both of them on the same machine at the same time, though, change the value in “name:” and “PHP_IDE_CONFIG:” of at least one of them first. 😉

Rebuild your Drupal in Lando website in order to apply the new settings.

Create a new PhpStorm Project for your Drupal in Lando website:

Open PhpStorm and click on the following:

File > New Project from Existing Files

  • Source Files are in a local directory, no Web server is yet configured
  • Click on the “Next” button.

Mark as Project Root a directory to create the project in:

  • Click on “Project Root”
    • (in the top left window toolbar).
  • Select your drupal root directory.
    • For example, /Users/You/Sites/yourdrupal.lndo.site/web
  • Click on the “Finish” button.

Enable Drupal Support:

After the project finishes indexing, the Event log window should be visible. If it isn’t, click on “Event log” in the bottom-right of the screen.

In the Event log window, enable the suggested items by clicking on them:

  • Enable the Symfony Plugin with auto configuration now
    • (may or may not be available)
  • Enable Drupal Support, which should display the “Enable Drupal Integration” configuration window below.

Enable Drupal integration:

  • Verify that “Enable Drupal integration” is checked.
  • Drupal installation path: (Select your drupal root directory)
    • For example, /Users/You/Sites/yourdrupal.lndo.site/web
  • Verify that “Set up PHP Include paths” is checked
  • Version: 8
    • (or whatever Drupal version you are using)
  • OK

The above configurations can also be set at:

  • PhpStorm > Preferences > Languages & Frameworks > PHP > Frameworks

If prompted by the Event log window, “Set Drupal-style formatting for this project”.

Configure your PhpStorm project:

Setup the PHP Interpreter for the project:

  • PhpStorm > Preferences > Languages & Frameworks > PHP
  • PHP language level: 7.1
    • (or whatever PHP version your Drupal in Lando website uses).
  • Click on the “…” icon to the right of the “CLI Interpreter” field.

In the window that opens,

  • control+n
    • (or click on the “+” icon at the top left of the pane).
  • Select “From Docker…”
  • Server: Docker
  • Image Name: devwithlando/php:7.1-apache
    • (or whatever PHP version your Drupal in Lando website uses)
  • PHP interpreter path = php
  • OK
  • Apply
  • OK
  • Apply

Setup the PHP Server for the project:

  • PhpStorm > Preferences > Languages & Frameworks > PHP > Servers
  • Click on the “+” in the top left of the left pane.
  • Name: yourdrupal.lndo.site
    • (Change this to match the domain name of your Drupal in Lando website.)
  • Host: yourdrupal.lndo.site
    • (Change this to match the domain name of your Drupal in Lando website.)
  • Port: 80
    • (or whatever lando provided, if applicable)
  • Debugger: Xdebug
  • Enable: “Use path mappings”

Set the path mapping for the Drupal in Lando website’s root directory:

In the “File/Directory” column, highlight the (path to your Drupal root) row that is listed under the “Project files” folder, by clicking on it.

  • For example, click on: /Users/You/Sites/yourdrupal.lndo.site/web
  • Edit the “Absolute path on the server” field for the highlighted row.
    • Click on the highlighted edit icon that is visible on the right of the same row.
    • Type: /app/web
    • Press the enter key to update the field.
  • Apply

Set the path mapping for drush in Lando:

If Drupal 8:

In the “File/Directory” column, highlight the (path to your included drush) row that is listed the under the “Include path” folder, by clicking on it:

  • For example, click on: /Users/You/Sites/yourdrupal.lndo.site/web/vendor/drush/drush
  • Edit the “Absolute path on the server” field for the highlighted row.
    • Click on the highlighted edit icon that is visible on the right of the same row.
    • Type: /usr/local/bin/drush
    • Press the enter key to update the field.
  • Apply:
If Drupal 7:

In Terminal, add a symlink at your Drupal web root to your globally-installed drush

  • For example, on OSX:

In PhpStorm, highlight your newly created “drush” symlink row that is listed the under the “Include path” folder, by clicking on it.

  • Edit the “Absolute path on the server” field for the highlighted row.
    • Click on the highlighted edit icon that is visible on the right of the same row.
    • Type: /usr/local/bin/drush
    • Press the enter key to update the field.
  • Apply

Configure PhpStorm to debug browser-triggered events for your Drupal in Lando website:

  • PhpStorm > Preferences > Languages & Frameworks > PHP > Debug
  • External Connections
    • Enable “Break at first line in PHP scripts”
      • (to at least verify that the debug session is working)
    • Max simultaneous connections = 19
      • Press the tab key to update the field.
  • Apply

Configure PhpStorm to debug “lando drush” commands for your Drupal in Lando website

  • PhpStorm > Preferences > Tools > Command Line Tool Support
  • control+n
    • (or click on the “+” icon on the left side of the main pane)
  • Select “Custom tool” (not “Drush”) from the dropdown menu.
    • We don’t select “Drush” here because the path to the Lando appserver’s drush must be entered manually.
  • Visibility = project
  • OK
  • Set the path to the Lando appserver’s drush:
    • /usr/local/bin/drush
    • Alias: drush
  • OK
  • Show console in: tool window
  • Apply
  • OK

Test your Drupal in Lando PhpStorm Debugging Setup:

Start listening for PHP debug connections:

  • command+shift+L in PhpStorm

In your web browser, reload your Drupal in Lando website. You do NOT need an Xdebug Helper browser extension for this to work. With the above settings, PhpStorm will automatically pause your website at:

  • If Drupal 8: line 14 (“$autoloader) of index.php
  • If Drupal 7: line 17 (“define”) of index.php

Note: PhpStorm did NOT automatically focus the PhpStorm application in your computer display. With the current PhpStorm settings, you have to switch to PhpStorm manually in order to see that it is pausing your website. We will change this setting in the next step.

fn+command+F2 to stop debugging but continue listening for PHP Debug Connections

To focus PhpStorm automatically when a breakpoint is set:

  • PhpStorm > Preferences > Languages & Frameworks > PHP > Debug > External connections
  • Uncheck “Break at first line in PHP scripts”.
  • Apply
  • OK
Free

Test browser-triggered debugging:

If Drupal 8:

  • Add a breakpoint at line 14 (“$autoloader”) of web/index.php
  • Add a breakpoint at line 236 (“function user_load”) of web/core/modules/user/user.module

If Drupal 7:

  • Add a breakpoint at line 19 (“require_once”) of web/index.php
  • Add a breakpoint at line 365 (“function user_load”) of web/core/modules/user/user.module

In your web browser, navigate to yourdrupal.lndo.site/user/1

  • Focus will switch to PhpStorm and catch at the breakpoint in index.php.
  • fn+F9 to jump to the next breakpoint.
  • PhpStorm will catch at the breakpoint in user.module.
  • fn+command+F2 to stop debugging but continue listening for PHP Debug Connections

Test “lando drush” debugging:

In Terminal:

  • PhpStorm will catch at the breakpoint that is still set for user.module in the example above.
  • fn+command+F2 to stop debugging but continue listening for PHP Debug Connections

Test phpunit debugging:

If Drupal 8:

  • Add a breakpoint at line 62 (“$this->password”) of web/core/tests/Drupal/Tests/Core/Password/PasswordHashingTest.php
  • Run a phpunit test in Terminal:
  • Focus will switch to PhpStorm and catch at the breakpoint in PasswordHashingTest.php.
  • fn+command+F2 to stop debugging but continue listening for PHP Debug Connections
    • You may have to fn+command+F2 more than once

If Drupal 7:

  • Enable the Testing module:
  • Remove the breakpoint you set above at line 365 (“function user_load”) of web/core/modules/user/user.module
  • Add a breakpoint at line 23 (“require_once”) of web/modules/simpletest/tests/password.test
  • Run a phpunit test in Terminal:
  • Focus will switch to PhpStorm and catch at the breakpoint in password.test
  • fn+command+F2 to stop debugging but continue listening for PHP Debug Connections
    • You may have to fn+command+F2 more than once

Happy Drupal in Lando debugging with PhpStorm!

Have your own tricks for Drupal debugging? Share your thoughts with us on Twitter, and subscribe to our newsletter for more content like this!

Who is this guide for?

These steps are relatively complicated (although easier when you've done it once). Therefore we suggest only developers undertake the steps for setting up existing projects.

Lando Drupal 7 Free

Prerequisites

Once only

The following two steps will only need to be done once per computer you set up Lando on:

  1. You should have already installed Lando. If you haven't yet done that, please head back to the introduction page of these docs and follow the install notes in the How do I install Lando section.

  2. Save a global Lando config file which tells Lando what your username is. This is used for remote drush commands like sql-sync and makes your life easier:

    Important! If your local user name is different from the user you ssh into servers with then you'll need to manually edit the ~/.lando/config.yml file to add the correct user.

Understanding these steps

Don't just copy paste each of the commands! You will need to edit some lines before hitting return. You will also need to open an editor (vim, nano etc) to modify lines in files.

Project naming convention

Lando Drupal 7 Free

The specified convention [client code][project code] is the recommended naming scheme for new projects. The client code should be four letters (or less but ideally four), as should the project code. If the project is the organisation's main site then main should be used for the project code. Otherwise a code representing the project should be used.

Examples:

  • Agile Collective website: The organisation is Agile Collective (AC for short) and the project is their main website so this translates to acmain with a resulting Lando domain acmain.lndo.site
  • Bitcoin & Co project website: The organisation is Bitcoin & Co (BTC for short) and the project is their scam website so this translates to btcscam with a resulting Lando domain btcscam.lndo.site

Setting up an existing project

Drupal

To set up an existing project which doesn't have a .lando.yml file in the git root, the following steps can be used for Drupal 8 or Drupal 7 sites

Drupal 8

  1. Starting somewhere within your home directory, clone the project's repository from the Agile Collective GitLab server and change the word projectname in the following command so that it follows the convention[client code][project code]:
  1. Copy the boilerplate Drupal 8 Lando config and paste into a .lando.yml file in the gitroot directory.

  1. Edit the .lando.yml file and change the value for the name key so that it follows the convention [client code][project code].

    Also change the domain name for mailhog under the proxy key. The mail.projectname.lndo.site domain name should be updated so that projectname is something unique to the project, using the name value is preferable.

Note that Lando will remove any non alpha characters from domain names so if you wrote agile-collective for the project name the domain name will be agilecollective.lndo.site. You can confirm the domain name with lando info.

  1. (Optional) Modify the .lando.yml file for this project's particular needs. For example, it may need a specific PHP version, or Solr. See the Lando docs for details on how to add services.

Note that the front end stack might require specific Lando configuration. This is touched on in the Front end tooling set up

  1. Configure the domain for drush and Lando by creating a .env file with the following content (edit the domain to suit your project, can be discovered with lando info). You should replace projectname with whatever you chose for the .lando.yml file:
  1. Add the web root as a environment variable so that drush commands can be run from outside the webroot.
  1. Bring the Lando containers up:
  1. Download the boilerplate settings.local.php file (run this from the git root):
  1. Create the drush aliases:

Lando Drupal 9

  1. Edit the two drush alias files and enter the correct details for the remote server. More detailed information about the contents of these files and the set up of aliases can be found in the drush alias set up document.
  2. Import the database. This can be done with one of the following two methods:

  • Using the newly configured drush aliases:

  • Using a more manual method:

    1. Move the sql database file you want to import into the git root, e.g:
    1. Import the database:
    1. Delete or move the sql database file back out of the git root, e.g:
  1. Add an .htaccess file (run this from the git root):
  1. Modify the .gitignore file to ignore the .env file:
  1. Access your site:
  1. Commit the .lando.yml file, the drush aliases and the .gitignore file to the repository (run this from the git root):
  1. Note the project shortname in the support master sheet.
  2. Go to the front end set up documentation and configure the theme to work with Lando. Commit any changes.

Drupal 7

  1. Start in the repository root (referred to from here as the git root) directory:
  1. Copy the boilerplate Drupal 7 Lando config and paste into a .lando.yml file in the gitroot directory.

  1. Edit the .lando.yml file and change the value for the name key so that it follows the convention [client code][project code].

    Also change the domain name for mailhog under the proxy key. The mail.projectname.lndo.site domain name should be updated so that projectname is something unique to the project, using the name value is preferable.

Note that Lando will remove any non alpha characters from domain names so if you wrote agile-collective for the project name the domain name will be agilecollective.lndo.site. You can confirm the domain name with lando info.

  1. Check the PHP version the server uses by visiting the status page on the production site at: /admin/reports/status. Then change the PHP version if needed in the .lando.yml file:
  1. (Optional) Modify the .lando.yml file for this project's particular needs. For example, the project may need Solr. See the Lando docs for details on how to add services.
  2. Configure the domain for drush and Lando by creating a .env file with the following content (edit the domain to suit your project, can be discovered with lando info). You should replace projectname with whatever you chose for the .lando.yml file:
  1. Add the web root as a environment variable so that drush commands can be run from outside the webroot.
  1. Bring the Lando containers up:
  1. Add an .htaccess file (run this from the git root):
  1. Modify the .gitignore file to ignore the .env file and sql files:
  1. Download the boilerplate settings.php file:
  1. Create the drush aliases:
  1. Edit the two drush alias files (in drush/sites/) and enter the correct details for the remote server. More detailed information about the contents of these files and the set up of aliases can be found in the drush alias set up document.
  2. Import the database. This can be done with one of the following two methods:

  • Using the newly configured drush aliases:

  • Using a more manual method:

    1. Move the sql database file you want to import into the git root, e.g:
    1. Import the database:
    1. Delete or move the sql database file back out of the git root, e.g:
  1. Access your site (run this command from the web root):
  1. Commit the .gitignore and .lando.yml file to the repository (run this from the git root):
  1. Note the project shortname in the support master sheet.
  2. Go to the front end set up documentation and configure the theme to work with Lando. Commit any changes.

Lando Drupal 7 Latest

Drupal 6

Drupal 7 Release Date

While Drupal 6 is not supported sometimes you may need to set up a D6 site for a site audit or migration project.

Lando Drupal 8 Import Site

You can follow a mix of the Drupal 7 set up and the official Drupal 6 guide from Lando.