PHPackages                             mcaskill/charcoal-model-collection - 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. mcaskill/charcoal-model-collection

ActiveLibrary

mcaskill/charcoal-model-collection
==================================

Model collection and repository classes for Charcoal.

1.4.1(9mo ago)01.4k11MITPHPPHP >7.1CI failing

Since Feb 3Pushed 9mo ago2 watchersCompare

[ Source](https://github.com/mcaskill/charcoal-model-collection)[ Packagist](https://packagist.org/packages/mcaskill/charcoal-model-collection)[ RSS](/packages/mcaskill-charcoal-model-collection/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (6)Versions (9)Used By (1)

Charcoal Model Collections / Repositories
=========================================

[](#charcoal-model-collections--repositories)

[![License](https://camo.githubusercontent.com/611074df9cb12d53290062ad4dc1af663fa23dd9093a8de289a0d658c7dc4cf8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d6361736b696c6c2f63686172636f616c2d6d6f64656c2d636f6c6c656374696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mcaskill/charcoal-model-collection)[![Latest Stable Version](https://camo.githubusercontent.com/1616157a573fc44edb1b7f0b56bdcf7c5ba19fdc5c2bd028bc96de079448d081/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6361736b696c6c2f63686172636f616c2d6d6f64656c2d636f6c6c656374696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mcaskill/charcoal-model-collection)[![Build Status](https://camo.githubusercontent.com/4d910f0f6061be79a99dac23632341be20a45f2a66c0a3fad5fdcd42708f2d60/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6d6361736b696c6c2f63686172636f616c2d6d6f64656c2d636f6c6c656374696f6e2e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/mcaskill/charcoal-model-collection)

Support package providing advanced model collections and collection loaders for [Charcoal](https://packagist.org/packages/locomotivemtl/charcoal-core) projects.

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

[](#installation)

```
composer require mcaskill/charcoal-model-collection
```

See [`composer.json`](composer.json) for depenencides.

Collections
-----------

[](#collections)

### 1. `Charcoal\Support\Model\Collection\Collection`

[](#1-charcoalsupportmodelcollectioncollection)

Provides methods to manipulate the collection or retrieve specific models.

#### `filter()`

[](#filter)

Filter the collection of objects using the given callback.

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [
//     1 => Model (active: 1), 2 => Model (active: 0),
//     3 => Model (active: 1), 4 => Model (active: 1),
//     5 => Model (active: 0)
// ]

$filtered = $collection->filter(function ($obj, $id) {
    return ($obj['active'] === true);
});
// [ 1 => Model, 3 => Model, 4 => Model ]
```

#### `forPage()`

[](#forpage)

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

```
$collection = new Collection([ $a, $b, $c, $d, $e, $f, $g, $h, $i, $j ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model,… ]

$chunk = $collection->forPage(2, 3);
// [ 4 => Model, 5 => Model, 6 => Model ]
```

#### `only()`

[](#only)

Extract the objects with the specified keys.

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model ]

$filtered = $collection->only(2);
// [ 2 => Model ]

$filtered = $collection->only([ 1, 3 ]);
// [ 1 => Model, 3 => Model ]

$filtered = $collection->only(2, 4);
// [ 2 => Model, 4 => Model ]
```

#### `pop()`

[](#pop)

Remove and return the last object from the collection.

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model ]

$collection->pop();
// Model (5)

$collection->toArray();
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model ]
```

#### `prepend()`

[](#prepend)

Add an object onto the beginning of the collection.

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model ]

$collection->prepend($o);
// Model (15)

$filtered->toArray();
// [ 15 => Model, 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model ]
```

#### `random()`

[](#random)

Retrieve one or more random objects from the collection.

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model ]

$collection->random();
// Model (3)

$collection->random(2);
// [ 1 => Model, 3 => Model ]
```

#### `reverse()`

[](#reverse)

Reverse the order of objects in the collection.

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model ]

$reversed = $collection->reverse();
// [ 5 => Model, 4 => Model, 3 => Model, 2 => Model, 1 => Model ]
```

#### `shift()`

[](#shift)

Remove and return the first object from the collection.

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model ]

$collection->shift();
// Model (1)

$collection->toArray();
// [ 2 => Model, 3 => Model, 4 => Model, 5 => Model ]
```

#### `slice()`

[](#slice)

Extract a slice of the collection.

```
$collection = new Collection([ $a, $b, $c, $d, $e, $f, $g, $h, $i, $j ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model,… ]

$slice = $collection->slice(4);
// [ 5 => Model, 6 => Model, 7 => Model, 8 => Model, 9 => Model, 10 => Model ]

$slice = $collection->slice(4, 2);
// [ 5 => Model, 6 => Model ]
```

#### `sortBy()`

[](#sortby)

Sort the collection by the given callback or object property.

```
$collection = new Collection([ $a, $b, $c ]);
// [ 1 => Model (position: 5), 2 => Model (position: 2), 3 => Model (position: 0) ]

$sorted = $collection->sortBy('position');
// [ 3 => Model, 2 => Model, 1 => Model ]
```

#### `sortByDesc()`

[](#sortbydesc)

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

#### `take()`

[](#take)

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

```
$collection = new Collection([ $a, $b, $c, $d, $e, $f ]);
// [ 1 => Model, 2 => Model, 3 => Model, 4 => Model, 5 => Model, 6 => Model ]

$chunk = $collection->take(3);
// [ 1 => Model, 2 => Model, 3 => Model ]

$chunk = $collection->take(-2);
// [ 5 => Model, 6 => Model ]
```

#### `where()`

[](#where)

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

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [
//     1 => Model (active: 1), 2 => Model (active: 0),
//     3 => Model (active: 1), 4 => Model (active: 1),
//     5 => Model (active: 0)
// ]

$filtered = $collection->where('active', true);
// [ 1 => Model, 3 => Model, 4 => Model ]
```

#### `whereIn()`

[](#wherein)

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

```
$collection = new Collection([ $a, $b, $c, $d, $e ]);
// [
//     1 => Model (name: "Lorem"), 2 => Model (name: "Ipsum"),
//     3 => Model (name: "Dolor"), 4 => Model (name: "Elit"),
//     5 => Model (name: "Amet")
// ]

$filtered = $collection->whereIn('name', [ 'Amet', 'Dolor' ]);
// [ 3 => Model, 5 => Model ]
```

Repositories
------------

[](#repositories)

### 1. `Charcoal\Support\Model\Repository\CollectionLoaderIterator`

[](#1-charcoalsupportmodelrepositorycollectionloaderiterator)

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

[](#11-lazy-collections)

The `CollectionLoaderIterator` leverages PHP's [generators](https://www.php.net/manual/en/language.generators.overview.php) 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.

```
$repository = (new CollectionLoaderIterator)->setModel(Post::class);

$repository->addFilter('active', true)->addFilter('published  $container['logger'],
    'factory'         => $container['model/factory'],
    'model'           => Post::class,
    'default_filters' => [
        [
            'property' => 'active',
            'value'    => true,
        ],
        [
            'property' => 'publish_date',
            'operator' => 'IS NOT NULL',
        ],
    ],
    'default_orders'  => [
        [
            'property'  => 'publish_date',
            'direction' => 'desc',
        ],
    ],
    'default_pagination' => [
        'num_per_page' => 20,
    ],
]);

$posts = $repository->addFilter('publish_date