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          * Load the specified fields from the database.
  37          *
  38          * @since 1.20
  39          * @deprecated since 1.22
  40          *
  41          * @param array|null $fields
  42          * @param bool $override
  43          * @param bool $skipLoaded
  44          *
  45          * @return bool Success indicator
  46          */
  47         public function loadFields( $fields = null, $override = true, $skipLoaded = false );
  48
  49         /**
  50          * Gets the value of a field.
  51          *
  52          * @since 1.20
  53          *
  54          * @param string $name
  55          * @param mixed $default
  56          *
  57          * @throws MWException
  58          * @return mixed
  59          */
  60         public function getField( $name, $default = null );
  61
  62         /**
  63          * Gets the value of a field but first loads it if not done so already.
  64          *
  65          * @since 1.20
  66          * @deprecated since 1.22
  67          *
  68          * @param string $name
  69          *
  70          * @return mixed
  71          */
  72         public function loadAndGetField( $name );
  73
  74         /**
  75          * Remove a field.
  76          *
  77          * @since 1.20
  78          *
  79          * @param string $name
  80          */
  81         public function removeField( $name );
  82
  83         /**
  84          * Returns the objects database id.
  85          *
  86          * @since 1.20
  87          *
  88          * @return int|null
  89          */
  90         public function getId();
  91
  92         /**
  93          * Sets the objects database id.
  94          *
  95          * @since 1.20
  96          *
  97          * @param int|null $id
  98          */
  99         public function setId( $id );
 100
 101         /**
 102          * Gets if a certain field is set.
 103          *
 104          * @since 1.20
 105          *
 106          * @param string $name
 107          *
 108          * @return bool
 109          */
 110         public function hasField( $name );
 111
 112         /**
 113          * Gets if the id field is set.
 114          *
 115          * @since 1.20
 116          *
 117          * @return bool
 118          */
 119         public function hasIdField();
 120
 121         /**
 122          * Sets multiple fields.
 123          *
 124          * @since 1.20
 125          *
 126          * @param array $fields The fields to set
 127          * @param bool $override Override already set fields with the provided values?
 128          */
 129         public function setFields( array $fields, $override = true );
 130
 131         /**
 132          * Serializes the object to an associative array which
 133          * can then easily be converted into JSON or similar.
 134          *
 135          * @since 1.20
 136          *
 137          * @param null|array $fields
 138          * @param bool $incNullId
 139          *
 140          * @return array
 141          */
 142         public function toArray( $fields = null, $incNullId = false );
 143
 144         /**
 145          * Load the default values, via getDefaults.
 146          *
 147          * @since 1.20
 148          * @deprecated since 1.22
 149          *
 150          * @param bool $override
 151          */
 152         public function loadDefaults( $override = true );
 153
 154         /**
 155          * Writes the answer to the database, either updating it
 156          * when it already exists, or inserting it when it doesn't.
 157          *
 158          * @since 1.20
 159          *
 160          * @param string|null $functionName
 161          * @deprecated since 1.22
 162          *
 163          * @return bool Success indicator
 164          */
 165         public function save( $functionName = null );
 166
 167         /**
 168          * Removes the object from the database.
 169          *
 170          * @since 1.20
 171          * @deprecated since 1.22
 172          *
 173          * @return bool Success indicator
 174          */
 175         public function remove();
 176
 177         /**
 178          * Return the names and values of the fields.
 179          *
 180          * @since 1.20
 181          *
 182          * @return array
 183          */
 184         public function getFields();
 185
 186         /**
 187          * Return the names of the fields.
 188          *
 189          * @since 1.20
 190          *
 191          * @return array
 192          */
 193         public function getSetFieldNames();
 194
 195         /**
 196          * Sets the value of a field.
 197          * Strings can be provided for other types,
 198          * so this method can be called from unserialization handlers.
 199          *
 200          * @since 1.20
 201          *
 202          * @param string $name
 203          * @param mixed $value
 204          *
 205          * @throws MWException
 206          */
 207         public function setField( $name, $value );
 208
 209         /**
 210          * Add an amount (can be negative) to the specified field (needs to be numeric).
 211          *
 212          * @since 1.20
 213          * @deprecated since 1.22
 214          *
 215          * @param string $field
 216          * @param int $amount
 217          *
 218          * @return bool Success indicator
 219          */
 220         public function addToField( $field, $amount );
 221
 222         /**
 223          * Return the names of the fields.
 224          *
 225          * @since 1.20
 226          *
 227          * @return array
 228          */
 229         public function getFieldNames();
 230
 231         /**
 232          * Computes and updates the values of the summary fields.
 233          *
 234          * @since 1.20
 235          * @deprecated since 1.22
 236          *
 237          * @param array|string|null $summaryFields
 238          */
 239         public function loadSummaryFields( $summaryFields = null );
 240
 241         /**
 242          * Sets the value for the @see $updateSummaries field.
 243          *
 244          * @since 1.20
 245          * @deprecated since 1.22
 246          *
 247          * @param bool $update
 248          */
 249         public function setUpdateSummaries( $update );
 250
 251         /**
 252          * Sets the value for the @see $inSummaryMode field.
 253          *
 254          * @since 1.20
 255          * @deprecated since 1.22
 256          *
 257          * @param bool $summaryMode
 258          */
 259         public function setSummaryMode( $summaryMode );
 260
 261         /**
 262          * Returns the table this IORMRow is a row in.
 263          *
 264          * @since 1.20
 265          * @deprecated since 1.22
 266          *
 267          * @return IORMTable
 268          */
 269         public function getTable();
 270 }