README

An extended version of Laravel's collections

This is my very personal extension of Laravel's amazing Collection class (as extracted by tightenco/collect). It adds some methods that I need regularly.

The declared aim of this project is to feed its methods back into Laravel by making proposals in laravel/ideas.

Install

composer require loilo/collection

Methods

Note: In all code examples below, Collection refers to Loilo\Collection\Collection.

Table of Contents:

• insertBefore()/insertAfter()
• mergeInBefore()/mergeInAfter()
• extract()
• rearrange()

insertBefore()/insertAfter()

Inserts items before/after a reference item (modifies the collection).

Proposal: #650 (declined)

Details: Specification

Examples:

Insert a list of items after a certain value:

$c = Collection::make([ 10, 20, 30, 40 ]);
$c->insertAfter(20, [ 24, 25, 26 ]);
$c->all() === [ 10, 20, 24, 25, 26, 30, 40 ];

Insert data after a certain key:

$c = Collection::make([
    'name' => 'loilo/collection',
    'version' => '1.0.0'
]);

$c->insertAfter(function ($value, $key) {
    return $key === 'name';
}, [ 'description' => "An extended version of Laravel's collections" ]);

$c->all() === [
    'name' => 'loilo/collection',
    'description' => "An extended version of Laravel's collections",
    'version' => '1.0.0'
];

mergeInBefore()/mergeInAfter()

These are equivalent to insertBefore()/insertAfter() but do not modify the collection.

extract()

Extract structures from the collection, kind of an advanced pluck().

Details: Specification

Examples:

Take certain items from a list:

$c = Collection::make([ 1, 2, 3 ])->extract([ 0, 1 ])
$c->all() === [ 1, 2 ];

Transform a collection to a certain structure:

$c = Collection::make([
    'a' => [
        'd' => 3,
        'e' => 4
    ],
    'b' => [
        'd' => 5,
        'e' => 6
    ],
    'c' => [
        'd' => 7,
        'e' => 8
    ]
]);

$c->extract([ 'a' ])->all() === [
    'a' => [
        'd' => 3,
        'e' => 4
    ]
];

$c->extract([ '*' => [ 'd' ] ])->all() === [
    'a' => [ 'd' => 3 ],
    'b' => [ 'd' => 5 ],
    'c' => [ 'd' => 7 ]
];

rearrange()

This method re-orders a collection, according to a predefined order.

Collection::make([ 'a', 'b', 'c' ]);
    ->rearrange([ 2, 0, 1 ])
    ->all() === [ 'c', 'a', 'b' ];

Behavior of Unarrangeable Items

When a collection item is not matched by the new order, it will be appended to the ordered items:

Collection::make([ 'a', 'b', 'c' ]);
    ->rearrange([ 1 ])
    ->all() === [ 'b', 'a', 'c' ];

This behavior is controlled by the second argument of the rearrange() method. The default behavior $c->rearrange([ ... ]) is equivalent to $c->rearrange([ ... ], Collection::UNARRANGEABLE_APPEND).

Possible values for this parameter are:

Map to Reordered Items

By default, the new order passed to rearrange() will map to the collection's keys. However, you may pass any callable as the 3rd parameter to the method to map the order values yourself:

Collection::make([ 'a', 'b', 'c' ]);
    ->rearrange(
        [ 'b', 'a', 'c' ],
        Collection::UNARRANGEABLE_APPEND,
        function ($value, $key) {
            return $value;
        }
    ),
    ->all() === [ 'b', 'a', 'c' ];