includes/db/IORMRow.php

   1 <?php
   2 /**
   3  * Interface for representing objects that are stored in some DB table.
   4  * This is basically an ORM-like wrapper around rows in database tables that
   5  * aims to be both simple and very flexible. It is centered around an associative
   6  * array of fields and various methods to do common interaction with the database.
   7  *
   8  * Documentation inline and at https://www.mediawiki.org/wiki/Manual:ORMTable
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  *
  25  * @since 1.20
  26  *
  27  * @file
  28  * @ingroup ORM
  29  *
  30  * @license GNU GPL v2 or later
  31  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  32  */
  33
  34 interface IORMRow {
  35
  36         /**
  37          * Load the specified fields from the database.
  38          *
  39          * @since 1.20
  40          * @deprecated since 1.22
  41          *
  42          * @param array|null $fields
  43          * @param boolean $override
  44          * @param boolean $skipLoaded
  45          *
  46          * @return bool Success indicator
  47          */
  48         public function loadFields( $fields = null, $override = true, $skipLoaded = false );
  49
  50         /**
  51          * Gets the value of a field.
  52          *
  53          * @since 1.20
  54          *
  55          * @param string $name
  56          * @param mixed $default
  57          *
  58          * @throws MWException
  59          * @return mixed
  60          */
  61         public function getField( $name, $default = null );
  62
  63         /**
  64          * Gets the value of a field but first loads it if not done so already.
  65          *
  66          * @since 1.20
  67          * @deprecated since 1.22
  68          *
  69          * @param string $name
  70          *
  71          * @return mixed
  72          */
  73         public function loadAndGetField( $name );
  74
  75         /**
  76          * Remove a field.
  77          *
  78          * @since 1.20
  79          *
  80          * @param string $name
  81          */
  82         public function removeField( $name );
  83
  84         /**
  85          * Returns the objects database id.
  86          *
  87          * @since 1.20
  88          *
  89          * @return integer|null
  90          */
  91         public function getId();
  92
  93         /**
  94          * Sets the objects database id.
  95          *
  96          * @since 1.20
  97          *
  98          * @param integer|null $id
  99          */
 100         public function setId( $id );
 101
 102         /**
 103          * Gets if a certain field is set.
 104          *
 105          * @since 1.20
 106          *
 107          * @param string $name
 108          *
 109          * @return boolean
 110          */
 111         public function hasField( $name );
 112
 113         /**
 114          * Gets if the id field is set.
 115          *
 116          * @since 1.20
 117          *
 118          * @return boolean
 119          */
 120         public function hasIdField();
 121
 122         /**
 123          * Sets multiple fields.
 124          *
 125          * @since 1.20
 126          *
 127          * @param array $fields The fields to set
 128          * @param boolean $override Override already set fields with the provided values?
 129          */
 130         public function setFields( array $fields, $override = true );
 131
 132         /**
 133          * Serializes the object to an associative array which
 134          * can then easily be converted into JSON or similar.
 135          *
 136          * @since 1.20
 137          *
 138          * @param null|array $fields
 139          * @param boolean $incNullId
 140          *
 141          * @return array
 142          */
 143         public function toArray( $fields = null, $incNullId = false );
 144
 145         /**
 146          * Load the default values, via getDefaults.
 147          *
 148          * @since 1.20
 149          * @deprecated since 1.22
 150          *
 151          * @param boolean $override
 152          */
 153         public function loadDefaults( $override = true );
 154
 155         /**
 156          * Writes the answer to the database, either updating it
 157          * when it already exists, or inserting it when it doesn't.
 158          *
 159          * @since 1.20
 160          *
 161          * @param string|null $functionName
 162          * @deprecated since 1.22
 163          *
 164          * @return boolean Success indicator
 165          */
 166         public function save( $functionName = null );
 167
 168         /**
 169          * Removes the object from the database.
 170          *
 171          * @since 1.20
 172          * @deprecated since 1.22
 173          *
 174          * @return boolean Success indicator
 175          */
 176         public function remove();
 177
 178         /**
 179          * Return the names and values of the fields.
 180          *
 181          * @since 1.20
 182          *
 183          * @return array
 184          */
 185         public function getFields();
 186
 187         /**
 188          * Return the names of the fields.
 189          *
 190          * @since 1.20
 191          *
 192          * @return array
 193          */
 194         public function getSetFieldNames();
 195
 196         /**
 197          * Sets the value of a field.
 198          * Strings can be provided for other types,
 199          * so this method can be called from unserialization handlers.
 200          *
 201          * @since 1.20
 202          *
 203          * @param string $name
 204          * @param mixed $value
 205          *
 206          * @throws MWException
 207          */
 208         public function setField( $name, $value );
 209
 210         /**
 211          * Add an amount (can be negative) to the specified field (needs to be numeric).
 212          *
 213          * @since 1.20
 214          * @deprecated since 1.22
 215          *
 216          * @param string $field
 217          * @param integer $amount
 218          *
 219          * @return boolean Success indicator
 220          */
 221         public function addToField( $field, $amount );
 222
 223         /**
 224          * Return the names of the fields.
 225          *
 226          * @since 1.20
 227          *
 228          * @return array
 229          */
 230         public function getFieldNames();
 231
 232         /**
 233          * Computes and updates the values of the summary fields.
 234          *
 235          * @since 1.20
 236          * @deprecated since 1.22
 237          *
 238          * @param array|string|null $summaryFields
 239          */
 240         public function loadSummaryFields( $summaryFields = null );
 241
 242         /**
 243          * Sets the value for the @see $updateSummaries field.
 244          *
 245          * @since 1.20
 246          * @deprecated since 1.22
 247          *
 248          * @param boolean $update
 249          */
 250         public function setUpdateSummaries( $update );
 251
 252         /**
 253          * Sets the value for the @see $inSummaryMode field.
 254          *
 255          * @since 1.20
 256          * @deprecated since 1.22
 257          *
 258          * @param boolean $summaryMode
 259          */
 260         public function setSummaryMode( $summaryMode );
 261
 262         /**
 263          * Returns the table this IORMRow is a row in.
 264          *
 265          * @since 1.20
 266          * @deprecated since 1.22
 267          *
 268          * @return IORMTable
 269          */
 270         public function getTable();
 271
 272 }