External iterator API.

DalStatement.php

@@ -46,6 +46,142 @@
  */
 class DalStatement
 {
+    /**
+     * Start at the first offset.
+     *
+     * @var int
+     */
+    const FROM_START                  = 0;
+
+    /**
+     * Start at the last offset.
+     *
+     * @var int
+     */
+    const FROM_END                    = -1;
+
+    /**
+     * Fetch the next row in the result set.
+     *
+     * @var int
+     */
+    const FORWARD                     = 0;
+
+    /**
+     * Fetch the previous row in the result set.
+     *
+     * @var int
+     */
+    const BACKWARD                    = 1;
+
+    /**
+     * Specifies that the fetch method shall return each row as an object with
+     * variable names that correspond to the column names returned in the result
+     * set. `AS_LAZY_OBJECT` creates the object variable names as they are
+     * accessed.
+     *
+     * @var int
+     */
+    const AS_LAZY_OBJECT              = 1;
+
+    /**
+     * Specifies that the fetch method shall return each row as an array indexed
+     * by column name as returned in the corresponding result set. If the result
+     * set contains multiple columns with the same name, `AS_MAP` returns only a
+     * single value per column name.
+     *
+     * @var int
+     */
+    const AS_MAP                      = 2;
+
+    /**
+     * Specifies that the fetch method shall return each row as an array indexed
+     * by column number as returned in the corresponding result set, starting at
+     * column 0.
+     *
+     * @var int
+     */
+    const AS_SET                      = 3;
+
+    /**
+     * Specifies that the fetch method shall return each row as an object with
+     * property names that correspond to the column names returned in the result
+     * set.
+     *
+     * @var int
+     */
+    const AS_OBJECT                   = 5;
+
+    /**
+     * Specifies that the fetch method shall return a new instance of the
+     * requested class, mapping the columns to named properties in the class.
+     * The magic `__set` method is called if the property doesn't exist in the
+     * requested class.
+     *
+     * @var int
+     */
+    const AS_CLASS                    = 8;
+
+    /**
+     * Specifies that the fetch method shall update an existing instance of the
+     * requested class, mapping the columns to named properties in the class.
+     *
+     * @var int
+     */
+    const AS_REUSABLE_OBJECT          = 9;
+
+    /**
+     * Specifies that the fetch method shall return each row as an array indexed
+     * by column name as returned in the corresponding result set. If the result
+     * set contains multiple columns with the same name, `AS_DEBUG_MAP` returns
+     * an array of values per column name.
+     *
+     * @var int
+     */
+    const AS_DEBUG_MAP                = 11;
+
+    /**
+     * The start cursor offset.
+     *
+     * @var int
+     */
+    const STYLE_OFFSET                = 0;
+
+    /**
+     * The cursor orientation.
+     *
+     * @var int
+     */
+    const STYLE_ORIENTATION           = 1;
+
+    /**
+     * The fetching style.
+     *
+     * @var int
+     */
+    const STYLE_MODE                  = 2;
+
+    /**
+     * The class name for `AS_CLASS`.
+     *
+     * @var int
+     */
+    const STYLE_CLASS_NAME            = 3;
+
+    /**
+     * The constructor arguments for `AS_CLASS`.
+     *
+     * @var int
+     */
+    const STYLE_CONSTRUCTOR_ARGUMENTS = 4;
+
+    /**
+     * The reused object for `AS_REUSABLE_OBJECT`.
+     *
+     * @var int
+     */
+    const STYLE_OBJECT                = 5;
+
     /**
      * The statement instance.
      *
@@ -161,47 +297,68 @@ public function fetchAll()
     }
 
     /**
-     * Fetch the first row in the result set.
+     * Set the iterator fetching style.
      *
-     * @return  mixed
-     * @throws  \Hoa\Database\Exception
+     * @param   int    $offset         This value must be one of the
+     *                                 DalStatement::FROM_* constants or an
+     *                                 arbitrary offset.
+     * @param   int    $orientation    This value must be DalStatement::FORWARD
+     *                                 or DalStatement::BACKWARD constant.
+     * @param   int    $style          This value must be one of the
+     *                                 DalStatement::AS_* constants.
+     * @param   mixed  $arg1           For AS_CLASS: The class name.
+     *                                 For AS_REUSABLE_OBJECT: An object.
+     * @param   array  $arg2           For AS_CLASS: Constructor arguments.
+     * @return  \Hoa\Database\DalStatement
      */
-    public function fetchFirst()
-    {
-        return $this->getStatement()->fetchFirst();
+    public function setFetchingStyle(
+        $offset      = self::FROM_START,
+        $orientation = self::FORWARD,
+        $style       = self::AS_MAP,
+        $arg1        = null,
+        $arg2        = null
+    ) {
+        $this->getStatement()->setFetchingStyle(
+            $offset,
+            $orientation,
+            $style,
+            $arg1,
+            $arg2
+        );
+
+        return $this;
     }
 
     /**
-     * Fetch the last row in the result set.
+     * Get an Iterator.
      *
-     * @return  mixed
-     * @throws  \Hoa\Database\Exception
+     * @return  \Hoa\Database\IDal\WrapperIterator
      */
-    public function fetchLast()
+    public function getIterator()
     {
-        return $this->getStatement()->fetchLast();
+        return $this->getStatement()->getIterator();
     }
 
     /**
-     * Fetch the next row in the result set.
+     * Fetch the first row in the result set.
      *
+     * @param   int  $style    Must be one of the DalStatement::AS_* constants.
      * @return  mixed
-     * @throws  \Hoa\Database\Exception
      */
-    public function fetchNext()
+    public function fetchFirst($style = null)
     {
-        return $this->getStatement()->fetchNext();
+        return $this->getStatement()->fetchFirst($style);
     }
 
     /**
-     * Fetch the previous row in the result set.
+     * Fetch the last row in the result set.
      *
+     * @param   int  $style    Must be one of the DalStatement::AS_* constants.
      * @return  mixed
-     * @throws  \Hoa\Database\Exception
      */
-    public function fetchPrior()
+    public function fetchLast($style = null)
     {
-        return $this->getStatement()->fetchPrior();
+        return $this->getStatement()->fetchLast($style);
     }
 
     /**

IDal/WrapperIterator.php

@@ -0,0 +1,59 @@
+<?php
+
+/**
+ * Hoa
+ *
+ *
+ * @license
+ *
+ * New BSD License
+ *
+ * Copyright © 2007-2016, Hoa community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *     * Neither the name of the Hoa nor the names of its contributors may be
+ *       used to endorse or promote products derived from this software without
+ *       specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+namespace Hoa\Database\IDal;
+
+use Hoa\Iterator;
+
+/**
+ * Interface \Hoa\Database\IDal\WrapperIterator.
+ *
+ * Interface of a DAL iterator statement wrapper.
+ *
+ * @copyright  Copyright © 2007-2016 Hoa community
+ * @license    New BSD License
+ */
+interface WrapperIterator extends Iterator\Iterator
+{
+    /**
+     * Create an iterator instance.
+     *
+     * @param   object  $statement    The underlying statement instance.
+     * @param   array   $style        An array of fetching style options.
+     * @return  void
+     */
+    public function __construct($statement, $style);
+}

IDal/WrapperStatement.php

@@ -36,6 +36,9 @@
 
 namespace Hoa\Database\IDal;
 
+use Hoa\Database;
+use Hoa\Iterator;
+
 /**
  * Interface \Hoa\Database\IDal\WrapperStatement.
  *
@@ -44,7 +47,7 @@
  * @copyright  Copyright © 2007-2016 Hoa community
  * @license    New BSD License
  */
-interface WrapperStatement
+interface WrapperStatement extends Iterator\Aggregate
 {
     /**
      * Execute a prepared statement.
@@ -82,36 +85,43 @@ public function bindParameter(
     public function fetchAll();
 
     /**
-     * Fetch the first row in the result set.
-     *
-     * @return  mixed
-     * @throws  \Hoa\Database\Exception
-     */
-    public function fetchFirst();
-
-    /**
-     * Fetch the last row in the result set.
+     * Set the Iterator fetching style.
      *
-     * @return  mixed
-     * @throws  \Hoa\Database\Exception
+     * @param   int    $offset         This value must be one of the
+     *                                 DalStatement::FROM_* constants or an
+     *                                 arbitrary offset.
+     * @param   int    $orientation    This value must be DalStatement::FORWARD
+     *                                 or DalStatement::BACKWARD constant.
+     * @param   int    $style          This value must be one of the
+     *                                 DalStatement::AS_* constants.
+     * @param   mixed  $arg1           For AS_CLASS: The Class name.
+     *                                 For AS_REUSABLE_OBJECT: An object.
+     * @param   array  $arg2           For AS_CLASS: Constructor arguments.
+     * @return  \Hoa\Database\IDal\WrapperStatement
      */
-    public function fetchLast();
+    public function setFetchingStyle(
+        $offset      = Database\DalStatement::FROM_START,
+        $orientation = Database\DalStatement::FORWARD,
+        $style       = Database\DalStatement::AS_MAP,
+        $arg1        = null,
+        $arg2        = null
+    );
 
     /**
-     * Fetch the next row in the result set.
+     * Fetch the first row in the result set.
      *
+     * @param   int  $style    Must be one of the DalStatement::AS_* constants.
      * @return  mixed
-     * @throws  \Hoa\Database\Exception
      */
-    public function fetchNext();
+    public function fetchFirst($style = null);
 
     /**
-     * Fetch the previous row in the result set.
+     * Fetch the last row in the result set.
      *
+     * @param   int  $style    Must be one of the DalStatement::AS_* constants.
      * @return  mixed
-     * @throws  \Hoa\Database\Exception
      */
-    public function fetchPrior();
+    public function fetchLast($style = null);
 
     /**
      * Return a single column from the next row of the result set or false if