README

This library provides a powerful implementation of the Collection class, offering a rich set of functions that enable developers to work with arrays in PHP more efficiently. Since nearly everything in PHP can be represented as an array, managing them can sometimes become difficult and confusing, especially when working with the array_*() family of functions such as array_map() and array_filter().

SigmaPHP-Collections addresses this challenge by introducing a utility data structure called Collection. It provides a wide range of features including method chaining, mapping, filtering, grouping, chunking, and iteration, allowing developers to work with arrays using a clean object-oriented approach rather than relying on complex and repetitive manual operations.

The Collection class supports all types of arrays and data structures. Collections can contain:

Numeric arrays
Associative arrays
Objects
Nested Collection instances

Note: Collection is mutable by default, which means most operations will modify the underlying collection directly.

However, the following methods are immutable and will always return a new Collection instance without affecting the original collection:

where

chunk

groupBy

pluck

diff

reverse

flatten

partition

zip

unique

map

filter

slice

Keep this behavior in mind when working with collections to avoid unexpected mutations.

Installation

composer require sigmaphp/sigmaphp-collections

Documentation

You can find below the complete list of available methods, along with an example for each one.

all	count	get	take	first	last	set	has	hasKey	keys
values	remove	clear	every	contains	partition	where	push	pop	unique
getIterator	orderBy	sort	map	filter	reduce	merge	shuffle	toJson	slice
range	times	isEmpty	isNotEmpty	avg	max	min	sum	random	chunk
each	groupBy	pluck	diff	reverse	toString	make	flatten	pad	zip

all

Get all items stored inside the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$result = $collection->all();

print_r($result);

/*
Array
(
    [0] => apple
    [1] => banana
    [2] => orange
)
*/

count

Count all elements inside the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$result = $collection->count();

var_dump($result);

// int(3)

get

Get item identified by a specific key.

<?php

$collection = new Collection([
    'name' => 'Ahmed',
    'age' => '15'
]);

$result = $collection->get('name');

var_dump($result);

// string(7) "Ahmed"

take

Get a specific number of items from the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange',
    'grape'
]);

$result = $collection->take(2);

print_r($result);

/*
Array
(
    [0] => apple
    [1] => banana
)
*/

first

Get the first item from the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$result = $collection->first();

var_dump($result);

// string(5) "apple"

last

Get the last item from the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$result = $collection->last();

var_dump($result);

// string(6) "orange"

set

Set a value in the collection using a specific key.

<?php

$collection = new Collection([]);

$collection->set('name', 'Ahmed');

$result = $collection->all();

print_r($result);

/*
Array
(
    [name] => Ahmed
)
*/

has

Check if a value exists in the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$result = $collection->has('banana');

var_dump($result);

// bool(true)

hasKey

Check if a specific key exists in the collection.

<?php

$collection = new Collection([
    'name' => 'Ahmed',
    'age' => '15'
]);

$result = $collection->hasKey('age');

var_dump($result);

// bool(true)

keys

Get all keys stored in the collection.

<?php

$collection = new Collection([
    'name' => 'Ahmed',
    'age' => '15'
]);

$result = $collection->keys();

print_r($result);

/*
Array
(
    [0] => name
    [1] => age
)
*/

values

Get all values stored in the collection.

<?php

$collection = new Collection([
    'name' => 'Ahmed',
    'age' => '15'
]);

$result = $collection->values();

print_r($result);

/*
Array
(
    [0] => Ahmed
    [1] => 15
)
*/

remove

Remove item from the collection using a specific key.

<?php

$collection = new Collection([
    'name' => 'Ahmed',
    'age' => '15'
]);

$collection->remove('age');

$result = $collection->all();

print_r($result);

/*
Array
(
    [name] => Ahmed
)
*/

clear

Remove all items from the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$collection->clear();

$result = $collection->all();

print_r($result);

/*
Array
(
)
*/

every

Check if all items meet a specific condition.

<?php

$collection = new Collection([
    2,
    4,
    6
]);

$result = $collection->every(function ($item, $key) {
    return $item % 2 === 0;
});

var_dump($result);

// bool(true)

contains

Check if any item meets a specific condition.

<?php

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

$result = $collection->contains(function ($item, $key) {
    return $item % 2 === 0;
});

var_dump($result);

// bool(true)

partition

Split collection into 2 groups based on a specific condition.

<?php

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

$result = $collection->partition(function ($item, $key) {
    return $item % 2 === 0;
});

print_r($result[0]->all());
print_r($result[1]->all());

