All 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 usefull functions. Therefore in simple classes extending the class Repository and leaving the class empty otherwise is sufficient.

The BlogRepository sets some default orderings and is otherwise empty:

class BlogRepository extends Repository


Magic find methods

The class Repository 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.

Custom find methods

Custom find methods can be implemented. They can be used, for example, to filter by multiple properties, apply a different sorting. They can also be used for complex queries.


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


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

use FriendsOfTYPO3\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();

Query settings

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

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 be cause information disclosure. Use with care.

When the query settings should only be changed for a certain method they can be set in the method itself:

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.

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<non-empty-string, QueryInterface::ORDER_*>)

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

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

  • QueryInterface::ORDER_*> (array<non-empty-string,) -- $defaultOrderings 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)

Dispatches magic methods (findBy[Property]())

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

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