Important OOP Concepts For Drupal Developers To Create Custom Modules

Modifying existing code might be all fun and games for a developer, but what about the time when you have to venture out to unknown shores and create your own custom modules? 

Scary, right? 

But you shouldn’t fear because Drupal 8 is here.

Drupal 8 uses a PHP framework called Symphony which relies heavily on Object-oriented programming.

It has been granting its users with benefits like code reuse and encapsulation, and these benefits allow users to maintain and structure code in a better way possible. 

Phew! 

However, this might leave you with a farrago of questions - What do I need to know in Drupal 8 to start developing? What is OOP? Why is it used in Drupal 8 to make modules? How does it create the custom modules? 

Thus, here is how you can do it all that might help make the OOP principle of PHP a little less daunting. 

Start With Prerequisites to Create Custom Modules

We all know that Object Oriented Programming has provided us with the power to create our desired objects and construct methods to handle them. And with the usage of various OOP principles and design patterns, Drupal 8 has brought about a much easier path in terms of development.  

Drupal 8 serves as a great introduction to PHP. Here are some of the design patterns which are important to understand to solve the basic object-oriented design problem. 

PHP Namespace (introduced in version 5.3)

In PHP you can’t have two classes that deal with the same name (they have to be unique). Therefore, PHP namespace allows you to dodge this issue by presenting a similar code into neat little packages, or even to determine ownership.

Drupal 8 consists of a number of files that declare the namespace in order to remain compatible with PHP 5.3. Therefore, with the help of two standards in Drupal, PHP interfaces and traits are easily namespaced.

Use statement

Classes and interfaces with a (\) backslash inside their fully qualified name should not use it inside the core. If it differs from the current file, then it can be solved by using the “use” statement on the top. For example

namespace Drupal\mymodule\Tests\Foo;

use Drupal\simpletest\WebTestBase;

/**
 * Tests that the foo bars.
 */
