Last updated August 19, 2015. Created on December 14, 2013.
Edited by Nicolaj, HongPong, rakesh.gectcr, Fabianx. 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. 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/
    • css/
    • js/
    • src/
      • Controller/
        • VegetableController.php → class Drupal\vegetable\Controller\VegetableController
      • Form/
        • VegetableForm.php → class Drupal\vegetable\Form\VegetableForm
      • Entity/
        • Tomato.php → class Drupal\vegetable\Entity\Tomato
        • Cucumber.php → class Drupal\vegetable\Entity\Cucumber
      • tests/
        • TomatoTest.php → class Drupal\Tests\vegetable\Entity\TomatoTest
        • CucumberTest.php → class Drupal\Tests\vegetable\Entity\CucumberTest
        • VegetableManagerTest.php → class Drupal\Tests\vegetable\VegetableManagerTest
      • templates/
      • 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?

DragonEye’s picture

Wich means that if the directoryname is lowercase you need to use lower case in your namespaces... that doesn't make it easier.

balagan’s picture

Is the example correct?

TomatoTest.php → class Drupal\Tests\vegetable\Entity\TomatoTest
CucumberTest.php → class Drupal\Tests\vegetable\Entity\CucumberTest

The paths above contradict with:

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

I am not sure Entity is needed in these paths