[FEATURE] Use properties for configuration of Extbase attributes #1476
Description
ℹ️ View this commit on Github
👥 Authored by Elias Häußler [email protected]
✔️ Merged by Christian Kuhn [email protected]
Commit message
[FEATURE] Use properties for configuration of Extbase attributes
When Extbase annotations were added in TYPO3 v9, the possibility to
define configuration options was quite limited. All available options
needed to be defined in a single array. Since annotations were dropped
with #107229 in favor of PHP attributes, the definition of configuration
options is now possible in a more flexible way.
This patch serves as follow-up to #107229 and strives to improve the
attribute configuration option mechanism by using constructor property
promotion in combination with strictly typed properties. In order to
maintain backwards compatibility, the first property of each attribute
still accepts an array with configuration options to be passed. However,
this is considered deprecated and will be dropped with TYPO3 v15.0.
Developers are advised to migrate towards single properties when using
PHP attributes in Extbase.
Example migration
Before:
use TYPO3\CMS\Extbase\Attribute\FileUpload;
use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
class MyModel extends AbstractEntity
{
#[Validate(['validator' => 'NotEmpty'])]
protected string $foo = '';
#[FileUpload([
'validation' => [
'required' => true,
'maxFiles' => 1,
'fileSize' => ['minimum' => '0K', 'maximum' => '2M'],
'allowedMimeTypes' => ['image/jpeg', 'image/png'],
],
'uploadFolder' => '1:/user_upload/files/',
])]
protected ?FileReference $bar = null;
}
After:
use TYPO3\CMS\Extbase\Attribute\FileUpload;
use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
class MyModel extends AbstractEntity
{
#[Validate(validator: 'NotEmpty')]
protected string $foo = '';
#[FileUpload(
validation: [
'required' => true,
'maxFiles' => 1,
'fileSize' => ['minimum' => '0K', 'maximum' => '2M'],
'allowedMimeTypes' => ['image/jpeg', 'image/png'],
],
uploadFolder: '1:/user_upload/files/',
)]
protected ?FileReference $bar = null;
}
Resolves: #97559
Related: #107229
Releases: main
Change-Id: If93524006005cff07b7fe9037f806a6926079185
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/90296
Reviewed-by: Christian Kuhn [email protected]
Reviewed-by: Torben Hansen [email protected]
Tested-by: Lina Wolf [email protected]
Tested-by: Christian Kuhn [email protected]
Tested-by: Oliver Klee [email protected]
Tested-by: Torben Hansen [email protected]
Tested-by: core-ci [email protected]
Reviewed-by: Lina Wolf [email protected]
➕ Added files
14.0/Deprecation-97559-DeprecatePassingAnArrayOfConfigurationValuesToExtbaseAttributes.rst
.. include:: /Includes.rst.txt
.. _deprecation-97559-1760453281:
==============================================================================================
Deprecation: #97559 - Deprecate passing an array of configuration values to Extbase attributes
==============================================================================================
See :issue:`97559`
Description
===========
Passing an array of configuration values to Extbase attributes has been
deprecated. All configuration values should now be passed as single properties
using constructor property promotion. When an array of configuration values is
passed for the first available property in an attribute, a deprecation notice
will be triggered. The possibility to pass such an array will be removed with
TYPO3 v15.
Impact
======
The usage of constructor property promotion as alternative to an array of
configuration values enables type-safety and value hardening and pushes Extbase
attributes towards a modern configuration element for Models, DTOs, and
Controller actions.
Affected installations
======================
All installations which make use of Extbase attribute configuration are
affected, since this was previously only possible by passing an array of
configuration values.
Migration
=========
Use the available attribute properties instead of an array.
Before:
-------
.. code-block:: php
use TYPO3\CMS\Extbase\Attribute\FileUpload;
use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
class MyModel extends AbstractEntity
{
#[Validate(['validator' => 'NotEmpty'])]
protected string $foo = '';
#[FileUpload([
'validation' => [
'required' => true,
'maxFiles' => 1,
'fileSize' => ['minimum' => '0K', 'maximum' => '2M'],
'allowedMimeTypes' => ['image/jpeg', 'image/png'],
],
'uploadFolder' => '1:/user_upload/files/',
])]
protected ?FileReference $bar = null;
}
After:
------
.. code-block:: php
use TYPO3\CMS\Extbase\Attribute\FileUpload;
use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
class MyModel extends AbstractEntity
{
#[Validate(validator: 'NotEmpty')]
protected string $foo = '';
#[FileUpload(
validation: [
'required' => true,
'maxFiles' => 1,
'fileSize' => ['minimum' => '0K', 'maximum' => '2M'],
'allowedMimeTypes' => ['image/jpeg', 'image/png'],
],
uploadFolder: '1:/user_upload/files/',
)]
protected ?FileReference $bar = null;
}
Combined diff:
--------------
.. code-block:: diff
class MyModel extends AbstractEntity
{
- #[Validate(['validator' => 'NotEmpty'])]
+ #[Validate(validator: 'NotEmpty')]
protected string $foo = '';
- #[FileUpload([
- 'validation' => [
+ #[FileUpload(
+ validation: [
'required' => true,
'maxFiles' => 1,
'fileSize' => ['minimum' => '0K', 'maximum' => '2M'],
'allowedMimeTypes' => ['image/jpeg', 'image/png'],
],
- 'uploadFolder' => '1:/user_upload/files/',
- ])]
+ uploadFolder: '1:/user_upload/files/',
+ )]
protected ?FileReference $bar = null;
}
.. index:: PHP-API, NotScanned, ext:extbase
14.0/Feature-97559-UsePropertiesForConfigurationOfExtbaseAttributes.rst
.. include:: /Includes.rst.txt
.. _feature-97559-1760451913:
=============================================================================
Feature: #97559 - Support property-based configuration for Extbase attributes
=============================================================================
See :issue:`97559`
Description
===========
PHP attributes in Extbase context can now be configured using properties
instead of an array of configuration values. This resolves a limitation which
was present since the introduction of Extbase annotations back in TYPO3 v9,
where annotation configuration was quite limited – all available options
needed to be defined in a single array. Since annotations were dropped
with :issue:`107229` in favor of PHP attributes, the definition of configuration
options is now possible in a more flexible and typesafe way.
Example usage
-------------
.. code-block:: php
use TYPO3\CMS\Extbase\Attribute\FileUpload;
use TYPO3\CMS\Extbase\Attribute\Validate;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
class MyModel extends AbstractEntity
{
#[Validate(validator: 'NotEmpty')]
protected string $foo = '';
#[FileUpload(
validation: [
'required' => true,
'maxFiles' => 1,
'fileSize' => ['minimum' => '0K', 'maximum' => '2M'],
'allowedMimeTypes' => ['image/jpeg', 'image/png'],
],
uploadFolder: '1:/user_upload/files/',
)]
protected ?FileReference $bar = null;
}
Impact
======
This patch serves as follow-up to :issue:`107229` and thrives to improve the
attribute configuration option mechanism by using constructor property
promotion in combination with strictly typed properties. In order to maintain
backwards compatibility, the first property of each attribute still accepts an
array with configuration options to be passed. However, this is considered
deprecated and will be dropped with TYPO3 v15.0 (see :ref:`deprecation notice
<deprecation-97559-1760453281>`). Developers are advised to migrate towards
single properties when using PHP attributes in Extbase.
.. index:: PHP-API, ext:extbase