Drupal: Tooling

Things I wish I'd known before I started

In: Drupal · Web Development

So you’ve decided you want to use Drupal for your project and you’ve reached a point where you have to start writing some code. It is very easy at this point to become lost and frustrated because there are many things you need to know that aren’t obvious. In summary:

  • Use an IDE
  • Develop on your own machine with DDEV
  • Get familiar with Git
  • Use the ‘GitOps’ workflow
  • It can be tricky to get Xdebug working but it will be worth it. Persevere.
  • Documentation is available from several sources
  • Twig appears

Let’s break this down.

VSCode

If you’re reading this thinking “My IDE is better”, you’re not the audience for this post. VSCode is free, widely used, and has a lot of very helpful extensions:

PHP Intelephense

The Intelephense extension provides autocompletion based on the methods and properties of classes in your project. Suppose you’re writing a module to calculate shipping costs and you have the $order variable at hand. In the past this would have simply been an array that you can print_r to inspect, but now it’s a mysterious, impenetrable ‘object’. You can type $order-> and Intelephense will suggest the available methods. Without this extension you would have to find the order object’s class definition in the commerce module’s source code and read through it to find out what you can do with it.

Sometimes it’s useful to have a look at the source code of a class anyway, and this is made much quicker by the ‘Go to Definition’ feature. You can right-click on a variable and select ‘Go to Definition’. If the variable is an object, this will take you to the class definition.

Twig

Twig is a templating engine, and is used in other PHP CMSs such as Craft. It takes some getting used to, and the first step is to install an extension that provides syntax highlighting and autocompletion. There are a few options, but I recommend installing both of these:

Copilot

AI won’t be able to do everything for you (yet) but it is useful in two ways:

  • It can speed up the simple things for you
  • It can suggest avenues of investigation

Local Development with DDEV

General DDEV Commands:

  • ddev init: Create a new project
  • ddev start: Start the project
  • ddev describe: Show information about the project, including the project URLs and the Mailpit URL
  • ddev launch: Open the project in a browser
  • ddev ssh: SSH into the project container
  • ddev mysql: SSH into the project database
  • ddev stop: Stop the project
  • ddev restart: Restart the project
  • ddev drush <command>: Run a Drush command
  • ddev composer <command>: Run a Composer command
  • ddev xdebug: Enable XDebug, assuming your VS Code launch.json is set up correctly

DDEV Database Snapshots

  • ddev snapshot -n <snapshot-name>: Create a snapshot of the current state of the project
  • ddev snapshot restore -n <snapshot-name>: Restore a snapshot
  • ddev snapshot list: List all snapshots

DDEV Platform.sh

  • ddev pull platform: Pull the current state of the Platform.sh environment
  • ddev push platform: Push the current state of the project to Platform.sh. Useful when first copying a site from your local environment to your staging server. You can transfer just the database by running ddev platform push --skip-files, or just the files by running ddev platform push --skip-db.

Twig

To the uninitiated, Twig appears to be completely opaque. The variable you want is never available and it’s impossible to tell which template file is rendering the part of the page you want to change. There are three things you can do to make this easier:

  • Enable ‘Twig debug mode’ at /admin/config/development/settings
  • Use the dump() function to find out what variables are available in a template. Adding {{ dump() }} to the top of a template will print out all the variables that are available to that template. You can then drill into these by passing them as arguments to dump(). For example, {{ dump(content) }} will show you all the variables that are available within the content variable.
  • Use preprocess functions to add variables to the template

Even armed with this knowledge you will probably reach the point of exasperation several times while trying to theme your site.

Do you want to render a block or a view in a template? How about some implement different templates for the different view modes of an entity? Customise a form’s markup?

All of these basic site-building tasks require contrib modules. You’re also going to get familiar with hook_template_suggestion_alter.

Twig Tweak

Twig Tweak provides some succinct Twig tokens for common tasks such as rendering blocks, views, entities, files and links within a template. There is an excellent cheat sheet that lists all the things you can do with it.

Why some of these are not in core is beyond me.

Form Dazzle

This module has two key superpowers, among others:

  1. Exposes the hidden theme suggestion for the content of every form. Without Form Dazzle, only the form wrapper template is shown by Twig Debug. With Form Dazzle installed, the actual form template suggestion is shown, allowing you to render each form element individually within a template.

  2. Additional template suggestions for form elements, including the form element’s type and name, as well as the form ID. This allows you to target specific form elements with custom markup.

These two features combined make it possible to completely customise the markup of any form.

Template suggestions

Another source of pain for site builders is the lack of template suggestions. Some of the conspicuously missing ones are:

  • Page templates per node type
  • Taxonomy term templates per view mode
  • User templates per role
  • Block templates per region
  • Field templates per view mode

The Twig Template Suggester module takes care of these, and more.

Xdebug

Follow this DDEV documentation to configure Xdebug in VSCode.

Documentation

The official documentation for Drupal can be found on drupal.org. There are several sections that are worth exploring:

Documentation
https://www.drupal.org/docs
The main index of official documentation. Includes information on topics that even experienced site builders may not be familiar with; translation, cron, accessibility, caching, updating, upgrading, and more.
Developer Documentation
https://www.drupal.org/docs/develop
The index of official documentation aimed at developers.
Developer Documentation: Drupal APIs
https://www.drupal.org/docs/develop/drupal-apis
These API documentation pages are far more useful than the API Reference.
API Reference
https://api.drupal.org/api/drupal
The API reference is auto-generated from the source code; it often turns up in search results but isn’t very helpful.

Unofficial sources of documentation include:

Drupal Answers
https://drupal.stackexchange.com
Stack Exchange site. An excellent source of information.
Drupalize.me
https://drupalize.me
Guides and tutorials on a broad range of topics. Subscription based, with some free articles
Lullabot
https://www.lullabot.com/resources
Free articles

Devel module

Debugging Twig with template suggestions

Exposing Twig variables with dump()

Adding to Twig variables with preprocess functions (for any template)

Form Dazzle