Extbase repository 

The minimal Extbase repository 

A repository extends \TYPO3\CMS\Extbase\Persistence\Repository . The class name must follow the convention: the model class \Domain\Model\Conference maps to \Domain\Repository\ConferenceRepository. Extbase resolves this automatically.

namespace MyVendor\MyExtension\Domain\Repository;

use TYPO3\CMS\Extbase\Persistence\Repository;

class ConferenceRepository extends Repository {}

That empty class already provides all the standard methods described below.

Built-in find methods in Extbase repositories 

Repository provides these methods for finding, returning, and counting domain objects out of the box:

Ordering results in Extbase repositories 

There are two distinct places to define ordering, and they serve different purposes.

Repository-wide default ordering applies to every query from this repository — findAll(), findBy(), and custom methods that do not override it. Set the $defaultOrderings class property:

use TYPO3\CMS\Extbase\Persistence\QueryInterface;
use TYPO3\CMS\Extbase\Persistence\Repository;

class ConferenceRepository extends Repository
{
    protected $defaultOrderings = [
        'conferenceDate' => QueryInterface::ORDER_ASCENDING,
        'title'     => QueryInterface::ORDER_ASCENDING,
    ];
}

Method-level ordering applies only to the query built in that method, overriding the default for that call. Use $query->setOrderings():

public function findUpcomingByTitle(): QueryResultInterface
{
    $query = $this->createQuery();
    $query->matching(
        $query->greaterThanOrEqual('conferenceDate', new \DateTimeImmutable('today'))
    );
    $query->setOrderings(['title' => QueryInterface::ORDER_ASCENDING]);
    return $query->execute();
}

In both cases the keys are property names, not column names. Order direction is QueryInterface::ORDER_ASCENDING ( 'ASC') or QueryInterface::ORDER_DESCENDING ( 'DESC').

If neither $defaultOrderings nor a method-level setOrderings() is set, no ORDER BY clause is added and the database returns rows in an undefined order. This may appear consistent in development but is not guaranteed — the order can change after inserts, updates, or database maintenance. Always define an explicit ordering for any query whose result order matters to the user.

Custom query methods in Extbase repositories 

Use createQuery() when the built-in find methods are not enough:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Domain\Repository;

use MyVendor\MyExtension\Domain\Model\Conference;
use TYPO3\CMS\Extbase\Persistence\QueryInterface;
use TYPO3\CMS\Extbase\Persistence\QueryResultInterface;
use TYPO3\CMS\Extbase\Persistence\Repository;

class ConferenceRepository extends Repository
{
    protected $defaultOrderings = [
        'conferenceDate' => QueryInterface::ORDER_ASCENDING,
    ];

    /** @return QueryResultInterface<Conference> */
    public function findUpcoming(): QueryResultInterface
    {
        $query = $this->createQuery();
        $query->matching(
            $query->greaterThanOrEqual('conferenceDate', new \DateTimeImmutable('today')),
        );
        return $query->execute();
    }

    /** @return QueryResultInterface<Conference> */
    public function findByTitleContaining(string $search): QueryResultInterface
    {
        $query = $this->createQuery();
        $query->matching(
            $query->like('title', '%' . $search . '%'),
        );
        $query->setOrderings(['title' => QueryInterface::ORDER_ASCENDING]);
        return $query->execute();
    }
}

The query <\TYPO3\CMS\Extbase\Persistence\QueryInterface> API supports these constraint methods:

Chain multiple constraints:

$query->matching(
    $query->logicalAnd(
        $query->equals('published', true),
        $query->greaterThanOrEqual('conferenceDate', new \DateTimeImmutable('today')),
    )
);

storagePid — when findAll() returns nothing 

Every repository query (except findByUid()) is filtered to one or more storage pages by default. If findAll() returns an empty result and records clearly exist in the database, or if there are unexpected objects in the result, the most likely cause is a missing or misconfigured storagePid.

Configure it for example in TypoScript:

plugin.tx_myextension.persistence.storagePid = 42

Injecting repositories with dependency injection 

Inject the repository via constructor injection in your controller or service. Do not use GeneralUtility::makeInstance() — it bypasses the Bootstrap procedure applied by extbase, so any query settings configured on the shared instance are lost and the repository is not wired with its own injected dependencies:

use MyVendor\MyExtension\Domain\Repository\ConferenceRepository;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class ConferenceController extends ActionController
{
    public function __construct(
        protected readonly ConferenceRepository $conferenceRepository,
    ) {}

    public function listAction(): ResponseInterface
    {
        $this->view->assign('conferences', $this->conferenceRepository->findAll());
        return $this->htmlResponse();
    }
}

TYPO3's DI container resolves the repository automatically. No @inject annotation, no factory call.

When to drop out of the ORM (Object Relational Mapping) 

The Extbase query API covers most common patterns. Use raw DBAL — TYPO3's database layer built on top of Doctrine DBAL — when you need:

• Aggregate functions ( SUM, AVG, GROUP BY)
• Bulk inserts or updates across many records
• Complex multi-table joins that the ORM cannot express
• Performance-critical queries where loading full objects is wasteful

While you can technically access the database directly from controllers or services, you should limit raw DBAL usage to repository classes. Spreading database calls across controllers and services makes the code harder to test, harder to change the underlying query, and harder to enforce consistent filters (such as storagePid or language overlay).

Access ConnectionPool from within the repository:

use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Extbase\Persistence\Repository;

class ConferenceRepository extends Repository
{
    public function __construct(
        protected readonly ConnectionPool $connectionPool,
    ) {
        parent::__construct();
    }

    public function countByYear(int $year): array
    {
        $connection = $this->connectionPool->getConnectionForTable('tx_myextension_domain_model_conference');
        // ... build and execute raw query
    }
}