includes/libs/rdbms/database/resultwrapper/IResultWrapper.php

   1 <?php
   2
   3 namespace Wikimedia\Rdbms;
   4
   5 use Countable;
   6 use OutOfBoundsException;
   7 use SeekableIterator;
   8 use stdClass;
   9
  10 /**
  11  * Result wrapper for grabbing data queried from an IDatabase object
  12  *
  13  * Note that using the Iterator methods in combination with the non-Iterator
  14  * DB result iteration functions may cause rows to be skipped or repeated.
  15  *
  16  * By default, this will use the iteration methods of the IDatabase handle if provided.
  17  * Subclasses can override methods to make it solely work on the result resource instead.
  18  * If no database is provided, and the subclass does not override the DB iteration methods,
  19  * then a RuntimeException will be thrown when iteration is attempted.
  20  *
  21  * The result resource field should not be accessed from non-Database related classes.
  22  * It is database class specific and is stored here to associate iterators with queries.
  23  *
  24  * @ingroup Database
  25  */
  26 interface IResultWrapper extends Countable, SeekableIterator {
  27         /**
  28          * Get the number of rows in a result object
  29          *
  30          * @return int
  31          */
  32         public function numRows();
  33
  34         /**
  35          * Get the number of rows in a result object
  36          *
  37          * @return int
  38          */
  39         public function count(): int;
  40
  41         /**
  42          * Fetch the next row from the given result object, in object form. Fields can be retrieved with
  43          * $row->fieldname, with fields acting like member variables. If no more rows are available,
  44          * false is returned.
  45          *
  46          * @return stdClass|false
  47          * @throws DBUnexpectedError Thrown if the database returns an error
  48          */
  49         public function fetchObject();
  50
  51         /**
  52          * Fetch the next row from the given result object, in associative array form. Fields are
  53          * retrieved with $row['fieldname']. If no more rows are available, false is returned.
  54          *
  55          * @return array|false
  56          * @throws DBUnexpectedError Thrown if the database returns an error
  57          */
  58         public function fetchRow();
  59
  60         /**
  61          * Change the position of the cursor in a result object.
  62          * See mysql_data_seek()
  63          *
  64          * @throws OutOfBoundsException
  65          * @param int $pos
  66          */
  67         public function seek( $pos ): void;
  68
  69         /**
  70          * Free a result object
  71          *
  72          * This either saves memory in PHP (buffered queries) or on the server (unbuffered queries).
  73          * In general, queries are not large enough in result sets for this to be worth calling.
  74          */
  75         public function free();
  76
  77         /**
  78          * @return stdClass|array|false
  79          */
  80         #[\ReturnTypeWillChange]
  81         public function current();
  82
  83         /**
  84          * @return int
  85          */
  86         public function key(): int;
  87
  88         /**
  89          * @return void
  90          */
  91         public function next(): void;
  92
  93         /**
  94          * Get the names of the fields in the result
  95          *
  96          * @since 1.37
  97          * @return string[]
  98          */
  99         public function getFieldNames();
 100 }