Skip to content

Field Type API

Field Types are the smallest building blocks of content. Ibexa DXP comes with many built-in Field Types that cover most common needs e.g. Text line, Email address, Author list, Content relation, Map location, Float, etc.

Field Types are responsible for:

  • Storing data, either using the native storage engine mechanisms or specific means
  • Validating input data
  • Making the data searchable (if applicable)
  • Displaying Fields of this type

Custom data

Ibexa DXP can support custom data to be stored in the Fields of a Content item. To do so, you need to create a custom Field Type.

A custom Field Type must implement the FieldType Service Provider Interfaces available in the eZ\Publish\SPI\FieldType namespace.


Remember that all your custom Field Types must be registered in config/services.yml. For more information see Registration.

In order to provide custom functionality for a Field Type, the SPI interacts with multiple layers of the Ibexa DXP architecture:

Field Type Overview

On the top layer, the Field Type needs to provide conversion from and to a simple PHP hash value to support the REST API. The generated hash value may only consist of scalar values and hashes. It must not contain objects or arrays with numerical indexes that aren't sequential and/or don't start with zero.

Simple hash values

A simple hash value always means an array of scalar values and/or nested arrays of scalar values. To avoid issues with format conversion, don't use objects inside the simple hash values.

Below that, the Field Type must support the public PHP API implementation regarding:

  • Settings definition for FieldDefinition
  • Value creation and validation
  • Communication with the Persistence SPI

On the bottom level, a Field Type can additionally hook into the Persistence SPI in order to store data from a FieldValue in an external service. Note that all non-standard Ibexa DXP database tables (e.g. ezurl) are treated as external storage.

The following sequence diagrams visualize the process of creating and publishing new content across all layers, especially focused on the interaction with a Field Type.

Creating content

Create content sequence

Publishing content


For Solr Locations are indexed during Content indexing. For Legacy/SQL indexing is not required as Location data already exists in a database.

Publish content sequence

Updating content

Update content sequence

Loading content

Load content sequence