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