README

#php-chain

A thin abstraction over PHP arrays to help you easily chain array transformation functions.

What problems does this library solve?

The goal of this simple library is to help you work with arrays in PHP, particularly when using multiple of the transformation functions for arrays.

Examples:

Suppose you have an array of arrays such as the following:

    $users = array(
        array(
            'id' => 4,
            'username' => 'jshep',
            'firstName' => 'Jack',
            'lastName' => 'Shepherd',
            'active' => true
         ),
        array(
            'id' => 8,
            'username' => 'jlock',
            'firstName' => 'John',
            'lastName' => 'Lock',
            'active' => false
         ),
        // ...
        array(
            'id' => 23,
            'username' => 'jj-jacob',
            'firstName' => 'Jacob',
            'lastName' => null,
            'active' => false
        ),
        array(
            'id' => 42,
            'username' => 'smokey',
            'firstName' => 'Esau',
            'lastName' => 'Iratus',
            'active' => true
        ),
    );

With that on hand, you may want to map over that array, then filter it, and possibly diff those objects against an identical or similar collection representing the same data models.

    $activeUsers = array_filter($users, function($user) {
          return $user['active'];
    });

    $activeUsernames = array_map(function($user) {
          return $user['username'];
    }, $activeUsers);

One problem you've noticed if you've ever had to use some of PHP's array functions is that the order of the arguments is not consistent. Does the predicate function go before or after the array?

The other problem php-chain aims to solve is to using these functions more terse, and without dropping those intermediary collections along the way.

    $activeUsernames = Formigone\Chain::from($users)
         ->filter(function($user){ return $user['active']; })
         ->map(function($user){ return $user['username']; })
         ->get();

Supported functionality

• map($predicateFunction) - projects the current array into the output of the predicate function
• filter($predicateFunction) - filters the current array with the predicate function
• reduce($predicateFunction, $optInitialValue) - reduces the current array into a value generated by the predicate function
• intersect($predicateFunction, $otherArray) - iterates the current array with each element from the other array, keeping values found in both arrays (whenever the predicate function returns true)
• diff($predicateFunction, $otherArray) - iterates the current array with each element from the other array, keeping values unique to the current array (whenever the predicate function returns false)
• flip() - returns the current array flipping keys and values (not destroying the current array)
• get() - returns a copy of the current array