All Extbase repositories inherit from \TYPO3\CMS\Extbase\Persistence\Repository.

A repository is always responsible for precisely one type of domain object.

The naming of the repositories is important: If the domain object is, for example, Blog (with full name \FriendsOfTYPO3\BlogExample\Domain\Model\Blog), then the corresponding repository is named BlogRepository (with the full name \FriendsOfTYPO3\BlogExample\Domain\Repository\BlogRepository).

The \TYPO3\CMS\Extbase\Persistence\Repository already offers a large number of useful functions. Therefore, in simple classes that extend the Repository class and leaving the class empty otherwise is sufficient.

The BlogRepository sets some default orderings and is otherwise empty:

Class T3docs\BlogExample\Domain\Repository\BlogRepository
class BlogRepository extends Repository


Find methods

New in version 12.3.

The Repository class provides the following methods for querying against arbitrary criteria:

findBy(array $criteria, array $orderBy = null, int $limit = null, int $offset = null): QueryResultInterface

Finds all objects with the provided criteria.

findOneBy(array $criteria, array $orderBy = null): object|null

Returns the first object found with the provided criteria.

count(array $criteria): int

Counts all objects with the provided criteria.


$this->blogRepository->findBy(['author' => 1, 'published' => true]);

Custom find methods

Custom find methods can be implemented. They can be used for complex queries.


As Extbase repositories turn the results into objects, querying large amounts of data is resource-intensive.


The PostRepository of the EXT:blog example extension implements several custom find methods, two of them are shown below:

Class T3docs\BlogExample\Domain\Repository\PostRepository
use T3docs\BlogExample\Domain\Model\Blog;
use TYPO3\CMS\Extbase\Persistence\QueryInterface;
use TYPO3\CMS\Extbase\Persistence\QueryResultInterface;

