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