T13886 collection (#13891)

* [4.0.x] - Added unicode flag for email filter

* [4.0.x] - Updating the ext folder

* [4.0.x] - Added Arr helper class

* Revert "[4.0.x] - Added Arr helper class"

This reverts commit f8153d3.

* Revert "[4.0.x] - Updating the ext folder"

This reverts commit 655eafe.

* [#13886] - Initial implementation and test stubs

* [#13886] - Fixing interface

* [#13886] - Added constructor

* [#13886] - Implementation of the collection

* [#13886] - Collection tests

* [#13886] - Updated the CHANGELOG

CHANGELOG-4.0.md

@@ -22,6 +22,8 @@ The implementation offers PSR-7/PSR-17 compatible components in a different name
     - `Phalcon\Helper\Arr`
     - `Phalcon\Helper\Number`
 [#13889](https://github.com/phalcon/cphalcon/pull/13889)
+- Added `Phalcon\Collection`, an object implementing `ArrayAccess`, `Countable`, `IteratorAggregate`, `JsonSerializable`, `Serializable`, offering an easy way to handle collections of data such as arrays, superglobals etc. [#13886](https://github.com/phalcon/cphalcon/issues/13886)
+
 
 # [4.0.0-alpha.3](https://github.com/phalcon/cphalcon/releases/tag/v4.0.0-alpha.3) (2019-02-31)
 ## Added

phalcon/collection.zep

@@ -0,0 +1,259 @@
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon;
+
+/**
+ * Phalcon\Collection
+ *
+ * Phalcon\Collection is a supercharged object oriented array. It implements
+ * ArrayAccess, Countable, IteratorAggregate, JsonSerializable, Serializable
+ *
+ * It can be used in any part of the application that needs collection of data
+ * Such implementatins are for instance accessing globals `$_GET`, `$_POST` etc.
+ */
+class Collection implements \ArrayAccess, \Countable, \IteratorAggregate, \JsonSerializable, \Serializable
+{
+	/**
+	 * @var array
+	 */
+	private data = [];
+
+	public function __construct(array! data = null) -> void
+	{
+		if typeof data === "array" {
+			this->init(data);
+		}
+	}
+
+	/**
+	 * Magic getter to get an element from the collection
+	 */
+	public function __get(string! element) -> var
+	{
+		return this->get(element);
+	}
+
+	/**
+	 * Magic isset to check whether an element exists or not
+	 */
+	public function __isset(string! element) -> bool
+	{
+		return this->has(element);
+	}
+
+	/**
+	 * Magic setter to assign values to an element
+	 */
+	public function __set(string! element, var value) -> void
+	{
+		this->set(element, value);
+	}
+
+	/**
+	 * Magic unset to remove an element from the collection
+	 */
+	public function __unset(string! element) -> void
+	{
+		this->remove(element);
+	}
+
+	/**
+	 * Clears the internal collection
+	 */
+	public function clear() -> void
+	{
+		let this->data = [];
+	}
+
+	/**
+	 * Count elements of an object
+	 *
+	 * @link https://php.net/manual/en/countable.count.php
+	 */
+	public function count() -> int
+	{
+		return count(this->data);
+	}
+
+	/**
+	 * Get the element from the collection
+	 */
+	public function get(string! element, var defaultValue = null) -> var | bool
+	{
+		var value;
+
+		if likely fetch value, this->data[element] {
+			return value;
+		}
+
+		return defaultValue;
+	}
+
+	/**
+	 * Returns the iterator of the class
+	 */
+	public function getIterator() -> <Traversable>
+	{
+		return new \ArrayIterator(this);
+	}
+
+	/**
+	 * Get the element from the collection
+	 */
+	public function has(string! element) -> bool
+	{
+		return isset this->data[element];
+	}
+
+	/**
+	 * Delete the element from the collection
+	 */
+	public function remove(string! element) -> void
+	{
+		array data;
+
+		let data = this->data;
+
+		unset data[element];
+
+		this->init(data);
+	}
+
+	/**
+	 * Set an element in the collection
+	 */
+	public function set(string! element, var value) -> void
+	{
+		array data;
+
+		let data          = this->data,
+			data[element] = value;
+
+		this->init(data);
+	}
+
+	/**
+	 * Initialize internal array
+	 */
+	public function init(array! data = [])
+	{
+		let this->data = data;
+	}
+
+	/**
+	 * Specify data which should be serialized to JSON
+	 *
+	 * @link https://php.net/manual/en/jsonserializable.jsonserialize.php
+	 */
+	public function jsonSerialize () -> array
+	{
+		return this->data;
+	}
+
+	/**
+	 * Whether a offset exists
+	 *
+	 * @link https://php.net/manual/en/arrayaccess.offsetexists.php
+	 */
+	public function offsetExists(var element) -> bool
+	{
+		let element = (string) element;
+
+		return this->has(element);
+	}
+
+	/**
+	 * Offset to retrieve
+	 *
+	 * @link https://php.net/manual/en/arrayaccess.offsetget.php
+	 */
+	public function offsetGet(var element) -> var
+	{
+		let element = (string) element;
+
+		return this->get(element);
+	}
+
+	/**
+	 * Offset to set
+	 *
+	 * @link https://php.net/manual/en/arrayaccess.offsetset.php
+	 */
+	public function offsetSet(var element, var value) -> void
+	{
+		let element = (string) element;
+
+		this->set(element, value);
+	}
+
+	/**
+	 * Offset to unset
+	 *
+	 * @link https://php.net/manual/en/arrayaccess.offsetunset.php
+	 */
+	public function offsetUnset(var element) -> void
+	{
+		let element = (string) element;
+
+		this->remove(element);
+	}
+
+    /**
+     * String representation of object
+     *
+     * @link https://php.net/manual/en/serializable.serialize.php
+     */
+    public function serialize() -> string
+    {
+		array data;
+
+		let data = this->data;
+
+		return serialize(data);
+    }
+
+	/**
+	 * Returns the object in an array format
+	 */
+	public function toArray() -> array
+	{
+		return this->data;
+	}
+
+	/**
+	 * Returns the object in a JSON format
+	 *
+	 * The default string uses the following options for json_encode
+	 *
+	 * JSON_HEX_TAG, JSON_HEX_APOS, JSON_HEX_AMP, JSON_HEX_QUOT, JSON_UNESCAPED_SLASHES
+	 *
+	 * @see https://www.ietf.org/rfc/rfc4627.txt
+	 */
+	public function toJson(int options = 74) -> string
+	{
+		return json_encode(this->data, options);
+	}
+
+    /**
+     * Constructs the object
+     *
+     * @link https://php.net/manual/en/serializable.unserialize.php
+     */
+    public function unserialize(var serialized) -> void
+    {
+		var data;
+
+		let serialized = (string) serialized,
+			data       = unserialize(serialized);
+
+		this->init(data);
+    }
+}

tests/unit/Collection/ClearCest.php

@@ -0,0 +1,50 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Test\Unit\Collection;
+
+use Phalcon\Collection;
+use UnitTester;
+
+/**
+ * Class ClearCest
+ */
+class ClearCest
+{
+    /**
+     * Tests Phalcon\Collection :: clear()
+     *
+     * @param UnitTester $I
+     *
+     * @author Phalcon Team <[email protected]>
+     * @since  2018-11-13
+     */
+    public function collectionClear(UnitTester $I)
+    {
+        $I->wantToTest('Collection - clear()');
+        $data       = [
+            'one'   => 'two',
+            'three' => 'four',
+            'five'  => 'six',
+        ];
+        $collection = new Collection($data);
+
+        $expected = $data;
+        $actual   = $collection->toArray();
+        $I->assertEquals($expected, $actual);
+
+        $collection->clear();
+        $expected = 0;
+        $actual   = $collection->count();
+        $I->assertEquals($expected, $actual);
+    }
+}

tests/unit/Collection/ConstructCest.php

@@ -0,0 +1,39 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * This file is part of the Phalcon Framework.
+ *
+ * (c) Phalcon Team <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+namespace Phalcon\Test\Unit\Collection;
+
+use Phalcon\Collection;
+use UnitTester;
+
+/**
+ * Class ConstructCest
+ */
+class ConstructCest
+{
+    /**
+     * Tests Phalcon\Collection :: __construct()
+     *
+     * @param UnitTester $I
+     *
+     * @author Phalcon Team <[email protected]>
+     * @since  2018-11-13
+     */
+    public function collectionConstruct(UnitTester $I)
+    {
+        $I->wantToTest('Collection - __construct()');
+        $collection = new Collection();
+
+        $class = Collection::class;
+        $I->assertInstanceOf($class, $collection);
+    }
+}