Drupal 8: Best Use of the Block System

The release of Drupal 8 brings a plethora of new features; one of the more pertinent and important ones is the Drupal 8 block system. The block API has gone through a ground-up overhaul and allows much more flexibility with how your blocks are both defined and displayed. This post will highlight some of the more powerful features of the Drupal 8 block system as well as some gotchas and best practices. Let’s get started.

Required: Freshly installed and running Drupal 8 site
Tools Used: PHP Storm with Drupal and Symfony support

The first step towards defining a block plugin for Drupal 8 is to create a new module.

In this example, I have created the “d_blocks” module to work with. This module will be used throughout this series. The folder structure I am using looks like this: modules/custom/d_blocks

Note: In Drupal 7 all modules would be put into the “sites/all/modules” folder. If you were using the refined folder structure it may look like “sites/all/modules/custom.” In Drupal 8 however, you now put your modules in the aptly named “modules” folder located in the root of your project.

Now that we have our folder structure for our module in place we can create the required files. As anyone that has developed with Drupal will know, the required item to get Drupal to recognize your module is the info file. Drupal 8 uses the YAML file type to define configuration files. The naming convention looks like this: d_blocks.info.yml Create that file and insert the code below:

name: D Blocks description: Defines custom blocks for this example type: module
core: 8.x

Great! Now if you go to your site, clear your cache and go to the modules list, you will see your new custom module. Be sure to enable it so you start seeing changes in your environment.

The next step is to create the folder structure for the block plugin side of your module. Create the necessary folders in your project so it reflects this path: d_blocks/src/Plugin/Block

Note: The folder structure is case sensitive so be sure to mimic capitalization.

With Drupal 8 we say goodbye to the old’ hook_block_info and hook_block_view functions. Embrace the change, this is a good thing. In Drupal 8 all custom blocks are defined by writing a Plugin. There are many benefits to this, such as all your code being in a class, PSR-4, easy extensibility and more. In my opinion, the greatest benefit, but a lesser appreciated one, is the more manageable code files. Gone are the days of module files with lines of code counting past the thousands. Now each block you define is held nicely in its own manageable file, the way it should be.

Another thing to note is the way Drupal 8 uses these files and instantiates your blocks. In Drupal 7 you wrote a function to populate the content of the block based on some parameters and that was it. Any configuration you wanted to have for that block had to be done programmatically or exported to another system form to handle. Well there will be no more bashing your code for hours trying to hook up multiple blocks and forms to interact with each other. Drupal 8 allows you to define your block content, configuration, twig templates to use and anything else you can think of right in its own file. Brilliant!

Also, when selecting your custom block in the Drupal 8 block UI things are a little different under the hood. In Drupal 7 when you selected your custom block you essentially had just that….one block. If you wanted another one just like it with the same functionality you had to define another block in your code. Drupal 8 solves that with block Plugins. Think of your block plugin as a scaffolding for a custom block. When you select your block in the UI, Drupal creates a block with all of the settings and configuration you defined in your plugin. This allows you to make multiple instances of your custom block with different values while only having to define it once in the code.

CTA 1 - Don't Wait to MIGR8

Don’t Wait to MIGR8

Let Duo guide you on the right path to Drupal 8.

Enough talk; let's do this!

In the Block folder create the file “ExampleBlock.php” (case sensitive). This will be the file that holds all of the code for our custom block. In this file paste the following code:

 * @file
  * Contains \Drupal\d_blocks\Plugin\Block\ExampleBlock
 namespace Drupal\d_blocks\Plugin\Block;
 use Drupal\Core\Block\BlockBase;
  * @Block(
  *   id = "example_block",
  *   admin_label = @Translation("Example Block"),
  * )
class ExampleBlock extends BlockBase {
    * On block call and build
    * @return string
   public function build() {
     return array(
       '#markup' => 'This is an example block!',


This is the minimum code that is needed to create and return a custom block. If you want to see this in action, save your code, clear cache and go to the blocks config page. Then you will be able to add your block and view it on your site. Groovy!

Drupal Block System

Let’s break down what we just pasted:

  • First we have the namespace. Drupal 8 uses the PSR-4 standard to indicate where the files are for your modules and plugins. Here we are telling Drupal the location of this custom block in the project.

  • Next we include the BlockBase class. You can see the build function in our code at the bottom of the file. This is a function provided by the BlockBase class and is essential for Drupal to build your block.

  • The next big chuck of this is the interesting looking comment block. What we have here is an annotation. This is new in Drupal 8 and comes from the Symfony way of doing things. This is an array of values that relays information about the block you are configuring. Think about it like hook_block_info but just in comment form. What we have defined above is the “id” which is the plugin ID and the “admin_label” which is the default name and title that displays for the block on the block configuration page. To see a list of all the parameters that can be defined please see the documentation page here.

  • After the annotation we have a straightforward custom class that extends BlockBase. Inside that we have a simple build function that returns an array of block parameters and values to Drupal.

Note: Be sure that the name of your file and the name of your class are exactly the same. class ExampleBlock = ExampleBlock.php

​​​​​​​There you have it. You have now defined a module with a custom block Plugin that is being recognized and rendered by Drupal. Congratulations! If you'd like to explore some additional example module code files, you can download them here: d_blocks.

Coming soon we’ll share Part II of this post, where we’ll start using some of the new and more powerful features of the Drupal 8 block system.

CTA 4 - Got a Project? - Let's Talk!

We Like Challenges.

Our team of experts can help your organization
reach its digital goals.