DDEV Archives - Víctor Dorado https://www.victordorado.es/category/ddev/ Tue, 05 May 2026 07:33:40 +0000 en-US hourly 1 https://wordpress.org/?v=7.0.2 Bring the AWS Cloud to Your Desktop with LocalStack™, DDEV and Drupal https://www.victordorado.es/2024/12/19/bring-the-aws-cloud-to-your-desktop-with-localstack-and-drupal/ https://www.victordorado.es/2024/12/19/bring-the-aws-cloud-to-your-desktop-with-localstack-and-drupal/#comments Thu, 19 Dec 2024 19:07:56 +0000 https://www.victordorado.es/?p=2323 Developing applications to run on AWS can become much simpler with a local setup. We will perform a complete S3 local service installation with Drupal and DDEV

The post Bring the AWS Cloud to Your Desktop with LocalStack™, DDEV and Drupal appeared first on Víctor Dorado.

]]> Developing applications to run on AWS can become much simpler with a local setup. Imagine working without needing an internet connection or incurring additional costs. As LocalStack states on its website:

“Develop and test your AWS applications locally to reduce development time and increase product velocity. Reduce unnecessary AWS spend and remove the complexity and risk of maintaining AWS dev accounts.”

LocalStack™ offers both a community and a pro version, allowing users to access the community version for free. In this guide, we’ll walk you through configuring a local instance of Simple Storage Service (S3) hosted in a DDEV container.

Installing Drupal with DDEV

From the DDEV quickstart guide, we can follow these steps to set up a new Drupal 11 project:

mkdir my-drupal11-site && cd my-drupal11-site \
ddev config --project-type=drupal11 --docroot=web \
ddev composer create drupal/recommended-project:^11.0.0 \
ddev composer require drush/drush \
ddev drush site:install --account-name=admin --account-pass=admin -y \
ddev launch

Important:

At the time of writing this guide, the S3 Filesystem module requires drupal/core:^11.0.0. This means it is not compatible with Drupal 11.1, which is currently the latest core version. To address this, we’ve specified the ^11.0.0 version constraint in Composer, ensuring the installation of the latest 11.0.x version.

With these steps, you should now have a DDEV project running a clean Drupal installation with Drush.

Adding the LocalStack service to DDEV

Next, we need to create a file named docker-compose.localstack.yml in the root of the .ddev directory with the following content:

docker-compose.localstack.yml
services:
  localstack:
    container_name: ddev-${DDEV_SITENAME}-localstack
    image: localstack/localstack
    restart: always
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment:
      # LocalStack config: https://docs.localstack.cloud/references/configuration/
      - VIRTUAL_HOST=$DDEV_HOSTNAME
      - DEBUG=0
    ports:
      - 4566:4566
    volumes:
      - "./localstack/volume:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

  web:
    links:
      - localstack