class PostRepository extends Repository
    public function findByTagAndBlog(
        string $tag,
        Blog $blog
    ): QueryResultInterface {
        $query = $this->createQuery();
        return $query
                    $query->equals('blog', $blog),
                    $query->equals('', $tag)

    public function findAllSortedByCategory(array $uids): QueryResultInterface
        $q = $this->createQuery();
        $q->matching($q->in('uid', $uids));
            'categories.title' => QueryInterface::ORDER_ASCENDING,
            'uid' => QueryInterface::ORDER_ASCENDING,
        return $q->execute();

Magic find methods

Deprecated since version 12.3: As these methods are widely used in almost all Extbase-based extensions, they are marked as deprecated in TYPO3 v12, but will only trigger a deprecation notice in TYPO3 v13, as they will be removed in TYPO3 v14. Migrate the usage of these methods to the new find methods.

The Repository class creates "magic" methods to find by attributes of model.


Finds all objects with the provided property.


Returns the first object found with the provided property.


Counts all objects with the provided property.

If necessary, these methods can also be overridden by implementing them in the concrete repository.


findBy[PropertyName]($propertyValue) can be replaced with a call to findBy():

$this->myRepository->findBy(['propertyName' => $propertyValue]);

findOneBy[PropertyName]($propertyValue) can be replaced with a call to findOneBy:

$this->myRepository->findOneBy(['propertyName' => $propertyValue]);

countBy[PropertyName]($propertyValue) can be replaced with a call to count:

$this->myRepository->count(['propertyName' => $propertyValue]);

Query settings

If the query settings should be used for all methods in the repository, they should be set in the method initializeObject() method.

Class T3docs\BlogExample\Domain\Repository\CommentRepository
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface;
use TYPO3\CMS\Extbase\Persistence\Generic\Typo3QuerySettings;

class CommentRepository extends Repository
    public function initializeObject()
        /** @var QuerySettingsInterface $querySettings */
        $querySettings = GeneralUtility::makeInstance(Typo3QuerySettings::class);
        // Show comments from all pages


Depending on the query settings, hidden or even deleted objects can become visible. This might cause sensitive information to be disclosed. Use with care.

If you only want to change the query settings for a specific method, they can be set in the method itself:

Class T3docs\BlogExample\Domain\Repository\CommentRepository
use TYPO3\CMS\Extbase\Persistence\QueryResultInterface;

class CommentRepository extends Repository
    public function findAllIgnoreEnableFields(): QueryResultInterface|array
        $query = $this->createQuery();
        return $query->execute();

Repository API

class TYPO3\CMS\Extbase\Persistence\Repository

The base repository - will usually be extended by a more concrete repository.

injectPersistenceManager(TYPO3\\CMS\\Extbase\\Persistence\\PersistenceManagerInterface $persistenceManager)
  • $persistenceManager (TYPO3\CMS\Extbase\Persistence\PersistenceManagerInterface) -- the persistenceManager

add(object $object)

Adds an object to this repository

  • $object (object) -- The object to add

remove(object $object)

Removes an object from this repository.

  • $object (object) -- The object to remove

update(object $modifiedObject)

Replaces an existing object with the same identifier by the given object

  • $modifiedObject (object) -- The modified object


Returns all objects of this repository.


Returns the total number objects of this repository.


Removes all objects of this repository as if remove() was called for all of them.

findByUid(int $uid)

Finds an object matching the given identifier.

  • $uid (int) -- The identifier of the object to find

findByIdentifier(mixed $identifier)

Finds an object matching the given identifier.

  • $identifier (mixed) -- The identifier of the object to find

setDefaultOrderings(array $defaultOrderings)

Sets the property names to order the result by per default.

Expected like this: array( 'foo' => TYPO3CMSExtbasePersistenceQueryInterface::ORDER_ASCENDING, 'bar' => TYPO3CMSExtbasePersistenceQueryInterface::ORDER_DESCENDING )

  • $defaultOrderings (array) -- The property names to order by

setDefaultQuerySettings(TYPO3\\CMS\\Extbase\\Persistence\\Generic\\QuerySettingsInterface $defaultQuerySettings)

Sets the default query settings to be used in this repository.

A typical use case is an initializeObject() method that creates a QuerySettingsInterface object, configures it and sets it to be used for all queries created by the repository.

Warning: Using this setter fully overrides native query settings created by QueryFactory->create(). This especially means that storagePid settings from configuration are not applied anymore, if not explicitly set. Make sure to apply these to your own QuerySettingsInterface object if needed, when using this method.

  • $defaultQuerySettings (TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface) -- the defaultQuerySettings


Returns a query for objects of this repository

__call(non-empty-string $methodName, array<int, mixed> $arguments)

Deprecated: since v12, will be removed in v14, use {@see findBy}, {@see findOneBy} and {@see count} instead

Dispatches magic methods (findBy[Property]())

  • $methodName (non-empty-string) -- The name of the magic method

  • $arguments (array) -- The arguments of the magic method

findBy(array $criteria, array $orderBy = NULL, int $limit = NULL, int $offset = NULL)
  • $criteria (array) -- the criteria

  • $orderBy (array) -- the orderBy, default: NULL

  • $limit (int) -- the limit, default: NULL

  • $offset (int) -- the offset, default: NULL

Return type




findOneBy(array $criteria, array $orderBy = NULL)
  • $criteria (array) -- the criteria

  • $orderBy (array) -- the orderBy, default: NULL

Return type


count(array $criteria)
  • $criteria (array) -- the criteria

Return type


Typo3QuerySettings and localization

Extbase renders the translated records in the same way as TypoScript rendering.

Changed in version 12.0: The Extbase query settings rely on \TYPO3\CMS\Core\Context\LanguageAspect now.

The following methods can be used to set and get the language aspect from any \TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface:

  • QuerySettingsInterface::getLanguageAspect(): LanguageAspect

  • QuerySettingsInterface::setLanguageAspect(LanguageAspect $aspect)

You can specify a custom language aspect per query as defined in the query settings in any repository class:

Example to use the fallback to the default language when working with overlays:



namespace MyVendor\MyExtension\Domain\Repository;

use TYPO3\CMS\Core\Context\LanguageAspect;
use TYPO3\CMS\Extbase\Persistence\Repository;

final class MyRepository extends Repository
    public function findSomethingByLanguage(int $languageId, int $contentId)
        $query = $this->createQuery();
            new LanguageAspect(
        // query something

For compatibility with TYPO3 v11 you can still use the now deprecated methods in the default implementation:

  • Typo3QuerySettings::getLanguageOverlayMode()

  • Typo3QuerySettings::setLanguageOverlayMode($languageOverlayMode)

  • Typo3QuerySettings::getLanguageUid()

  • Typo3QuerySettings::setLanguageUid($languageUid)

These methods have been removed from the interface however. For more consistent results use the language aspect via version switch.