|
| 1 | +# Doctrine Entity Preloader |
| 2 | + |
| 3 | +`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. |
| 4 | + |
| 5 | +- 🚀 **Performance Boost:** Minimizes n+1 issues by preloading related entities with **constant number of queries**. |
| 6 | +- 🔄 **Flexible:** Supports all associations: `#[OneToOne]`, `#[OneToMany]`, `#[ManyToOne]`, and `#[ManyToMany]`. |
| 7 | +- 💡 **Easy Integration:** Simple to integrate with your existing Doctrine setup. |
| 8 | + |
| 9 | + |
| 10 | +## Comparison |
| 11 | + |
| 12 | +| | Default | Manual Preload | Fetch Join | setFetchMode | **EntityPreloader** | |
| 13 | +|------------------------------------------------------------------------|------------|--------------------------|------------------------|--------------|--------------------------------| |
| 14 | +| [OneToMany](tests/EntityPreloadBlogOneHasManyTest.php) | 1 + n | impossible in Doctrine 3 | 1, but duplicates rows | 1 + 1 | 1 + 1 | |
| 15 | +| [OneToManyDeep](tests/EntityPreloadBlogOneHasManyDeepTest.php) | 1 + n + n² | impossible in Doctrine 3 | 1, but duplicates rows | 1 + 1 + n² | 1 + 1 + 1 | |
| 16 | +| [OneToManyAbstract](tests/EntityPreloadBlogOneHasManyAbstractTest.php) | 1 + n + n² | impossible in Doctrine 3 | 1, but duplicates rows | 1 + 1 + n² | 1 + 1 + 1, but duplicates rows | |
| 17 | +| [ManyToOne](tests/EntityPreloadBlogManyHasOneTest.php) | 1 + n | 1 + 1 | 1, but duplicates rows | 1 + 1 | 1 + 1 | |
| 18 | +| [ManyToOneDeep](tests/EntityPreloadBlogManyHasOneDeepTest.php) | 1 + n + n | 1 + 1 + 1 | 1, but duplicates rows | 1 + 1 + n | 1 + 1 + 1 | |
| 19 | +| [ManyToMany](tests/EntityPreloadBlogManyHasManyTest.php) | 1 + n | impossible in Doctrine 3 | 1, but duplicates rows | 1 + n | 1 + 1 | |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +Unlike `Doctrine\ORM\AbstractQuery::setFetchMode` it can |
| 24 | + |
| 25 | +* preload nested associations |
| 26 | +* preload `#[ManyToMany]` association |
| 27 | +* avoid additional queries fired by Doctrine during hydration process |
| 28 | + |
| 29 | + |
| 30 | +## Installation |
| 31 | + |
| 32 | +To install the library, use Composer: |
| 33 | + |
| 34 | +```sh |
| 35 | +composer require shipmonk/doctrine-entity-preloader |
| 36 | +``` |
| 37 | + |
| 38 | +## Usage |
| 39 | + |
| 40 | +Below is a basic example demonstrating how to use `EntityPreloader` to preload related entities and avoid the n+1 problem: |
| 41 | + |
| 42 | +```php |
| 43 | +use ShipMonk\DoctrineEntityPreloader\EntityPreloader; |
| 44 | + |
| 45 | +$categories = $entityManager->getRepository(Category::class)->findAll(); |
| 46 | + |
| 47 | +$preloader = new EntityPreloader($entityManager); |
| 48 | +$articles = $preloader->preload($categories, 'articles'); // 1 query to preload articles |
| 49 | +$preloader->preload($articles, 'tags'); // 1 query to preload tags |
| 50 | +$preloader->preload($articles, 'comments'); // 1 query to preload comments |
| 51 | + |
| 52 | +// no more queries are needed now |
| 53 | +foreach ($categories as $category) { |
| 54 | + foreach ($category->getArticles() as $article) { |
| 55 | + echo $article->getTitle(), "\n"; |
| 56 | + |
| 57 | + foreach ($articles->getTags() as $tag) { |
| 58 | + echo $tag->getLabel(), "\n"; |
| 59 | + } |
| 60 | + |
| 61 | + foreach ($articles->getComments() as $comment) { |
| 62 | + echo $comment->getText(), "\n"; |
| 63 | + } |
| 64 | + } |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +## Configuration |
| 69 | + |
| 70 | +`EntityPreloader` allows you to adjust batch sizes and fetch join limits to fit your application's performance needs: |
| 71 | + |
| 72 | +- **Batch Size:** Set a custom batch size for preloading to optimize memory usage. |
| 73 | +- **Max Fetch Join Same Field Count:** Define the maximum number of join fetches allowed per field. |
| 74 | + |
| 75 | +```php |
| 76 | +$preloader->preload( |
| 77 | + $articles, |
| 78 | + 'category', |
| 79 | + batchSize: 20, |
| 80 | + maxFetchJoinSameFieldCount: 5 |
| 81 | +); |
| 82 | +``` |
| 83 | + |
| 84 | + |
| 85 | +## Limitations |
| 86 | + |
| 87 | +- no support for indexed collections |
| 88 | +- no support for dirty collections |
| 89 | +- no support for composite primary keys |
0 commit comments