https://github.com/shipmonk-rnd/doctrine-entity-preloader
💡 Doctrine entity preloading: Efficient & easy to use solution to n+1 problem in Doctrine ORM
https://github.com/shipmonk-rnd/doctrine-entity-preloader
doctrine entity nplus1 orm preloading
Last synced: 4 months ago
JSON representation
💡 Doctrine entity preloading: Efficient & easy to use solution to n+1 problem in Doctrine ORM
- Host: GitHub
- URL: https://github.com/shipmonk-rnd/doctrine-entity-preloader
- Owner: shipmonk-rnd
- License: mit
- Created: 2024-09-23T09:00:30.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-06-16T12:41:30.000Z (4 months ago)
- Last Synced: 2025-06-23T23:54:54.326Z (4 months ago)
- Topics: doctrine, entity, nplus1, orm, preloading
- Language: PHP
- Homepage:
- Size: 68.4 KB
- Stars: 79
- Watchers: 4
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
- :rocket: **Performance Boost:** Minimizes n+1 issues by preloading related entities with **constant number of queries**.
- :arrows_counterclockwise: **Flexible:** Supports all associations: `#[OneToOne]`, `#[OneToMany]`, `#[ManyToOne]`, and `#[ManyToMany]`.
- :bulb: **Easy Integration:** Simple to integrate with your existing Doctrine setup (supports both v2 and v3).
## 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) | :red_circle: 1 + n | :green_circle: 2 | :orange_circle: 1, but
duplicate rows | :green_circle: 2 | :green_circle: 2 |
| [OneToManyDeep](tests/EntityPreloadBlogOneHasManyDeepTest.php) | :red_circle: 1 + n + n² | :green_circle: 3 | :orange_circle: 1, but
duplicate rows | :red_circle: 2 + n² | :green_circle: 3 |
| [OneToManyAbstract](tests/EntityPreloadBlogOneHasManyAbstractTest.php) | :red_circle: 1 + n + n² | :orange_circle: 3, but
duplicate rows | :orange_circle: 1, but
duplicate rows | :red_circle: 2 + n² | :orange_circle: 3, but
duplicate rows |
| [ManyToOne](tests/EntityPreloadBlogManyHasOneTest.php) | :red_circle: 1 + n | :green_circle: 2 | :orange_circle: 1, but
duplicate rows | :green_circle: 2 | :green_circle: 2 |
| [ManyToOneDeep](tests/EntityPreloadBlogManyHasOneDeepTest.php) | :red_circle: 1 + n + n | :green_circle: 3 | :orange_circle: 1, but
duplicate rows | :red_circle: 2 + n | :green_circle: 3 |
| [ManyToMany](tests/EntityPreloadBlogManyHasManyTest.php) | :red_circle: 1 + n | :green_circle: 2 | :orange_circle: 1, but
duplicate rows | :red_circle: 1 + n | :green_circle: 2 |
### Comparison vs. Manual Preload
Unlike manual preload, the EntityPreloader does not require writing custom queries for each association.
### 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
Unlike `Doctrine\ORM\AbstractQuery::setFetchMode` it can
* preload nested associations
* preload `#[ManyToMany]` association
* avoid additional queries fired by Doctrine during hydration process
## Installation
To install the library, use Composer:
```sh
composer require shipmonk/doctrine-entity-preloader
```
## Usage
Below is a basic example demonstrating how to use `EntityPreloader` to preload related entities and avoid the n+1 problem:
```php
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 ($articles->getTags() as $tag) {
echo $tag->getLabel(), "\n";
}
foreach ($articles->getComments() as $comment) {
echo $comment->getText(), "\n";
}
}
}
```
## 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.
```php
$preloader->preload(
$articles,
'category',
batchSize: 20,
maxFetchJoinSameFieldCount: 5
);
```
## Limitations
- no support for indexed collections
- no support for dirty collections
- no support for composite primary keys