Extbase built-in type converters reference

Extbase selects a type converter automatically based on the PHP type declaration of the action parameter and the shape of the incoming request value. This page lists all converters shipped with TYPO3, their accepted source types, and the configuration constants they expose.

For an introduction to how type converters are selected and configured, see Property mapping: request arguments to objects.

On this page

Simple type converters

These converters handle PHP primitive types and arrays and are selected automatically whenever an action parameter is typed as int, float, bool, string, or array.

IntegerConverter

Class: IntegerConverter
Sources: integer, string
Target: integer
Priority: 10

Casts the source value to int. Returns an error object if the value is not numeric.

No configuration constants.

FloatConverter

Class: FloatConverter
Sources: float, integer, string
Target: float
Priority: 10

Casts the source value to float. When the source is a string, thousands separator and decimal point characters can be configured:

FloatConverter::CONFIGURATION_THOUSANDS_SEPARATOR: Character used as the thousands separator in the input string (for example '.' for German locale). Default: none.
FloatConverter::CONFIGURATION_DECIMAL_POINT: Character used as the decimal separator in the input string (for example ',' for German locale). Default: '.'.

BooleanConverter

Class: BooleanConverter
Sources: boolean, string
Target: boolean
Priority: 10

Casts the source value to bool via a PHP typecast.

No configuration constants.

StringConverter

Class: StringConverter
Sources: string, integer
Target: string
Priority: 10

Casts the source value to string via a PHP typecast.

No configuration constants.

ArrayConverter

Class: ArrayConverter
Sources: array, string
Target: array
Priority: 10

Passes an array source unchanged. If the source is a string, splits it on a configurable delimiter:

ArrayConverter::CONFIGURATION_DELIMITER: The delimiter character to split the string on. Required when the source is a non-empty string; throws a TypeConverterException if not set.
ArrayConverter::CONFIGURATION_REMOVE_EMPTY_VALUES: When true, filters out empty strings after splitting. Default: false.
ArrayConverter::CONFIGURATION_LIMIT: Maximum number of elements to return (passed as the third argument to explode()). Default: 0 (no limit).

DateTimeConverter

Class: DateTimeConverter
Sources: string, integer, array
Target: DateTime (or DateTimeImmutable)
Priority: 10

Converts a string, Unix timestamp, or array of date parts into a \DateTime or \DateTimeImmutable object.

DateTimeConverter::CONFIGURATION_DATE_FORMAT: The format string passed to \DateTime::createFromFormat(). Defaults to \DateTime::W3C. Set this if your form sends a date in a locale format (for example 'd.m.Y').

EXT:my_extension/Classes/Controller/ConferenceController.php

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Domain\Model\Conference;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
use TYPO3\CMS\Extbase\Property\TypeConverter\DateTimeConverter;

class ConferenceController extends ActionController
{
    public function initializeCreateAction(): void
    {
        $this->arguments['conference']
            ->getPropertyMappingConfiguration()
            ->forProperty('conferenceDate')
            ->setTypeConverterOption(
                DateTimeConverter::class,
                DateTimeConverter::CONFIGURATION_DATE_FORMAT,
                'd.m.Y',
            );
    }

    public function createAction(Conference $conference): ResponseInterface
    {
        // ...
        return $this->htmlResponse();
    }
}

Object type converters

These converters handle PHP objects and are selected automatically when an action parameter is typed as a domain object, an enum, or ObjectStorage.

PersistentObjectConverter

Class: PersistentObjectConverter
Sources: integer, string, array
Target: AbstractDomainObject (and subclasses)
Priority: 20

The converter used for domain object parameters. If the source is an integer or plain string, it loads the record with that UID from the repository. If the source is an array, it maps array keys to object properties (and optionally creates or modifies the object):

PersistentObjectConverter::CONFIGURATION_MODIFICATION_ALLOWED: Set to true to allow property updates on an object that already has a UID. Required when an array payload includes an __identity key alongside changed properties.
PersistentObjectConverter::CONFIGURATION_CREATION_ALLOWED: Set to true to allow creating a new object from an array payload that carries no __identity key.

