Drupal 8 8.0.2
API for describing data based on a set of available data types.
PHP has data types, such as int, string, float, array, etc., and it is an object-oriented language that lets you define classes and interfaces. However, in some cases, it is useful to be able to define an abstract type (as in an interface, free of implementation details), that still has properties (which an interface cannot) as well as meta-data. The Typed Data API provides this abstraction.
Each data type in the Typed Data API is a plugin class (annotation class example: ); these plugins are managed by the typed_data_manager service (by default ). Each data object encapsulates a single piece of data, provides access to the metadata, and provides validation capability. Also, the typed data plugins have a shorthand for easily accessing data values, described in Tree handling.
The metadata of a data object is defined by an object based on a class called the definition class (see ). The class used can vary by data type and can be specified in the data type's plugin definition, while the default is set in the $definition_class property of the annotation class. The default class is . For data types provided by a plugin deriver, the plugin deriver can set the definition_class property too. The metadata object provides information about the data, such as the data type, whether it is translatable, the names of its properties (for complex types), and who can access it.
See https://www.drupal.org/node/1794140 for more information about the Typed Data API.
There are three kinds of typed data: primitive, complex, and list.
Primitive data types wrap PHP data types and also serve as building blocks for complex and list typed data. Each primitive data type has an interface that extends , with getValue() and setValue() methods for accessing the data value, and a default plugin implementation. Here's a list:
Complex data types, with interface , represent data with named properties; the properties can be accessed with get() and set() methods. The value of each property is itself a typed data object, which can be primitive, complex, or list data.
The base type for most complex data is the class, which represents an associative array. Map provides its own definition class in the annotation, , and most complex data classes extend this class. The getValue() and setValue() methods on the Map class enforce the data definition and its property structure.
The Drupal Field API uses complex typed data for its field items, with definition class .
List data types, with interface , represent data that is an ordered list of typed data, all of the same type. More precisely, the plugins in the list must have the same base plugin ID; however, some types (for example field items and entities) are provided by plugin derivatives and the sub IDs can be different.
Typed data allows you to use shorthand to get data values nested in the implicit tree structure of the data. For example, to get the value from an entity field item, the Entity Field API allows you to call:
This is really shorthand for:
To define a new data type:
The data types of the Typed Data API can be used in several ways, once they have been defined: