Implement basic functionality

Author: Florian Eckerstorfer

.gitignore

@@ -0,0 +1,4 @@
+/build
+/composer.lock
+/phpunit.xml
+/vendor

README.md

@@ -0,0 +1,110 @@
+Chain
+=====
+
+> Chain provides you with a consistent and chainable way to work with arrays in PHP.
+
+Made by [Florian Eckerstorfer](https://florian.ec) in Vienna, Europe.
+
+
+Motivation
+----------
+
+Let us be honest. Working with arrays in PHP is a mess. First of all, you have to prefix most (but not all) functions
+with `array_`, the parameter ordering is not consistent. For example, `array_map()` expects the callback as first
+parameter and the array as the second, but `array_filter()` expects the array as first and the callback as second. You
+also have to wrap the function calls around the array, the resulting code is not nice to look, not readable and
+hard to understand.
+
+```php
+$arr = array_filter(
+    array_map(
+        function ($v) { return rand(0, $v); },
+        array_fill(0, 10, 20)
+    ),
+    function ($v) { return $v & 1; }
+);
+```
+
+Chain wraps the array in an object and gives you a chainable interface.
+
+```php
+$arr = Chain::fill(0, 10, 20)
+    ->map(function ($v) { return rand(0, $v); })
+    ->filter(function ($v) { return $v & 1; });
+```
+
+
+Usage
+-----
+
+Chain allows you to create, manipulate and access arrays.
+
+### Array Creation
+
+You can create a Chain by passing an array to the constructor.
+
+```php
+$chain = new Chain([1, 2, 3]);
+```
+
+In addition a Chain can also be created by the static `fill()` method, which is a wrapper for the `array_fill()`
+function.
+
+```php
+$chain = Chain::fill(0, 10, 'foo');
+```
+
+### Array Manipulation
+
+Chains manipulation methods manipulate the underlying array and return the object, that is, they can be chained. Most
+of the methods are simple wrappers around the corresponding `array_` function.
+
+In the following example `->map()` is used to multply each element by `3` and then filter the array to only contain
+odd elements.
+
+```php
+$chain = (new Chain([1, 2, 3]))
+    ->map(function ($v) { return $v*3; })
+    ->filter(function ($v) { return $v & 1; });
+$chain->array; // -> [3, 9]
+```
+
+When a method accepts an array (`->diff()` or `->intersect()`) then you can pass in another instance of `Chain`
+instead of the array.
+
+#### List of Array Manipulation Methods
+
+- `->diff(array|Chain)`
+- `->filter(callable)`
+- `->intersect(array|chain)`
+- `->map(callable)`
+
+### Array Access
+
+Most importantly you can access the underlying array using the public `chain` property.
+
+```php
+$chain = new Chain([1, 2, 3]);
+$chain->array; // -> [1, 2, 3]
+```
+
+Additionally `Chain` contains a number of methods to access properties of the array. In contrast to the manipulation
+methods these methods return a value instead of a reference to the `Chain` object. That is, array access methods are
+not chainable.
+ 
+```php
+$chain = new Chain([1, 2, 3]);
+$chain->count(); // -> 3
+$chain->sum(); // -> 6
+
+$chain->reduce(function ($current, $value) {
+    return $current * $value;
+}, 1); // -> 6
+```
+
+
+#### List of Array Manipulation Methods
+
+- `->count()`
+- `->reduce(callable[, int])`
+- `->sum()`

composer.json

@@ -0,0 +1,10 @@
+{
+    "name": "cocur/chain",
+    "description": "Consistent and chainable array manipulation",
+    "autoload": {
+        "psr-4": {"Cocur\\Chain\\": "src"}
+    },
+    "require-dev": {
+        "phpunit/phpunit": "~4.8"
+    }
+}

examples/diff-intersect-sum.php

@@ -0,0 +1,17 @@
+<?php
+
+use Cocur\Chain\Chain;
+
+require_once __DIR__.'/../vendor/autoload.php';
+
+echo array_sum(array_intersect(
+    array_diff([1, 2, 3, 4, 5], [0, 1, 9]),
+    array_filter([2, 3, 4], function ($v) { return !($v & 1); })
+));
+
+echo "\n";
+
+echo (new Chain([1, 2, 3, 4, 5]))
+    ->diff([0, 1, 9])
+    ->intersect((new Chain([2, 3, 4]))->filter(function ($v) { return !($v & 1); }))
+    ->sum();

examples/fill-map-filter.php

@@ -0,0 +1,20 @@
+<?php
+
+use Cocur\Chain\Chain;
+
+require_once __DIR__.'/../vendor/autoload.php';
+
+$arr = array_filter(
+    array_map(
+        function ($v) { return rand(0, $v); },
+        array_fill(0, 10, 20)
+    ),
+    function ($v) { return $v & 1; }
+);
+
+print_r($arr);
+
+$chain = Chain::fill(0, 10, 20)
+            ->map(function ($v) { return rand(0, $v); })
+            ->filter(function ($v) { return $v & 1; });
+print_r($chain->array);

phpunit.xml.dist

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<phpunit bootstrap="vendor/autoload.php" colors="true">
+    <testsuites>
+        <testsuite name="cocur/chain Test Suite">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory suffix=".php">src</directory>
+        </whitelist>
+    </filter>
+</phpunit>

src/Chain.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Cocur\Chain;
+
+use Cocur\Chain\Link\Count;
+use Cocur\Chain\Link\Diff;
+use Cocur\Chain\Link\Fill;
+use Cocur\Chain\Link\Filter;
+use Cocur\Chain\Link\Intersect;
+use Cocur\Chain\Link\Map;
+use Cocur\Chain\Link\Reduce;
+use Cocur\Chain\Link\Sum;
+
+/**
+ * Chain
+ *
+ * @package   Cocur\Chain
+ * @author    Florian Eckerstorfer
+ * @copyright 2015 Florian Eckerstorfer
+ */
+class Chain
+{
+    use Count,
+        Diff,
+        Filter,
+        Fill,
+        Intersect,
+        Map,
+        Reduce,
+        Sum;
+
+    /**
+     * @var array
+     */
+    public $array;
+
+    /**
+     * @param array $array
+     */
+    public function __construct(array $array = [])
+    {
+        $this->array = $array;
+    }
+}

src/Link/Count.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Cocur\Chain\Link;
+
+/**
+ * Count
+ *
+ * @package   Cocur\Chain\Link
+ * @author    Florian Eckerstorfer
+ * @copyright 2015 Florian Eckerstorfer
+ */
+trait Count
+{
+    /**
+     * @return int
+     */
+    public function count()
+    {
+        return count($this->array);
+    }
+}

src/Link/Diff.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Cocur\Chain\Link;
+
+use Cocur\Chain\Chain;
+
+/**
+ * Diff
+ *
+ * @package   Cocur\Chain\Link
+ * @author    Florian Eckerstorfer
+ * @copyright 2015 Florian Eckerstorfer
+ */
+trait Diff
+{
+    /**
+     * @param Chain|array $array2
+     *
+     * @return Chain
+     */
+    public function diff($array2)
+    {
+        $this->array = array_diff(
+            $this->array,
+            $array2 instanceof Chain ? $array2->array : $array2
+        );
+
+        return $this;
+    }
+}

src/Link/Fill.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Cocur\Chain\Link;
+
+use Cocur\Chain\Chain;
+
+/**
+ * Fill
+ *
+ * @package   Cocur\Chain\Link
+ * @author    Florian Eckerstorfer
+ * @copyright 2015 Florian Eckerstorfer
+ */
+trait Fill
+{
+    /**
+     * @param int   $startIndex
+     * @param int   $num
+     * @param mixed $value
+     *
+     * @return Chain
+     */
+    public static function fill($startIndex, $num, $value = null)
+    {
+        return new self(array_fill($startIndex, $num, $value));
+    }
+}