Array manipulation extension for PHP.
This repository has been archived on 2020-03-30. You can view files and clone it, but cannot push or open issues or pull requests.
Go to file
CismonX f4b5e60ba9 Update readme and travis config. 2020-03-30 12:28:12 +08:00
src fix bug. refactor code. 2020-03-20 11:15:54 +08:00
stubs update stub 2018-10-24 13:37:37 +08:00
tests Add `zip()`. 2019-01-18 21:37:42 +08:00
.gitattributes small refactor && update documentation 2019-07-25 00:09:02 +08:00
.gitignore integrating Codecov 2020-03-24 11:07:16 +08:00
.travis.yml Update readme and travis config. 2020-03-30 12:28:12 +08:00
LICENSE initial commit 2018-03-20 22:44:25 +08:00
README.md Update readme and travis config. 2020-03-30 12:28:12 +08:00
config.m4 Implement ArrayAccess. Fix config.m4, .travis.yml. Update stubs. 2018-03-31 12:02:13 +08:00
config.w32 Update config.w32. Update README. 2018-08-16 01:23:05 +08:00

README.md

ext-collections

Travis-CI Codecov MIT license

1. Introduction

This PHP extension provides a set of useful and convenient operations on PHP arrays, which makes working with arrays simple and scalable.

Method names and functionalities are inspired by Kotlin.Collections, having a slightly different style than that of Laravel Collections.

Requires PHP version >= 7.1 and < 8.0 (master branch).

1.1 Example

Here is a simple example on how to work with arrays gracefully using this extension.

$employees = [
    ['name' => 'Alice',    'gender' => 'female', 'age' => 35],
    ['name' => 'Bob',      'gender' => 'male',   'age' => 29],
    ['name' => 'David',    'gender' => 'male',   'age' => 40],
    ['name' => 'Benjamin', 'gender' => '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)
    ->filter(function ($value) {
        return $value['gender'] == 'male';
    })
    ->sortedByDescending(function ($value) {
        return $value['age'];
    })
    ->map(function ($value) {
        return $value['name'];
    })
    ->toArray();
// You got $names == ['David', 'Benjamin', 'Bob'].

2. Getting Started

2.1 Installation

Like other PHP extensions, ext-collections can be built with a few commands:

phpize
./configure
make
sudo make install

Include it in your PHP configuration file to enable this extension:

extension=collections.so

2.2 API reference

See stubs directory for signature of all classes and methods of this extension, with PHPDoc. They can also serve as IDE helper.

2.3 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.
  • Elements can be accessed via property and bracket expression.
  • empty(), count() can be used on instance of Collection.
  • Elements can be traversed via foreach() keyword.

3. Notes

  • The Collection::xxxTo() methods will preserve the original key-value pairs of destination Collection when keys collide.
  • Some methods of Collection involves comparing two of its elements, which accepts $flags as one of its arguments. When these methods are being invoked, make sure all elements are of the same type (numeric/string/others), otherwise you're likely to get a segfault.

3.1 Copy-on-write mechanism

Class Collection does not introduce new data structures internally. Instead, it only holds a pointer to a zend_array, and all its methods works directly on top of zend_array. Which means conversion between Collection and array does not involve copying, until write operation is performed on one of the duplicates.

$foo = ['a', 'b'];              // arr0: refcount = 1
$bar = Collection::init($foo);  // arr0: refcount = 2, no copying of either `zend_array` or its elements
echo $bar->containsValue('a');  // arr0: refcount = 2, read operation, no copying
$bar->shuffle();                // arr0: refcount = 1, arr1: refcount = 1, write operation, `zend_array` is separated
$baz = $bar->toArray();         // arr0: refcount = 1, arr1: refcount = 2, no copying