(based on https://docs.localstack.cloud/getting-started/installation/#docker-compose)

Then, we must restart the DDEV project:

ddev restart

And we will be able to open a ssh connection to our new localstack container:

docker exec -ti ddev-drupal11-localstack-localstack bash

Following the instructions from the LocalStack S3 User Guide, we will now proceed to create a bucket:

awslocal s3api create-bucket --bucket sample-bucket

And we will get a positive feedback response:

{
    "Location": "/sample-bucket"
}

At this point, we now have a local AWS S3 instance up and running inside a container, accessible as localstack from the other DDEV project containers.

Important Caveat:

The community version of the LocalStack container does not include persistence. This feature is only available in the paid LocalStack Pro version. As a result, when using the community edition, all buckets and their content will be lost each time the localstack container is restarted. This limitation means we can only perform very basic tests with this setup.

Configuring EC2 Metadata Mock

Many AWS SDKs rely on a critical component available in every EC2 instance: a metadata server accessible at 169.254.169.254. Since this server won’t be available from our DDEV web container, we need to mock it using a tool provided by Amazon.

Amazon EC2 Metadata Mock

Fortunately, this tool is available as a Docker image, which allows us to create another container within our DDEV project to host it. To set this up, create a file named docker-compose.ec2-metadata-mock.yml inside the .ddev directory with the following content:

docker-compose.ec2-metadata-mock.yml
services:
  ec2-metadata-mock:
    container_name: ddev-${DDEV_SITENAME}-ec2-metadata-mock
    image: public.ecr.aws/aws-ec2/amazon-ec2-metadata-mock:v1.12.0
    restart: always
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment: []
    ports:
      - 1338:1338
    volumes: []

  web:
    links:
      - ec2-metadata-mock

The tool listens on port 1338 instead of the standard port 80, but we’ll address this difference later. More details will follow in the next sections.

Restart DDEV to deploy the new container:

ddev restart

After restarting, the EC2 Metadata Mock will be running on port 1338 and accessible as ec2-metadata-mock from other containers within the DDEV project.

We now can make a simple request from our web container to http://ec2-metadata-mock:1338/

ddev ssh

curl http://ec2-metadata-mock:1338/latest/meta-data/iam/security-credentials
baskinc-role

curl http://ec2-metadata-mock:1338/latest/meta-data/iam/security-credentials/baskinc-role
{
  "Code": "Success",
  "LastUpdated": "2020-04-02T18:50:40Z",
  "Type": "AWS-HMAC",
  "AccessKeyId": "12345678901",
  "SecretAccessKey": "v/12345678901",
  "Token": "TEST92test48TEST+y6RpoTEST92test48TEST/8oWVAiBqTEsT5Ky7ty2tEStxC1T==",
  "Expiration": "2020-04-02T00:49:51Z"
}

The Expiration value will trigger a warning later when validating the configuration in Drupal. However, this warning can safely be ignored.

For more information on making requests to the EC2 Metadata Mock, refer to the official documentation at https://github.com/aws/amazon-ec2-metadata-mock/tree/main?tab=readme-ov-file#making-a-request.

Patch the aws-sdk-php Composer package

The simplest way to make the AWS SDK recognize a custom EC2 Metadata Service location is by directly modifying its hardcoded IP address:

Change the value of the class constant Aws\Credentials\InstanceProfileProvider::DEFAULT_METADATA_SERVICE_IPv4_ENDPOINT to http://ec2-metadata-mock:1338

PHP
<?php
namespace Aws\Credentials;

use ...

/**
 * Credential provider that provides credentials from the EC2 metadata service.
 */
class InstanceProfileProvider
{
    ...
    const DEFAULT_METADATA_SERVICE_IPv4_ENDPOINT = 'http://ec2-metadata-mock:1338';

This way, the credentials provider accessed will be our EC2 Metadata Mock server.

You can make a composer patch to retain this configuration. See https://github.com/cweagans/composer-patches for more information.

Edit /etc/hosts file in the host computer

From the web container, the LocalStack container is accessible as localstack via http://localstack:4566. This setup enables internal communication between Drupal and LocalStack to function seamlessly.

However, we also need access to the bucket from the host computer (our PC), as the web browser navigating the Drupal site will be running locally and needs to access the files stored in the bucket.

So, add a new hostname to your localhost definition line inside your /etc/hosts file:

/etc/hosts
127.0.0.1 localhost localstack
127.0.1.1 MY-PC

# The following lines are desirable for IPv6 capable hosts
::1 ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

And that’s it! Both your web browser and the DDEV web container can now access the bucket via http://localstack:4566/sample-bucket.

Remember, we selected the “Use path-style endpoint” option in the S3 FileSystem configuration, which ensures compatibility with this setup.

Configuring Drupal

Install the module “S3 Filesystem”.

ddev composer require drupal/s3fs \
ddev drush en s3fs

And go to configure its settings at /admin/config/media/s3fs.

We will only have to fill these settings:

  • S3 Bucket Name: sample-bucket
  • Use a Custom Host: Checked
  • Hostname: http://localstack:4566
  • Use path-style endpoint: Checked

Now, you can go to the “Actions” tab or visit /admin/config/media/s3fs/actions and click on the “Validate configuration” button.

Despite the warning about the EC2 Metadata Mock credentials’ expiration date (set to the year 2020), the settings will still be validated correctly. This means that your Drupal configuration will function as expected, even with this warning present.

Make an image field use the new S3 storage

Go to /admin/structure/types/manage/article/fields/node.article.field_image so we can configure the image field in the default “Article” content type:

Then, change the Field Storage to “S3 File System” and click on “Save settings”.

From now on, any new images added to articles will be stored in the new LocalStack sample-bucket

Let’s now create a new Article with an image:

We can view the image thanks to the previously configured entry in /etc/hosts for the localstack hostname. This ensures that the image’s src attribute, pointing to:

https://[ddev-project-name].ddev.site/s3/files/styles/wide/s3/2024-12/image.webp?itok=_NXZWAN7

Which is redirected with a 302 to:

http://localstack:4566/sample-bucket/styles/wide/s3/2024-12/localstack.png.webp?itok=_NXZWAN7

On the other hand, we can also see that the image and its image styles are effectively stored in the bucket:

Bash
docker exec -ti ddev-drupal11-localstack-localstack bash

awslocal s3api list-objects --bucket sample-bucket

{
    "Contents": [
        {
            "Key": "2024-12/localstack.png",
            "LastModified": "2024-12-19T18:26:47.000Z",
            "ETag": "\"d7cbf11f95e7d277c8989d2e8a11267f\"",
            "Size": 11510,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        },
        {
            "Key": "styles/thumbnail/s3/2024-12/localstack.png.webp",
            "LastModified": "2024-12-19T18:26:47.000Z",
            "ETag": "\"34ab21d0998bd749a7cfe82085ca6f76\"",
            "Size": 780,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        },
        {
            "Key": "styles/wide/s3/2024-12/localstack.png.webp",
            "LastModified": "2024-12-19T18:26:55.000Z",
            "ETag": "\"4f4f644fc0a98604de82e58b720af7cb\"",
            "Size": 3212,
            "StorageClass": "STANDARD",
            "Owner": {
                "DisplayName": "webfile",
                "ID": "75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a"
            }
        }
    ],
    "RequestCharged": null,
    "Prefix": ""
}

Conclusion

Having a local implementation of AWS services is incredibly helpful for development purposes. This applies not only to the S3 service but also to the wide range of complex services supported by LocalStack. Using LocalStack can prevent unnecessary expenses—potentially significant ones—caused by mistakes during development.

In this guide, we focused solely on the S3 service and demonstrated the simplest configuration method. However, with a more advanced understanding of Docker Compose, it’s possible to design and implement a fully-featured local AWS cloud infrastructure to meet even the most complex development needs.

The post Bring the AWS Cloud to Your Desktop with LocalStack™, DDEV and Drupal appeared first on Víctor Dorado.

]]> https://www.victordorado.es/2024/12/19/bring-the-aws-cloud-to-your-desktop-with-localstack-and-drupal/feed/ 2 Improve your code quality from PHPStorm with PHP_CodeSniffer https://www.victordorado.es/2024/06/28/improve-your-code-quality-with-php-codesniffer-phpstan-eslint-stylelint-phpstorm-integration/ Fri, 28 Jun 2024 20:01:01 +0000 https://www.victordorado.es/?p=2284 Learn how to set up some quality tools with PHPStorm and DDEV: PHP_CodeSniffer, PHPStan, and others

