init

.gitignore

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

LICENSE

@@ -0,0 +1,19 @@
+Copyright 2020 Jarek Jakubowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,84 @@
+# Immutable, type-aware PHP Collection
+
+Collection pattern implementation with map, flatMap, reduce, sort, unique etc. methods. Serializable to JSON.
+
+## Requirements
+
+PHP >= 7.1
+
+## Installation
+This package is available on composer via packagist.
+
+`composer require jarjak/collection`
+
+## Basic usage
+
+### Initialization
+```php
+use JarJak\Collection\Collection;
+
+$dateArray = [
+    new DateTime(),
+    new DateTimeImmutable(),
+];
+
+$dateCollection = new Collection(...$dateArray);
+# or
+$dateCollection = Collection::from($dateArray);
+
+# then do what you know from other collection implementations
+$plusYears = $dateCollection
+    ->map(fn($date) => $date->modify('+1 year'))
+    ->toArray();
+```
+
+### Adding type check feature
+```php
+use JarJak\Collection\Collection;
+
+class DateCollection extends Collection
+{
+    // accept only date objects
+    public function __construct(DateTimeInterface ...$items)
+    {
+        parent::__construct(...$items);
+    }
+
+    // you can personalize it by adding custom methods too!
+    public function getMaxYear(): int
+    {
+        return $this->reduce(
+            0, 
+            function (int $current, DateTimeInterface $date): int {
+                $year = (int) $date->format('Y');
+                return $current > $year ? $current : $year; 
+            }
+        );
+    }
+}
+
+# this is ok
+$dateCollection = new DateCollection(
+    new DateTime(),
+    new DateTimeImmutable()
+);
+# this is not
+$dateCollection = new DateCollection(
+    new DateTime(),
+    new DateTimeImmutable(),
+    date('now')
+);
+
+# then this will work
+$plusYears = $dateCollection->map(fn($date) => $date->modify('+1 year'));
+# but this won't
+$dateStrings = $dateCollection->map(fn($date) => $date->format('Y-m-d'));
+# unless you explicitly disable type check (which effectively sends you back to the base Collection class)
+$dateStrings = $dateCollection
+    ->disableTypeCheck()
+    ->map(fn($date) => $date->format('Y-m-d'));
+```
+
+## Inspired by
+
+https://github.com/jkoudys/immutable.php

composer.json

@@ -0,0 +1,44 @@
+{
+  "name": "jarjak/collection",
+  "type": "library",
+  "description" : "Immutable, type-aware PHP Collection.",
+  "keywords": ["collection", "immutable"],
+  "homepage": "https://github.com/JarJak/Collection",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Jarek Jakubowski",
+      "email": "[email protected]"
+    }
+  ],
+  "require": {
+    "php": ">=7.1"
+  },
+  "scripts": {
+    "post-update-cmd": "cp -n phpunit.xml.dist phpunit.xml",
+    "test": [
+      "vendor/bin/phpunit",
+      "@cscheck"
+    ],
+    "cscheck": [
+      "php -d memory_limit=1024M vendor/bin/ecs check"
+    ],
+    "csfix": [
+      "php -d memory_limit=1024M vendor/bin/ecs check --fix"
+    ]
+  },
+  "autoload": {
+    "psr-4": {
+      "JarJak\\Collection\\": "src/JarJak/Collection"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Tests\\": "tests/"
+    }
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^9.4",
+    "symplify/easy-coding-standard": "^8.3"
+  }
+}

