---
title: "Property mapping: request arguments to objects"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:extbase-property-mapping@main"
source: "ExtensionArchitecture/Extbase/Controller/PropertyMapping.rst"
rendered: "2026-09-23T16:24:37+00:00"
---

# Property mapping: request arguments to objects {#extbase-property-mapping}

Property mapping is the process by which Extbase converts raw request
arguments into typed PHP values and domain objects before they reach an action
method. Those arguments arrive from GET parameters (the query string), POST
parameters (the form body), or a combination of both — as a
PSR-7
server request. Extbase extracts the relevant values and converts them
automatically, so action methods receive typed objects rather than raw strings.

**On this page**

-   [How Extbase property mapping works](https://docs.typo3.org/permalink/t3coreapi:how-extbase-property-mapping-works@main)
-   [Mass assignment protection and the trusted-properties token](https://docs.typo3.org/permalink/t3coreapi:mass-assignment-protection-and-the-trusted-properties-token@main)
-   [Configuring Extbase type converters](https://docs.typo3.org/permalink/t3coreapi:configuring-extbase-type-converters@main)
-   [Manually allowing properties on Extbase action arguments](https://docs.typo3.org/permalink/t3coreapi:manually-allowing-properties-on-extbase-action-arguments@main)
-   [Allowing creation and modification of nested Extbase objects](https://docs.typo3.org/permalink/t3coreapi:allowing-creation-and-modification-of-nested-extbase-objects@main)

## How Extbase property mapping works {#extbase-property-mapping-how-to}

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](https://www.php.net/manual/en/class.datetime.php) or
    [\\DateTimeImmutable](https://www.php.net/manual/en/class.datetimeimmutable.php)
    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 `\TYPO3\CMS\Extbase\DomainObject\AbstractDomainObject`)
    are constructed from an array of submitted values via the
    `\TYPO3\CMS\Extbase\Property\TypeConverter\ObjectConverter`.
-   File uploads arrive as
    [PSR-7 UploadedFileInterface](https://www.php.net/manual/en/class.psr-http-message-uploadedfileinterface.php)
    objects and are handled by the
    `\TYPO3\CMS\Extbase\Property\TypeConverter\FileConverter` or
    `\TYPO3\CMS\Extbase\Property\TypeConverter\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](https://docs.typo3.org/permalink/t3coreapi:extbase-appendix-typeconverters-custom@main).

## Mass assignment protection and the trusted-properties token {#extbase-controller-propertymapping-trusted}

To prevent
[mass assignment](https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/07-Input_Validation_Testing/20-Testing_for_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](https://docs.typo3.org/permalink/t3coreapi:extbase-controller-propertymapping-allowproperties@main).

## Configuring Extbase type converters {#extbase-controller-propertymapping-typeconverters}

Each type converter exposes configuration constants that can be set via
`setTypeConverterOption()`. The most common example is configuring the
date format for
`\TYPO3\CMS\Extbase\Property\TypeConverter\DateTimeConverter`:

**EXT:my_extension/Classes/Controller/ConferenceController.php**

```php
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.

> [!NOTE]
> **See also**
>
> -   [Built-in type converters reference](https://docs.typo3.org/permalink/t3coreapi:extbase-appendix-typeconverters@main)
>     for all converters, their source/target types, and configuration constants.
> -   [Writing a custom type converter](https://docs.typo3.org/permalink/t3coreapi:extbase-appendix-typeconverters-custom@main)
>     for how to implement and register a converter for your own types.

## Manually allowing properties on Extbase action arguments {#extbase-controller-propertymapping-allowproperties}

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:

**EXT:my_extension/Classes/Controller/ConferenceController.php**

```php
<?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
`\TYPO3\CMS\Extbase\Mvc\Controller\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:

**EXT:my_extension/Classes/Controller/ConferenceController.php**

```php
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](https://docs.typo3.org/permalink/t3coreapi:extbase-appendix-pitfalls-property-mapping-denied@main)
in the common pitfalls appendix.

## Allowing creation and modification of nested Extbase objects {#extbase-controller-propertymapping-creation-modification}

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
`\TYPO3\CMS\Extbase\Property\TypeConverter\PersistentObjectConverter`:

**EXT:my_extension/Classes/Controller/ConferenceController.php**

```php
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,
    );
}
```

> [!NOTE]
> **See also**
>
> -   [Extbase validation](https://docs.typo3.org/permalink/t3coreapi:extbase-validation-overview@main)
>     for how to add validation rules to action parameters and model properties via
>     `#[Validate]` attributes.
> -   [errorAction: Extbase validation and argument-mapping errors](https://docs.typo3.org/permalink/t3coreapi:extbase-controller-action-error@main)
>     for what happens when property mapping or validation fails.