2018-03-20 14:44:25 +00:00
|
|
|
# ext-collections
|
|
|
|
|
2018-03-23 09:29:34 +00:00
|
|
|
[![Travis-CI](https://travis-ci.org/CismonX/ext-collections.svg?branch=master)](https://travis-ci.org/CismonX/ext-collections)
|
|
|
|
[![MIT license](https://img.shields.io/badge/licence-MIT-blue.svg)](https://opensource.org/licenses/MIT)
|
|
|
|
|
2018-03-20 14:44:25 +00:00
|
|
|
## 1. Introduction
|
|
|
|
|
|
|
|
This PHP extension provides a set of useful functional-style operations on PHP arrays, which makes array manipulation simple and scalable.
|
|
|
|
|
|
|
|
Method names and functionalities are inspired by [Kotlin.Collections](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/).
|
|
|
|
|
2018-05-26 11:31:14 +00:00
|
|
|
### 1.1 Notes
|
|
|
|
|
2018-08-08 07:55:57 +00:00
|
|
|
* Requires PHP 7.1 and above.
|
2018-08-15 17:23:05 +00:00
|
|
|
* Thread safety:
|
|
|
|
* Distinct objects: **safe**.
|
|
|
|
* Shared objects: **unsafe**.
|
2018-05-26 11:31:14 +00:00
|
|
|
|
2018-03-20 14:44:25 +00:00
|
|
|
## 2. Documentation
|
|
|
|
|
2018-04-22 15:06:49 +00:00
|
|
|
### 2.1 Functionalities
|
|
|
|
|
2018-08-07 16:43:09 +00:00
|
|
|
See [stubs](stubs/) directory for signature of all classes and methods of this extension, with PHPDoc. They can also serve as IDE helper.
|
2018-03-20 14:44:25 +00:00
|
|
|
|
2018-04-22 15:06:49 +00:00
|
|
|
### 2.2 PHP-style access
|
|
|
|
|
|
|
|
The `Collection` class implements `ArrayAccess` and `Countable` interface internally, you can treat an instance of `Collection` as an `ArrayObject`.
|
|
|
|
|
|
|
|
* The `isset()`, `unset()` keywords can be used on elements of `Collection`.
|
2018-05-05 10:29:14 +00:00
|
|
|
* Elements can be accessed via property and bracket expression.
|
2018-04-22 15:06:49 +00:00
|
|
|
* `empty()`, `count()` can be used on instance of `Collection`.
|
|
|
|
* Elements can be traversed via `foreach()` keyword.
|
|
|
|
|
2018-04-26 14:05:26 +00:00
|
|
|
### 2.3 Notes
|
|
|
|
|
|
|
|
* The `Collection::xxxTo()` methods will preserve the original key-value pairs of destination `Collection` when keys collide.
|
|
|
|
|
2018-03-20 14:44:25 +00:00
|
|
|
## 3. Example
|
|
|
|
|
2018-03-31 04:16:59 +00:00
|
|
|
Here is a simple example for how to work with arrays gracefully using this extension.
|
2018-03-20 14:44:25 +00:00
|
|
|
|
|
|
|
```php
|
|
|
|
$employees = [
|
|
|
|
['name' => 'Alice', 'sex' => 'female', 'age' => 35],
|
|
|
|
['name' => 'Bob', 'sex' => 'male', 'age' => 29],
|
|
|
|
['name' => 'David', 'sex' => 'male', 'age' => 40],
|
|
|
|
['name' => 'Benjamin', 'sex' => 'male', 'age' => 32]
|
|
|
|
];
|
|
|
|
// Trying to get an array of names of male employees,
|
|
|
|
// sorted by the descending order of their age.
|
|
|
|
$names = Collection::init($employees)
|
2018-04-22 15:06:49 +00:00
|
|
|
->filter(function ($value) {
|
|
|
|
return $value['sex'] == 'male';
|
2018-03-20 14:44:25 +00:00
|
|
|
})
|
2018-04-22 15:06:49 +00:00
|
|
|
->sortedByDescending(function ($value) {
|
|
|
|
return $value['age'];
|
2018-03-20 14:44:25 +00:00
|
|
|
})
|
2018-07-23 17:24:00 +00:00
|
|
|
->map(function ($value) {
|
2018-04-22 15:06:49 +00:00
|
|
|
return $value['name'];
|
2018-03-20 14:44:25 +00:00
|
|
|
})
|
|
|
|
->toArray();
|
2018-03-28 05:02:51 +00:00
|
|
|
// You got $names == ['David', 'Benjamin', 'Bob'].
|
2018-03-20 14:44:25 +00:00
|
|
|
```
|