Building modules with Drupal 8

Regardless of your previous Drupal experience, developing modules for Drupal 8 has its own particular challenges and opportunities. To help developers with this process, we have created this Building modules with Drupal 8 resource to provide some needed insight and guidance about module development. This guide was designed in a manner where it can be followed as a textbook with exercises, but if you already have module development experience, you can jump directly to your section of interest.


Although it can be difficult to determine your particular skill level with a topic, we have designed these lessons to meet developers' needs at all skill levels. For example, while the lessons attempt to meet the needs of most developers, module creation beginners can refer to the hints and notes for additional assistance. Experienced developers can, instead, focus more on the extra credit.

If you're just getting started with PHP and object-oriented programming (OOP), Code Academy has a starter class at

Familiarity with the following items will help you better succeed with the lessons in this resource:

  • Basic understanding of programming in PHP
  • Basic familiarity with object-oriented programming (OOP) terminology
  • Basic experience in using PHPStorm

Along with the preceding items, we also suggest that you review the code organization and the important terms sections on this page.

Code organization

In this resources lessons and examples, you will be using path naming patterns based on the following example:

  • project/module_name/*

Future lessons will use the following paths:

  • examples/page_example/*
  • examples/block_example/*
  • examples/form_example/*
  • examples/field_example/*
  • examples/entity_example/*
  • examples/theme_example/*

Files and directories in those paths will appear similar to the following:

  • src/*
  • src/Form/FormExampleForm.php
  • templates/*
  • images/*
  • config/*

Important terms

This section describes the Drupal and general terms with which you should be familiar.

Drupal terms

For important Drupal terms, see the Drupal term index.

General programming terms

TermDefinition - 

Class - An extensible program-code-template for creating objects, providing initial values for state (member variables) and implementations of behavior (member functions or methods) — object-oriented programming definition

Comment - A programming language construct used to embed programmer-readable annotations in the source code of a computer program

Function - A sequence of program instructions that perform a specific task, packaged as a unit, which can then be used in programs wherever that particular task should be performed

Method - A function used in the context of a class/object — also known as a member function

Namespace - Provides a method to group related classes, interfaces, functions, and constants, which can solve two problems that authors of libraries and applications encounter when creating re-usable code elements such as classes or functions:

  • Name collisions between code that you create, and internal PHP classes/functions/constants or third-party classes/functions/constants
  • Ability to alias (or shorten) Extra_Long_Names designed to alleviate the first problem, improving readability of source code

Object - A variable, function, or data structure that refers to a particular instance of a class where the object can be a combination of variables, functions, and data structures — comprised of variables (such as properties, attributes, or fields) and functions (methods), and allows the bundling of functions and data in one structure — create using classes/object constructors object-oriented programming definition

Object-oriented programming (OOP) - Provides a model for programming based on objects, integrating code and data using the concept of an object

Variable - A symbolic name associated with a value and whose associated value may be changed

Code example


// This is a comment
/* This is a comment that
   spans multiple lines */
// This is a variable
$age = '33'; 
// This is a function
function displayAge() {
  return $age;
// This is a class
class personClass {
  // This is a property variable
  public $age = '33'; 
  // This is a method
  public function displayAge() {
    return $this->age;

// This is an instantiated class
$age = new personClass();

// This is calling the 'displayAge' method of the class
echo $age->displayAge();


If you're not familiar with most of the previous terms, you should consider reviewing the Code Academy class. It can hopefully provide additional context and experience for the remainder of this lesson. With time and practice, through the iterations provided, it should be possible to improve your understand of Drupal 8 using module migration. Some concepts can take many tries (such as dependency injection and service containers) while others (such as YAML files) might make sense the first time that you encounter them.

Next: Lesson 1 - Examples module, Symfony, Controllers, and the Menu >

Creative Commons License This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Contact supportStill need assistance? Contact Acquia Support