https://github.com/jeremyharris/cakephp-lazyload
A lazy loader for CakePHP entities.
https://github.com/jeremyharris/cakephp-lazyload
cakephp-orm lazyload
Last synced: 11 months ago
JSON representation
A lazy loader for CakePHP entities.
- Host: GitHub
- URL: https://github.com/jeremyharris/cakephp-lazyload
- Owner: jeremyharris
- License: mit
- Created: 2016-03-12T18:31:11.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2024-01-05T14:38:46.000Z (about 2 years ago)
- Last Synced: 2025-03-31T18:19:47.108Z (12 months ago)
- Topics: cakephp-orm, lazyload
- Language: PHP
- Size: 85 KB
- Stars: 61
- Watchers: 7
- Forks: 10
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://packagist.org/packages/jeremyharris/cakephp-lazyload)
[]()
# CakePHP ORM LazyLoad Plugin
This is an association lazy loader for CakePHP ORM entities. It allows you to
lazily load association data by accessessing the property, without using
`contain()` (the eager loader).
## Installation
Requirements
- CakePHP ORM (or the full framework) 5.x
- sloth
`$ composer require jeremyharris/cakephp-lazyload`
For older versions of the CakePHP ORM, look at older releases of this library.
## Usage
If you have a base entity, add the trait to get lazy loading across
all of your entities. Or, attach it to a single entity to only lazy
load on that entity:
**src/Model/Entity/User.php**
```php
Programmers->get(1);
```
When accessing an association property (as if the data was eagerly loaded), the
associated data is loaded automatically.
```php
beers as $beer) {
// brewery is lazy loaded onto $beer
echo $programmer->name . ' drinks beer ' . $beer->name . ' from ' . $beer->brewery->name;
}
```
### Using contain in conjunction with the lazy loader
The lazy loader will not overwrite results that are generated by the eager
loader (`contain()`). You can continue to write complex contain conditions and
still take advantage of the lazy loader.
```php
Programmers->get(1, [
'contain' => [
'Beers'
]
]);
// beers is loaded via the eager loader
$programmer->beers;
// brewery is lazy loaded onto $beer[0]
$programmer->beers[0]->brewery;
```
## Entity method support
Entities with the lazy loader trait support lazy loading using the different
property access methods provided by the Cake ORM:
- Getters: `$programmer->get('beers)`, `$programmer->beers`
- Has: `$programmer->has('beers)`
- Unset: `$programmer->unsetProperty('beers')`
When unsetting a property via `Entity::unsetProperty()`, the property will be
prevented from being lazily loaded in the future for that entity, as it
respects the state in the same way a typical Entity would. If you wish to re-hydrate
an association, you can use `Table::loadInto` as provided by the ORM:
```php
Programmers->get(1);
// beers is lazy loaded
$programmer->beers;
// remove beers from the entity
$programmer->unsetProperty('beers');
// this now returns false
$programmer->has('beers');
// if we want access to beers again, we can manually load it
$programmer = $this->Programmers->loadInto($programmer, ['Beers']);
```
## Testing
Sometimes in tests, we create entities that don't necessarily have tables. When
accessing a property that doesn't exist, the LazyLoad trait will try to load the
table in order to get association data, which would throw an error if the table
doesn't exist. To prevent this, you can override `_repository()` in your entity:
```php
_loadRepository();
} catch (Exception $e) {
return false;
}
return $repository;
}
}
```
By default, the LazyLoad trait will throw whatever error bubbles up
`TableRegistry::get()`.
### Plugins
If testing plugins entities that don't have tables, make sure to override the
`_repository()` method to return the *plugin's* table.
## Notes
- **Contain:** This is not a replacement for `contain()`, which can write complex queries to dictate
what data to contain. The lazy loader obeys the association's conditions that
you set when defining the association on the table, but apart from that it grabs
all associated data.
- **Speed:** Lazy loading in this manner isn't necessarily a speed improvement. In fact, it can be a
detriment to speed in certain cases, such as looping over entities that lazy load associations within
the loop (creates a single SQL query per-item rather than using joins or the ORM). This plugin is
intended as a helper for bootstrapping projects.
- **Hydration:** The lazy loader requires that your result set is hydrated in order to
provide lazy loading functionality.
> Special thanks to @lorenzo for reviewing the plugin before its initial release!