Permissions in Drupal control access to features and functions. Modules define permissions, which allow site administrators to grant or restrict access based on user roles. As a module developer, you'll create new permissions to restrict access to your module's custom features, independent of existing permissions defined by other modules.
In this tutorial, we'll:
- Explore how and where permissions are defined within a module.
- Discuss the concept of static and dynamic permissions in Drupal.
By the end of this tutorial, you'll have a clear understanding of how permissions function in Drupal and their implementation in modules.
Modules can define custom permissions to restrict access to specific routes or page sections. This control allows module developers to provide granular access while enabling site administrators to manage user privileges. We'll add a view weekly weather
permission via the anytown module to limit access to the weather page.
In this tutorial, we'll:
- Create an MODULE_NAME.permissions.yml file.
- Define a new permission.
- Use the new permission to restrict access to a route.
By the end of this tutorial, you should be able to define a new permission in a module and use it to control access to a route.
Custom services in Drupal modules encapsulate specific business logic or functionality. In our example, we'll demonstrate moving code required to access a weather forecast API from a controller into a service. This will help make our controller thin and our module code more reusable, testable, and maintainable.
In this tutorial, we'll:
- Explore the advantages of custom services for managing business logic.
- Define the components of a custom service.
By the end of this tutorial, you'll understand why creating custom services is a beneficial practice in Drupal module development.
To access services in Drupal through the service container, you'll need to know the unique machine name of the service. We'll use the example of making HTTP requests to a weather forecast API in the anytown module to demonstrate several methods you can use to identify an existing service's ID.
In this tutorial, we'll:
- Discover existing services and their machine names.
- Take a look at an example service definition.
By the end of this tutorial, you should be able to locate and use existing services in your Drupal module.
Concept: Testing
FreeTesting ensures that code remains reliable and functional. This tutorial introduces the primary types of tests in Drupal: Unit, Kernel, Functional, and FunctionalJavascript -- all executed via PHPUnit. We'll clarify the differences between each type of test and appropriate use cases. As module developers, understanding what to test and how to write tests is vital for robust and maintainable code.
In this tutorial, we'll:
- Identify the primary test types in Drupal and their use cases.
- Emphasize the importance of functional tests in custom module development.
- Introduce the basics of authoring tests in a custom module.
By the end of this tutorial, you should recognize the different types of tests Drupal uses and when and how to use each kind.
Before you can run tests, you'll need to configure your local environment. This setup involves Drupal-specific configuration for PHPUnit and ensuring your environment supports Functional JavaScript tests with a WebDriver client and a compatible browser. The setup process varies based on the development environment. In this tutorial, we're using DDEV as the local environment.
In this tutorial, we'll:
- Install all required dependencies.
- Configure PHPUnit specific to our environment.
- Validate the setup by running a Drupal core test.
By the end of this tutorial, you'll be equipped to run Drupal's PHPUnit tests locally using DDEV.
Functional tests simulate user interactions with Drupal applications, which enables us to test user interfaces and complex workflows. This tutorial guides you through writing functional tests for the anytown module, focusing on custom user registration workflow enhancements.
In this tutorial, we'll:
- Examine functional test structure.
- Test
anytown_form_user_register_form_alter()
customizations. - Discuss the functional test execution environment.
By the end of this tutorial, you'll know how to write functional tests that emulate browser interactions with your Drupal application.
Kernel tests in Drupal enable module integration testing with Drupal core systems in a bootstrapped environment. Kernel tests bridge the gap between unit and functional tests. This tutorial focuses on writing kernel tests for the anytown module, specifically to test the ForecastClient
service's caching logic and custom username validation.
In this tutorial, we'll:
- Explore the parts of a kernel test.
- Write kernel tests for anytown module features.
- Use mocks and the Drupal container in kernel tests.
By the end of this tutorial, you should be able to get started writing kernel tests to verify your module's integration with Drupal core.
Unit tests are the simplest among Drupal's test types, ideal for verifying code that performs computations. This tutorial guides through writing unit tests for the anytown module, focusing on the ForecastClient
service, and illustrates how to use mocks for dependencies.
In this tutorial, we'll:
- List potential unit tests for the anytown module.
- Write tests for
ForecastClient
service logic. - Demonstrate how to mock services in unit tests.
By the end of this tutorial you should be able to write PHPUnit Unit tests for logic in the anytown module.
Fields are the building blocks of Drupal's powerful content modeling system. The field API allows for the development of custom field types to suit almost any data display and collection needs. Developers can create custom field types that can be bundled together and attached to various pieces of content. Fields allow a Drupal Site Administrator to create an information architecture that matches the needs of each individual site.
This series will provide you with all the information you need to be able to define a custom field in your own module. After completing all the lessons in this series, you should have a firm grasp of the Drupal 7 field API and the tools and knowledge you need in order to define your own custom field types.
Prerequisites
This series requires an understanding of PHP and basic Drupal 7 module development. For a refresher, or if you get stuck, check out our Drupal 7 Module Development series.
Additional resources
Drupal 7 Module Development series (Drupalize.Me).
Before diving into the code it's important to understand some of the building blocks that make up the Field API. There's a lot of different terminology in the Field API and it helps to understand what each of the terms mean. As well as understanding the relationship between the Fields and Entities in Drupal 7. Knowing these things will give you a strong foundation on which to start exploring the Drupal 7 Field API.
Terms & concepts covered in this video:
- What is a field? what is an instance?
- How do fields relate to entities?
- Field types
- Field storage
- Field widgets
- Field formatters
For more information about these terms see the Drupal.org handbook page: https://drupal.org/node/443540
- Field CRUD API - creates field instances and bundles, e.g.) what you see on the manage fields page.
- Field attach API - connects entities and fields, uses info from Field Info API to retrieve defined fields and do things like display their widget on the appropriate entity form when someone tries to edit an entity.
- Field info API - retrieve information about defined fields and instances.
- Field storage API - pluggable back-end storage for fields. Defaults to SQL backend provided by core.
- Field language API - provides native multilingual support for fields.
There's quite a bit of documentation and other resources already available to help you better understand the Drupal 7 Field API. Lets take a look at what's already available on Drupal.org, in the Examples project, and in the Drupal 7 core code that will serve as good reference material. We'll be referring back to these resources in later lessons, and they'll serve as a great place to look up additional information or to continue your learning via other examples.
Resources covered in this video:
- The Drupal.org Handbook for Field API
- API documentation in field.api.php, which gives an overview of all the Field API hooks.
- Field API documentation available on api.drupal.org - https://api.drupal.org/api/drupal/modules%21field%21field.module/group/…
- Examples for Developers project
We've also got some additional resources here on Drupalize.Me that will serve as a good refresher for how/where fields are used in Drupal:
- For learning more about how to use fields in the UI and how the UI works - http://drupalize.me/series/intro-fields-site-builders-series
- Attaching fields to custom entities - http://drupalize.me/videos/make-your-entity-fieldable-bundles
Additional resources
Before we can start building our custom field we need a vanilla Drupal site to work with and a skeleton module. This lesson will ensure you've got Drupal 7 up and running and walk through creation of a basic .info file and .module file for the module we'll be building. If you're already familiar with Drupal module development this lesson can likely be skipped and you can simply download the attached starter files, add them to an existing Drupal site, and continue on with the next lesson.
Grab a fresh copy of Drupal 7, and install it. If you need a refresher on installing Drupal checkout this series.
You'll also want to download and install the devel module as we'll make use of some of the debugging functions in provides (namely dsm()
) in later lessons in this series.
Alternatly, you can grab the .zip file under the companion files listed on this page which contains Drupal 7, and a database dump you can import to get started.
The first step to defining a custom field is telling Drupal that our module provides a field. This is done by implementing hook_field_info(), hook_field_formatter_info(), and hook_field_widget_info(). The combination of which provides some basic information about our field including a label, description, default settings, and basic information about how the field will be formatted and what widgets can be used for data collection.
In this lesson we'll implement the basics for the following hooks:
Doing so will allow us to enable our module and see our new field type appear in the list of available fields to add to a content type. The field won't do much beyond that yet, but it's a good start towards telling Drupal about our custom RGB field type.
If you want to just follow along and look at the already written code you can grab a copy in the companion files section of this page and use that to follow along.
Before we can actually get our field to store data for us we need to define what the data that we're going to store looks like. The Field API does this with hook_field_schema(), which uses a very similar syntax to what is used by the hook_schema() that modules can use to define database tables. In this particular case though we're only defining what the column, or columns, that store our specific data will be and allowing the Field Storage API to decide what the structure of the created table, or tables, should be. This allows our field to remain mostly storage system agnostic and frees us from having to worry about things like how the stored field data is connected back to the entity that it belongs to, or how to format our table for proper handling of revision data or translations.
- Documentation for hook_field_schema - https://api.drupal.org/api/drupal/modules%21field%21field.api.php/funct…
- Schema API docs - https://drupal.org/developing/api/schema
Example hook_field_schema()
implemenatation.
/**
* Implements hook_field_schema().
*/
function rgb_field_schema($field) {
$columns = array(
'rgb' => array(
'type' => 'varchar',
'length' => 6,
'not null' => FALSE,
),
'label' => array(
'type' => 'varchar',
'length' => 128,
'not null' => FALSE,
),
);
$indexes = array(
'rgb' => array('rgb'),
);
return array(
'columns' => $columns,
'indexes' => $indexes,
);
}
Additional resources
The term widget refers to the form element, or elements, that are presented to the user when they are entering data for a field. For example, the file upload field on the Article content type is the widget for the image field attached to that content type. When a field instance is attached to a bundle and an admin is creating or editing an entity of that bundle type the Field Attach API calls out to each individual field and asks it for the widget it would like to use to collect data. Adding a widget for a custom field type is a combination of implementing hook_field_widget_info() and hook_field_widget_form().
Examples:
/**
* Implements hook_field_widget_info().
*/
function rgb_field_widget_info() {
return array(
'rgb_textfield' => array(
'label' => t('RGB Textfields'),
'field types' => array('rgb_color'),
),
);
}
/**
* Implements hook_field_widget_form().
*/
function rgb_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
if ($field['cardinality'] == 1) {
$element['#type'] = 'fieldset';
}
$element['rgb'] = array(
'#type' => 'textfield',
'#field_prefix' => t('RGB: #'),
'#size' => 6,
'#default_value' => isset($items[$delta]['rgb']) ? $items[$delta]['rgb'] : '',
);
$element['label'] = array(
'#type' => 'textfield',
'#field_prefix' => t('Color name: '),
'#default_value' => isset($items[$delta]['label']) ? $items[$delta]['label'] : '',
);
return $element;
}
Additional resources
Before our field can save user provided data we need to use hook_field_validate() and hook_field_is_empty() to perform validation on field data. In certain context values like 0, FALSE, and NULL can all be a valid value. In fact, even a blank space could be valid input for a field. As such, it's not possible for Drupal to know what constitutes an empty state for a field without a little extra help. The same is true for checking if the value of a field is valid.
Examples:
/**
* Implementation of hook_field_is_empty().
*/
function rgb_field_is_empty($item, $field) {
if (empty($item['rgb']) || empty($item['label'])) {
return TRUE;
}
return FALSE;
}
/**
* Implements hook_field_validate().
*/
function rgb_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
foreach($items as $delta => $item) {
if (!empty($item['rgb'])) {
// Make sure it's 6 characters.
if (drupal_strlen($item['rgb']) !== 6) {
$errors[$field['field_name']][$langcode][$delta][] = array(
'error' => 'rgb_length',
'message' => t('%name: the hex color must be 6 characters.', array('%name' => $instance['label'])),
);
}
}
}
}
Additional resources
In order to allow for maximum flexibility in our widget we can add widget settings that apply to each individual instance of our field. By implementing hook_field_widget_settings_form() and then refactoring some of our existing code we can make it possible for a site administrator to set a custom prefix value for the label field, which the Field API will store for as part of the field instance's settings and we can use it when creating our widget.
Implementations of hook_field_widget_settings_form()
return a Form API array that represents the element or elements that you would like to add to the widget settings form. Values are automatically serialized and saved as part of the field's instance configuration and can be accessed by the passed in $instance
array's $instance['widget']['settings']
key.
Example:
/**
* Implements hook_field_widget_settings_form().
*/
function rgb_field_widget_settings_form($field, $instance) {
$element = array(
'rgb_label_text' => array(
'#type' => 'textfield',
'#title' => t('Alternate label text'),
'#description' => t('If an alternate label text is provided it will be used in place of the default "Color" title for the label field.'),
'#default_value' => isset($instance['widget']['settings']['rgb_label_text']) ? $instance['widget']['settings']['rgb_label_text'] : '',
),
);
return $element;
}