The post Improve your code quality from PHPStorm with PHP_CodeSniffer appeared first on Víctor Dorado.

]]> Following a consistent code style in a project is crucial for making it easier for developers to read each other’s code. When the code feels familiar, cognitive effort can be redirected to more important tasks.

However, adhering to agreed-upon rules isn’t always easy. With many conventions to remember, we need tools to assist us. This is where our quality tools come in. They provide a powerful toolkit to ensure that our coding standards and style agreements are met. Furthermore, we can configure PHPStorm to use these tools, creating an integrated in-editor coding experience.

In this article we will be working on a Drupal project, but the process is applicable to any project type, as long as we will be using standard npm/yarn and Composer package management to get the tools.

Installing PHP_CodeSniffer

We will install it with Composer, as usual for many other PHP packages. We will also use a handy tool to ease the installation process.

#ddev composer require --dev squizlabs/php_codesniffer dealerdirect/phpcodesniffer-composer-installer drupal/coder

After that, as the documentation states (https://packagist.org/packages/dealerdirect/phpcodesniffer-composer-installer) we must ensure the following config is present in our composer.json:

{
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    }
}

If we are using Composer < 2.2 it won’t and we will have to add it with the following command:

# composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

After that, we will let the magic happen:

# composer install

Now, we can execute the phpcs command inside our DDEV web container:

