Property mapping: request arguments to objects 

How Extbase property mapping works 

When a request arrives, Extbase inspects the type declaration of each action parameter and runs the matching type converter:

• A parameter typed int, string or bool is cast directly.
• A parameter typed as a domain object (for example Conference) receives a UID from the request — either as a plain integer or as an array containing an __identity key. Extbase uses that identity to load the corresponding record from the repository and passes the hydrated object to the action. Additional array keys alongside __identity are mapped onto the object's properties, enabling update forms to submit both the identity of an existing record and its changed values in one request. The same mechanism works for child relations: a nested array with its own __identity key identifies a related object.
• A parameter typed as a \DateTime or \DateTimeImmutable parses the string value according to a configurable format.
• A parameter typed as array receives the submitted array directly — useful for multi-select inputs and other array-valued form fields.
• A parameter typed as a backed PHP enum is converted from its scalar backing value automatically.
• Plain PHP objects and DTO classes (those not extending AbstractDomainObject ) are constructed from an array of submitted values via the ObjectConverter .
• File uploads arrive as PSR-7 UploadedFileInterface objects and are handled by the FileConverter or FileReferenceConverter for FAL-backed uploads.

If conversion fails, for example, because a UID does not exist in the database, Extbase calls errorAction() instead of the action method.

For any type not covered by the built-in converters, you can register a custom type converter — see Writing a custom type converter.

Mass assignment protection and the trusted-properties token 

To prevent mass assignment attacks, Extbase only writes properties that have been explicitly "allowlisted". When a form is built with <f:form>, this allowlisting happens automatically and transparently: the ViewHelper generates a __trustedProperties token — an HMAC-signed list of every field rendered in the form. On submission, Extbase reads the token, verifies its signature, and permits exactly those properties. Whether to allow creation or modification of a persistent object is also derived from the token automatically, based on whether an __identity field is present.

For the standard Extbase workflow, Fluid form → controller action, no additional configuration is needed. If your request does not originate from a <f:form> (URL parameters, hand-built forms, JSON payloads), see Manually allowing properties on Extbase action arguments.

Configuring Extbase type converters 

Each type converter exposes configuration constants that can be set via setTypeConverterOption(). The most common example is configuring the date format for DateTimeConverter :

use TYPO3\CMS\Extbase\Property\TypeConverter\DateTimeConverter;

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

TYPO3 ships type converters for common scalar types, date/time, arrays, integers, floats, and persistent objects. Extensions can register additional converters.

Manually allowing properties on Extbase action arguments 

Manual allowlisting is only needed when the request does not carry a __trustedProperties token — for example when receiving URL parameters directly, processing a custom form that omits the ViewHelper, or consuming a JSON payload. If you are using <f:form>, you do not need this.

Define a method named initialize + the capitalized action method name + Action (for example initializeCreateAction() before createAction()). Extbase calls it automatically before the action:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Domain\Model\Conference;
use MyVendor\MyExtension\Domain\Repository\ConferenceRepository;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class ConferenceController extends ActionController
{
    public function __construct(
        protected readonly ConferenceRepository $conferenceRepository,
    ) {}

    public function initializeCreateAction(): void
    {
        $this->arguments['conference']
            ->getPropertyMappingConfiguration()
            ->allowProperties('title', 'conferenceDate');
    }

    public function createAction(Conference $conference): ResponseInterface
    {
        $this->conferenceRepository->add($conference);
        return $this->redirect('list');
    }
}

Key methods on MvcPropertyMappingConfiguration :

allowProperties('title', 'conferenceDate')

Allows an explicit list of properties and denies everything else. Prefer this over allowAllProperties() when the set of fields is known upfront.

allowAllProperties()

Allows every property of the argument. Use with care — it trusts all submitted field names for this argument.

allowAllPropertiesExcept('uid', 'pid')

Allows everything except the listed properties.

For nested objects (for example a Conference that has a related Speaker), use forProperty() to reach into the sub-object. This goes inside the same initializeCreateAction() method:

public function initializeCreateAction(): void
{
    $mappingConfig = $this->arguments['conference']->getPropertyMappingConfiguration();
    $mappingConfig->allowProperties('title', 'speaker');
    $mappingConfig->forProperty('speaker')->allowProperties('name');
}

If a domain object arrives with all properties set to their default values even though the form contains data, see Property mapping denied: form fields not saved without a trusted-properties token in the common pitfalls appendix.

Allowing creation and modification of nested Extbase objects 

When a request (without a __trustedProperties token) submits a nested object that does not yet have a UID (creation) or has a UID and additional fields (modification), you must explicitly unlock those operations on the PersistentObjectConverter :

use TYPO3\CMS\Extbase\Property\TypeConverter\PersistentObjectConverter;

public function initializeCreateAction(): void
{
    $speakerConfig = $this->arguments['conference']
        ->getPropertyMappingConfiguration()
        ->forProperty('speaker');

    $speakerConfig->setTypeConverterOption(
        PersistentObjectConverter::class,
        PersistentObjectConverter::CONFIGURATION_CREATION_ALLOWED,
        true,
    );

    $speakerConfig->setTypeConverterOption(
        PersistentObjectConverter::class,
        PersistentObjectConverter::CONFIGURATION_MODIFICATION_ALLOWED,
        true,
    );
}