PHPackages                             shipmonk/doctrine-entity-preloader - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. shipmonk/doctrine-entity-preloader

ActiveLibrary[Database & ORM](/categories/database)

shipmonk/doctrine-entity-preloader
==================================

Efficient & easy to use solution to n+1 problem in Doctrine ORM

1.4.1(6mo ago)102166.8k↓54.1%5[1 issues](https://github.com/shipmonk-rnd/doctrine-entity-preloader/issues)[1 PRs](https://github.com/shipmonk-rnd/doctrine-entity-preloader/pulls)MITPHPPHP ^8.1CI passing

Since Oct 14Pushed 1mo ago3 watchersCompare

[ Source](https://github.com/shipmonk-rnd/doctrine-entity-preloader)[ Packagist](https://packagist.org/packages/shipmonk/doctrine-entity-preloader)[ RSS](/packages/shipmonk-doctrine-entity-preloader/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (6)Dependencies (42)Versions (8)Used By (0)

Doctrine Entity Preloader
=========================

[](#doctrine-entity-preloader)

`shipmonk/doctrine-entity-preloader` is a PHP library designed to tackle the n+1 query problem in Doctrine ORM by efficiently preloading related entities. This library offers a flexible and powerful way to optimize database access patterns, especially in cases with complex entity relationships.

- 🚀 **Performance Boost:** Minimizes n+1 issues by preloading related entities with **constant number of queries**.
- 🔄 **Flexible:** Supports all associations: `#[OneToOne]`, `#[OneToMany]`, `#[ManyToOne]`, and `#[ManyToMany]`.
- 💡 **Easy Integration:** Simple to integrate with your existing Doctrine setup (supports both v2 and v3).

Comparison
----------

[](#comparison)

[Default](https://docs.google.com/presentation/d/1sSlZOxmEUVKt0l8zhimex-6lR0ilC001GXh8colaXxg/edit#slide=id.g30998e74a82_0_0)[Manual](https://docs.google.com/presentation/d/1sSlZOxmEUVKt0l8zhimex-6lR0ilC001GXh8colaXxg/edit#slide=id.g309b68062f4_0_0)[Fetch Join](https://docs.google.com/presentation/d/1sSlZOxmEUVKt0l8zhimex-6lR0ilC001GXh8colaXxg/edit#slide=id.g309b68062f4_0_15)[setFetchMode](https://docs.google.com/presentation/d/1sSlZOxmEUVKt0l8zhimex-6lR0ilC001GXh8colaXxg/edit#slide=id.g309b68062f4_0_35)[**EntityPreloader**](https://docs.google.com/presentation/d/1sSlZOxmEUVKt0l8zhimex-6lR0ilC001GXh8colaXxg/edit#slide=id.g309b68062f4_0_265)[OneToMany](tests/EntityPreloadBlogOneHasManyTest.php)🔴 1 + n🟢 2🟠 1, but
duplicate rows🟢 2🟢 2[OneToManyDeep](tests/EntityPreloadBlogOneHasManyDeepTest.php)🔴 1 + n + n²🟢 3🟠 1, but
duplicate rows🔴 2 + n²🟢 3[OneToManyAbstract](tests/EntityPreloadBlogOneHasManyAbstractTest.php)🔴 1 + n + n²🟠 3, but
duplicate rows🟠 1, but
duplicate rows🔴 2 + n²🟠 3, but
duplicate rows[ManyToOne](tests/EntityPreloadBlogManyHasOneTest.php)🔴 1 + n🟢 2🟠 1, but
duplicate rows🟢 2🟢 2[ManyToOneDeep](tests/EntityPreloadBlogManyHasOneDeepTest.php)🔴 1 + n + n🟢 3🟠 1, but
duplicate rows🔴 2 + n🟢 3[ManyToMany](tests/EntityPreloadBlogManyHasManyTest.php)🔴 1 + n🟢 2🟠 1, but
duplicate rows🔴 1 + n🟢 2### Comparison vs. Manual Preload

[](#comparison-vs-manual-preload)

Unlike manual preload, the EntityPreloader does not require writing custom queries for each association.

### Comparison vs. Fetch Join

[](#comparison-vs-fetch-join)

Unlike fetch joins, the EntityPreloader does not fetches duplicate data, which slows down both the query and the hydration process, except when necessary to prevent additional queries fired by Doctrine during hydration process.

The fetch join scales poorly with the number of associations. With every preloaded association, the number of duplicate rows grows. The EntityPreloader does not have this problem.

### Comparison vs. setFetchMode

[](#comparison-vs-setfetchmode)

Unlike `Doctrine\ORM\AbstractQuery::setFetchMode` it can

- preload nested associations
- preload `#[ManyToMany]` association
- avoid additional queries fired by Doctrine during hydration process

Installation
------------

[](#installation)

To install the library, use Composer:

```
composer require shipmonk/doctrine-entity-preloader
```

### PHPStan

[](#phpstan)

This library provides PHPStan integration:

- **extension.neon** - Infers return types for `EntityPreloader::preload()` based on the preloaded association
- **rules.neon** - Validates that the property name passed to `preload()` exists on the entity

If you use [PHPStan](https://phpstan.org/) and have [phpstan/extension-installer](https://github.com/phpstan/extension-installer) installed, the extension and rules are enabled automatically.

Otherwise, add the following to your `phpstan.neon`:

```
includes:
    - vendor/shipmonk/doctrine-entity-preloader/extension.neon
    - vendor/shipmonk/doctrine-entity-preloader/rules.neon
```

If [phpstan/phpstan-doctrine](https://github.com/phpstan/phpstan-doctrine) is installed and `objectManagerLoader` is used, all mapping formats become available (xml, phpdoc, yaml). Otherwise, only modern attributes are supported.

Usage
-----

[](#usage)

Below is a basic example demonstrating how to use `EntityPreloader` to preload related entities and avoid the n+1 problem:

```
use ShipMonk\DoctrineEntityPreloader\EntityPreloader;

$categories = $entityManager->getRepository(Category::class)->findAll();

$preloader = new EntityPreloader($entityManager);
$articles = $preloader->preload($categories, 'articles'); // 1 query to preload articles
$preloader->preload($articles, 'tags'); // 2 queries to preload tags
$preloader->preload($articles, 'comments'); // 1 query to preload comments

// no more queries are needed now
foreach ($categories as $category) {
    foreach ($category->getArticles() as $article) {
        echo $article->getTitle(), "\n";

        foreach ($article->getTags() as $tag) {
            echo $tag->getLabel(), "\n";
        }

        foreach ($article->getComments() as $comment) {
            echo $comment->getText(), "\n";
        }
    }
}
```

Configuration
-------------

[](#configuration)

`EntityPreloader` allows you to adjust batch sizes and fetch join limits to fit your application's performance needs:

- **Batch Size:** Set a custom batch size for preloading to optimize memory usage.
- **Max Fetch Join Same Field Count:** Define the maximum number of join fetches allowed per field.

```
$preloader->preload(
    $articles,
    'category',
    batchSize: 20,
    maxFetchJoinSameFieldCount: 5
);
```

Limitations
-----------

[](#limitations)

- no support for indexed collections
- no support for dirty collections
- no support for composite primary keys

###  Health Score

53

—

FairBetter than 96% of packages

Maintenance80

Actively maintained with recent releases

Popularity48

Moderate usage in the ecosystem

Community15

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 66.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~85 days

Recently: every ~29 days

Total

6

Last Release

200d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5b545e3f9d982d538f11bc42b3dc2d186f706cef92c8bc8bc8f8788b08186ea5?d=identicon)[janedbal](/maintainers/janedbal)

![](https://www.gravatar.com/avatar/7a4170ebe9281cb76be91fe00f8eee307beb3e0744dfd40ba89d9c856372c7eb?d=identicon)[shipmonk](/maintainers/shipmonk)

![](https://www.gravatar.com/avatar/6163a0eec16c2bfc9cce0c7c8801b5166cca9af81a146764676059a965044000?d=identicon)[JanTvrdik](/maintainers/JanTvrdik)

---

Top Contributors

[![JanTvrdik](https://avatars.githubusercontent.com/u/175109?v=4)](https://github.com/JanTvrdik "JanTvrdik (22 commits)")[![janedbal](https://avatars.githubusercontent.com/u/1993453?v=4)](https://github.com/janedbal "janedbal (11 commits)")

---

Tags

doctrineentitynplus1ormpreloading

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/shipmonk-doctrine-entity-preloader/health.svg)

```
[![Health](https://phpackages.com/badges/shipmonk-doctrine-entity-preloader/health.svg)](https://phpackages.com/packages/shipmonk-doctrine-entity-preloader)
```

###  Alternatives

[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k17.9M388](/packages/easycorp-easyadmin-bundle)[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1189.8k](/packages/rcsofttech-audit-trail-bundle)[2lenet/crudit-bundle

The easy like Crud'it Bundle.

1616.4k14](/packages/2lenet-crudit-bundle)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

9421.6k61](/packages/open-dxp-opendxp)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)