# ddev exec phpcs --version
Registering sniffs in the PEAR standard... DONE (28 sniffs registered)
PHP_CodeSniffer version 3.10.1 (stable) by Squiz and PHPCSStandards

Note that PHP_CodeSniffer says something about a “standard”. PHP_CodeSniffer checks our code against one of various possible “standards”, and there are some of them bundled by default with it. The default standard that will be used is the “PEAR” one.

But, for a Drupal project (a website, a theme, a contrib module… etc.), we must use a special crafted standard called “Drupal”, that has all the Drupal community-agreed coding standards. Thanks to our previously installed dealerdirect/phpcodesniffer-composer-installer, we can see that the standards “Drupal” and “DrupalPractice” are installed:

# ddev exec phpcs -i
The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, Drupal, DrupalPractice, VariableAnalysis and SlevomatCodingStandard

(DrupalPractice is a more exhaustive standard that checks not only the coding style used, but also some best practices for Drupal development).

In this article, we will focus in the use of PHPCS through the UI, that is what will make a more “realtime” development experience. Using phpcs from the command line is harder, and is often only used by cli scripts, like in CI environment QA tests, or s Git precommit hook in a local development environment.

Integrating PHP_CodeSniffer with PHPStorm

PHPStorm has friendly configuration dialogs for some popular quality tools, and one of them is PHPCS.

Is highly recommended executing PHPCS inside our DDEV container, in order to keep consistency with our project’s PHP version and configuration instead of relying on our own machine config. To do so, first we must have a PHPStorm “DDEV” PHP interpreter (check my previous article PHPUnit up and running with Drupal, DDEV and PHPStorm to know how to accomplish it).

Then, go to Settings, under the “PHP – Quality Tools” section, and open the first accordion, setting its configuration and options as follows:

Notice that Drupal Core uses a different more relaxed standard. If you are going to develop for core you should set the coding standard to “Custom” and point to your project’s <drupal-root>/core/phpcs.xml.dist

You can also configure some additional inspection settings in the “Editor – Inspections” menu:

Once configured, edit any file and PHPStorm will automatically execute PHPCS, showing the warnings and errors in that file.

Conclusion

Maintaining a consistent code style in our projects is made easier with these supportive tools. Including them in every developer’s toolkit is highly beneficial.

The post Improve your code quality from PHPStorm with PHP_CodeSniffer appeared first on Víctor Dorado.

]]> PHPUnit up and running with Drupal, DDEV and PHPStorm https://www.victordorado.es/2024/03/18/phpunit-up-and-running-with-drupal-ddev-and-phpstorm/ Mon, 18 Mar 2024 00:01:03 +0000 https://www.victordorado.es/?p=2229 Getting PHPStorm, DDEV, Drupal and PHPUnit to work together is not a trivial task. Read this guide to get up and running!

