pckg/collection

Implementation for more human-like dealing with collections

dev-next-8.0 2022-12-09 19:32 UTC

Requires

• ext-json: *
• pckg/concept: dev-master

Requires (Dev)

• pckg-app/frontend-dev: dev-next-8.0 as dev-master
• pckg/database: dev-next-8.0 as dev-master
• pckg/framework: dev-next-8.0 as dev-master

MIT

• Bojan Rajh

README

Pckg/collection provides a ways handle collection of items / arrays and strings differently. It works really well with pckg/skeleton, pckg/framework and pckg/database.

Installation

For standalone usage simply require pckg/collection in composer.

$ composer require pckg/collection

For advanced usage check pckg/skeleton.

$ composer install pckg/skeleton .

Dependencies

Package does not depend on any other package.

Tests

Test can be run with codeception

$ cp ./codeception.sample.yml ./codeception.yml
$ codecept run

Simple usage

// create a new Collection

$collection = new Collection();

// push items to the last position of the collection

// push some single items

$collection->push('foo');
$collection->push('bar');

// push a whole array

$collection->pushArray(['first', 'second']);

// pop last item and remove it from collection

$item = $collection->pop();

// add an item at the first position

$collection->prepend('prepended');

// retrieve and remove first item

$item = $collection->shift();

// retrieve first and last items keeping then in colection

$collection->first();
$collection->last();

Callbacks

has

Testing if collection has a set of values:

$collection = new Collection([
                                 'foo' => [
                                     'id'    => 1,
                                     'title' => 'baz',
                                 ],
                                 'bar' => [
                                     'id'    => 2,
                                     'title' => 'unknown',
                                 ],
                             ]);

$collection->has(['id' => 1, 'title' => 'baz'])); // return true

$collection->has(['id' => 2, 'title' => 'baz'])); // return false

Filtering entries

Return all itens that has a true return from annonymous function.

$filtered = $collection->filter(function($item) {
    return $item['id'] == 1;
});

var_dump($filtered->all()); // ['foo' => ['id' => 1, 'title' => 'baz']]

Seting keys

Set entry keys by some array item value. At following sample all keys are setted by title inner array entry.

$keyed = $collection->keyBy('title');

var_dump($keyed->all()); 

/**
* [
*     'baz'     => [
*         'id'    => 1,
*         'title' => 'baz',
*     ],
*     'unknown' => [
*         'id'    => 2,
*         'title' => 'unknown',
*     ],
* ]
**/

Get first item by satisfied check

Return the firt item that satisfies a logical test.

$first = $collection->first(function($item) { 
   return $item['id'] > 1; 
});

var_dump($first); //['id' => 2, 'title' => 'unknown']

Map key by inner value

Map the key of each entry to a inner value based on inner key.

$mapped = $collection->map('title');

var_dump($mapped->all()); // ['foo' => 'baz', 'bar' => 'unknown']

Keys and Values

$collection = new Collection(['foo' => 'bar', 'baz' => 'test', 'john' => 'doe', 'jane' => 'name']);

// get a collection with a removed entry based on it key

$removedOne = $collection->removeKeys('baz');  // ['foo' => 'bar', 'john' => 'doe', 'jane' => 'name']

// get a collection with several entries removed based on they keys
        
$removedMultiple = $collection->removeKeys(['baz', 'john']); // ['foo' => 'bar', 'jane' => 'name']
        
// get a collection with several entries removed based on they values
        
$removedValues = $collection->removeValues(['bar', 'test']); // ['john' => 'doe', 'jane' => 'name']

// get all keys of a collection

$keys = $collection->keys(); // ['foo', 'baz', 'john', 'jane']
        
// get all values of a collection

$values = $collection->values(); // ['bar', 'test', 'doe', 'name']
 
// test if a key exist

$collection->hasKey('baz'); // true
$collection->hasKey('bz'); // false

// retrieve the value of a key

$collection->getKey('baz'); // 'test'

Manipulations

Slice a collection

$collection = new Collection(['foo', 'bar', 'baz', '', ' untrimmed ']);

$sliced = $collection->slice(1, 2); // ['bar', 'baz']

Chunk

Chunk by pieces.

$chunked = $collection->chunk(2);

/**
* [
*    ['foo', 'bar'], 
*    ['baz', ''], 
*    [' untrimmed ']
* 
**/

Flat

$flatten = $chunked->flat(); // ['foo', 'bar', 'baz', '', ' untrimmed ']

Trim

$trimmed = $collection->trim(); // ['foo', 'bar', 'baz', '', 'untrimmed']

Multiply by x

Duplicate the items by the number passed.

$multiplied = $collection->multiply(2);

/**
* [
*    'foo',
*    'bar',
*    'baz',
*    '',
*    ' untrimmed ',
*    'foo',
*    'bar',
*    'baz',
*    '',
*    ' untrimmed ',
* ]
**/

unique

Return a collection with no duplicated values

$unique = $multiplied->unique(); // ['foo', 'bar', 'baz', '', 'untrimmed']

Implode

Get a string with all collection values separated by imploded char.

$imploded = $collection->implode(' ', ' - '); // 'foo bar baz  -  untrimmed '

Remove empty values

  
$nonEmpty = $collection->removeEmpty(); // ['foo', 'bar', 'baz', ' untrimmed ']

Math

$collection = new Collection([2, 1, 13, 3, 1, 5, 21, 8]);

$sum = $collection->sum(); // 54

$avg = $collection->avg(); // 6.75
        
$min = $collection->min(); // 1
        
$max = $collection->max(); // 21