Querying the database with Extbase 

Building a query with createQuery() 

When findBy(['published' => true]) is not expressive enough — you need a range, a pattern, or a combination of conditions — write a method on the repository that builds the query itself. Every custom query follows the same three steps:

1. Create a query object with $this->createQuery(). It is already bound to this repository's model and its storage pages.
2. Constrain it with matching(), passing one constraint built from the query's own constraint methods ( equals(), like(), greaterThan(), …).
3. Execute it with execute(), which returns a \TYPO3\CMS\Extbase\Persistence\QueryResultInterface you can iterate and count.

<?php

namespace MyVendor\MyExtension\Domain\Repository;

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

class ConferenceRepository extends Repository
{
    public function findPublished(): QueryResultInterface
    {
        $query = $this->createQuery();
        $query->matching(
            $query->equals('published', true),
        );
        return $query->execute();
    }
}

The method lives on the repository because the repository is the only place that should talk to the database. The controller calls $conferenceRepository->findPublished() and never sees the query.

<?php

namespace MyVendor\MyExtension\Domain\Repository;

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

class ConferenceRepository extends Repository
{
    public function findUpcomingPublished(): QueryResultInterface
    {
        $query = $this->createQuery();
        $query->matching(
            $query->logicalAnd(
                $query->equals('published', true),
                $query->greaterThanOrEqual('conferenceDate', new \DateTimeImmutable('today')),
            ),
        );
        return $query->execute();
    }
}

<?php

namespace MyVendor\MyExtension\Domain\Repository;

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

class ConferenceRepository extends Repository
{
    public function findSlice(int $limit, int $offset = 0): QueryResultInterface
    {
        $query = $this->createQuery();
        $query->setLimit($limit);
        $query->setOffset($offset);
        return $query->execute();
    }
}

The storagePid page restriction 

Every query a repository builds is restricted to records on configured storage pages (the storagePid), in addition to the constraints you set with matching(). This is the most common reason a query returns something other than what you expect, and it has its own page:

Overriding query behaviour with query settings 

Every query carries a query settings <\TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface> object that controls the implicit restrictions Extbase applies. Set it with $query->getQuerySettings() inside a custom repository method:

<?php

namespace MyVendor\MyExtension\Domain\Repository;

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

class ConferenceRepository extends Repository
{
    public function findAllAcrossPages(): QueryResultInterface
    {
        $query = $this->createQuery();
        $query->getQuerySettings()->setRespectStoragePage(false);
        return $query->execute();
    }
}

The storagePid is one of these settings; its two methods ( setRespectStoragePage() and setStoragePageIds()) are documented on the storagePid page. The remaining settings control language and visibility:

Paginating a query result 

For page-by-page navigation, do not compute offsets by hand. TYPO3 splits pagination into two collaborating roles, each with its own family of classes:

• A paginator wraps the item source and slices it to the current page. All paginators extend \TYPO3\CMS\Core\Pagination\AbstractPaginator and expose the current page's items in getPaginatedItems(). Which one you pick depends on the source: \TYPO3\CMS\Extbase\Pagination\QueryResultPaginator for an Extbase query result, \TYPO3\CMS\Core\Pagination\ArrayPaginator for a plain array, \TYPO3\CMS\Core\Pagination\QueryBuilderPaginator for a raw DBAL query, and several source-specific paginators shipped by other extensions.
• Pagination takes a paginator and computes the page-number metadata used to render the navigation — previous, next, first, last and the list of page numbers. All implement \TYPO3\CMS\Core\Pagination\PaginationInterface . Core ships two strategies: \TYPO3\CMS\Core\Pagination\SimplePagination (every page number) and \TYPO3\CMS\Core\Pagination\SlidingWindowPagination (a moving window around the current page, for long result sets).

For an Extbase query result you therefore combine a QueryResultPaginator with the pagination strategy of your choice. The controller creates both and assigns them to the view:

<?php

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Domain\Repository\ConferenceRepository;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Core\Pagination\SimplePagination;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
use TYPO3\CMS\Extbase\Pagination\QueryResultPaginator;

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

    public function listAction(int $currentPage = 1): ResponseInterface
    {
        $conferences = $this->conferenceRepository->findAll();
        $paginator = new QueryResultPaginator($conferences, $currentPage, 10);
        $pagination = new SimplePagination($paginator);

        $this->view->assignMultiple([
            'paginator' => $paginator,
            'pagination' => $pagination,
        ]);
        return $this->htmlResponse();
    }
}