ecs.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpCsFixer\Fixer\ClassNotation\ClassDefinitionFixer;
+use PhpCsFixer\Fixer\ControlStructure\YodaStyleFixer;
+use PhpCsFixer\Fixer\PhpTag\BlankLineAfterOpeningTagFixer;
+use PhpCsFixer\Fixer\Whitespace\ArrayIndentationFixer;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use Symplify\CodingStandard\Fixer\ArrayNotation\ArrayOpenerAndCloserNewlineFixer;
+use Symplify\CodingStandard\Sniffs\Debug\CommentedOutCodeSniff;
+use Symplify\EasyCodingStandard\ValueObject\Option;
+use Symplify\EasyCodingStandard\ValueObject\Set\SetList;
+
+return static function (ContainerConfigurator $containerConfigurator): void {
+    $services = $containerConfigurator->services();
+    $services->set(BlankLineAfterOpeningTagFixer::class);
+    $services->set(CommentedOutCodeSniff::class);
+    $services->set(YodaStyleFixer::class)
+        ->call('configure', [
+            [
+                'equal' => true,
+                'identical' => true,
+                'less_and_greater' => null,
+            ],
+        ]);
+
+    $parameters = $containerConfigurator->parameters();
+
+    $parameters->set(Option::SETS, [
+        SetList::COMMON,
+        SetList::PHP_70,
+        SetList::PHP_71,
+        SetList::PHP_73_MIGRATION,
+        SetList::PSR_12,
+        SetList::CLEAN_CODE,
+        SetList::DEAD_CODE,
+    ]);
+
+    $parameters->set(Option::PATHS, [
+        __DIR__ . '/src',
+        __DIR__ . '/tests',
+        __DIR__ . '/ecs.php',
+    ]);
+
+    $parameters->set(Option::SKIP, [
+        ArrayIndentationFixer::class => [
+            '*Test.php',
+        ],
+        ArrayOpenerAndCloserNewlineFixer::class => [
+            '*Test.php',
+        ],
+        ClassDefinitionFixer::class => [
+            '*Test.php',
+        ],
+    ]);
+};

phpunit.xml.dist

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.8/phpunit.xsd"
+         backupGlobals="false"
+         colors="true"
+         bootstrap="./vendor/autoload.php"
+>
+    <php>
+        <ini name="error_reporting" value="-1" />
+    </php>
+
+    <testsuites>
+        <testsuite name="Collection Test Suite">
+            <directory>./tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

src/JarJak/Collection/Collection.php

@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace JarJak\Collection;
+
+class Collection extends \SplFixedArray implements \JsonSerializable
+{
+    public function __construct(...$items)
+    {
+        parent::__construct(\count($items));
+
+        foreach ($items as $i => $item) {
+            $this[$i] = $item;
+        }
+    }
+
+    public static function from(iterable $array)
+    {
+        return new static(...$array);
+    }
+
+    public function isEmpty(): bool
+    {
+        return 0 === $this->count();
+    }
+
+    /**
+     * Run before map or flatMap to accept other collection items than parent collection
+     */
+    public function disableTypeCheck(): self
+    {
+        return new self(...$this);
+    }
+
+    /**
+     * Closure result must be of type accepted by this collection, unless disableTypeCheck() has been called before
+     */
+    public function map(\Closure $callback)
+    {
+        return static::from(array_map($callback, $this->toArray()));
+    }
+
+    /**
+     * Closure result must be an iterable of types accepted by this collection, unless disableTypeCheck() has been called before
+     */
+    public function flatMap(\Closure $callback)
+    {
+        return static::from(
+            array_merge(
+                ...array_map(
+                    $callback,
+                    $this->toArray()
+                )
+            )
+        );
+    }
+
+    public function reduce($initial, \Closure $reductor)
+    {
+        return array_reduce($this->toArray(), $reductor, $initial);
+    }
+
+    public function filter(?\Closure $callback = null)
+    {
+        if (null === $callback) {
+            $callback = fn ($a): bool => null !== $a;
+        }
+
+        return static::from(array_filter($this->toArray(), $callback, ARRAY_FILTER_USE_BOTH));
+    }
+
+    public function remove($element)
+    {
+        $array = $this->toArray();
+        foreach (array_keys($array, $element, true) as $key) {
+            unset($array[$key]);
+        }
+
+        return static::from($array);
+    }
+
+    /**
+     * @param callable|null $comparator fn($a,$b) must return true if same elements, false otherwise
+     */
+    public function unique(?callable $comparator = null)
+    {
+        if (null === $comparator) {
+            $comparator = fn ($a, $b): bool => $a === $b;
+        }
+
+        $newCount = 0;
+        $unique = new \SplFixedArray($this->count());
+
+        foreach ($this as $el) {
+            for ($i = $newCount; $i >= 0; $i--) {
+                // going from back to forward to find sequence of duplicates faster
+                if ($comparator($unique[$i], $el)) {
+                    continue 2;
+                }
+            }
+            $unique[$newCount++] = $el;
+        }
+
+        $unique->setSize($newCount);
+
+        return static::from($unique);
+    }
+
+    public function sort(?callable $comparator = null): self
+    {
+        $array = $this->toArray();
+
+        if ($comparator) {
+            usort($array, $comparator);
+        } else {
+            sort($array);
+        }
+
+        return static::from($array);
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
+}