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