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

   1 <?php
   2
   3 namespace Wikimedia\Rdbms;
   4
   5 use stdClass;
   6 use RuntimeException;
   7
   8 /**
   9  * Result wrapper for grabbing data queried from an IDatabase object
  10  *
  11  * Note that using the Iterator methods in combination with the non-Iterator
  12  * DB result iteration functions may cause rows to be skipped or repeated.
  13  *
  14  * By default, this will use the iteration methods of the IDatabase handle if provided.
  15  * Subclasses can override methods to make it solely work on the result resource instead.
  16  * If no database is provided, and the subclass does not override the DB iteration methods,
  17  * then a RuntimeException will be thrown when iteration is attempted.
  18  *
  19  * The result resource field should not be accessed from non-Database related classes.
  20  * It is database class specific and is stored here to associate iterators with queries.
  21  *
  22  * @ingroup Database
  23  */
  24 class ResultWrapper implements IResultWrapper {
  25         /** @var resource|array|null Optional underlying result handle for subclass usage */
  26         public $result;
  27
  28         /** @var IDatabase|null */
  29         protected $db;
  30
  31         /** @var int */
  32         protected $pos = 0;
  33         /** @var stdClass|null */
  34         protected $currentRow = null;
  35
  36         /**
  37          * Create a row iterator from a result resource and an optional Database object
  38          *
  39          * Only Database-related classes should construct ResultWrapper. Other code may
  40          * use the FakeResultWrapper subclass for convenience or compatibility shims, however.
  41          *
  42          * @param IDatabase|null $db Optional database handle
  43          * @param ResultWrapper|array|resource $result Optional underlying result handle
  44          */
  45         public function __construct( IDatabase $db = null, $result ) {
  46                 $this->db = $db;
  47                 if ( $result instanceof ResultWrapper ) {
  48                         $this->result = $result->result;
  49                 } else {
  50                         $this->result = $result;
  51                 }
  52         }
  53
  54         public function numRows() {
  55                 return $this->getDB()->numRows( $this );
  56         }
  57
  58         public function fetchObject() {
  59                 return $this->getDB()->fetchObject( $this );
  60         }
  61
  62         public function fetchRow() {
  63                 return $this->getDB()->fetchRow( $this );
  64         }
  65
  66         public function seek( $row ) {
  67                 $this->getDB()->dataSeek( $this, $row );
  68         }
  69
  70         public function free() {
  71                 if ( $this->db ) {
  72                         $this->db = null;
  73                 }
  74                 $this->result = null;
  75         }
  76
  77         /**
  78          * @return IDatabase
  79          * @throws RuntimeException
  80          */
  81         private function getDB() {
  82                 if ( !$this->db ) {
  83                         throw new RuntimeException( static::class . ' needs a DB handle for iteration.' );
  84                 }
  85
  86                 return $this->db;
  87         }
  88
  89         function rewind() {
  90                 if ( $this->numRows() ) {
  91                         $this->getDB()->dataSeek( $this, 0 );
  92                 }
  93                 $this->pos = 0;
  94                 $this->currentRow = null;
  95         }
  96
  97         function current() {
  98                 if ( is_null( $this->currentRow ) ) {
  99                         $this->next();
 100                 }
 101
 102                 return $this->currentRow;
 103         }
 104
 105         function key() {
 106                 return $this->pos;
 107         }
 108
 109         function next() {
 110                 $this->pos++;
 111                 $this->currentRow = $this->fetchObject();
 112
 113                 return $this->currentRow;
 114         }
 115
 116         function valid() {
 117                 return $this->current() !== false;
 118         }
 119 }
 120
 121 /**
 122  * @deprecated since 1.29
 123  */
 124 class_alias( ResultWrapper::class, 'ResultWrapper' );