Doctrine ORM 3.8.0 was released on 14 November 2026, alongside the 3.7.7 bugfix release. It isn’t a flashy release, but it changes things you will notice: the second-level cache now needs an extra package, pagination gets cheaper, fewer useless UPDATE queries run, and repositories accept PHP’s new \SortDirection enum. This guide walks through each change with code, then gives you an upgrade checklist.

Sources: the official 3.8.0 release notes, the UPGRADE.md file and the pagination docs.

Install or upgrade

composer require doctrine/orm:^3.8
composer show doctrine/orm | grep versions

Doctrine ORM 3.8 still requires PHP 8.1 or newer, and it pulls in symfony/polyfill-php86, so you can use the PHP 8.6 \SortDirection enum even on older PHP versions.

1. BC break: the second-level cache is now a separate package

The second-level cache (SLC) is large and deeply wired into the UnitOfWork. In the pull request, the maintainers explain that nobody on the team is an expert on that code anymore, so maintaining it is a risk. As a first step, ORM 3.8 requires an extra package, which also lets the team see how many projects actually use the feature through Packagist install numbers.

If you use the SLC, install the plugin before deploying 3.8:

composer require doctrine/orm-plugin-second-level-cache

Without it, this call now throws a LogicException:

$config->setSecondLevelCacheEnabled(true);

Check quickly whether you’re affected:

grep -rn "SecondLevelCache\|second_level_cache\|#\[ORM\\\\Cache" src config

If that finds nothing, you can skip this section.

2. Cheaper pagination with OffsetPaginator

Doctrine’s newer OffsetPaginator returns an immutable WindowPage. In 3.8 it gets two practical improvements.

The COUNT query only runs when you ask for it

