Drupal Coding Standards

if ($condition) {
  doSomething();
}
else {
  doOther();
}

try {
  riskyOperation();
}
catch (SuspendQueueException $e) {
  throw $e;
}
catch (\Exception $e) {
  handleError($e);
}

Docblock requirements

Every class, method, function, and constant MUST have a docblock.

WRONG: Class or public method without docblock:

class MyController extends ControllerBase {
  public function build() {
    return ['#markup' => 'Hello'];
  }
}

RIGHT: All classes and public methods get docblocks with @param/@return:

/**
 * Provides a page for displaying custom content.
 */
class MyController extends ControllerBase {

  /**
   * Builds the page content.
   *
   * @return array
   *   A render array.
   */
  public function build() {
    return ['#markup' => 'Hello'];
  }

}

Hook implementation docblocks

WRONG: Hook with @param/@return tags:

/**
 * Implements hook_cron().
 *
 * @return void
 */
function my_module_cron() {

RIGHT: Hook implementations use ONLY the Implements line -- no @param or @return:

/**
 * Implements hook_cron().
 */
function my_module_cron() {

@file docblocks

@file docblocks are ONLY for procedural files (.module, .install, .theme).

WRONG: @file in a class file:

<?php
/**
 * @file
 * Contains \Drupal\my_module\Controller\MyController.
 */
namespace Drupal\my_module\Controller;

RIGHT: No @file in class files. Only in procedural files:

<?php
/**
 * @file
 * Hook implementations for the My Module module.
 */

Nullable parameter types

When a typed parameter defaults to NULL, the type MUST use ? nullable syntax.

WRONG: Implicit nullable (deprecated PHP 8.4, error in PHP 9):

public function init(ViewExecutable $view, DisplayPluginBase $display, array $options = NULL) {

RIGHT: Explicit ?type nullable:

public function init(ViewExecutable $view, DisplayPluginBase $display, ?array $options = NULL) {

Critical when overriding parent methods with nullable parameters.

General formatting

• One class per file -- each .php in src/ has exactly one class/interface/trait
• Short array syntax -- [] not array()
• Trailing commas in multi-line arrays
• Single blank line between methods
• No closing ?> tag
• Two blank lines before class declaration (after use statements)
• Space after control keywords -- if (, foreach (, while (

DrupalPractice service patterns

The DrupalPractice phpcs standard flags service anti-patterns. The GlobalDrupal sniff fails any \Drupal:: static call inside a class file under src/.

WRONG: \Drupal::service(), \Drupal::entityTypeManager(), or any \Drupal:: call in controllers, forms, services, or list builders:

class MyController extends ControllerBase {
  public function build() {
    $nodes = \Drupal::entityTypeManager()->getStorage('node')->loadMultiple();
  }
}

RIGHT: Inject via create() + constructor. \Drupal:: is ONLY valid in .module procedural files:

class MyController extends ControllerBase {
  public function __construct(
    protected EntityTypeManagerInterface $entityTypeManager,
  ) {}
  public static function create(ContainerInterface $container) {
    return new static($container->get('entity_type.manager'));
  }
}

This applies to ALL classes: controllers, forms, list builders, event subscribers, services. Any class that can implement ContainerInjectionInterface MUST inject dependencies.