Initial Commit

Author: Daniel Gomes

.gitignore

@@ -0,0 +1,2 @@
+composer.lock
+vendor/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Daniel Gomes
+
+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,94 @@
+# Minimalist and Typed Immutable Collections for PHP
+
+A library that provides a set of minimalist, typed and piped Immutable Collections for PHP.
+
+#### What Problems does this solve?
+
+* Immutable List Collection
+* Immutable Set Collection
+
+#### Why Typed Immutable Collections
+
+###### Typed Collections
+
+Since PHP does not have [Generics](https://en.wikipedia.org/wiki/Generics_in_Java) like Java has, it's not possible to have native typed collections.
+The Collections available in this Library are the foundation for you to create your own Typed Collections, you just need to extend them.
+
+###### Typed Immutable Collections for [DDD (Domain Driven Design)](https://en.wikipedia.org/wiki/Domain-driven_design)
+
+DDD is all about having your code speaking the business language, the called Ubiquitous Language. Without Collections in PHP this is very hard to achieve using `Arrays` because you cannot add behavior to them. So what usually happens you add that behavior to your entity but it shouldn't be there. Another problem is the mutability of `Arrays`, `VOs` (Value Objects) **MUST** be always **immutable** and that's impossible with `Arrays` and you should always guarantee that the `elements` of that `Array` are all of the same type. 
+
+#### Collections vs [Arrays](https://secure.php.net/manual/pt_BR/language.types.array.php)
+
+* `Collections` and `Arrays` both represent a Group of Elements.
+* `Collections` are not natively supported by PHP while `Arrays` are.
+* `Arrays` is THE data structure of PHP and is used for almost everything.
+* `Arrays` don't allow you to add new behavior while `Collections` allow it.
+* `Arrays` don't allow you to define a **type** for its elements while `Collections` allow it.  
+
+#### Other PHP Collections
+
+There are other Collections for PHP out there, naming a few we have [Doctrine Collections](https://github.com/doctrine/collections/tree/master/lib/Doctrine/Common/Collections) and [Illuminate Collections](https://github.com/illuminate/support/blob/master/Collection.php).
+Those collections they solve different problems, are tailored to their specific use case, and their APIs are extensive and more important those Collections are Mutable.
+These combinations make it difficult to use those Collections for more simple use cases.
+That's why the Collections we provide here, have a very small API and don't even expose the Iterator API.
+This way you have the possibility to use them and extend it's behavior tailored for your needs. 
+
+#### Features
+
+* Static construction for pipe usage.
+* Util methods like `isEmpty`, `count`, `toArray`, `contains`, `get` ,`map`, `filter`, `slice`, `merge`, `reverse`, `reduce`, `first`, `last`, `head`, `tail`.
+
+#### Basic usage
+
+###### Creating a Typed List Collection
+
+```php
+<?php
+
+use DCSG\ImmutableCollections\Collection;
+
+final class MyStringCollection extends Collection {
+    // We have to override the `validateItems` in order to ensure the right Type for the Collection.
+    protected function validateItems(array $elements): void
+    {
+        foreach ($elements as $element) {
+            if (!\is_string($element)) {
+                throw new InvalidArgumentException('Element is not a String.');
+            }
+        }
+    }
+}
+
+$collection = MyStringCollection::create(['foo', 'bar']);
+echo $collection->count(); // 2
+```
+
+###### Creating a Typed Set Collection
+
+```php
+<?php
+
+use DCSG\ImmutableCollections\SetCollection;
+
+final class MyStringSetCollection extends SetCollection {
+    // We have to override the `validateItems` in order to ensure the right Type for the Collection.
+    protected function validateItems(array $elements): void
+    {
+        foreach ($elements as $element) {
+            if (!\is_string($element)) {
+                throw new InvalidArgumentException('Element is not a String.');
+            }
+        }
+    }
+}
+
+$collection = MyStringSetCollection::create(['foo', 'bar']);
+echo $collection->count(); // 2
+
+$collection = MyStringSetCollection::create(['foo', 'bar', 'foo']); // Throws InvalidArgumentException
+```
+
+## Examples
+
+We provide two simple examples for better understanding. One related to [invoices](https://github.com/dcsg/php-immutable-collections/blob/master/examples/Invoices/app.php) and another one regarding [Legs of a Cargo Ship](https://github.com/dcsg/php-immutable-collections/blob/master/examples/CargoLegs/app.php).

composer.json

@@ -0,0 +1,36 @@
+{
+  "name": "dcsg/php-immutable-collections",
+  "type": "library",
+  "description": "Minimalist and Typed Immutable Collections",
+  "keywords": [
+    "collection",
+    "immutable",
+    "immutable-collection",
+    "pipe"
+  ],
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Daniel Gomes",
+      "email": "[email protected]",
+      "homepage": "https://dcsg.me"
+    }
+  ],
+  "require": {
+    "php": "^7.1"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^7"
+  },
+  "autoload": {
+    "psr-4": {
+      "DCSG\\ImmutableCollections\\": "src",
+      "Test\\DCSG\\ImmutableCollections\\": "tests"
+    }
+  },
+  "scripts": {
+    "test": [
+      "./vendor/bin/phpunit"
+    ]
+  }
+}

examples/CargoLegs/Leg.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Examples\DCSG\ImmutableCollections\CargoLegs;
+
+final class Leg
+{
+    /** @var string */
+    private $from;
+
+    /** @var string */
+    private $to;
+
+    /** @var float */
+    private $distance;
+
+    public function __construct(string $from, string $to, float $distance)
+    {
+        $this->from = $from;
+        $this->to = $to;
+        $this->distance = $distance;
+    }
+
+    public function from(): string
+    {
+        return $this->from;
+    }
+
+    public function to(): string
+    {
+        return $this->to;
+    }
+
+    /**
+     * @return float
+     */
+    public function distance(): float
+    {
+        return $this->distance;
+    }
+
+    public function __toString(): string
+    {
+        return "From: {$this->from()}\tTo: {$this->to()}\tDistance: {$this->distance()}";
+    }
+}

examples/CargoLegs/Legs.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Examples\DCSG\ImmutableCollections\CargoLegs;
+
+use InvalidArgumentException;
+use DCSG\ImmutableCollections\Collection;
+
+/**
+ * @method Leg first()
+ * @method Leg last()
+ * @method Leg head()
+ * @method Leg[] getIterator(): CollectionIterator
+ */
+final class Legs extends Collection
+{
+    public function from(string $location): Legs
+    {
+        return $this->filter(function (Leg $leg) use ($location) {
+            return $leg->from() === $location;
+        });
+    }
+
+    public function to(string $location): Legs
+    {
+        return $this->filter(function (Leg $leg) use ($location) {
+            return $leg->to() === $location;
+        });
+    }
+
+    public function totalDistance(): float
+    {
+        return (float)$this->reduce(function (?float $total, Leg $leg): float {
+            return $total + $leg->distance();
+        });
+    }
+
+    public function printLog(): void
+    {
+        foreach ($this as $leg) {
+            echo "{$leg}\n";
+        }
+    }
+
+    /**
+     * @param Leg[] $legs
+     */
+    protected function validateItems(array $legs): void
+    {
+        foreach ($legs as $leg) {
+            if (!$leg instanceof Leg) {
+                throw new InvalidArgumentException('Element is not an instance of Leg');
+            }
+        }
+    }
+}

examples/CargoLegs/app.php

@@ -0,0 +1,26 @@
+<?php
+
+$loader = require __DIR__ . '/../../vendor/autoload.php';
+$loader->addPsr4('Examples\\DCSG\\ImmutableCollections\\CargoLegs\\', __DIR__);
+
+use Examples\DCSG\ImmutableCollections\CargoLegs\Leg;
+use Examples\DCSG\ImmutableCollections\CargoLegs\Legs;
+
+$legs = Legs::create([
+    new Leg('Lisbon', 'Porto', 240),
+    new Leg('Lisbon', 'Aveiro', 200),
+    new Leg('Lisbon', 'Setubal', 40),
+    new Leg('Porto', 'Setubal', 280),
+    new Leg('Porto', 'Lisbon', 240),
+]);
+
+$totalDistance = $legs->totalDistance();
+
+echo "Total distance: {$totalDistance}km\n";
+echo "# Legs from Lisbon: {$legs->from('Lisbon')->count()}\n";
+echo "# Legs to Setubal: {$legs->to('Setubal')->count()}\n";
+echo "# Legs from Porto: {$legs->from('Porto')->count()}\n";
+echo "# Legs to Porto: {$legs->to('Porto')->count()}\n";
+
+echo "\n## Log\n";
+$legs->printLog();

examples/Invoices/Invoice.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Examples\DCSG\ImmutableCollections\Invoices;
+
+final class Invoice
+{
+    /** @var string */
+    private $id;
+    /** @var int */
+    private $number;
+    /** @var int */
+    private $year;
+    /** @var InvoiceItems */
+    private $items;
+    /** @var bool */
+    private $paid;
+
+    public function __construct(string $id, int $number, int $year, InvoiceItems $items)
+    {
+        $this->id = $id;
+        $this->number = $number;
+        $this->year = $year;
+        $this->items = $items;
+        $this->paid = false;
+    }
+
+    public function pay(): void
+    {
+        $this->paid = true;
+    }
+
+    public function isPaid(): bool
+    {
+        return $this->paid;
+    }
+
+    public function totalIncludingVAT(): float
+    {
+        return $this->items()->totalIncludingVAT();
+    }
+
+    public function items(): InvoiceItems
+    {
+        return $this->items;
+    }
+
+    public function totalExcludingVAT(): float
+    {
+        return $this->items()->totalExcludingVAT();
+    }
+
+    public function __toString(): string
+    {
+        $paid = $this->isPaid() ? 'Yes' : 'No';
+
+        return "Invoice # {$this->number}/{$this->year}\tPaid: {$paid}\tTotal excl. VAT: {$this->totalExcludingVAT()}\tTotal incl. VAT: {$this->totalIncludingVAT()}";
+    }
+}