Before 3.8, building a page ran the COUNT query straight away. Now WindowPage::getTotalCount() runs it lazily on first access and caches the result. Infinite-scroll and “load more” screens that never show a total don’t pay for a COUNT query at all (#12627).

use Doctrine\ORM\Tools\Pagination\OffsetPaginator;
use Doctrine\ORM\Tools\Pagination\Window;

$query = $entityManager->createQuery(
    'SELECT p, c FROM App\Entity\BlogPost p JOIN p.comments c ORDER BY p.id ASC'
);

$paginator = new OffsetPaginator();
$page = $paginator->paginate($query, Window::fromPageNumberAndSize(1, 25));

foreach ($page as $post) {
    echo $post->getHeadline(), PHP_EOL;   // no COUNT query yet
}

if ($page->hasNextPage()) {
    $next = $paginator->paginate($query, $page->getNextWindow());
}

One side effect: errors from the COUNT query now surface when you call getTotalCount(), not when you call paginate(). If you wrapped paginate() in a try/catch for count failures, move it.

Get the total without fetching rows

The new OffsetPaginator::getTotalCount() runs only the COUNT query (#12657). It’s useful for clamping a requested page number before you fetch it, or for showing an “N results” badge:

$paginator = new OffsetPaginator();

$total    = $paginator->getTotalCount($query);
$lastPage = max(1, (int) ceil($total / 25));

$requested = (int) ($_GET['page'] ?? 1);
$page = $paginator->paginate(
    $query,
    Window::fromPageNumberAndSize(min(max(1, $requested), $lastPage), 25)
);

printf('%d results, page %d of %d', $total, $page->getPageNumber(), $page->getPageCount());

INDEX BY keys are preserved (BC break)

With DQL INDEX BY, OffsetPaginator used to re-index results from 0, while the legacy Paginator kept your keys. 3.8 now preserves the keys (#12678), so WindowPage::getItems() is typed array<array-key, T> rather than list<T>:

$query = $entityManager->createQuery(
    'SELECT u FROM App\Entity\User u INDEX BY u.email ORDER BY u.id'
);

$page = (new OffsetPaginator())->paginate($query, new Window(0, 50));

foreach ($page->getItems() as $email => $user) {
    // $email is the key again in 3.8
}

If code calls array_is_list() on the items or relies on numeric keys, wrap it in array_values().

3. No more pointless UPDATEs for dates and value objects

Before 3.8, replacing a DateTimeImmutable or a value object with a new instance that holds the same database value produced an UPDATE, because Doctrine compared objects by identity. Now the UnitOfWork converts both values to their database form with the field’s type and compares those (#12753).

#[ORM\Column(type: 'date_immutable')]
private \DateTimeImmutable $publishedOn;

// Same day, different time: the `date` type stores only the day
$post->setPublishedOn(new \DateTimeImmutable('2026-11-14 18:30'));
$entityManager->flush(); // 3.8: no UPDATE if the stored day is unchanged

This works for the built-in date and time types and for custom value object types. Only object values are compared this way. Scalars were already compared by value, so there’s no extra cost on hot paths.

Watch out: if you relied on a “touch” update to fire preUpdate/postUpdate listeners or to bump an updatedAt column, that update may no longer happen. Change a real field instead.

4. \SortDirection in findBy() and findOneBy()

PHP 8.6 adds a native \SortDirection enum. Doctrine 3.7 had already deprecated strings in QueryBuilder::orderBy()/addOrderBy() and Expr\OrderBy. In 3.8, EntityRepository::findBy() and findOneBy() also accept the enum (#12613):

use App\Entity\Article;

$latest = $entityManager->getRepository(Article::class)->findBy(
    ['status' => 'published'],
    ['publishedAt' => \SortDirection::Descending, 'id' => \SortDirection::Ascending],
    10
);

$qb = $entityManager->createQueryBuilder()
    ->select('a')
    ->from(Article::class, 'a')
    ->orderBy('a.publishedAt', \SortDirection::Descending)
    ->addOrderBy('a.id', \SortDirection::Ascending);

For repositories, 'ASC'/'DESC' strings still work without a deprecation, because doctrine/persistence 3.x and 4.x only document strings on ObjectRepository.

Static analysis BC break: if a custom repository overrides findBy() or findOneBy() and copies the old docblock type for $orderBy, PHPStan or Psalm may now report the override as incompatible. Widen the docblock to include \SortDirection:

/**
 * @param array<string, mixed> $criteria
 * @param array<string, \SortDirection|'asc'|'desc'|'ASC'|'DESC'>|null $orderBy
 */
public function findBy(array $criteria, ?array $orderBy = null, ?int $limit = null, ?int $offset = null): array
{
    return parent::findBy($criteria, $orderBy, $limit, $offset);
}

5. New deprecations to plan for

  • Schema editor API. With doctrine/dbal 4.5 or newer, not using the schema editor API is deprecated and won’t be possible in ORM 4.0. Opt in with $configuration->setUseSchemaEditorApi(true);. With this API, unnamed foreign keys are named by the database, and on MySQL a long derived name can exceed the identifier limit. Name such keys explicitly with the foreignKeyName argument of #[ORM\JoinColumn].
  • Custom column platform options in mapping options (anything other than comment, unsigned, fixed, default or values) are deprecated, because DBAL 5 removes them.
  • Hydrator APIs no longer use references (#12728). This only matters if you wrote a custom hydrator.

6. Other changes worth knowing

  • Custom ID generators without an explicit strategy now imply CUSTOM instead of NONE.
  • Results of DQL functions that declare a return type are converted like columns of that type.
  • Hydration and Criteria-handling performance improvements (#12751, #12734).
  • Paginator bug fixes for custom-type ordering and nested subselects (#12716, #12715).

Upgrade checklist

  1. Using the second-level cache? composer require doctrine/orm-plugin-second-level-cache first.
  2. composer require doctrine/orm:^3.8 and run your tests.
  3. Search for OffsetPaginator usage that depends on numeric keys or catches COUNT errors around paginate().
  4. Check listeners that expected an UPDATE after reassigning an equal date or value object.
  5. Run PHPStan/Psalm. Widen $orderBy docblocks in overridden repository methods.
  6. With DBAL 4.5+, try setUseSchemaEditorApi(true) in a branch and run doctrine:schema:validate.

Takeaway

Doctrine ORM 3.8 saves queries in places you’ll feel, with lazy COUNTs and fewer redundant UPDATEs, and adopts PHP 8.6’s \SortDirection. The one change that can break a deploy is the second-level cache plugin, so check for it first, then follow the checklist.