Field Type API & best practices

eZ Platform can support arbitrary data to be stored in the fields of a content item. In order to support custom data, besides the standard data types, a developer needs to create a custom Field Type.

The implementation of a custom Field Type is done based on the Field Type SPI and its interfaces. These can be found under eZ\Publish\SPI\FieldType.

In order to provide custom functionality for a Field Type, the SPI interacts with multiple layers of the eZ Platform architecture, as shown in the following diagram:

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.

Below that, the Field Type must support the Public API implementation (aka Business Layer), regarding:

• Settings definition for FieldDefinitions
• 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 eZ Publish database tables (e.g. ezurl) are also considered "external storage" from now on.

The following sequence diagram visualizes the process of creating a new Content across all layers, especially focused on the interaction with a FieldType.

In the next lines/pages, this document explains how to implement a custom Field Type based on the SPI and what is expected from it. As a code example, please refer to the Url FieldType, which has been implemented as a reference.

Public API interaction

The interaction with the Public API is done through the interface eZ\Publish\SPI\FieldType\FieldType. A custom Field Type must provide an implementation of this interface. In addition, it is considered best practice to provide a value object class for storing the custom field value provided by the Field Type.

FieldDefinition handling

In order to make use of a custom Field Type, the user must apply it in a eZ\Publish\API\Repository\Values\ContentType\FieldDefinition of a custom Content Type. The user may in addition provide settings for the Field Type and a validator configuration.  Since the Public API cannot know anything about these, their handling is delegated to the Field Type itself through the following methods:

getFieldTypeIdentifier()

Returns a unique identifier for the custom Field Type, which is used to assign the type to a Field Definition. By convention for the returned type identifier string should be prefixed by a unique shortcut for the vendor (e.g. ez for eZ Systems).

getSettingsSchema()

Using this method, the Public API retrieves a schema for the field type settings. A typical setting would e.g. be a default value. The settings structure defined by this schema is stored in the FieldDefinition. Since it is not possible to define a generic format for such a schema, the Field Type is free to return any serializable data structure from this method.

getValidatorConfigurationSchema()

In addition to normal settings, the Field Type should provide a schema settings for it's validation process. The schema describes, what kind of validation can be performed by the Field Type and which settings the user can specify to these validation methods. For example, the ezstring type can validate minimum and maximum length of the string. It therefore provides a schema to indicate to the user that he might specify the corresponding restrictions, when creating a FieldDefinition with this type. Again, the schema does not underlie any regulations, except for that it must be serializable.

validateFieldSettings()

Before the Public API stores settings for the FieldType in a FieldDefinition, the type is asked to validate the settings (which were provided by the user). As a result, the FieldType must return if the given settings comply to the schema defined by getSettingsSchema(). validateValidatorConfiguration() Analog to validateFieldSettings(), this method verifies that the given validator configuration complies to the schema provided by getValidatorConfigurationSchema().

It is important to note that while the schema definitions of the FieldType maybe both be of arbitrary, serializable format, it is highly recommended to use a simple hash structure. It is highly recommended to follow the Best practices in order to create future proof schemas.

Name of the Field Type

If you implement Nameable as an extra service, and registered register this Service using the tag nameable, the method {FieldType}Nameable->getFieldName() will be used to retrieve the name.

Otherwise the regular  regular {FieldType}->getName() method is used.

# Nameable services (for fieldtypes that need advance name handling)
    ezpublish.fieldType.ezobjectrelation.nameable_field:
        class: %ezpublish.fieldType.ezobjectrelation.nameable_field.class%
        arguments:
          - @ezpublish.spi.persistence.cache.contentHandler
        tags:
            - {name: ezpublish.fieldType.nameable, alias: ezobjectrelation}

Value handling

A field type needs to deal with the custom value format provided by it. In order for the public API to work properly, it delegates working with such custom field values to the corresponding Field Type. The SPI\FieldType\FieldType interface therefore provides the following methods:

acceptValue()

This method is responsible for accepting and converting user input for the field. It checks the input structure it accepts and might build and return a different structure holding the data. An example would be, that the user just provides an HTTP link as a string, which is converted to the value object of the Url FieldType. Unlike the FieldType\Value constructor, it is perfectly acceptable to make this method aware of multiple input types (object or primitive, for instance).

Note: The method must assert structural consistency of the value, but must not validate plausibility of the value.

getEmptyValue()

Through settings, the FieldType can specify, that the user may define a default value for the Field of the type. If no such default is provided by the user, the FieldType itself is asked for an "empty value" as the final fallback. The value chain for a specific field is therefore like this, when a Field of the FieldType is filled out:

1. 1. Is a value provided by the filling user?
   2. Is a default provided by the FieldDefinition?
   3. Take the empty value provided by the FieldType

validate()

In contrast to acceptValue() this method validates the plausibility of the given value, based on the FieldType settings and validator configuration, stored in the corresponding FieldDefinition.

array(
    'url'  => new Search\FieldType\StringField(),
    'text' => new Search\FieldType\StringField(),
)

<field name="article/name/value_s" type="string" indexed="true" stored="true" required="false"/>

array(
    'backupData' => array(
        'type' => 'bool',
        'default' => false
    ),
    'defaultValue' => array(
        'type' => 'string',
        'default' => 'Sindelfingen'
    )
);

array(
    'stringLength' => array(
        'minStringLength' => array(
            'type'    => 'int',
            'default' => 0,
        ),
        'maxStringLength' => array(
            'type'    => 'int'
            'default' => null,
        )
    ),
);

Testing

FieldType s should be integration tested on 1 different levels:

1. Their integration with the Persistence SPI
2. Their integration with the Public API

For both test environments, infrastructure is already in place, so that you can easily implement the required tests for your custom FieldType

$ phpunit -c phpunit.xml eZ/Publish/SPI/Tests/FieldType

Public API

On a second level, the interaction between an implementation of the Public API (aka the Business Layer) and the Field Type is tested. Again, there is a common base class as the infrastructural basis for such tests, which resides in eZ\Publish\API\Repository\Tests\FieldType\BaseIntegrationTest.

 

In this topic:

Table of Contents
maxLevel 3