Data type plugins

A data type plugin defines the setting and getting of values for a primitive or complex data type. A primitive data type refers to data that has a single property such as a boolean, string, URI, or date time value. Conversely a complex data type has multiple properties that are also data types such as the EntityAdapter or Map data type plugins.

This plugin is defined by the DataType PHP Attribute with the following properties:

• id: The plugin id that is passed into the create method for a data definition class.
• label: A translatable label to use for the data type.
• description: An optional translatable description to use when describing the data type.
• definition_class: The definition class to use for a complex data type. This is not necessary for primitive data types. This is defined as the fully-qualified class name.
• list_class: An optional class that will be used when instantiating a sequence of this data type. This is useful for implementing custom normalization.
• list_definition_class: An optional class that will be used as the data definition when creating a list of this data type.
• constraints: An optional array of default validation constraints. This is assembled by the Typed Data Manager when a data definition is getting the constraints for a data type. These will also add the NotBlank or NotNull constraints when the data definition sets a property to be required. For instance, the Email data type provides the Email constraint so there is no need to add that constraint to a data definition that provides a property using that type.

The EntityAdapter data type is ready-made for Drupal entities. The Map data type is an example for developers to extend, and is a way of representing hierarchical data without any assumptions about storage and requires a corresponding data definition to describe the properties.

This is a fictitious example of a simple Color class, which extends the Map data type.

use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\Core\TypedData\Attribute\DataType;
use Drupal\example\TypedData\ColorDefinition;

#[DataType(
  id: 'example_color',
  label: new TranslatableMarkup('Color'),
  definition_class: ColorDefinition::class,
  constraints: [],
)]
class Color extends Map { }

A data type plugin may have methods to interact with the values, but validation (constraints) should be handled by the data definition class. For instance, a Color class could have methods for helping to get the value as RGB or CMYK. It is not necessary to implement any methods on this class to use the basic functionality described in the Typed Data API Overview.

class Color extends Map {
   // @todo add some example methods.
}

The data type plugins provided by core may be found in core/lib/Drupal/Core/TypedData/Plugin/DataType.  Their ids are listed in their annotations, and include (as of Drupal 8.9): any, binary, boolean, datetime_iso8601, duration_iso8601, email, float, integer, list, language, language_reference, map, string, timespan, timestamp, and uri.