start a restructure

Behavioral/Iterator/File.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace DesignPatterns\Iterator;
+
+/**
+ * class File
+ *
+ * THIS EXAMPLE ALSO APPLIES THE COMPOSITE PATTERN
+ */
+class File
+{
+    /**
+     * @var RowSet
+     */
+    protected $rowSet;
+
+    /**
+     * @var string
+     */
+    protected $pathName;
+
+    /**
+     * @param string $pathName
+     */
+    public function __construct($pathName)
+    {
+        $this->rowSet = new Rowset($this);
+    }
+
+    /**
+     * processes the rowSet
+     */
+    public function process()
+    {
+        // this is the place to show how using an iterator, with foreach
+        // See the CardGame.php file
+        $this->rowSet->process();
+    }
+}

Behavioral/Iterator/README.md

@@ -0,0 +1,13 @@
+# Iterator
+
+## Purpose
+
+To make an object iterable and to make it appear like a collection of objects.
+
+## Examples
+
+* to process a file line by line by just running over all lines (which have an object representation) for a file (which of course is an object, too)
+
+## Note
+
+Standard PHP Library (SPL) defines an interface Iterator which is best suited for this! Often you would want to implement the Countable interface too, to allow `count($object)` on your iterable object

Behavioral/Iterator/Row.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace DesignPatterns\Iterator;
+
+/**
+ * Class Row
+ */
+class Row
+{
+    protected $data;
+
+    /**
+     * {@inheritdoc}
+     */
+    public function __construct($data)
+    {
+        $this->data = $data;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function process()
+    {
+        // do some fancy things here ...
+    }
+}

Behavioral/Iterator/RowSet.php

@@ -0,0 +1,100 @@
+<?php
+
+namespace DesignPatterns\Iterator;
+
+/**
+ * Class RowSet
+ */
+class RowSet implements \Iterator
+{
+    /**
+     * @var
+     */
+    protected $currentRow;
+
+    /**
+     * @var string
+     */
+    protected $file;
+
+    /**
+     * @var int
+     */
+    protected $lineNumber;
+
+    /**
+     * @param string $file
+     */
+    public function __construct($file)
+    {
+        $this->file = $file;
+    }
+
+    /**
+     * composite pattern: run through all rows and process them
+     *
+     * @return void
+     */
+    public function process()
+    {
+        // this actually calls rewind(), { next(), valid(), key() and current() :}
+        /**
+         * THE key feature of the Iterator Pattern is to provide a *public contract*
+         * to iterate on a collection without knowing how items are handled inside
+         * the collection. It is not just an easy way to use "foreach"
+         *
+         * One cannot see the point of iterator pattern if you iterate on $this.
+         * This example is unclear and mixed with some Composite pattern ideas.
+         */
+        foreach ($this as $line => $row) {
+            $row->process();
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function rewind()
+    {
+        // seek to first line from $this->file
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function next()
+    {
+        // read the next line from $this->file
+        if (!$eof) {
+            $data = ''; // get the line
+            $this->currentRow = new Row($data);
+        } else {
+            $this->currentRow = null;
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function current()
+    {
+        return $this->currentRow;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function valid()
+    {
+        return null !== $this->currentRow;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function key()
+    {
+        // you would want to increment this in next() or whatsoever
+        return $this->lineNumber;
+    }
+}