If you want to define a new URL that a user can navigate to, and custom PHP code that will generate the content of the page, you need a route and a controller. Most of the time you'll want to do something more complex than hard code the content of the page. This will require using services in your controller. This can be accomplished in different ways.
In this tutorial we'll:
- Provide the definition for a new route which maps a path to the callback method of a controller class.
- Create a controller that returns a hard coded string.
- Look at examples of using both
ControllerBase
and dependency injection to access services from a controller, and discuss the benefits of both approaches.
By the end of this tutorial, you should be able to define a new route that maps to a controller and displays content on the page as a result of your custom logic.
The routing system can get dynamic values from the URL and pass them as arguments to the controller. This means a single route with a path of /node/{node}
can be used to display any node entity. Route parameters can be validated, and upcast to complex data types via parameter conversion. If you ever want to pass arguments to the controller for a route, you'll use parameters to do so.
In this tutorial we'll:
- Define what parameters (slugs, placeholders) are and what they are used for in a route definition.
- Explain how URL parameters are passed to a controller.
- Define parameter upcasting.
By the end of this tutorial, you should be able to explain how to define a route that uses parameters to pass dynamic values to the route controller, and explain how parameter upcasting works.
Every route should define its access control parameters. When you define routes in a module, you can limit who has access to those routes via different access control options. Route-level access control applies to the path. If your route defines a path like /journey/example
, the access control configuration will determine whether to show the current user the page at the path defined by the route, or to have Drupal serve an "HTTP 403 Access Denied" message instead.
In this tutorial we'll look at different ways of adding access control to a route including:
- Access based on the current user's roles and permissions
- Access based on custom logic in a callback method
- Logic in an access checker service
By the end of this tutorial, you should be able to add access control logic to your custom routes that will meet any requirement.
When defining a route and subsequently displaying the page, often we need to calculate the page title based on route parameters or other logic. In these cases, we can't just hard code the value into the _title
configuration of the route. To set a dynamic title for a page, we'll use the route's _title_callback
option, and point to a PHP callback that contains the logic that computes the title of the page.
In this tutorial we'll:
- Learn how to use the
_title_callback
route configuration option to dynamically set a page title - Explain how arguments are provided to the title callback method
- Update the route and controller from a previous tutorial to use a dynamic title callback
By the end of this tutorial, you should be able to configure a route so that its title can be set dynamically using route parameters, instead of hard-coding the title with a static string of text.
Let's write some code that will allow us to see route parameters in action. We'll define a new route with a path like /journey/42/full but where 42
can be any node ID, and full
can be any view mode. When a user accesses the path we'll pass the dynamic parameters from the URL to the controller. The controller will then load the corresponding node and render it using the provided view mode, and return that to display on the page.
By the end of this tutorial you should be able to:
- Use dynamic slugs in a route to pass parameters to the route controller.
- See how Drupal will upcast a value like the node ID, 42, to a
Node
object automatically. - Explain what happens when you visit a URL that matches a route but the parameters don't pass validation.
By the end of this tutorial, you should be able to pass dynamic values from the URL to a route's controller.
Every web framework, including Drupal, has basically the same job: provide a way for developers to map URLs to the code that builds the corresponding pages. Drupal uses Symfony's HTTPKernel component. Kernel events are dispatched to coordinate the following tasks:
- Process the incoming request
- Figure out what to put on the page
- Create a response
- Deliver that response to the user's browser
Knowing a bit more about how Drupal handles the request-to-response workflow will help you better understand how to use routes and controllers to create your own custom pages or deal with authentication, access checking, and error handling in a Drupal module.
In this tutorial we'll:
- Walk through the process that Drupal uses to convert an incoming request into HTML that a browser can read
- See how the Symfony
HTTPKernel
helps orchestrate this process - Learn about how the output from a custom controller gets incorporated into the final page
By the end of this tutorial, you should be able to describe the process that Drupal goes through to convert an incoming request for a URL into an HTML response displayed by the browser.
Sometimes we need the response returned from a controller to be something other than HTML content wrapped with the rest of a Drupal theme. Maybe we need to return plain text, or JSON structured data for an application to consume. Perhaps we need greater control over the HTTP headers sent in the response. This is possible by building on the fact that controllers can return generic Response
objects instead of renderable arrays, allowing you to gain complete control over what is sent to the requesting agent.
In this tutorial we'll:
- Look at how to return a plain text response, and JSON data
- Show how to make your responses cacheable by adding cacheability metadata
- Learn about how to use a generic Symfony
Response
to gain greater control over what gets returned
By the end of this tutorial, you should be able to return responses from a controller in a Drupal module that are not HTML content wrapped in a Drupal theme.
When it's time to start a custom Drupal theme from scratch (especially if you're new to Drupal theming), we recommend using Starterkit. Starterkit helps you get a new theme up and running by scaffolding a set of theme files with sensible defaults, saving you from a bunch of repetitive work.
In this tutorial we'll:
- Learn what Starterkit is
- Discuss when you should--and should not--use Starterkit
- Walk through how to use Starterkit to generate a new Drupal theme
By the end of this tutorial you should be able to explain the use case for Starterkit and understand how to use it to start a new custom theme.
We just added a new tutorial all about starting a new theme with Starterkit. Learn how to use it, how it works, and what prompted its addition to Drupal core.
We've updated our Search API and Solr in Drupal tutorials in 2 ways:
1. Instead of providing custom Docker containers, we show you how to use DDEV to set up a local Solr and Drupal development environment.
2. We've tested and updated steps and screenshots for Drupal 10.
If you've been wanting to learn how to develop a Search API and Solr solution for your Drupal site, it's a good time to dive in to this updated course!
We're excited to announce a new course, Performance and Scalability for Drupal Sites! This course is a deep dive into the concepts, terminology, tools, and strategies around performance and scalability for Drupal sites. By the end of this course, you will be well-equipped to understand your site's performance and how you can make your Drupal site blazing fast.
Drupal has robust Cache API, and various caching layers (both internal and external to Drupal), that work together to decrease application load and boost performance. Drupal's APIs allow developers to declare the cacheability of data. How long can this be stored before it becomes stale? And under what conditions should it be invalidated? Drupal uses that information during the process of building a page to cache as much of the work it does as is possible so that it won't need to do it again. Additionally, Drupal bubbles up the cacheability data from everything required to build a page into HTTP response headers that caching layers external to Drupal can also use to cache the rendered HTML.
When these APIs are combined (and used appropriately), Drupal can be extremely fast for both anonymous and authenticated traffic. But doing so requires understanding the various caching layers, their roles, and their interconnections.
In this tutorial, we'll:
- Review the caching layers and systems behind them
- Learn about components of the Drupal cache system
By the end of this tutorial, you should have a broad understanding of the Drupal caching system, its layers, and a better understanding of where in the stack you should look to optimize for different scenarios.
Note: This tutorial is specific to Drupal sites hosted on the Acquia platform and covers integrating its features to improve performance.
The Acquia platform includes Memcache, Varnish, and Content Delivery Network (CDN) integration. In order for these to be as effective as possible, they should be configured and tuned for your specific use case. This tutorial provides an introduction to these utilities and common configuration. For more detail, you should consult the Acquia documentation.
In this tutorial, we'll:
- Learn what caching utilities are included in the Acquia platform
- Set up and tune different parts of Acquia's application caching level including Memcache and Varnish
By the end of this tutorial, you'll know what application-level caching options exist on Acquia's platform. And how to configure it, and your Drupal application, for better performance.
WebPageTest (webpagetest.org) is a free open source resource that runs performance tests on a site, provides educational reports about what it finds, and suggests optimizations you can make. The tests performed via the WebPageTest interface include Lighthouse tests, performance-specific tests, Core Web Vitals, visual comparisons, and traceroute tests. The tool also allows saving a history of tests if you sign up for a free account. This tool won't make your site faster on its own, but it will give you some good ideas about where to focus your efforts.
In this tutorial we'll:
- Learn how to run performance tests via the WebPageTest web interface
- Learn how to read and interpret the results
By the end of this tutorial, you should know how to use the WebPageTest online interface to analyze a Drupal site's performance.
Lighthouse is an open source, automated tool for analyzing your site's performance. Lighthouse is built-in to the Google Chrome browser. When auditing a page, Lighthouse runs various tests against the page and then reports how well the page did across a broad spectrum of metrics. While Lighthouse doesn't improve the performance of a Drupal site itself, it helps to establish a performance profile and point towards areas that could be improved.
Lighthouse requires the use of Google Chrome. Other browsers include their own performance auditing tools. While the exact usage of each tool varies, the end result is the same: a report that can be interpreted to suggest where to focus your performance-tuning efforts.
In this tutorial, we'll:
- Learn how to run Lighthouse tests against a Drupal site
- Interpret the results of the report generated by Lighthouse
- Provide guidance on next steps to take to address the performance issues Lighthouse finds in our Drupal site
By the end of this tutorial you should be able to use Lighthouse to profile a Drupal site, interpret the results, and know where to start on making improvements.
Content Delivery Networks (CDNs) play an important role in making a Drupal-powered site fast and secure. The distributed nature of CDNs allows serving web assets such as HTML files, JavaScript, CSS, and media assets through servers located in close geographical proximity to the users, thereby reducing the physical distance data has to travel between the user and the server, and improving performance.
In addition to providing a performance boost, CDNs may also act as a firewall and protect sites from common attacks such as DDoS. The popularity of CDNs has been growing over the past few years, and integrating with them has also gotten easier. Most Drupal web operation platforms, such as Acquia and Pantheon, offer integrations with CDNs out-of-the-box. Even if your hosting platform doesn't provide a CDN, you can always set up your Drupal site to use one.
In this tutorial we'll:
- Define what a CDN is and what it can offer for your site
- Learn about popular CDNs used with Drupal sites
- Review some contributed modules that you can use to help integrate your Drupal site with a CDN
By the end of this tutorial you should be able to define what a CDN is, list CDNs with Drupal integrations, and describe the steps you will need to take to set up your site to work with a CDN.