Add library

Author: 1blankz7

.gitignore

@@ -0,0 +1,3 @@
+.idea/
+/vendor/
+/composer.lock

.travis-ci.yml

@@ -0,0 +1,20 @@
+language: php
+
+matrix:
+  include:
+    - php: 5.6
+    - php: hhvm
+    - php: 7.0
+    - php: 7.1
+    - php: nightly
+  allow_failures:
+    - php: nightly
+  fast_finish: true
+
+before_install:
+
+install:
+  - composer install
+
+script:
+   - vendor/bin/phpunit tests

README.md

@@ -1,2 +1,20 @@
-# php-sorting
-A sorting library for PHP
+Sorting Module
+==============
+
+Implementation of a generic sorting system with an interface definition compatible
+to the [Comparable RFC](https://wiki.php.net/rfc/comparable).
+
+## Usage
+
+You have two possible options. Depending on your use case you can implement the
+`Sorting\Comparable` interface or use a comparator.
+
+```php
+<?php
+
+// with a comparable
+$orderedList = $sortManager->sortComparable($unorderedListOfComparable);
+
+// or with a comparator
+$orderedList = $sortManager->sortWithComparator($comparator, $unorderedList);
+```

composer.json

@@ -0,0 +1,27 @@
+{
+    "name": "1blankz7/php-sorting",
+    "description": "A sorting library for PHP",
+    "keywords":     ["array", "sorting"],
+    "homepage":     "https://github.com/1blankz7/php-sorting",
+    "type": "library",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Christian Blank",
+            "email": "1blankz7@googlemail.com"
+        }
+    ],
+    "require-dev": {
+        "phpunit/phpunit": "^5.7"
+    },
+    "autoload": {
+        "psr-4": {
+            "Sorting\\": [
+                "src"
+            ],
+            "Sorting\\Test\\": [
+                "tests"
+            ]
+        }
+    }
+}

src/Comparable.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Sorting;
+
+use Sorting\Exception\InvalidComparisonException;
+
+/**
+ * Interface for the natural ordering of objects.
+ *
+ * @package Sorting
+ */
+interface Comparable {
+
+    /**
+     * Compares the current object to the passed $other.
+     *
+     * Returns 0 if they are semantically equal, 1 if the other object
+     * is less than the current one, or -1 if its more than the current one.
+     *
+     * @param mixed $other
+     *
+     * @return int
+     * @throws InvalidComparisonException
+     */
+    public function compareTo($other);
+}

src/ComparatorInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Sorting;
+
+/**
+ * Interface ComparatorInterface
+ *
+ * @package Sorting
+ */
+interface ComparatorInterface
+{
+    /**
+     * @param mixed $a
+     * @param mixed $b
+     *
+     * @return int
+     */
+    public function compare($a, $b);
+}

src/Exception/InvalidComparisonException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Sorting\Exception;
+
+use \Exception;
+
+/**
+ * Exception should be thrown if a given value or object cannot be compared to
+ * another value or object.
+ *
+ * @package Sorting\Exception
+ */
+class InvalidComparisonException extends Exception
+{
+
+}

src/SortManager.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Sorting;
+
+/**
+ * Class SortManager
+ *
+ * @package Sorting
+ */
+class SortManager implements SortManagerInterface
+{
+    /**
+     * @inheritdoc
+     */
+    public function sortWithComparator(ComparatorInterface $comparator, array $list)
+    {
+        usort($list, [$comparator, 'compare']);
+
+        return $list;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function sortComparable(array $list)
+    {
+        usort(
+            $list,
+            function(Comparable $a, Comparable $b) {
+                return $a->compareTo($b);
+            }
+        );
+
+        return $list;
+    }
+}

src/SortManagerInterface.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Sorting;
+
+/**
+ * A sort manager handles user defined sorting of objects or value types. Make sure
+ * that the objects or the values you want to sort have a total ordering, otherwise
+ * the result of the methods is not specified.
+ *
+ * @package Sorting
+ */
+interface SortManagerInterface
+{
+    /**
+     * Sort a list of values or objects by a given comparator.
+     *
+     * @param ComparatorInterface $comparator
+     * @param array $list a possible unsorted list
+     *
+     * @return array the sorted list
+     */
+    public function sortWithComparator(ComparatorInterface $comparator, array $list);
+
+
+    /**
+     * Sort the list of objects by their natural order.
+     *
+     * @param Comparable[] $list
+     *
+     * @return array the sorted list
+     */
+    public function sortComparable(array $list);
+}

tests/Unit/SortManagerTest.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Sorting\Test\Unit;
+
+use Prophecy\Argument;
+use Prophecy\Prophecy\ObjectProphecy;
+use Sorting\Comparable;
+use Sorting\ComparatorInterface;
+use Sorting\SortManager;
+use Sorting\SortManagerInterface;
+
+/**
+ * Class SortManagerTest
+ *
+ * @package Sorting
+ */
+class SortManagerTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var SortManagerInterface
+     */
+    private $sortManager;
+
+    /**
+     *
+     */
+    protected function setUp()
+    {
+        parent::setUp();
+        $this->sortManager = new SortManager();
+    }
+
+    /**
+     * @test
+     */
+    public function itShouldReturnAnEmptyListIfAnEmptyListAndAComparatorIsGiven()
+    {
+        $comparator = $this->getComparator();
+
+        $actual = $this->sortManager->sortWithComparator($comparator->reveal(), []);
+
+        $this->assertSame([], $actual);
+    }
+
+    /**
+     * @test
+     */
+    public function itShouldCallTheCompareMethodOnTheComparatorWithTwoValues()
+    {
+        $comparator = $this->getComparator();
+        $comparator->compare(Argument::any(), Argument::any())->willReturn(-1)->shouldBeCalled();
+
+        $this->sortManager->sortWithComparator($comparator->reveal(), [1, 2]);
+    }
+
+    /**
+     * @test
+     */
+    public function itShouldReturnAnEmptyListIfAnEmptyListOfComparablesIsGiven()
+    {
+        $actual = $this->sortManager->sortComparable([]);
+
+        $this->assertSame([], $actual);
+    }
+
+    /**
+     * @test
+     */
+    public function itShouldCallCompareToOnOneComparable()
+    {
+        $comparable1 = $this->getComparable();
+        $comparable2 = $this->getComparable();
+        $comparable1->compareTo($comparable2->reveal())->willReturn(1)->shouldBeCalled();
+
+        $this->sortManager->sortComparable([$comparable1->reveal(), $comparable2->reveal()]);
+    }
+
+    /**
+     * @return ObjectProphecy
+     */
+    private function getComparator()
+    {
+        return $this->prophesize(ComparatorInterface::class);
+    }
+
+    /**
+     * @return ObjectProphecy
+     */
+    private function getComparable()
+    {
+        return $this->prophesize(Comparable::class);
+    }
+}