Controllers

  
Last updated December 16, 2021
Module DevelopmentDrupal 9Drupal 8

When Drupal receives an incoming request the HTTP Kernel identifies the appropriate route for the requested path. The routing system then matches this route with a controller that has been registered to handle responses for these types of requests. Sections of code responsible for generating the response to these requests are called Controllers.

Example tasks

  • Write the code in a custom module that responds to particular incoming requests
  • Understand how to identify the controllers responsible for responding to a given url, path and route.

Confidence

Drupal's system of mapping request routes to controllers is quite well established. Since it's based on Symfony components it is unlikely to change dramatically in the foreseeable future.

Drupalize.Me resources

This tutorial covers how controllers work in the Symfony framework. Because Drupal is built on top of Symfony components, controllers in Drupal are very similar.

VideoHDCC

Symfony Controllers

7m53s  //  Backend and Infrastructure
VideoHDCC

Create a Module with a Route and Controller

Free
6m39s  //  Module Development, Drupal 8
VideoHDCC

Install Webprofiler and Identify Controllers

4m25s  //  Module Development, Drupal 8

Controllers and Form API

Tutorial

Define a New Form Controller and Route

Module Development, Drupal 8, Drupal 9
More information

Each form is defined by a controller, a class that implements the \Drupal\Core\Form\FormInterface. Form controllers declare the unique ID of the form, the $form array that describes the content of the form, how to validate the form, and what to do with the data collected.

In this tutorial we'll:

Tutorial

Validate a Form via the Form Controller

Module Development, Drupal 8, Drupal 9
More information

When your module defines the form and the form controller, you can add your validation logic as part of the form controller. This is done via the implementation of a validateForm() method. The FormBuilder service will automatically invoke this method at the appropriate time during the process of submitting a form. While the validateForm() method is required by \Drupal\Core\Form\FormInterface, an empty method will fulfill that requirement. It's up to you to provide appropriate validation code inside the method.

Tutorial

Process Submitted Form Data via the Form Controller

Module Development, Drupal 8, Drupal 9
More information

When you create a custom form for Drupal and your module defines the form controller, the best way to handle processing of submitted data is via the submitForm() method of your controller. This method is called automatically by the Form API during the process of handling a user-submitted form. It can be used to save incoming data to the database, trigger a workflow based on user input, and instruct the Form API where to send the user after form processing has completed.

In this tutorial we'll:

Tutorial

Inject Services into a Form Controller

Module Development, Drupal 9, Drupal 8
More information

Eventually you'll want to do something with the information your form collects beyond just printing it to the screen. It's generally considered a best practice to keep business logic out of your form controller so that it can be reused. In order to accomplish that you'll generally define your business logic in a service, and then call out to that service from your form controller. Or, you can make use of one of the existing services provided by Drupal core to save data.

In this tutorial we'll:

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • Adding a basic controller (drupal.org)
    • This tutorial covers creating a very basic controller.
  • Routing and controllers in Drupal 8 (lakshminp.com)
    • This tutorial walks through creating a custom module, using Drupal Console, that creates a simple route and controller.
  • Examples' projects page_example module (cgit.drupalcode.org)
    • The Examples project contains many sub-modules that demonstrate various Drupal sub-systems through well-documented code. To learn more about how routing and controllers work, take a look at the page_example module here.