At the moment, no documentation is available that references our FieldTypes.

Each of them has specifics that are really critical for developers, as they impact both Public API code as well as REST calls, for both read & write.

Documenting those requires a walkthrough of each Type & Value class in eZ/Publish/Core/FieldType.

Note: as it is very likely that new field types will be introduced over time, this documentation should be built as easily extensible. The doc format should also be reusable, as it is very likely that extensions will provide custom field types.

Referenced data

1. Validators
2. Value object
3. Input expectations
4. Output fields / format

Where to get the data from

Validators

Validators for a FieldType can be found in the Type class for the FieldType, such as FieldType\TextLine\Type for TextLine.

Which validators a Type support is defined in the $validatorConfigurationSchema property:

protected $validatorConfigurationSchema = array(
    'StringLengthValidator' => array(
        'minStringLength' => array(
            'type' => 'int',
            'default' => 0
        ),
        'maxStringLength' => array(
            'type' => 'int',
            'default' => null
        )
    )
);

In this case, the type supports one validator: StringLengthValidator. This validator has two properties: minStringLength and maxStringLength. Both have a value of 0, that means disabled (this can't be guessed from the array. The validateValidatorConfiguration method needs to be inspected for that)

Value objects

Each FieldType comes with its very own Value class (see {{TextLine/Value. This one has to be documented, even though automatically generated documentation should and could be used here, but we haven't worked on it yet. Maybe this can be considered.

I see 3 things that can be documented for the Value:

• the properties (like TextLine\Value::$text. Some Value objects have several, others have one value of a complex type (like Author\Value::$authors or of a simple type, like TextLine.
• what the constructor accepts as an argument. The one for TextLine accepts a string, while Author expects a structured hash of authors. In most cases, it is necessary to follow the ctor code in order to figure out what it does with the input value.
• the __toString() format the type generates. The only way is to test it or analyze the code.

Input expectations

Field values are set using $contentCreateStruct->setField( $fieldIdentifier, $value[, $languageCode ). $value can always be a Value of the used Type. But other values are possible, depending on each type.

Values provided to setField are sent to the AcceptValue() method, that calls internalAcceptValue(), defined by each FieldType class. In TextLine\Type::internalAcceptValue we can see that we first check if the parameter is a primitive string, and create a TextLine\Value from it if it is.

Some field types will accept many formats, while others will only accept one. DateTime\Type::internalAcceptValue() is a good example of a very polymorphic Field Type.

Another input value is the hash input format, which is used by REST when providing Field values. To determine which keys are accepted, the fromHash() method of the FieldType must be inspected. Most of those will just pass on the hash to Value, in which case the documentation for Value::__construct is enough, but others may behave differently.