Both constants default to false. When a __trustedProperties token is present (generated by <f:form>), Extbase enables or disables them automatically based on whether an __identity field was rendered.

ObjectConverter

Class: ObjectConverter
Sources: array
Target: object
Priority: 10

Creates a plain (non-persistent) PHP object from an array of constructor arguments or property values. Used for value objects and DTO classes that do not extend AbstractDomainObject.

ObjectConverter::CONFIGURATION_TARGET_TYPE: Override the concrete class to instantiate (must be a subclass of the declared target type).
ObjectConverter::CONFIGURATION_OVERRIDE_TARGET_TYPE_ALLOWED: Set to true to permit the CONFIGURATION_TARGET_TYPE override. Disabled by default as a security measure.

ObjectStorageConverter

Class: ObjectStorageConverter
Sources: string, array
Target: ObjectStorage
Priority: 10

Converts an array (or comma-separated string) into an ObjectStorage. Each element is converted individually using the converter registered for the storage's generic type.

No configuration constants.

EnumConverter

Class: EnumConverter
Sources: string, integer, float
Target: object (any \UnitEnum subclass)
Priority: 20

New in version 14.0

Converts a scalar value to a PHP backed enum case. For backed enums the source value is matched against the value of each case. For pure (unit) enums it is matched against the case name.

No configuration constants.

TYPO3 Core type converters

These converters handle TYPO3-specific types and are selected automatically for the relevant action parameters.

CoreTypeConverter

Class: CoreTypeConverter
Sources: string, integer, float, boolean, array
Target: TypeInterface
Priority: 10

Handles TYPO3 Core value types that implement TypeInterface, such as \Enumeration subclasses.

No configuration constants.

CountryConverter

Class: CountryConverter
Sources: string
Target: Country
Priority: 10

Looks up a Country object by ISO code. Defaults to matching alpha-2 codes (for example 'DE'):

CountryConverter::CONFIGURATION_FROM

How to match the source string. Accepted values:

'alpha2IsoCode' (default) — two-letter ISO 3166-1 alpha-2 code.
'alpha3IsoCode' — three-letter ISO 3166-1 alpha-3 code.

FAL type converters

Warning

These three converter classes are @internal at the class level and are not part of the public Extbase API. Their behaviour or existence may change without notice.

FileConverter: Converts an integer (file UID) or string to a File object.
FileReferenceConverter: Converts an integer (file reference UID) to a FileReference object.
FolderConverter: Converts a string (folder combined identifier) to a Folder object.

Writing a custom type converter

There are no PHP attributes for registering type converters. Registration requires an extbase.type_converter service tag in Configuration/Services.yaml.

Implement TypeConverterInterface (or extend AbstractTypeConverter). Then register it via a service tag in Configuration/Services.yaml:

EXT:my_extension/Classes/Property/TypeConverter/IsbnConverter.php

namespace MyVendor\MyExtension\Property\TypeConverter;

use TYPO3\CMS\Extbase\Property\PropertyMappingConfigurationInterface;
use TYPO3\CMS\Extbase\Property\TypeConverter\AbstractTypeConverter;

class IsbnConverter extends AbstractTypeConverter
{
    public function convertFrom(
        $source,
        string $targetType,
        array $convertedChildProperties = [],
        ?PropertyMappingConfigurationInterface $configuration = null,
    ): mixed {
        // return the converted value or a \TYPO3\CMS\Extbase\Error\Error instance
    }
}

EXT:my_extension/Configuration/Services.yaml

MyVendor\MyExtension\Property\TypeConverter\IsbnConverter:
  tags:
    - name: extbase.type_converter
      priority: 10
      target: MyVendor\MyExtension\Domain\Model\Isbn
      sources: string

The priority determines which converter wins when multiple converters match the same source-and-target combination. Higher numbers win.