https://github.com/enzyme/collection
An all encompassing array manager.
https://github.com/enzyme/collection
Last synced: 8 months ago
JSON representation
An all encompassing array manager.
- Host: GitHub
- URL: https://github.com/enzyme/collection
- Owner: enzyme
- License: mit
- Created: 2016-05-19T06:12:01.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2016-10-11T23:24:30.000Z (over 9 years ago)
- Last Synced: 2025-05-31T11:52:57.114Z (about 1 year ago)
- Language: PHP
- Homepage:
- Size: 27.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Collection
[](https://travis-ci.org/enzyme/collection)
[](https://coveralls.io/github/enzyme/collection?branch=develop)
[](https://scrutinizer-ci.com/g/enzyme/collection/?branch=master)
[](https://styleci.io/repos/59178796)
An all encompassing array manager.
# Installation
```bash
$ composer require enzyme/collection
```
# Usage
You can create a collection from a standard PHP array. Once you have a collection, you can make use of all the methods it exposes.
```php
use Acme\Mailer;
use Enzyme\Collection\Collection;
$users = new Collection(['John123', 'Jane456', 'Harry789']);
// Send each user an email.
$users->each(function ($user) {
Mailer::sendWelcomeEmail($user);
});
```
The collection implements `ArrayAccess`, `Iterator` and `Countable`, so you can use it as a standard array.
```php
use Enzyme\Collection\Collection;
$users = new Collection(['John123', 'Jane456', 'Harry789']);
var_dump($users[0]); // 'John123'
```
In the example above, the equivalent and much more readable method would be `$collection->first()`.
# Available methods
| Method signature | Description |
| ---: | :--- |
| `count()` | Return the number of elements in the collection. |
| `each(Closure $fn)` | Execute the callback function provided on each item in the collection. The callback function is passed `$value, $key` as arguments. If the callback returns `false`, the function will return early and will not continue iterating over the remaining items left in the collection.|
| `except(array $keys)` | Return a new collection containing all the keys in the current collection except those whose keys match the ones provided. |
| `filter(Closure $fn)` | Return a new collection will all items that pass the given callback functions truth test. |
| `first()` | Get the value of the first item in the collection. If the collection is empty, a `CollectionException` will be thrown. |
| `firstOrDefault($default = null)` | Same as above, except instead of throwing an exception, return the provided default value. |
| `get($key)` | Get the value associated with the specified key. If the key does not exist, a `CollectionException` will be thrown. |
| `getOrDefault($key, $default = null)` | Same as above, except instead of throwing an exception, return the provided default value. |
| `has($key, $value = null)` | Checks whether the collection has the specified key, and/or key/value pair. |
| `hasCount($min, $max = null)` | Checks whether the collection has the minimum count specified, or a count that falls within the range specified. |
| `isEmpty()` | Whether the collection is empty. |
| `keys()` | Returns an array of all the keys used by the collection. |
| `last()` | Get the value of the last item in the collection. If the collection is empty, a `CollectionException` will be thrown. |
| `lastOrDefault($default = null)` | Same as above, except instead of throwing an exception, return the provided default value. |
| `make(array $initial)` *static* | Static helper method to instantiate a new collection. Useful for when you want to immediately chain a method. Eg: Collection::make([1, 2, 3])->map(...) |
| `map(Closure $fn)` | Execute the callback function provided on each item in the collection. The callback function is passed `$value, $key` as arguments. The return value of the callback function will be saved into a new collection and that collection will be returned as a result |
| `mapWithKey(Closure $fn)` | Execute the given callback function for each element in this collection and save the results to a new collection with the specified key. The callback function should return a 1 element associative array, eg: ['key' => 'value'] to be mapped. |
| `only(array $keys)` | Return a new collection containing only the items in the current collection whose keys match the ones provided. |
| `pluck($pluck_key, $deep = true)` | Grab and return a new collection will all values that have the specified `key`. By default, this will traverse multidimensional arrays. |
| `push($value)` | Return a new collection with the given value pushed onto a copy of the current collection's items. |
| `pushArray(array $data)` | Return a new collection with the given array pushed onto a copy of the current collection's items. |
| `pushWithKey($key, $value)` | Return a new collection with the given key/value pair pushed onto a copy of the current collection's items. |
| `sort(Closure $fn)` | Return a new collection after the user defined sort function has been executed on the items. Same callback function parameters as the PHP `usort` function. |
| `toArray()` | Returns the current collection as a standard PHP array. |
# Contributing
Please see `CONTRIBUTING.md`
# License
MIT - Copyright (c) 2016 Tristan Strathearn, see `LICENSE`