The post PHPUnit up and running with Drupal, DDEV and PHPStorm appeared first on Víctor Dorado.

]]> There are some articles out there about this topic: like the official DDEV docs PHPStorm – Enabling PHPUnit or Matt Glaman’s Running Drupal’s PHPUnit test suites on DDEV, but I haven’t found it so easy to figure it out. So, I’m writing this guide, although knowing that one day it will become obsolete, like it always have been with guides and new versions of things 🙂

First step: enabling DDEV integration plugin for PHPStorm

DDEV has a PHPStorm plugin that eases a lot working with DDEV. One of the great things DDEV’s plugin does is creating a CLI interpreter that executes PHP code inside the web container. This will be the cornerstone of our setup.

Setting DDEV as the project’s CLI interpreter and the Test framework interpreter

Under Settings -> PHP section, we can now select the DDEV CLI interpreter:

If you don’t see the interpreter, check that you have a Docker connection added in Build, Execution, Deployment -> Docker:

And check that “Use Compose V2” is enabled under the Tools subsection:

Now, we must go to PHP -> Test Frameworks and add a new one that uses the DDEV CLI interpreter:

We must also set a custom Default configuration file named phpunit.xml and located in our project’s root directory. DDEV’s CLI interpreter runs inside the web docker container, so we must set the path as it’s seen inside the container: /var/www/html/phpunit.xml. (this file doesn’t exist yet, we will create it later).

Now, we have to tell PHPStorm to run this project’s tests with this new test framework. Go to Run -> Edit configurations menu and clear any configuration you may find here.

Then, click on Edit configuration templates… -> PHPUnit and set DDEV as the Command Line Interpreter:

Creating project’s PHPUnit configuration file

Copy core’s PHPUnit configuration file /web/core/phpunit.xml.dist to /phpunit.xml, and edit it as follows:

<?xml version="1.0" encoding="UTF-8"?>

<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         bootstrap="web/core/tests/bootstrap.php"
         colors="true"
         beStrictAboutTestsThatDoNotTestAnything="true"
         beStrictAboutOutputDuringTests="true"
         beStrictAboutChangesToGlobalState="true"
         failOnWarning="true"
         printerClass="\Drupal\Tests\Listeners\HtmlOutputPrinter"
         cacheResult="false"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
  <php>
    <ini name="error_reporting" value="32767"/> <!-- 32767 = E_ALL. -->
    <ini name="memory_limit" value="-1"/>
    <env name="SIMPLETEST_BASE_URL" value="http://my-project.ddev.site"/>
    <env name="SIMPLETEST_DB" value="mysql://db:db@db:3306/test"/>
    <env name="BROWSERTEST_OUTPUT_DIRECTORY" value=""/>
<!--    <env name="SYMFONY_DEPRECATIONS_HELPER" value="weak"/>-->
  </php>

  <testsuites>
    <testsuite name="unit">
      <directory>web/modules/custom/*/tests/src/Unit/</directory>
    </testsuite>
    <testsuite name="kernel">
      <directory>web/modules/custom/*/tests/src/Kernel/</directory>
    </testsuite>
    <testsuite name="functional">
      <directory>web/modules/custom/*/tests/src/Functional/</directory>
    </testsuite>
    <testsuite name="functional-javascript">
      <directory>web/modules/custom/*/tests/src/FunctionalJavascript/</directory>
    </testsuite>
  </testsuites>

  <listeners>
    <listener class="\Drupal\Tests\Listeners\DrupalListener">
    </listener>
    <!-- The Symfony deprecation listener has to come after the Drupal listener -->
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
    </listener>
  </listeners>

  <coverage>
    <include>
      <directory suffix=".php">web/modules/custom/*/src</directory>
    </include>
  </coverage>

</phpunit>

These are all the customizations that have been made:

1. Adjust the boostrap path to core’s bootstrap

bootstrap="web/core/tests/bootstrap.php"

2. Set site URL and database connection details (for Kernel, Functional… etc. tests). Note that PHPUnit will be executed inside the web container, so we must set “db” and port 3306 as our database host, as it is seen from the web container. We also set the testing database name to “test”, that is the convention.

<env name="SIMPLETEST_BASE_URL" value="https://my-project.ddev.site"/>
<env name="SIMPLETEST_DB" value="mysql://db:db@db:3306/test"/>

3. Finally, we adjust all test suites to only execute tests from our custom modules by default, if we execute phpunit without file parameters nor filters.

<testsuite name="unit">
  <directory>web/modules/custom/*/tests/src/Unit/</directory>