/*
Array
(
    [1] => 2
    [3] => 4
)

Array
(
    [0] => 1
    [2] => 3
    [4] => 5
)
*/

where

Get all items that meet a specific condition using a comparison operator.

Supported operators: =, !=, >, <, >=, <=, ===, !==

<?php

$collection = new Collection([
    [
        'name' => 'Ahmed',
        'age' => 25
    ],
    [
        'name' => 'John',
        'age' => 30
    ],
    [
        'name' => 'Ali',
        'age' => 20
    ]
]);

$result = $collection->where('age', '>=', 25);

print_r($result->all());

/*
Array
(
    [0] => Array
    (
        [name] => Ahmed
        [age] => 25
    )

    [1] => Array
    (
        [name] => John
        [age] => 30
    )
)
*/

push

Add a new item at the end of the collection.

<?php

$collection = new Collection([
    'apple',
    'banana'
]);

$collection->push('orange');

$result = $collection->all();

print_r($result);

/*
Array
(
    [0] => apple
    [1] => banana
    [2] => orange
)
*/

pop

Remove the last item from the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$collection->pop();

$result = $collection->all();

print_r($result);

/*
Array
(
    [0] => apple
    [1] => banana
)
*/

unique

Get all unique items from the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'apple',
    'orange'
]);

$result = $collection->unique();

print_r($result->all());

/*
Array
(
    [0] => apple
    [1] => banana
    [3] => orange
)
*/

orderBy

Order the items in the collection.

<?php

$collection = new Collection([
    30,
    10,
    20
]);

$collection->orderBy();

$result = $collection->all();

print_r($result);

/*
Array
(
    [1] => 10
    [2] => 20
    [0] => 30
)
*/

sort

Sort the collection using a custom callback.

<?php

$collection = new Collection([
    'banana',
    'apple',
    'orange'
]);

$collection->sort(function ($a, $b) {
    return strlen($a) <=> strlen($b);
});

$result = $collection->all();

print_r($result);

/*
Array
(
    [1] => apple
    [0] => banana
    [2] => orange
)
*/

map

Apply a transformation function on all items in the collection.

<?php

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

$result = $collection->map(function ($item) {
    return $item * 10;
});

print_r($result->all());

/*
Array
(
    [0] => 10
    [1] => 20
    [2] => 30
)
*/

filter

Filter items in the collection using a callback function.

<?php

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

$result = $collection->filter(function ($item) {
    return $item % 2 === 0;
});

print_r($result->all());

/*
Array
(
    [1] => 2
    [3] => 4
)
*/

reduce

Reduce all items in the collection into a single value.

<?php

$collection = new Collection([
    10,
    20,
    30
]);

$result = $collection->reduce(function ($acc, $item) {
    return $acc + $item;
});

var_dump($result);

// int(60)

merge

Add multiple items to the collection.

<?php

$collection = new Collection([
    'name' => 'Ahmed'
]);

$collection->merge([
    'age' => 15
]);

$result = $collection->all();

print_r($result);

/*
Array
(
    [name] => Ahmed
    [age] => 15
)
*/

shuffle

Shuffle the order of items in the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$collection->shuffle();

$result = $collection->all();

print_r($result);

/*
Example output:

Array
(
    [0] => orange
    [1] => apple
    [2] => banana
)
*/

toJson

Serialize the collection into JSON.

<?php

$collection = new Collection([
    'name' => 'Ahmed',
    'age' => 15
]);

$result = $collection->toJson();

echo $result;

// {"name":"Ahmed","age":15}

slice

Get a slice of the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange',
    'grape'
]);

$result = $collection->slice(1, 2);

print_r($result->all());

/*
Array
(
    [1] => banana
    [2] => orange
)
*/

range

Create a new collection with integer items between a start and end value.

<?php

$collection = new Collection();

$result = $collection->range(1, 5);

print_r($result->all());

/*
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)
*/

times

Create a new collection with a specific number of items.

<?php

$collection = new Collection();

$result = $collection->times(5, function ($index) {
    return $index * 10;
});

print_r($result->all());

/*
Array
(
    [0] => 0
    [1] => 10
    [2] => 20
    [3] => 30
    [4] => 40
)
*/

isEmpty

Check if the collection contains no items.

<?php

$collection = new Collection([]);

$result = $collection->isEmpty();

var_dump($result);

// bool(true)

isNotEmpty

Check if the collection contains any items.

<?php

$collection = new Collection([
    'apple'
]);

$result = $collection->isNotEmpty();