The paginator queries lazily — it only fetches the records for the current page, not the whole result set — so it is safe to use over large tables. In the template the records for the current page come from {paginator.paginatedItems} (you loop over that to render the items), while {pagination.allPageNumbers} supplies the page numbers for the navigation links. The original findAll() result is never passed to the view:

<h1>Conferences</h1>

<ul>
    <f:for each="{paginator.paginatedItems}" as="conference">
        <li>{conference.title}</li>
    </f:for>
</ul>

<nav aria-label="Pagination">
    <f:for each="{pagination.allPageNumbers}" as="page">
        <f:link.action action="list" arguments="{currentPage: page}">
            {page}
        </f:link.action>
    </f:for>
</nav>

When changes reach the database 

Reads happen immediately. Writes do not. Extbase tracks the state of every object it loads and flushes the accumulated changes once, automatically, at the end of the request — comparing each object against its original state and writing only what has changed. In most actions you do not need to call a save method on an object that you have loaded and modified; the ORM will detect the change and write it for you.

This deferred flush is convenient, but has two consequences that are worth knowing.

<?php

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Domain\Model\Conference;
use MyVendor\MyExtension\Domain\Repository\ConferenceRepository;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
use TYPO3\CMS\Extbase\Persistence\PersistenceManagerInterface;

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

    public function createAction(Conference $conference): ResponseInterface
    {
        $this->conferenceRepository->add($conference);

        // Force the write now: the redirect below ends the request before the
        // automatic flush, and we need the new UID for the show action.
        $this->persistenceManager->persistAll();

        return $this->redirect('show', null, null, ['conference' => $conference->getUid()]);
    }
}

<?php

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Domain\Model\Conference;
use MyVendor\MyExtension\Domain\Repository\ConferenceRepository;
use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;
use TYPO3\CMS\Extbase\Persistence\PersistenceManagerInterface;

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

    public function saveAction(Conference $conference): ResponseInterface
    {
        if ($this->persistenceManager->isNewObject($conference)) {
            $this->conferenceRepository->add($conference);
        } else {
            $this->conferenceRepository->update($conference);
        }

        return $this->redirect('list');
    }
}

Debugging an Extbase query 

When a query returns something other than what you expect — nothing, too few records, too many, or the wrong ones — work through this checklist first before checking for possibly incorrect constraint logic:

1. Check the storagePid first. This is the cause far more often than the query itself. Confirm which page the records live on and which page the query searches.
2. Check the recursive depth. Records in subfolders are invisible without it; an over-broad depth pulls in unrelated records.
3. Check the language. With setRespectSysLanguage(true) (the default), records in other languages are filtered out or overlaid.
4. Check enable fields. Hidden or time-restricted records are excluded by default — correct for the frontend, surprising during debugging.
5. Inspect the generated SQL. Extbase builds real SQL; seeing the exact SQL statement and its parameters will show the page restrictions and any conditions that have been applied.

To see the SQL, convert the query to a Doctrine query builder and dump it using the Extbase debugger:

<?php

namespace MyVendor\MyExtension\Domain\Repository;

use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Extbase\Persistence\Generic\Storage\Typo3DbQueryParser;
use TYPO3\CMS\Extbase\Persistence\QueryResultInterface;
use TYPO3\CMS\Extbase\Persistence\Repository;
use TYPO3\CMS\Extbase\Utility\DebuggerUtility;

class ConferenceRepository extends Repository
{
    public function findPublished(bool $debug = false): QueryResultInterface
    {
        $query = $this->createQuery();
        $query->matching($query->equals('published', true));

        if ($debug) {
            $parser = GeneralUtility::makeInstance(Typo3DbQueryParser::class);
            $queryBuilder = $parser->convertQueryToDoctrineQueryBuilder($query);
            DebuggerUtility::var_dump($queryBuilder->getSQL());
            DebuggerUtility::var_dump($queryBuilder->getParameters());
        }

        return $query->execute();
    }
}

Once you can query confidently, the next step is understanding how Extbase loads related objects — and the performance trade-off that comes with them. That is covered in Object relations in Extbase.