</testsuite>
<testsuite name="kernel">
  <directory>web/modules/custom/*/tests/src/Kernel/</directory>
</testsuite>
...

Installing PHPUnit

As simple as installing these packages with Composer

# ddev composer require --dev \
  phpunit/phpunit \
  phpspec/prophecy-phpunit \
  symfony/phpunit-bridge \
  dmore/chrome-mink-driver \
  behat/mink-browserkit-driver \
  behat/mink-selenium2-driver \
  mikey179/vfsstream
  • phpunit/phpunit – The PHPUnit core package.
  • phpspec/prophecy-phpunit – The Prophecy mocking system. In a lot of tests it is used instead of PHPUnit Mock Object Framework, the PHPUnit standard.
  • symfony/phpunit-bridge – Bridges the gap between Symfony and PHPUnit.
  • dmore/chrome-mink-driver – Required for some Kernel nad Functional tests.
  • behat/mink-browserkit-driver – Required for some Functional tests.
  • mikey179/vfsstream – Some tests make use of this virtual filesystem mocker.

Configuring DDEV Selenium Standalone Chrome

This config is necessary to execute Javascript and FunctionalJavascript Drupal tests. PHPUnit needs a headless Chromium browser to control and to send commands to. That’s what this DDEV addon provides.

Follow the instructions in https://github.com/ddev/ddev-selenium-standalone-chrome:

# ddev get ddev/ddev-selenium-standalone-chrome

Then, update your .ddev/config.selenium-standalone-chrome.yaml and set the local domain for your DDEV project, making sure you set it as http:// and not https:// (I got an “invalid cookie domain” error when I did).

#ddev-generated  <- REMOVE THIS LINE

...

- SIMPLETEST_BASE_URL=http://my-project.ddev.site

...

- DRUPAL_TEST_BASE_URL=http://my-project.ddev.site

...

- DTT_BASE_URL=http://my-project.ddev.site

Then, restart DDEV:

# ddev restart

Executing tests from the command line

If we want being able to execute our tests easily from outside the web container, we must create the file /.ddev/commands/web/phpunit with this content:

#!/bin/bash

phpunit "$@"

And now, outside the web container, we can do:

# ddev phpunit
# ddev phpunit --testsuite <name>

Executing tests from PHPStorm

From PHPStorm’s interface, we can go to any test case class and use the GUI to run its tests, either all at once or one by one, simply clicking on the run icons next to the class and test method definitions:

We can even right click on any directory in the project’s explorer and click on “Run (tests PHPUnit)” and all tests in that directory will be executed. This is very convenient when we want to debug only a test method or execute only one type of tests inside a module, for example.

Conclusion

Getting PHPStorm, DDEV, Drupal and PHPUnit to work together is not a trivial task. Although DDEV’s PHPStorm plugin eases a bit the task, we have yet to wire all the things correctly.

The post PHPUnit up and running with Drupal, DDEV and PHPStorm appeared first on Víctor Dorado.

]]> Debug your Drupal code with PHPStorm, DDEV and Xdebug https://www.victordorado.es/2024/03/17/debug-your-drupal-code-with-phpstorm-ddev-and-xdebug/ Sun, 17 Mar 2024 17:37:16 +0000 https://www.victordorado.es/?p=2186 Debugging goes next level when it's done with a tool like Xdebug and through a debugging GUI like PHPStorm has.

The post Debug your Drupal code with PHPStorm, DDEV and Xdebug appeared first on Víctor Dorado.

]]> How would have been our lives without debuggers? We would have been spreading print_r, echo and the like everywhere. Our world got better with tools like Krumo or (in the case of Drupal) with dpm(), but nothing like a real [IDE + debugger] couple like [PHPStorm + Xdebug].

If you also add DDEV and its docker containers to the mix, it’s not easy to get all pieces working, without a proper recipe. This article aims to be that recipe.

Preparing DDEV’s web container

DDEV automatically adds two environment variables to its .ddev-docker-compose-base.yaml file:

PHP_IDE_CONFIG=serverName=${DDEV_SITENAME}.${DDEV_TLD}
DRUSH_ALLOW_XDEBUG=1

Mind the serverName because we will need it later, when configuring a server in PHPStorm.

Now, we must config the Xdebug PHP extension. Create a new directory .ddev/php/ and create a file called xdebug.ini inside it, with this content.

xdebug.client_port = 9000
xdebug.idekey = PHPSTORM
xdebug.mode = develop,debug
xdebug.start_with_request = yes

I like to set xdebug.start_with_request=yes and turn on and off the web contaniner’s xdebug PHP extension with ddev xdebug on and ddev xdebug off. You could set xdebug.start_with_request=no and play with a browser switch like Xdebug Helper, but this won’t have effect on drush commands.

After that, we have to restart DDEV’s web container:

# ddev restart

Configuring PHPStorm

Now, we must create a new PHP server under Settings -> PHP -> Servers. Recall the server name we saw in DDEV’s config: it was ${DDEV_SITENAME}.${DDEV_TLD}, that translates to my-project.ddev.site if your DDEV project is named my-project.

We need to set path mappings for the webserver docroot directory. A path mapping “maps” a real directory path in your filesystem with a directory inside the DDEV docker web container. In our case, a DDEV drupal project has its web server’s document root in /var/www/html/web, so we have to set this mapping:

  • /path/to/your/project/web -> /var/www/html/web

However, I recommend also adding this mapping to be able to debug vendor code.

  • /path/to/your/project/vendor -> /var/www/html/vendor

With these mappings, PHPStorm now knows how to map between the same file as it’s seen inside/outside DDEV’s web container.

After that, to be sure everything is ok, I recommend checking and configuring the Xdebug installation under PHP -> Debug:

First, click on the “Validate” link:

In the next screen configure the docroot directory as it’s seen by PHPStorm (your real machine path to the web directory inside your project directory) and the URL where the project’s docroot will be accesible. Then, click on “Validate”.

I strongly recommend unchecking these two “Force break” checkboxes, because we don’t want the execution to be paused if we don’t set or don’t reach a breakpoint. I remember myself waiting a drush command to finish unaware that the execution was paused, because of this.

So far, we have configured DDEV and PHPStorm to “connect” between them and our next step will be to set a breakpoint. For example, we can break on the handle() call that Drupal\Core\DrupalKernel class does on every page load.

Click next to the line number and a red dot will appear. This is our breakpoint. The PHP execution will stop here until we let it continue.

Remember to enable xdebug PHP extension on DDEV’s web container with

# ddev xdebug on

And to tell PHPStorm to listen to incoming debug connections with the Listen icon icon.

Now, reload any page in your browser and you will view a system notification letting you know that PHPStorm requires your attention. Go for it and you will see the breakpoint’s line highlighted and a panel where you can explore all the variables in it’s scope.

You can browse the variables panel and deep dive into the tree structures. This is VERY useful, specially when debugging a framework like Drupal that has many nesting levels on its variables.

You can also select any piece of code, right click on it and click on “Evaluate expression” and you could test it inside that paused execution state. You can even write directly your own expressions.

You can continue the execution step-by-step (step over, F8), even traveling inside method calls (step into, F7), or continue the execution until the next breakpoint (or the same breakpoint if it’s reached again)

Conclusion

Debugging goes next level when it’s done with a tool like Xdebug and through a debugging GUI like PHPStorm has.

The post Debug your Drupal code with PHPStorm, DDEV and Xdebug appeared first on Víctor Dorado.

]]>