Drupal

In Drupal 8, the majority of your module code will be in object-oriented classes. Unlike Drupal 7, there are particular rules for creating new classes due to the PSR-0 standard. The rules are simple, but new to Drupal

Step 1: Decide on a namespace name.

• The name should be descriptive, but as brief as possible.
• The name cannot contain underscores.
• Namespaces can nest and are separated by a backslash (\).
• The parent namespace path is always \Drupal\<your_module_short_name>.

Namespaces are used to prevent naming collisions in PHP. Two classes could have the same name as long as they exist in different namespaces. Namespaces also can nest in the same way that directories nest. In Drupal 8, the parent namespace is always “\Drupal”, and for your module classes it’s always “\Drupal\<your_module_short_name>”.

Deciding on a namespace name is part art, part plagiarism. Many Drupal modules will have namespaces such as:
\Drupal\module_name\Entity
\Drupal\module_name\Form

Step 2: Create the directory structure.

• Create the following directory path if you haven’t already:
  <your_module_root_directory>/lib/Drupal/<your_module_short_name>
• Create your namespace directories under the above path.
• Your namespace path should correspond the directory path under the lib directory.

Part of the PSR-0 standard specifies how use nested namespaces. The goal behind this is autoloading. By creating your classes along a regular paths, PHP can locate your class files automatically and load them without needing to use an include or require statement. This reduces the overall memory footprint.

The most important part to remember is that your namespace path (for example, \Drupal\flag\Plugin\FlagType) must correspond exactly to a directory structure under the lib directory in your module root directory (<your_module_directory>/lib/Drupal/flag/Plugin/FlagType).

Step 3: Decide a new class name.

• Try to keep the name brief, yet descriptive.
• Class names cannot contain spaces, special characters, and underscores.
• Do not use underscores. This cannot be stressed enough.
• Avoid numbers in your class names if possible.

Underscores have a special significance in PSR-0. Some autoloaders interpret underscores as directory separators. This can cause a lot of frustration when classes do not autoload correctly. If you do need a way to separate words within your class names, use CamelCase: Capitalize the first letter of each word in the class name.

Step 4: Create the class file.

• Create a new, empty file in the namespace directory.
• Name the file <your_class_name>.php
• The file must have a *.php extension.

In earlier versions of Drupal, it was considered best practice to avoid the *.php file extension. Instead, additional files to be included were given the *.inc extension. Drupal 7 loaded the files depending on the content of the files[] parameter of your module’s *.info file. In essence, Drupal looped through files[] and called require_once for each file.

The downside of the above method is that the code is still loaded on every execution of Drupal, even it not needed! The autoloader we use in Drupal 8 relies on a different logic and will only load files when needed.

Step 5: Edit the class file.

• The file must begin with <?php.
• The file never ends with ?>.
• The first line of code should be the namespace declaration:
  namespace \Drupal\<your_module_short_name>\<namespace_directories>;
• If your class references other classes in your module or in Drupal, the following lines should be use statements. You will need one for each class you reference.
• Follow this with your class declaration.

The above outlines the typical structure of class files you’ll find throughout Drupal 8. When you add docblocks, you get something like this:

<?php
/**
 * @file
 * Contains \Drupal\<your_module_short_name>\<your_namespace>\<your_class_name>.
 */

namespace \Drupal\<your_module_short_name>\<namespace_directories>;

use Drupal\some\class\you\reference;

/**
 * Your class description.
 */
class <your_class_name> {
}

The above isn’t a complete class, obviously. You need to add class variables and methods as needed.

Summary

In this recipe, we’ve created a basic, empty class file for use in our module. The above class is generic, and doesn’t represent anything special in Drupal. We have created the class according to the PSR-0 standard, making it easy for Drupal to autoload the class without the need for us to include or require it directly.