Small Collection 2.6

Small Collection 2.6 is out.

A lot of new methods to collections and a new Trigger management.

git : https://git.small-project.dev/lib/small-collection
packagist : https://packagist.org/packages/small/collection

Triggers

Triggers are methods or function to be called at each time a value is inserted :

$collection = new Collection();

$fn = function (&$value, &$key) {
    $value++;
};

$collection->addTrigger($fn);
$collection->merge([1, 2, 3], true);

$collection will be :

[2, 3, 4]

You can add triggers directly in constructor :

• Single trigger

$fn = function (&$value, &$key) {
    $value++;
};
$collection = new Collection([1, 2, 3], $fn);

• Multiple triggers

$collection = new Collection([1, 2, 3], [$fn, $fn2]);

• Or using a CallbackCollection

$callbacks = new \Small\Collection\Collection\CallbackCollection([
    $fn1,
    $fn2,
]);
$collection = new Collection([1, 2, 3], $callbacks);

New methods

flatten

This method bring all values of sub collections in collection.

Example:

$result = (
    new Collection([
        'a' => 1,
        'b' => [
            'e' => 2.1,
            'f' => 2.2
        ], 'c' => 3
    ]))->flatten();

Result :

{
  "a": 1,
  "e": 2.1,
  "f": 2.2,
  "c": 3
}

combine

This method combine a collection with another :

$from = new Collection([
    'a' => 1,
    'b' => 2,
    'c' => 3,
]);

$result = $from->combine(['a' => 2, 'c' => 3, 'z' => 26]);

The values of collection will be keys of result and values of collection to apply will be values of result.

Where no corresponding key, the value is dropped.

{
  "1": 2,
  "3": 3
}

find first occurrences

Return first occurrence of value in collection :

$from = new Collection(['a', 'b', 'c', 'd']);
$from->findFirstOccurrence('b'); // return 1

remove

Remove collection entries which value equal :

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]);
$collection->remove(1);

The collection will be :

{
  "b": 2,
  "c": 3
}

You can pass array or collections of values :

$collection->remove([2, 3]);

subPart

This method return sub partition of collection from a key with a given length :

$collection = new Collection(range(0, 26));
$sub = $collection->subPart(5, 6);

Result :

{
  "5": 5,
  "6": 6,
  "7": 7,
  "8": 8,
  "9": 9,
  "10": 10
}

countDistinct

This method cound number of distinct values :

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 3]);
$cpt = $collection->countDistinct();

$cpt will be 3

dot

This method return a flatten collection which keys are combined keys of sub collection separated by a dot :

$collection = new Collection(['a' => [1, 2], 'b' => [2, 3], 'c' => 3]);
$doted = $collection->dot();

$doted will be a new collection :

{
  "a.0": 1,
  "a.1": 2,
  "b.0": 2,
  "b.1": 3,
  "c": 3
}

It is possible to change the separator :

$doted = $collection->dot('/');

Result :

{
  "a/0": 1,
  "a/1": 2,
  "b/0": 2,
  "b/1": 3,
  "c": 3
}

undot

This method does exactly the reverse way of dotted :

$collection = new Collection(['a.1' => 1, 'b.Z.7' => 2, 'c' => 3]);
$undoted = $collection->undot();

Done :

{
  "a": {
    "1": 1
  },
  "b": {
    "Z": {
      "7": 2
    }
  },
  "c": 3
}

Same as dot, you can change the separator :

$collection = new Collection(['a/1' => 1, 'b/Z/7' => 2, 'c' => 3]);
$undoted = $collection->undot('/');

remove duplicates

This method remove duplicates in a collection :

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3, 'd' => 3]);
$result = $collection->removeDuplicates();

Result :

{
  "a": 1,
  "b": 2,
  "c": 3
}

It is possible to apply modifications directly to the collection :

$collection->removeDuplicates(true);

foreach

This method call a callback for each element :

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]);

$sum = 0;
$collection->foreach(function($value, $key) use(&$sum) {
    $sum += $value;
    return true;
});

$num will be 6.

flip

This method invert keys and values :

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]);
$collection->flip();

$collection will be :

{
  "1": "a",
  "2": "b",
  "3": "c"
}

It is possible to separate result with original collection :

$collection = new Collection(['a' => 1, 'b' => 2, 'c' => 3]);
$result = $collection->flip(true);

$result will be :

{
  "1": "a",
  "2": "b",
  "3": "c"
}

and $collection still be :

{
  "a": 1,
  "b": 2,
  "c": 3
}

paginate

This method return a sub collection corresponding to a page num for a given page size.

$collection = new Collection(range(1, 11));

$page = 1
do {
    $last = $collection->paginate($page, 3);
    if ($last->count() > 0) {
        $result[$page - 1] = $last;
    }
    $page++;
} while ($last->count() > 0);

Rsult will be :

[
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
  [10, 11, 12]
]

values as objects

This method create objects from collection values :

$collection = new Collection([['a', 'b'], ['c']]);
$result = $collection->valuesAsObjects(
    Chars::class,
);

foreach ($result as $item) {
    echo $item->toString() . "\n";
}

The result output will be :

ab
c

odd, even and nth

Odd method give a new collection walking original collection populating only odd walk :

$collection = new Collection([1, 2, 3]);
$result = $collection->odd();

Result will be

[1, 3]

Same for even :

$collection = new Collection([1, 2, 3, 4]);
$result = $collection->even();

Result will be

[2, 4]

nth is the same, but you can define the size of each step :

$collection = new Collection([
    1, 2, 3, 4, 5, 6
]);
$result = nth(3);

$result will be :

[1, 4]

You can also give a beginning offset, which must be less that step size :

$collection = new Collection([
    1, 2, 3, 4, 5, 6
]);
$result = nth(3, 1);

Which result :

[2, 5]

skip

This method skip x occurence of collection :

$collection = new Collection([
    1, 2, 3, 4, 5, 6,
]);
$collection->skip(3);

Will result in :

[4, 5, 6]

transform

Transform translate a collection to another :

$collection = new Collection([
    1, 2, 3, 4, 5, 6,
]);
$result = $collection->transform(NumericCollection::class);

The result collection is a clone of collection, but it is an instance of NumericCollection.

The CheckValueInterface is called to check if all collections values are compatible with destination class.

$collection = new Collection([
    1, 2, 3, 4, 5, 6, 'a'
]);
$result = $collection->transform(NumericCollection::class);

Will throw a ValidationFailException.

Triggers

Triggers are methods or function to be called at each time a value is inserted :

$collection = new Collection();

$fn = function (&$value, &$key) {
    $value++;
};

$collection->addTrigger($fn);
$collection->merge([1, 2, 3], true);

$collection will be :

[2, 3, 4]

You can add triggers directly in constructor :

• Single trigger

$fn = function (&$value, &$key) {
    $value++;
};
$collection = new Collection([1, 2, 3], $fn);

• Multiple triggers

$collection = new Collection([1, 2, 3], [$fn, $fn2]);

• Or using a CallbackCollection

$callbacks = new \Small\Collection\Collection\CallbackCollection([
    $fn1,
    $fn2,
]);
$collection = new Collection([1, 2, 3], $callbacks);