PSR-4 namespaces and autoloading in Drupal 8

Last updated on
3 April 2017

Summary
Drupal 8 implements the PSR-4 standard for package-based PHP namespace autoloading by the PHP
Framework Interoperability Group. Upgrading Drupal 7 modules to Drupal 8 will require using PSR-4
standards. See more background info on Drupal 8 development here, for PSR-4 in context.

Example vegetable.module directory structure:

 modules/vegetable/
o css/
o js/
o src/
 Controller/
 VegetableController.php → class
Drupal\vegetable\Controller\VegetableController
 Form/
 VegetableForm.php → class Drupal\vegetable\Form\VegetableForm
 Plugin/
 Block/
 VegetableBlock.php → class
Drupal\vegetable\Plugin\Block\VegetableBlock
 Entity/
 Tomato.php → class Drupal\vegetable\Entity\Tomato
 Cucumber.php → class Drupal\vegetable\Entity\Cucumber
 tests/
 TomatoTest.php → class Drupal\vegetable\Tests\Entity\TomatoTest
 CucumberTest.php → class Drupal\vegetable\Tests\Entity\CucumberTest
 VegetableManagerTest.php → class
Drupal\vegetable\Tests\VegetableManagerTest
 templates/
 fixtures/
 weather-data.json
o tests/
 src/
 Functional/
 Kernel/
 Unit/
 TomatoTest.php → class Drupal\Tests\vegetable\Unit\TomatoTest
 Traits/
 VegetableTestTrait.php → trait
Drupal\Tests\vegetable\Traits\VetegableTestTrait
o vegetable.info.yml
o vegetable.routing.yml
o vegetable.module

Explanation:

1. Each module has a namespace that corresponds to its module name.

 Here: Drupal\vegetable\

2. The module's namespace is mapped to the ./src/ folder in the module directory.

Here: Drupal\vegetable\ → modules/vegetable/src/

3. Anything after the module namespace directly maps to the directory and file structure in the ./src/
folder.

Here: Drupal\vegetable\Entity\Tomato → modules/vegetable/src/Entity/Tomato.php

The identical logic applies to PHPUnit tests contained in ./tests/src/.

Namespace resolution
The namespace of all Drupal core components, as well as contributed modules, begins with Drupal\

The first parts of a namespaced class name indicate the base namespace that maps to a registered base
directory, in which PHP files will be looked up:

Base namespace Base directory Contains

Drupal Drupal\Component\ core/lib/Drupal/Component/
Components that are
core reusable outside of Drupal.
Drupal\Core\ core/lib/Drupal/Core/
Components that are
specific to Drupal.
Drupal\Tests\ core/tests/Drupal/Tests/
PHPUnit tests of core
components.
Modules Drupal\$modulename\ modules/$modulename/src/ Main integration files.
Drupal\$modulename\Tests\ modules/$modulename/src/Tests/
Simpletest tests of the
module.
Drupal\Tests\$modulename\ modules/$modulename/tests/src/
PHPUnit tests of the
module.

For modules, $modulename is the unique machine name of the module, which consists of lowercase
characters and underscores.

The remaining part of a namespaced class name indicates the relative path within the base directory: each
PHP namespace separator (\) is replaced with a directory separator (/) and the .php extension is appended:

Base namespace Relative class name → Base directory Relative file path
Drupal\Component core/lib/Drupal/Componen
Diff\DiffEngine → Diff/DiffEngine.php
\ t/
Drupal\node\ Entity\Node → core/modules/node/src/ Entity/Node.php
Drupal\Tests\views Form\Ajax\RearrangeFilte core/modules/views_ui/test Form/Ajax/RearrangeFilterTe
→
_ui\ rTest s/src/ st.php
Plugin\Block\DevelSwitc Plugin/Block/DevelSwitchUs
Drupal\devel\ → modules/contrib/devel/src/
hUser er.php

Each PHP class, interface, or trait lives in a separate PHP file.

For example, the class Drupal\Component\Diff\DiffEngine is defined in
core/lib/Drupal/Component/Diff/Engine/DiffEngine.php.