var_dump($result);

// bool(true)

avg

Get the average value of all items in the collection.

<?php

$collection = new Collection([
    10,
    20,
    30
]);

$result = $collection->avg();

var_dump($result);

// float(20)

min

Get the minimum value from the collection.

<?php

$collection = new Collection([
    30,
    10,
    20
]);

$result = $collection->min();

var_dump($result);

// int(10)

max

Get the maximum value from the collection.

<?php

$collection = new Collection([
    30,
    10,
    20
]);

$result = $collection->max();

var_dump($result);

// int(30)

sum

Get the sum of all values in the collection.

<?php

$collection = new Collection([
    10,
    20,
    30
]);

$result = $collection->sum();

var_dump($result);

// int(60)

random

Get one or more random items from the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange',
    'grape'
]);

$result = $collection->random(2);

print_r($result);

/*
Example output:

Array
(
    [0] => banana
    [1] => grape
)
*/

chunk

Create a new collection with items divided into smaller chunks.

<?php

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

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

foreach ($result->all() as $chunk) {
    print_r($chunk);
}

/*
Array
(
    [0] => 1
    [1] => 2
)

Array
(
    [0] => 3
    [1] => 4
)

Array
(
    [0] => 5
)
*/

each

Iterate over all items in the collection and apply a callback.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$collection->each(function ($item) {
    echo strtoupper($item) . PHP_EOL;
});

/*
APPLE
BANANA
ORANGE
*/

groupBy

Group all items in the collection by a specific key.

<?php

$collection = new Collection([
    ['name' => 'Ahmed', 'country' => 'UAE'],
    ['name' => 'John', 'country' => 'USA'],
    ['name' => 'Ali', 'country' => 'UAE']
]);

$result = $collection->groupBy('country');

print_r($result->all());

/*
Array
(
    [UAE] => Array
    (
        [0] => Array
        (
            [name] => Ahmed
            [country] => UAE
        )

        [1] => Array
        (
            [name] => Ali
            [country] => UAE
        )
    )

    [USA] => Array
    (
        [0] => Array
        (
            [name] => John
            [country] => USA
        )
    )
)
*/

pluck

Extract all values for a specific key.

<?php

$collection = new Collection([
    ['name' => 'Ahmed', 'country' => 'UAE'],
    ['name' => 'John', 'country' => 'USA'],
    ['name' => 'Ali', 'country' => 'UAE']
]);

$result = $collection->pluck('name');

print_r($result->all());

/*
Array
(
    [0] => Ahmed
    [1] => John
    [2] => Ali
)
*/

diff

Find the differences between two collections.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$compare = new Collection([
    'banana'
]);

$result = $collection->diff($compare);

print_r($result->all());

/*
Array
(
    [0] => apple
    [2] => orange
)
*/

reverse

Reverse the order of the items in the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$reverse = $collection->reverse();

print_r($reverse->all());

/*
Array
(
    [2] => orange
    [1] => banana
    [0] => apple
)
*/

toString

Get the string representation of the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$result = $collection->toString();

echo $result;

// Collection(64): 00000000000000000000000000000000

make

Create a new collection using the static factory method.

<?php

$collection = Collection::make([
    'apple',
    'banana',
    'orange'
]);

print_r($collection->all());

/*
Array
(
    [0] => apple
    [1] => banana
    [2] => orange
)
*/

flatten

Convert a multi-dimensional collection into a single-dimensional collection.

<?php

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

$result = $collection->flatten();

print_r($result->all());

/*
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
    [5] => 6
)
*/

pad

Fill the collection with a value until reaching a specific size.

<?php

$collection = new Collection([
    'apple',
    'banana'
]);

$result = $collection->pad(5, 'unknown');

print_r($result->all());

/*
Array
(
    [0] => apple
    [1] => banana
    [2] => unknown
    [3] => unknown
    [4] => unknown
)
*/

zip

Merge the items of another array with the collection.

<?php

$collection = new Collection([
    'apple',
    'banana',
    'orange'
]);

$result = $collection->zip([
    'red',
    'yellow',
    'orange'
]);

print_r($result->all());

/*
Array
(
    [0] => Array
    (
        [0] => apple
        [1] => red
    )

    [1] => Array
    (
        [0] => banana
        [1] => yellow
    )

    [2] => Array
    (
        [0] => orange
        [1] => orange
    )
)
*/

License

(SigmaPHP-Collections) released under the terms of the MIT license.

sigmaphp/sigmaphp-collections

包简介

关键字：

README 文档