README

Adds support for Laravel collections to Kirby

Installation

unzip master.zip as folder site/plugins/kirby3-collect or
git submodule add https://github.com/bnomei/kirby3-collect.git site/plugins/kirby3-collect or
composer require bnomei/kirby3-collect

Why Laravel collections?

This is a plugin for those that create web-projects in Kirby that have to manipulate lots of array data and want to refactor to collections to avoid excessive use of foreach-loops and if-clauses.

Usage

See official Laravel docs on how to use the collect-helper and the collection methods.

all, average, avg, chunk, chunkWhile, collapse, collect, combine, concat, contains, containsStrict, count, countBy, crossJoin, dd, diff, diffAssoc, diffKeys, doesntContain, dump duplicates, duplicatesStrict, each, eachSpread, every, except, filter, first, firstOrFail, firstWhere, flatMap, flatten, flip, forget, forPage, get, groupBy, has, implode, intersect, intersectByKeys, isEmpty, isNotEmpty, join, keyBy, keys, last, lazy, macro, make, map, mapInto, mapSpread, mapToGroups, mapWithKeys, max, median, merge, mergeRecursive, min, mode, nth, only, pad, partition, pipe, pipeInto, pipeThrough, pluck, pop, prepend, pull, push, put, random, range, reduce, reduceSpread, reject, replace, replaceRecursive, reverse search, shift, shuffle, sliding, skip, skipUntil, skipWhile, slice, sole, some, sort, sortBy, sortByDesc, sortDesc, sortKeys, sortKeysDesc, sortKeysUsing, splice, split, splitIn, sum, take, takeUntil, takeWhile, tap, times, toArray, toJson, transform, undot, union, unique, uniqueStrict, unless, unlessEmpty, unlessNotEmpty, unwrap, values, when, whenEmpty, whenNotEmpty, where, whereStrict, whereBetween, whereIn, whereInStrict, whereInstanceOf, whereNotBetween, whereNotIn, whereNotInStrict, whereNotNull, whereNull, wrap, zip

The methodnames in bold indicate that Kirby has a similar collection method. It also features to some additional methods.

Laravel collections from an array

You can also get a laravel collection object from any array.

$laravelCollection = collect($array);

Create a Laravel collection from a Kirby collection

// retrieve a kirby collection
$kirbyCollection = site()->index()->children();

// get a laravel collection object from a kirby collection
$laravelCollection = $kirbyCollection->collect();
$laravelCollection = $kirbyCollection->_();

Primitive data-types only

You can also convert all objects into primitive types using json encoding and decoding. But be warned that most of Kirby's core objects will not (yet) automatically serialize themselves.

$laravelCollection = $kirbyCollection->collect(true); 
$laravelCollection = $kirbyCollection->_(true);

When to use Laravel collection methods (and when not)

To achieve certain common use-cases the Laravel collections methods are a bit more explicit than Kirby's collection methods.

$mostPopularPage = $kirbyCollection
    ->sortBy('viewcount')
    ->last()
    ->viewcount()
    ->toInt();
    
$mostPopularPage = $kirbyCollection
    ->collect()
    ->max('content.viewcount');

$hasProductWithBookcase = $kirbyCollection
    ->filterBy('product', '==', 'Bookcase')
    ->count() > 0;
    
$hasProductWithBookcase = $kirbyCollection
    ->collect()
    ->contains('content.product', 'Bookcase');

But keep in mind that Kirby's collection methods have been tailored to work with the core objects like Page and make some tasks very easy where using Laravel collection methods would be more tedious.

$allTags = $kirbyCollection
    ->pluck('tags', ', ', true);
    
$allTags = $kirbyCollection
    ->collect()
    ->pluck('content.tags')
    ->flatMap(fn($item) => explode(', ', $item))
    ->unique();

Underscore shorthand

Instead of calling the ->collect()/_() collection method evert time you can also use underscore to start with laravel collections object. But any further method calls do not need the _ prefix.

$mostPopularPage = $kirbyCollection
    ->_max('content.viewcount');

$hasProductWithBookcase = $kirbyCollection
    ->_contains('content.product', 'Bookcase');

$allTags = $kirbyCollection
    ->_pluck('content.tags')
    ->flatMap(fn($item) => explode(', ', $item))
    ->unique();

Dependencies

illuminate/collections

Disclaimer

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.

License

MIT

It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.

bnomei / kirby3-collect

Maintainers

Details