Upgrading from older Extbase versions

Note

This page is a work in progress. Content will be added as part of the Extbase documentation rewrite for TYPO3 v14.

This page collects breaking changes and the migration steps needed when upgrading an Extbase extension to a newer TYPO3 version. Each entry names what changed, which version introduced the change, and what to do.

Tip

Many migrations can be automated, and TYPO3 Rector ( ssch/typo3-rector ) provides rules to do so. The tool is actively maintained and extended for each TYPO3 version to be released.

On this page

Annotations replaced by PHP attributes (TYPO3 v12 / required from v14)

Changed in version 14.0

DocBlock annotation support was fully removed. Extbase ignores annotations silently — no error is thrown.

Native PHP attributes (introduced in PHP 8.0) replace the Doctrine-based DocBlock annotation syntax. Extbase has supported PHP attributes since TYPO3 v12; in TYPO3 v14 the annotation syntax was removed entirely.

Old annotation (removed in v14)	New PHP attribute
`@Extbase\ORM\Lazy`	`#[Lazy]`
`@Extbase\ORM\Cascade("remove")`	`#[Cascade('remove')]`
`@Extbase\ORM\Transient`	`#[Transient]`
`@Extbase\Validate(...)`	`#[Validate(...)]`
`@Extbase\IgnoreValidation`	`#[IgnoreValidation]`

EXT:my_extension/Classes/Domain/Model/Entity.php

 use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
+use TYPO3\CMS\Extbase\Attribute\ORM\Lazy;
 use TYPO3\CMS\Extbase\Persistence\ObjectStorage;

 class Entity extends AbstractEntity
 {
-    /**
-     * @var ObjectStorage<ChildEntity>
-     * @TYPO3\CMS\Extbase\Annotation\ORM\Lazy
-     */
+    #[Lazy]
     protected ObjectStorage $property;
 }

Attribute namespace moved from Annotation to Attribute (TYPO3 v14)

Changed in version 14.0

The namespace \TYPO3\CMS\Extbase\Annotation is deprecated. Class aliases remain available in v14 but will be removed in v15. Update your use statements to \TYPO3\CMS\Extbase\Attribute when dropping TYPO3 v13 support.

All Extbase attributes moved from \TYPO3\CMS\Extbase\Annotation to \TYPO3\CMS\Extbase\Attribute.

Attribute array syntax deprecated (TYPO3 v14, removed in v15)

Changed in version 14.0

Passing a configuration array as the first argument to Extbase attributes is deprecated (Deprecation #97559). The array-based syntax still works in v14 but will be removed in v15.

Old array syntax (deprecated in v14)	New named-argument syntax
`#[Cascade(['value' => 'remove'])]`	`#[Cascade('remove')]`
`#[Validate(['validator' => 'NotEmpty'])]`	`#[Validate('NotEmpty')]`

Important

There is no attribute syntax that is compatible with both TYPO3 v13 and v14. PHP attributes are parsed statically and cannot be conditionally defined based on the TYPO3 version. Extensions supporting both versions in the same release must keep the array-based syntax and accept the deprecation warning in v14.

Magic findBy(), findOneBy(), countBy*() methods removed (TYPO3 v14)

Changed in version 14.0

Magic property-name methods were deprecated in TYPO3 v12.3 and removed in v14. Replace them with the explicit array-based signatures.

Old (removed in v14)	New
`findByTitle($value)`	`findBy(['title' => $value])`
`findOneByTitle($value)`	`findOneBy(['title' => $value])`
`countByTitle($value)`	`count(['title' => $value])`

findByUid() and findByIdentifier() are not affected and remain available.