Last updated November 27, 2014. Created on December 14, 2013.
Edited by Fabianx, rakesh.gectcr, pferlito, xjm. Log in to edit this page.


Drupal 8 implements the PSR-4 standard for package-based PHP namespace autoloading by the PHP Framework Interoperability Group.

Example vegetable.module directory structure:

  • modules/vegetable/
    • css/
    • js/
    • src/
      • Controller/
        • VegetableController.php → class Drupal\vegetable\Controller
      • Form/
        • VegetableForm.php → class Drupal\vegetable\Form
      • Entity/
        • Tomato.php → class Drupal\vegetable\Entity\Tomato
        • Cucumber.php → class Drupal\vegetable\Entity\Cucumber
      • VegetableManager.php → class Drupal\vegetable\VegetableManager
    • templates/
    • tests/
      • src/
        • Entity/
          • TomatoTest.php → class Drupal\Tests\vegetable\Entity\TomatoTest
          • CucumberTest.php → class Drupal\Tests\vegetable\Entity\CucumberTest
        • VegetableManagerTest.php → class Drupal\Tests\vegetable\VegetableManagerTest
      • fixtures/
        • weather-data.json
    • vegetable.routing.yml
    • vegetable.module


  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\Tomatomodules/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 indicates the base namespace that maps to a registered base directory, in which PHP files will be looked up:

  Base namespace Base directory Contains
Drupal core Drupal\Component\ core/lib/Drupal/Component/ Components that are 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\ Diff\DiffEngine core/lib/Drupal/Component/ Diff/DiffEngine.php
Drupal\node\ Entity\Node core/modules/node/src/ Entity/Node.php
Drupal\views_ui\Tests\ Form\Ajax\RearrangeFilterTest core/modules/views_ui/tests/src/ Form/Ajax/RearrangeFilterTest.php
Drupal\devel\ Plugin\Block\DevelSwitchUser modules/contrib/devel/src/ Plugin/Block/DevelSwitchUser.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/DiffEngine.php.

Looking for support? Visit the forums, or join #drupal-support in IRC.


dustinmoris’s picture

In Drupal 7 I can have a module inside another module. Is this still the case in Drupal 8 and how would I namespace classes inside the sub module?

Another thing I can do in Drupal 7 is to create sub folders inside the modules folder to group my modules.

--- / all
--- / --- / modules
--- / --- / --- / Collection_Alpha
--- / --- / --- / --- / module_a
--- / --- / --- / --- / module_b
--- / --- / --- / Collection_Beta
--- / --- / --- / --- / module_x
--- / --- / --- / --- / module_y

Is this still possible in Drupal 8? If yes, how would I have to namespace my classes so the autoloader can resolve it to the correct folder structure?

e.g.: Drupal\Collection_Alpha\module_a\myClass1 ?



I raised the question on stackexchange as well and found all my answers here:

Mark_L6n’s picture

As of D8 beta 7, there appear to be differences in using a leading backslash to begin PSR-4 namespaced class names (i.e. Drupal or \Drupal) :

  • Empty:
    • This documentation
    • Core pages I have looked at.
  • Leading backslash:

Has D8 been programmed to accept PSR-4 namespaced class names that begin with either Drupal or \Drupal, or are these bugs yet to be worked out?