The field type interface which all field types have to implement.
Hashes:
The FieldType::toHash() method in this class is meant to generate a simple representation of a value of this field type. Hash does here not refer to MD5 or similar hashing algorithms, but rather to hash-map (associative array) type representation. This representation must be usable, to transfer the value over plain text encoding formats, like e.g. XML. As a result, the returned "hash" must either be a scalar value, a hash array (associative array) a pure numeric array or a nested combination of these. It must by no means contain objects, resources or cyclic references. The corresponding FieldType::fromHash() method must convert such a representation back into a value, which is understood by the FieldType.
Properties¶
$serializer
¶
|
|
|
$validator
¶
|
|
|
Methods¶
__construct()
¶
|
|
|
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $serializer | ValueSerializerInterface | - | - |
| $validator | ValidatorInterface | - | - |
acceptValue()
¶
Potentially builds and checks the type and structure of the $inputValue.
|
|
|
This method first inspects $inputValue and convert it into a dedicated value object.
After that, the value is checked for structural validity. Note that this does not include validation after the rules from validators, but only plausibility checks for the general data format.
Note that this method must also cope with the empty value for the field type as e.g. returned by FieldType::getEmptyValue().
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $inputValue | mixed | - | - |
Return values
The potentially converted and structurally plausible value.
applyDefaultSettings()
¶
Applies the default values to the fieldSettings of a FieldDefinitionCreateStruct.
|
|
|
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $fieldSettings | mixed | - | - |
applyDefaultValidatorConfiguration()
¶
Applies the default values to the given $validatorConfiguration of a FieldDefinitionCreateStruct.
|
|
|
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $validatorConfiguration | mixed | - | - |
fieldSettingsFromHash()
¶
Converts the given $fieldSettingsHash to field settings of the type.
|
|
|
This is the reverse operation of FieldType::fieldSettingsToHash(). See the class description for more details on a hash format.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $fieldSettingsHash | mixed | - | - |
fieldSettingsToHash()
¶
Converts the given $fieldSettings to a simple hash format.
|
|
|
See the class description for more details on a hash format.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $fieldSettings | mixed | - | - |
Return values
array<string|int, mixed>|scalar|null
fromHash()
¶
Converts an $hash to the Value defined by the field type.
|
|
|
This is the reverse operation to FieldType::toHash(). At least the hash format generated by FieldType::toHash() must be converted in reverse. Additional formats might be supported in the rare case that this is necessary. See the class description for more details on a hash format.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $hash | mixed | - | - |
Return values
fromPersistenceValue()
¶
Converts a persistence $value to a Value.
|
|
|
This method builds a field type value from the $data and $externalData properties.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $fieldValue | FieldValue | - | - |
Return values
getEmptyValue()
¶
Returns the empty value for this field type.
|
|
|
This value will be used, if no value was provided for a field of this type and no default value was specified in the field definition. It is also used to determine that a user intentionally (or unintentionally) did not set a non-empty value.
Return values
getFieldTypeIdentifier()
¶
Returns the field type identifier for this field type.
|
|
|
This identifier should be globally unique and the implementer of a FieldType must take care for the uniqueness. It is therefore recommended to prefix the field-type identifier by a unique string that identifies the implementer. A good identifier could for example take your companies main domain name as a prefix in reverse order.
Return values
string
getName()
¶
Returns a human readable string representation from a given value.
|
|
|
It will be used to generate content name and url alias if current field is designated to be used in the content name/urlAlias pattern.
The used $value can be assumed to be already accepted by FieldType::acceptValue().
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $value | Value | - | - |
| $fieldDefinition | FieldDefinition | - | - |
| $languageCode | string | - | - |
Return values
string
getRelations()
¶
Returns relation data extracted from value.
|
|
|
Not intended for \Ibexa\Contracts\Core\Repository\Values\Content\Relation::COMMON type relations, there is an API for handling those.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $value | Value | - | - |
Return values
array<string|int, mixed>
Hash with relation type as key and array of destination content ids as value.
Example:
array(
\Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK => array(
"contentIds" => array( 12, 13, 14 ),
"locationIds" => array( 24 )
),
\Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED => array(
"contentIds" => array( 12 ),
"locationIds" => array( 24, 45 )
),
\Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD => array( 12 )
)
getSettingsSchema()
¶
Returns a schema for the settings expected by the FieldType.
|
|
|
Returns an arbitrary value, representing a schema for the settings of the FieldType.
Explanation: There are no possible generic schemas for defining settings input, which is why no schema for the return value of this method is defined. It is up to the implementer to define and document a schema for the return value and document it. In addition, it is necessary that all consumers of this interface (e.g. Public API, REST API, GUIs, ...) provide plugin mechanisms to hook adapters for the specific FieldType into. These adapters then need to be either shipped with the FieldType or need to be implemented by a third party. If there is no adapter available for a specific FieldType, it will not be usable with the consumer.
getValidatorConfigurationSchema()
¶
Returns a schema for the validator configuration expected by the FieldType.
|
|
|
Returns an arbitrary value, representing a schema for the validator configuration of the FieldType.
Explanation: There are no possible generic schemas for defining settings input, which is why no schema for the return value of this method is defined. It is up to the implementer to define and document a schema for the return value and document it. In addition, it is necessary that all consumers of this interface (e.g. Public API, REST API, GUIs, ...) provide plugin mechanisms to hook adapters for the specific FieldType into. These adapters then need to be either shipped with the FieldType or need to be implemented by a third party. If there is no adapter available for a specific FieldType, it will not be usable with the consumer.
Best practice:
It is considered best practice to return a hash map, which contains rudimentary settings structures, like e.g. for the "ezstring" FieldType
array(
'stringLength' => array(
'minStringLength' => array(
'type' => 'int',
'default' => 0,
),
'maxStringLength' => array(
'type' => 'int'
'default' => null,
)
),
);
isEmptyValue()
¶
Returns if the given $value is considered empty by the field type.
|
|
|
Usually, only the value returned by FieldType::getEmptyValue() is considered empty. The given $value can be safely assumed to have already been processed by FieldType::acceptValue().
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $value | Value | - | - |
Return values
bool
isSearchable()
¶
Indicates if the field type supports indexing and sort keys for searching.
|
|
|
Return values
bool
isSingular()
¶
Indicates if the field definition of this type can appear only once in the same ContentType.
|
|
|
Return values
bool
onlyEmptyInstance()
¶
Indicates if the field definition of this type can be added to a ContentType with Content instances.
|
|
|
Return values
bool
toHash()
¶
Converts the given $value into a plain hash format.
|
|
|
Converts the given $value into a plain hash format, which can be used to transfer the value through plain text formats, e.g. XML, which do not support complex structures like objects. See the class level doc block for additional information. See the class description for more details on a hash format.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $value | Value | - | - |
toPersistenceValue()
¶
Converts a $value to a persistence value.
|
|
|
In this method the field type puts the data which is stored in the field of content in the repository into the property FieldValue::data. The format of $data is a primitive, an array (map) or an object, which is then canonically converted to e.g. json/xml structures by future storage engines without further conversions. For mapping the $data to the legacy database an appropriate Converter (implementing Converter) has implemented for the field type. Note: $data should only hold data which is actually stored in the field. It must not hold data which is stored externally.
The $externalData property in the FieldValue is used for storing data externally by the FieldStorage interface method storeFieldData.
The FieldValuer::sortKey is build by the field type for using by sort operations.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $value | Value | - |
The value of the field type |
Return values
the value processed by the storage engine
validate()
¶
Validates a field based on the validator configuration in the field definition.
|
|
|
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $fieldDefinition | FieldDefinition | - | - |
| $value | Value | - |
The field value for which an action is performed |
Return values
array<string|int, ValidationError>
validateFieldSettings()
¶
Validates the fieldSettings of a FieldDefinitionCreateStruct or FieldDefinitionUpdateStruct.
|
|
|
This methods determines if the given $fieldSettings are structurally correct and comply to the settings schema returned by FieldType::getSettingsSchema().
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $fieldSettings | mixed | - | - |
Return values
array<string|int, ValidationError>
validateValidatorConfiguration()
¶
Validates the validatorConfiguration of a FieldDefinitionCreateStruct or FieldDefinitionUpdateStruct.
|
|
|
This methods determines if the given $validatorConfiguration is structurally correct and complies to the validator configuration schema returned by FieldType::getValidatorConfigurationSchema().
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $validatorConfiguration | mixed | - | - |
Return values
array<string|int, ValidationError>
validatorConfigurationFromHash()
¶
Converts the given $validatorConfigurationHash to a validator configuration of the type.
|
|
|
See the class description for more details on a hash format.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $validatorConfiguration | mixed | - | - |
validatorConfigurationToHash()
¶
Converts the given $validatorConfiguration to a simple hash format.
|
|
|
See the class description for more details on a hash format.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $validatorConfiguration | mixed | - | - |
Return values
array<string|int, mixed>|scalar|null
checkValueType()
¶
Throws an exception if the given $value is not an instance of the supported value subtype.
|
|
|
This is an operation method for acceptValue().
Default implementation expects the value class to reside in the same namespace as its FieldType class and is named "Value".
Example implementation:
protected function checkValueType($value): void
{
if ( !$inputValue instanceof \My\FieldType\CookieJar\Value ) )
{
throw new InvalidArgumentException( "Given value type is not supported." );
}
}
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $value | mixed | - |
A value returned by createValueFromInput(). |
Tags
createValueFromInput()
¶
Inspects given $inputValue and potentially converts it into a dedicated value object.
|
|
|
If given $inputValue could not be converted or is already an instance of dedicate value object, the method should simply return it.
This is an operation method for acceptValue().
Example implementation:
protected function createValueFromInput( $inputValue )
{
if ( is_array( $inputValue ) )
{
$inputValue = \My\FieldType\CookieJar\Value( $inputValue );
}
return $inputValue;
}
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $inputValue | mixed | - | - |
Return values
mixed
The potentially converted input value.
getFieldSettingsConstraints()
¶
|
|
|
Return values
Collection|null
Tags
getFieldValueConstraints()
¶
|
|
|
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $fieldDefinition | FieldDefinition | - | - |
Return values
Collection|null
Tags
getSortInfo()
¶
Returns information for FieldValue->$sortKey relevant to the field type.
|
|
|
Return value is mixed. It should be something which is sensible for sorting.
It is up to the persistence implementation to handle those values. Common string and integer values are safe.
For the legacy storage it is up to the field converters to set this value in either sort_key_string or sort_key_int.
In case of multi value, values should be string and separated by "-" or ",".
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $value | Value | - | - |
getValueClass()
¶
Returns FQN of class representing Field Type Value.
|
|
|
Return values
string
mapConstraintViolationList()
¶
|
|
|
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| $constraintViolationList | ConstraintViolationListInterface | - | - |
Return values
array<string|int, mixed>