Preparing for Drupal 8: PSR-4 Autoloading

Note: This information applies to Drupal 8+ (including Drupal 9 and 10).

As a developer, one of the first new concepts you're going to need to understand for Drupal 8 is PSR-4. Or, the PHP Framework Interoperability Groups (php-fig), Proposal for Standard Request number 4 (PSR-4). A lot of fancy naming, abbreviations and numbers for a pretty simple idea. Allow your PHP classes to be automatically discovered and loaded by following a convention for class namespace and file/directory naming.

Drupal 8 implements the PSR-4 standard and makes use of it to discover code, and to load the code on an as-needed basis rather requiring every single file in Drupal's code base to be loaded for every request. This has all kinds of great implications.

Pro-tip: Drupal 8 initially used the PSR-0 standard but switched to PSR-4 for most everything to help simplify the developer experience. Change record

For starters, if you follow the standard, you can just do this:

$object = new MyAwesomeClass();

Instead of:

require_once 'path/to/my/file/myawesomemodule.class.inc';
$object = new MyAwesomeClass();  

Or the more Drupal 7 appropriate:

module_load_include('inc', 'myawesomemodule', 'myawesomemodule.class');
$object = new MyAwesomeClass();  

I know it's only one line of extra code. But not having to know where a file lives and/or how to include it is absolutely glorious.

This system uses the PHP Autoloading Classes feature, which acts as a registry of sorts for classes. But it doesn't just load all the known files for every request, it's actually smart enough to defer loading of the file that contains a class until someone actually instantiates an instance of that class. This means less code loaded per-request, which reduces PHP's overall memory footprint and helps increase the speed of an application.

In Drupal 7, we have an approximation of this system in that, you can add a line to your .info file and Drupal will scan the listed files for class definitions and then add them to its database based registry —and it works. But, PSR-4 is more efficient and more like what our friends in the rest of the PHP world are doing. By using this system, the Drupal community helps pave the way for greater sharing between frameworks.

Implementing PSR-4

Okay, sold? Here's what you need to know about PSR-4 for Drupal module development.

Let's assume we've got a module named Markus. Each Drupal module has a namespace that corresponds to that module's name:

Drupal\markus

The module's namespace is mapped to the src/ directory for the module:

Drupal\markus → modules/markus/src/

Anything following the module's namespace maps directly to the directory and file structure:

Drupal\markus\Clothes\Pants → modules/markus/src/Clothes/Pants.php

Want to do something with Markus's pants in your code? Simply instantiate a copy of the class using its fully qualified namespace—anywhere in your code—and Drupal will take care of locating the file and including it.

$pants = new Drupal\markus\Clothes\Pants();
$pants->putOn();

Would use: modules/markus/src/Clothes/Pants.php

/**
 * @file
 * Pants object.
 */

namespace Drupal\markus\Clothes

class Pants extends Wearables {
  public function putOn() {
    // code goes here ...
  }
}

You can read more about PSR-4 and namespace resolution in Drupal in the handbook.