Download the PHP package mcaskill/charcoal-model-collection without Composer

Charcoal Model Collections / Repositories

Support package providing advanced model collections and collection loaders for Charcoal projects.

Installation

See composer.json for depenencides.

Collections

1. Charcoal\Support\Model\Collection\Collection

Provides methods to manipulate the collection or retrieve specific models.

filter()

Filter the collection of objects using the given callback.

forPage()

"Paginate" the collection by slicing it into a smaller collection.

only()

Extract the objects with the specified keys.

pop()

Remove and return the last object from the collection.

prepend()

Add an object onto the beginning of the collection.

random()

Retrieve one or more random objects from the collection.

reverse()

Reverse the order of objects in the collection.

shift()

Remove and return the first object from the collection.

slice()

Extract a slice of the collection.

sortBy()

Sort the collection by the given callback or object property.

sortByDesc()

Sort the collection in descending order using the given callback or object property.

take()

Extract a portion of the first or last objects from the collection.

where()

Filter the collection of objects by the given key/value pair.

whereIn()

Filter the collection of objects by the given key/value pair.

Repositories

1. Charcoal\Support\Model\Repository\CollectionLoaderIterator

Provides improved counting of found rows (via SQL_CALC_FOUND_ROWS), supports PHP Generators via "cursor" methods, and supports chaining the loader directly into an iterator construct or appending additional criteria.

1.1. Lazy Collections

The CollectionLoaderIterator leverages PHP's generators to allow you to work with large collections while keeping memory usage low.

When using the traditional load methods, all models must be loaded into memory at the same time.

However, the cursor methods return Generator objects instead. This allows you to keep one model loaded in memory at a time:

1.2. IteratorAggregate

The CollectionLoaderIterator implements IteratorAggregate which allows the repository to be used in a foreach construct without the need to explicitly call a query method.

Internally, the IteratorAggregate::getIterator() method calls the CollectionLoaderIterator::cursor() method which in turn returns a Generator object.

Furthermore, you can continue to chain constraints onto the repository:

1.3. SQL_CALC_FOUND_ROWS

If the SQL_CALC_FOUND_ROWS option is included in a SELECT statement, the FOUND_ROWS() function will be invoked afterwards to retrieve the number of objects the statement would have returned without the LIMIT.

Using the query builder interface, the generated statement will include SQL_CALC_FOUND_ROWS option unless the query is targeting a single object.

2. Charcoal\Support\Model\Repository\ModelCollectionLoader

Provides support for cloning, preventing model swapping, and sharing the same data source.

2.1. Model Protection

Once a model is assigned to the ModelCollectionLoader, any attempts to replace it will result in a thrown exception:

On its own, this feature is not very practical but in concert with the ScopedCollectionLoader this becomes an important safety measure.

2.2. Collection Loader Cloning

When cloning the ModelCollectionLoader via the clone keyword or the cloneWith() method, the model protection mechanism will be unlocked until a new object type is assigned or until the source() method is called.

2.3. Source Sharing

A Charcoal Model is based on the ActiveRecord implementation for working with data sources; which is to say a Model allows you to interact with data in your database. This interaction is facilitated by a "Data Source" interface, like the DatabaseSource class. Each instance of a Model will usually create its own instance of a Data Source object; in other words, you end up always working with two objects per Model (the Model and the Data Source).

To reduce the number of objects in a request's lifecycle, its a good practice to assign a single instance of a Data Source to all Models. When the ModelCollectionLoader creates a new instance of the Model being queried, it will assign the prototype Model's Data Source object (the one that is queried upon by the repository).

3. Charcoal\Support\Model\Repository\ScopedCollectionLoader

Provides support for default filters, orders, and pagination, which are automatically applied upon the loader's creation and after every reset.

If you would like to disable the default criteria on a repository, you may use the withoutDefaults method. The method accepts a callback to interact with collection loader if, for example, you only wish to apply default orders:

4. Charcoal\Support\Model\Repository\CachedCollectionLoader

Provides support for storing the data of loaded models in a cache pool, similar to the \Charcoal\Model\Service\ModelLoader and using the same cache key for interoperability.

If you would like to disable the caching process on a repository, you may use the withoutCache method. The method accepts a callback to interact with collection loader:

License

• Charcoal Model Collections and Repositories component is licensed under the MIT license. See LICENSE for details.
• Charcoal framework is licensed under the MIT license. See LICENSE for details.