class BarTest extends WebTestBase {

And, for the file which does not declare a namespace has to specify with the use statement at the top of the file 
For the classes that are without backslash, they must be fully qualified when used in the namespace file.

Also, while you are importing a class with “use”, do not use the backslash. 

Aliasing the class 

PHP has allowed the classes to be aliased when they are being imported into a namespace. It is done to avoid the collision. But suppose the collision still happens, you can alias the classes by prefixing the next higher portion of the namespace.

use Foo\Bar\Baz as BarBaz;
use Stuff\Thing\Baz as ThingBaz;

/**
 * Tests stuff for the whichever.
 */
function test() {
  $a = new BarBaz(); // This will be Foo\Bar\Baz
  $b = new ThingBaz(); // This will be Stuff\Thing\Baz
}

Dependency Injections

Dependency Injections is that software design pattern that would allow you to remove hard-coded dependencies and also make it possible to change them either on runtime or at compile time.

Drupal 8 introduced the concept of services (object managed by service container) in order to decouple reusable functionalities. It creates the services pluggable and replaceable by registering them with the help of a service container.

These services are used to perform operations that include accessing of the database or sending up of an e-mail. Therefore, to let the code simply access the database (without worrying about whether the database is MySQL or SQLite), usage of core provided service via the service container is done.

These core services are defined in CoreServiceProvider.php and core.services.yml. Somewhat like:

...
language_manager:
    class: Drupal\Core\Language\LanguageManager
    arguments: ['@language.default']
  ...
  path.alias_manager:
    class: Drupal\Core\Path\AliasManager
    arguments: ['@path.crud', '@path.alias_whitelist', '@language_manager']
  ...
  string_translation:
    class: Drupal\Core\StringTranslation\TranslationManager
  ...
  breadcrumb:
    class: Drupal\Core\Breadcrumb\BreadcrumbManager
    arguments: ['@module_handler']
  ...

Each service depends on the other service. Like in the example above path.alias_manager is dependent on the path. crud, path.alias_whitelist and language_manager services specified in the arguments list.

Dependency injection is the preferred procedure for accessing and using services in Drupal 8. Services are transferred as an argument to the container or injected via setter methods.

Symfony 

Symfony is a PHP framework that Drupal borrows from in order to reduce codes duplication across various PHP projects. Much of the code that Drupal 8 uses to handle routing, sessions, and service container. These components are flexible and universal solutions. They are the stable ones and solves most the problems that aren’t good practice, to reinvent the wheel. Symfony follows the standards that adhere to PSR-5 and PSR-7

Annotations

Annotations are the comments in your code that contain meta information. The main advantage of annotations is that they improve performance due to the less memory usage and is placed in the same files as the class is. For example

/**
 * Provides a 'Custom' Block
 *
 * @Block(
 *   id = "custom_block",
 *   admin_label = "Custom block",
 * )
 */

Drupal 8 uses PHP annotations for plugin discovery and to present additional context/meta-data for the codes that have to be executed. These are the read using Doctrine annotation parser (offers to implement custom annotation functionality for PHP classes.) and then they are turned into information that Drupal can use for better understanding on what your code is actually doing. 

Plugins 

Plugins are considered as a small piece of functionalities that can be swapped. Drupal consists of different plugins with different types. The CMS platform provides a set of guidelines and reusable code components that allows the developer to expose pluggable components within their code and manage these components with the user interface. Plugins have three basic elements namely.

Plugin type: It is a central controlling class that would define how the plugin of this type will be discovered and instantiated.

Plugin Discovery: It is the process of finding plugins within the code base that is qualified for the usage.

Plugin Factory: It is responsible for instantiating specific plugins.

Not to Forget the OOP Coding Standards 

If the end user is aware of key OOP principle and design pattern, then it becomes even more easy for them to use it with Drupal. For instance, different services become available when default container initializes while bootstrapping Drupal. In short, you have the power to build your own class, then define it as a service and make it available in the container. 

Drupal 8  has a set of coding standards just for object-oriented code and adheres to common PHP coding conventions. 

Thus, some of the common PHP conventions for OOP that Drupal follows for best practices would include:

• Declaring a class in OOP. It is important that there should always be one interface or trait per file. The classes are autoloaded based on PSR-4 namespacing convention, and in the core, the tree under PSR-4 starts as core/lib/. For the modules that contain contrib, custom and those in the core, the PSR-4 tree starts under modulename/src. It should also be noted that it is only possible to define a class in a module if the class does not contain any superclass. 
• Next in this coding standards would be whitespace or indentation method. Both of them leave an empty line between the start of the class definition and property definition. Just like this:

class GarfieldTheCat implements FelineInterface {
  // Leave an empty line here.
  public function meow() {
...
...
...

 For an empty space between property definition and method definition:

...
...
...
  protected $lasagnaEaten = 0;
  // Leave an empty line here.
  public function meow() {
    return t('Meow!');
  }

And then for the space between the end of method and end of the class definition:

class GarfieldTheCat implements FelineInterface {
...
...
...
  public function eatLasagna($amount) {
    $this->lasagnaEaten += $amount;
  }
  // Leave an empty line here.
}

• Without basic naming conventions, coding standard for OOP is a void. These naming conventions (set of rules) would help you to choose the character sequence to be used for the identifier that denotes the variables, functions, types and other entities.  
• There might be chances where you would also wish to extend your code. Thus the use of separate interface definition would help you by contributing highly in terms of flexibility and would also neatly centralizes the document, making it easier to read.  A class that has to be extended must always provide an interface that other class can implement rather than forming them to extend the base class.
• Also, it is important for all the methods and properties of classes to specify the visibility (private, protected or public). The use of public properties is strongly discouraged. It allows the entry of unwanted side effects and exposes implementation specific details, which in turn makes swapping out of class (for another implementation) much more hard. 
• Now comes the “Type Hinting” in PHP. It is basically used to specify the expected data type of an argument in a function declaration.  Although type hinting is optional, it is recommended for debugging.If an object of the incorrect type is passed, an error is shown. If the method’s parameter expects a certain type of interface, it is important to specify it. This would guarantee that you are checking for a type and also maintaining a fluid code.
• Next is instantiation. It is basically the creation of a real instance or a single realization of an abstraction/template such as the class of object. Drupal coding standards look down upon directly creating classes. Rather it is better to create a function to instantiate the object and return it. It is because:

1. The function which is written can be reused to return different objects with the same interface as it is needed. 
2. You are not allowed to chain construct in PHP, but you are allowed to chain return object from the function. 

• Last but not the least - Chaining.  Chaining is that blessing for you which allows you to immediately call a function on a return object. This is also known as “fluent interface”

// Unchained version
$result = db_query("SELECT title FROM {node} WHERE nid = :nid", array(':nid' => 42));
$title = $result->fetchField();

// Chained version
$title = db_query("SELECT title FROM {node} WHERE nid = :nid", array(':nid' => 42))->fetchField();

A method would return $this, and then would be chainable in a case where there is no other logical return value.

In cases that have a fluid interface of the classes, and code span of more than one line, the method calls should attend 2 spaces

$query = db_select('node')
  ->condition('type', 'article')
  ->condition('status', 1)
  ->execute();

Routing in Drupal 8 is Equally Important 

Drupal 8 routing system works with the Symfony HTTP kernel. The routing path has replaced hook_menu() in Drupal 7. Though in Drupal 8 heavy use of Symphony 2 components handle the routing part. Drupal 8 also uses YAML format. All the information about routes of a module is kept in the file MODULE_NAME.routing.yml. 

The routing system is responsible for matching paths to the controller and then you are allowed to those relations in routes. The additional information can also be passed to controllers in the router. 

Each route has to be described separately from one another with the involvement of these characteristics :

• Name for identifying the routes 
• Path beginning with a slash
• A route’s processor
• Condition managing the access to the route

example.my_page:
  path: '/mypage/page'
  defaults:
    _controller: '\Drupal\example\Controller\ExampleController::myPage'
    _title: 'My first page in Drupal8'
  requirements: 
    _permission: 'access content'

Example.my_page is the route in the .routing.yml file. The route is the Symfony component which maps the HTTP request to set the configuration variable. Under path, we specify the path where route should be registered. This acts as the URL to route 

Creating “Controller Class”

It is important to build the ModuleController.php according to the PSR-4 naming standard. You just have to create a folder along with a file name with the following content. 

<?php
/**
 * @file
 * @author Rakesh James
 * Contains \Drupal\example\Controller\ExampleController.
 * Please place this file under your example(module_root_folder)/src/Controller/
 */
namespace Drupal\example\Controller;
/**
 * Provides route responses for the Example module.
 */
class ExampleController {
  /**
   * Returns a simple page.
   *
   * @return array
   *   A simple renderable array.
   */
  public function myPage() {
    $element = array(
      '#markup' => 'Hello world!',
    );
    return $element;
  }
}
?>

A controller is a type of PHP function that you create. It takes the information from the HTTP request and creates or responds to an HTTP response.

Creating the “.module file”

In Drupal 8 hook_menu() is used to only define items. If you have a hook_menu() then make sure that route and path in example.module should match with example.routing.yml.

In the case of items and route example, .module should be on the same path.

<?php
/**
 * @File
 * Example custom module for Drupal 8.
 * @author Rakesh 
 */

/**
 * Implementing hook_menu().
 */
function example_menu() {
  // The paths given here need to match the ones in example.routing.yml exactly.
  $items['/mypage/page'] = array(
    'title' => 'First page',
    'description' => 'This is a example page.',
    // The name of the route from example.routing.yml
    'route' => 'example.my_page',
  );
  return $items;
}

Conclusion

So here it is. Now, you know the concepts of OOP to create a custom module. Yes, it is important to know OOP, design patterns, Twig, and modern PHP trends for creating the modules, and Drupal makes this task even more easy for you. Isn’t it?

If you’re looking for more good resources and reference material, head over to OpenSense labs, where we provide services that develop complex web applications with relative ease. Whether it is the development of a new custom module or optimization of your new website, everything is handled and tailored according to your needs. 

So contact us at [email protected] for more information and reference on the same.