Drupal  8.3.5
APl Documentation
Typed Data API

Data Structures

class  DataType
interface  ComplexDataDefinitionInterface
interface  ComplexDataInterface
interface  DataDefinitionInterface
interface  DataReferenceDefinitionInterface
interface  ListDataDefinitionInterface
interface  ListInterface
class  ItemList
class  Map
interface  PrimitiveInterface
interface  BinaryInterface
interface  DateTimeInterface
interface  DurationInterface
interface  FloatInterface
interface  IntegerInterface
interface  StringInterface
interface  UriInterface
class  TypedData
interface  TypedDataInterface

Detailed Description

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.

Overview of web services

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.

Varieties of typed data

There are three kinds of typed data: primitive, complex, and list.

Primitive data types

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

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.

Tree handling

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:

$value = $entity->fieldName->propertyName;

This is really shorthand for:

$field_item_list = $entity->get('fieldName');
$field_item = $field_item_list->get(0);
$property = $field_item->get('propertyName');
$value = $property->getValue();

Some notes:

Defining data types

To define a new data type:

Using data types

The data types of the Typed Data API can be used in several ways, once they have been defined:

See also
Plugin API
Services and Dependency Injection Container