Updated on 8 November 2017

This section is a rough introduction to the Drupal architecture so, instead of describing it, it gives you the keys to know where to look. It is based on Drupal 8.4. We will still illustrate the purpose with an example by having a quick look at the Node entity via class inheritence and SQL representation.

Drupalship engineering

Do I need to learn Symfony prior to the Drupal API?

Well, if you have time, for sure you will have benefits to understand the underlying framework.
Symfony is based on HTTP principles (Request, Response) so it will also improve your understanding of the protocol that rules the web.

But I am tempted to give the same answer that should probably be given for Laravel (that is also built on top of Symfony): just use Drupal first, and if you want to dive deeper in the understanding, it makes sense to deconstruct the underlying class inheritance. Another reason is that Drupal only uses a subset of the Symfony components.
IMO it makes much sense to improve skills in Object Oriented programming, Design Patterns, … that will be valid in most modern languages or frameworks.

The Drupal file system

The file system mentioned below is based on the result produced by the Composer template for Drupal projects. We will not list all the directories, but focus on the main ones.

* = marked as gitignored

composer.json     # The main Composer file, the only one that defines your project.
- config/sync     # The configuration should be exported here, outside of the docroot.
- private-files * # A good place to define the private user files (private://).
- vendor *        # External PHP libraries like Symfony, PHPUnit, Guzzle, Drush, ...
  - bin *         # Contains aliases to Drush, Drupal Console, ... executed on the CLI.
- web             # The docroot, contains the main front controller (index.php).
  - core *        # The Drupal core.
    - modules *   # Modules provided by the core.
    - themes *    # Themes provided by the core.
  - modules       # Modules related to your project.
    - contrib *   # Contributed modules related to your project.
    - custom      # Custom modules related to your project.
  - themes        # Themes related to your project.
    - contrib *   # Contributed themes related to your project.
    - custom      # Custom themes related to your project.
  - profiles      # Installation profiles.
  - libraries *   # External libraries related to your project (e.g. Chosen).
  - sites/default/settings.php * # Project configuration, like database credentials.
  - sites/default/files *        # Contains the public user files (public://).

Drupal 7 update

The contrib and custom projects (modules and themes) are now in /web/modules and /web/themes.
The core projects are in /web/core/modules and /web/core/themes.

The Drupal Core

As a frontend or backend developer, a way to adopt Drupal and gain confidence quite fast is by reading the core.


Just focus on the core/themes directory.

First, pick Stable or Classy to learn about Twig templates. These themes are dedicated to provide a starting point (known as base theme) so you can extend them.

In core/themes/classy/templates or core/themes/stable/templates you will find many templates grouped by directories (e.g. the layout directory will contain html.html.twig, the main "wrapper" template). As a first test, you can just copy any of these templates in your own theme (use Drupal Console command drupal generate:theme) and start playing around with template attributes, ... . Note that the Drupal Console command will suggest you to choose a base theme.

Then, pick a template like Bartik in core/themes/bartik that uses Classy as a base theme, you can see the base theme declaration in bartik.info.yml
There you can learn about how Bartik overrides Classy, either with its own templates or via preprocess in bartik.theme.


Content and Configuration Entities

You can learn a lot just by looking at the most used entities for describing content: Node and taxonomy Term. They live in the core/modules/node and core/modules/taxonomy directories.

Node module

In the core/modules/node/src/Entity, observe the class inheritance between Content Entity (via the Node class) and Configuration Entity (via the NodeType class, also known in the backend UI as “Content type”).

Node class

NodeType UML

Now, just have a look at how the taxonomy module handles that.

Term UML

Vocabulary UML

Read more in Drupal 8 - The Entity CMS or just go on with the file, user or views modules to dive deeper in the Entity world.

Content Entity cheat sheet

This cheat sheet, provided by Wizzlern, gives a really clear overview of frequently used methods, classes and interfaces for content entities.

Drupal 8 content entity cheat sheet

Fields and Fields Formatter

Pick a simple module like Telephone, in core/modules/telephone, there is a lot to learn here:

  • How to let know Drupal about your field in the telephone.info.yml and telephone_field_formatter_info_alter()
  • How to create the field type, the field formatter and field widget in the Plugin directory
  • How to create unit tests in the test directory

The Drupal database schema

The standard installation profile will create 65 tables.
Same principle as the file system, we will just focus here on the main tables and describe the Node entity as an example.

Drupal 8.4.0 SQL physical schema

Node related tables

This is one of the most powerful aspect of Drupal that allows its versatility. Roughly, the node table contains almost no data.

If you come from Drupal 7, the title column has moved in the node_field_data table, so we can fully rely on the entity translation system and do not need several node id's for each translation (like it was the case with i18n). Later, the Entity Translation coupled with the Title module allowed to avoid this, but it was not the case by default in version 7.

Then each field is represented by 2 tables: one for the current content (e.g. node_body), the other for the revision (node_revision__body).

Drupal 8.4.0 Node tables Drupal 8.4.0 node table Drupal 8.4.0 node data table Drupal 8.4.0 node body table

Now you can extrapolote this to other entities like Block Content, Comment, Menu, Term, User.
They surely come with their specialization but you've got the big picture.

Other noticeable tables

A quick sample:

  • Cache related tables: cache_config, cache_data, cache_render, cachetags, ...
  • Configuration storage: config
  • Background tasks processing: queue
  • Routing system: routing
  • Search (core): search_dataset, search_index, search_total
  • Logs: watchdog

As a conclusion, the Drupal core architecture is quite complex and powerful but still extremely readable, so do not hesitate to dive into it, you will always come back with something that can be used in your projects.

You can also continue the discovery of the Drupal architecture with

Add new comment

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
  • Only images hosted on this site may be used in <img> tags.
CAPTCHA This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.