From 3bb4e07a0824968d221f2c19afa6c2a92e4ec09c Mon Sep 17 00:00:00 2001
From: Aaron Schulz <aschulz@wikimedia.org>
Date: Tue, 7 Feb 2017 23:53:03 -0800
Subject: [PATCH] Create IResultWrapper interface for type-hints

Change-Id: Ie46ede59c09eb7b0b9ff06c6988e39fe2a953e46
---
 autoload.php                                  |  1 +
 .../database/resultwrapper/IResultWrapper.php | 82 +++++++++++++++++++
 .../database/resultwrapper/ResultWrapper.php  | 46 +----------
 3 files changed, 87 insertions(+), 42 deletions(-)
 create mode 100644 includes/libs/rdbms/database/resultwrapper/IResultWrapper.php

diff --git a/autoload.php b/autoload.php
index 1cb8a148ba..a6aebedae4 100644
--- a/autoload.php
+++ b/autoload.php
@@ -1588,6 +1588,7 @@ $wgAutoloadLocalClasses = [
 	'Wikimedia\\Rdbms\\ILBFactory' => __DIR__ . '/includes/libs/rdbms/lbfactory/ILBFactory.php',
 	'Wikimedia\\Rdbms\\ILoadBalancer' => __DIR__ . '/includes/libs/rdbms/loadbalancer/ILoadBalancer.php',
 	'Wikimedia\\Rdbms\\ILoadMonitor' => __DIR__ . '/includes/libs/rdbms/loadmonitor/ILoadMonitor.php',
+	'Wikimedia\\Rdbms\\IResultWrapper' => __DIR__ . '/includes/libs/rdbms/database/resultwrapper/IResultWrapper.php',
 	'Wikimedia\\Rdbms\\LBFactory' => __DIR__ . '/includes/libs/rdbms/lbfactory/LBFactory.php',
 	'Wikimedia\\Rdbms\\LBFactoryMulti' => __DIR__ . '/includes/libs/rdbms/lbfactory/LBFactoryMulti.php',
 	'Wikimedia\\Rdbms\\LBFactorySimple' => __DIR__ . '/includes/libs/rdbms/lbfactory/LBFactorySimple.php',
diff --git a/includes/libs/rdbms/database/resultwrapper/IResultWrapper.php b/includes/libs/rdbms/database/resultwrapper/IResultWrapper.php
new file mode 100644
index 0000000000..dc89a2dc04
--- /dev/null
+++ b/includes/libs/rdbms/database/resultwrapper/IResultWrapper.php
@@ -0,0 +1,82 @@
+<?php
+
+namespace Wikimedia\Rdbms;
+
+use Iterator;
+use DBUnexpectedError;
+use stdClass;
+
+/**
+ * Result wrapper for grabbing data queried from an IDatabase object
+ *
+ * Note that using the Iterator methods in combination with the non-Iterator
+ * DB result iteration functions may cause rows to be skipped or repeated.
+ *
+ * By default, this will use the iteration methods of the IDatabase handle if provided.
+ * Subclasses can override methods to make it solely work on the result resource instead.
+ * If no database is provided, and the subclass does not override the DB iteration methods,
+ * then a RuntimeException will be thrown when iteration is attempted.
+ *
+ * The result resource field should not be accessed from non-Database related classes.
+ * It is database class specific and is stored here to associate iterators with queries.
+ *
+ * @ingroup Database
+ */
+interface IResultWrapper extends Iterator {
+	/**
+	 * Get the number of rows in a result object
+	 *
+	 * @return int
+	 */
+	public function numRows();
+
+	/**
+	 * Fetch the next row from the given result object, in object form. Fields can be retrieved with
+	 * $row->fieldname, with fields acting like member variables. If no more rows are available,
+	 * false is returned.
+	 *
+	 * @return stdClass|bool
+	 * @throws DBUnexpectedError Thrown if the database returns an error
+	 */
+	public function fetchObject();
+
+	/**
+	 * Fetch the next row from the given result object, in associative array form. Fields are
+	 * retrieved with $row['fieldname']. If no more rows are available, false is returned.
+	 *
+	 * @return array|bool
+	 * @throws DBUnexpectedError Thrown if the database returns an error
+	 */
+	public function fetchRow();
+
+	/**
+	 * Change the position of the cursor in a result object.
+	 * See mysql_data_seek()
+	 *
+	 * @param int $row
+	 */
+	public function seek( $row );
+
+	/**
+	 * Free a result object
+	 *
+	 * This either saves memory in PHP (buffered queries) or on the server (unbuffered queries).
+	 * In general, queries are not large enough in result sets for this to be worth calling.
+	 */
+	public function free();
+
+	/**
+	 * @return stdClass|array|bool
+	 */
+	public function current();
+
+	/**
+	 * @return int
+	 */
+	public function key();
+
+	/**
+	 * @return stdClass
+	 */
+	function next();
+}
diff --git a/includes/libs/rdbms/database/resultwrapper/ResultWrapper.php b/includes/libs/rdbms/database/resultwrapper/ResultWrapper.php
index 53109c82da..88e7cdd05c 100644
--- a/includes/libs/rdbms/database/resultwrapper/ResultWrapper.php
+++ b/includes/libs/rdbms/database/resultwrapper/ResultWrapper.php
@@ -1,4 +1,7 @@
 <?php
+
+use Wikimedia\Rdbms\IResultWrapper;
+
 /**
  * Result wrapper for grabbing data queried from an IDatabase object
  *
@@ -15,7 +18,7 @@
  *
  * @ingroup Database
  */
-class ResultWrapper implements Iterator {
+class ResultWrapper implements IResultWrapper {
 	/** @var resource|array|null Optional underlying result handle for subclass usage */
 	public $result;
 
@@ -45,54 +48,22 @@ class ResultWrapper implements Iterator {
 		}
 	}
 
-	/**
-	 * Get the number of rows in a result object
-	 *
-	 * @return int
-	 */
 	public function numRows() {
 		return $this->getDB()->numRows( $this );
 	}
 
-	/**
-	 * Fetch the next row from the given result object, in object form. Fields can be retrieved with
-	 * $row->fieldname, with fields acting like member variables. If no more rows are available,
-	 * false is returned.
-	 *
-	 * @return stdClass|bool
-	 * @throws DBUnexpectedError Thrown if the database returns an error
-	 */
 	public function fetchObject() {
 		return $this->getDB()->fetchObject( $this );
 	}
 
-	/**
-	 * Fetch the next row from the given result object, in associative array form. Fields are
-	 * retrieved with $row['fieldname']. If no more rows are available, false is returned.
-	 *
-	 * @return array|bool
-	 * @throws DBUnexpectedError Thrown if the database returns an error
-	 */
 	public function fetchRow() {
 		return $this->getDB()->fetchRow( $this );
 	}
 
-	/**
-	 * Change the position of the cursor in a result object.
-	 * See mysql_data_seek()
-	 *
-	 * @param int $row
-	 */
 	public function seek( $row ) {
 		$this->getDB()->dataSeek( $this, $row );
 	}
 
-	/**
-	 * Free a result object
-	 *
-	 * This either saves memory in PHP (buffered queries) or on the server (unbuffered queries).
-	 * In general, queries are not large enough in result sets for this to be worth calling.
-	 */
 	public function free() {
 		if ( $this->db ) {
 			$this->db->freeResult( $this );
@@ -121,9 +92,6 @@ class ResultWrapper implements Iterator {
 		$this->currentRow = null;
 	}
 
-	/**
-	 * @return stdClass|array|bool
-	 */
 	function current() {
 		if ( is_null( $this->currentRow ) ) {
 			$this->next();
@@ -132,16 +100,10 @@ class ResultWrapper implements Iterator {
 		return $this->currentRow;
 	}
 
-	/**
-	 * @return int
-	 */
 	function key() {
 		return $this->pos;
 	}
 
-	/**
-	 * @return stdClass
-	 */
 	function next() {
 		$this->pos++;
 		$this->currentRow = $this->fetchObject();
-- 
2.20.1