includes/db/IORMTable.php

   1 <?php
   2 /**
   3  * Interface for objects representing a single database table.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @since 1.20
  21  *
  22  * @file
  23  * @ingroup ORM
  24  *
  25  * @licence GNU GPL v2 or later
  26  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  27  */
  28
  29 interface IORMTable {
  30
  31         /**
  32          * Returns the name of the database table objects of this type are stored in.
  33          *
  34          * @since 1.20
  35          *
  36          * @return string
  37          */
  38         public function getName();
  39
  40         /**
  41          * Returns the name of a IORMRow implementing class that
  42          * represents single rows in this table.
  43          *
  44          * @since 1.20
  45          *
  46          * @return string
  47          */
  48         public function getRowClass();
  49
  50         /**
  51          * Returns an array with the fields and their types this object contains.
  52          * This corresponds directly to the fields in the database, without prefix.
  53          *
  54          * field name => type
  55          *
  56          * Allowed types:
  57          * * id
  58          * * str
  59          * * int
  60          * * float
  61          * * bool
  62          * * array
  63          * * blob
  64          *
  65          * @since 1.20
  66          *
  67          * @return array
  68          */
  69         public function getFields();
  70
  71         /**
  72          * Returns a list of default field values.
  73          * field name => field value
  74          *
  75          * @since 1.20
  76          *
  77          * @return array
  78          */
  79         public function getDefaults();
  80
  81         /**
  82          * Returns a list of the summary fields.
  83          * These are fields that cache computed values, such as the amount of linked objects of $type.
  84          * This is relevant as one might not want to do actions such as log changes when these get updated.
  85          *
  86          * @since 1.20
  87          *
  88          * @return array
  89          */
  90         public function getSummaryFields();
  91
  92         /**
  93          * Selects the the specified fields of the records matching the provided
  94          * conditions and returns them as DBDataObject. Field names get prefixed.
  95          *
  96          * @since 1.20
  97          *
  98          * @param array|string|null $fields
  99          * @param array $conditions
 100          * @param array $options
 101          * @param string|null $functionName
 102          *
 103          * @return ORMResult
 104          */
 105         public function select( $fields = null, array $conditions = array(),
 106                                                         array $options = array(), $functionName  = null );
 107
 108         /**
 109          * Selects the the specified fields of the records matching the provided
 110          * conditions and returns them as DBDataObject. Field names get prefixed.
 111          *
 112          * @since 1.20
 113          *
 114          * @param array|string|null $fields
 115          * @param array $conditions
 116          * @param array $options
 117          * @param string|null $functionName
 118          *
 119          * @return array of self
 120          */
 121         public function selectObjects( $fields = null, array $conditions = array(),
 122                                                                    array $options = array(), $functionName  = null );
 123
 124         /**
 125          * Do the actual select.
 126          *
 127          * @since 1.20
 128          *
 129          * @param null|string|array $fields
 130          * @param array $conditions
 131          * @param array $options
 132          * @param null|string $functionName
 133          *
 134          * @return ResultWrapper
 135          */
 136         public function rawSelect( $fields = null, array $conditions = array(),
 137                                                            array $options = array(), $functionName  = null );
 138
 139         /**
 140          * Selects the the specified fields of the records matching the provided
 141          * conditions and returns them as associative arrays.
 142          * Provided field names get prefixed.
 143          * Returned field names will not have a prefix.
 144          *
 145          * When $collapse is true:
 146          * If one field is selected, each item in the result array will be this field.
 147          * If two fields are selected, each item in the result array will have as key
 148          * the first field and as value the second field.
 149          * If more then two fields are selected, each item will be an associative array.
 150          *
 151          * @since 1.20
 152          *
 153          * @param array|string|null $fields
 154          * @param array $conditions
 155          * @param array $options
 156          * @param boolean $collapse Set to false to always return each result row as associative array.
 157          * @param string|null $functionName
 158          *
 159          * @return array of array
 160          */
 161         public function selectFields( $fields = null, array $conditions = array(),
 162                                                                   array $options = array(), $collapse = true, $functionName  = null );
 163
 164         /**
 165          * Selects the the specified fields of the first matching record.
 166          * Field names get prefixed.
 167          *
 168          * @since 1.20
 169          *
 170          * @param array|string|null $fields
 171          * @param array $conditions
 172          * @param array $options
 173          * @param string|null $functionName
 174          *
 175          * @return IORMRow|bool False on failure
 176          */
 177         public function selectRow( $fields = null, array $conditions = array(),
 178                                                            array $options = array(), $functionName = null );
 179
 180         /**
 181          * Selects the the specified fields of the records matching the provided
 182          * conditions. Field names do NOT get prefixed.
 183          *
 184          * @since 1.20
 185          *
 186          * @param array $fields
 187          * @param array $conditions
 188          * @param array $options
 189          * @param string|null $functionName
 190          *
 191          * @return ResultWrapper
 192          */
 193         public function rawSelectRow( array $fields, array $conditions = array(),
 194                                                                   array $options = array(), $functionName = null );
 195
 196         /**
 197          * Selects the the specified fields of the first record matching the provided
 198          * conditions and returns it as an associative array, or false when nothing matches.
 199          * This method makes use of selectFields and expects the same parameters and
 200          * returns the same results (if there are any, if there are none, this method returns false).
 201          * @see IORMTable::selectFields
 202          *
 203          * @since 1.20
 204          *
 205          * @param array|string|null $fields
 206          * @param array $conditions
 207          * @param array $options
 208          * @param boolean $collapse Set to false to always return each result row as associative array.
 209          * @param string|null $functionName
 210          *
 211          * @return mixed|array|bool False on failure
 212          */
 213         public function selectFieldsRow( $fields = null, array $conditions = array(),
 214                                                                          array $options = array(), $collapse = true, $functionName = null );
 215
 216         /**
 217          * Returns if there is at least one record matching the provided conditions.
 218          * Condition field names get prefixed.
 219          *
 220          * @since 1.20
 221          *
 222          * @param array $conditions
 223          *
 224          * @return boolean
 225          */
 226         public function has( array $conditions = array() );
 227
 228         /**
 229          * Returns the amount of matching records.
 230          * Condition field names get prefixed.
 231          *
 232          * Note that this can be expensive on large tables.
 233          * In such cases you might want to use DatabaseBase::estimateRowCount instead.
 234          *
 235          * @since 1.20
 236          *
 237          * @param array $conditions
 238          * @param array $options
 239          *
 240          * @return integer
 241          */
 242         public function count( array $conditions = array(), array $options = array() );
 243
 244         /**
 245          * Removes the object from the database.
 246          *
 247          * @since 1.20
 248          *
 249          * @param array $conditions
 250          * @param string|null $functionName
 251          *
 252          * @return boolean Success indicator
 253          */
 254         public function delete( array $conditions, $functionName = null );
 255
 256         /**
 257          * Get API parameters for the fields supported by this object.
 258          *
 259          * @since 1.20
 260          *
 261          * @param boolean $requireParams
 262          * @param boolean $setDefaults
 263          *
 264          * @return array
 265          */
 266         public function getAPIParams( $requireParams = false, $setDefaults = false );
 267
 268         /**
 269          * Returns an array with the fields and their descriptions.
 270          *
 271          * field name => field description
 272          *
 273          * @since 1.20
 274          *
 275          * @return array
 276          */
 277         public function getFieldDescriptions();
 278
 279         /**
 280          * Get the database type used for read operations.
 281          *
 282          * @since 1.20
 283          *
 284          * @return integer DB_ enum
 285          */
 286         public function getReadDb();
 287
 288         /**
 289          * Set the database type to use for read operations.
 290          *
 291          * @param integer $db
 292          *
 293          * @since 1.20
 294          */
 295         public function setReadDb( $db );
 296
 297         /**
 298          * Update the records matching the provided conditions by
 299          * setting the fields that are keys in the $values param to
 300          * their corresponding values.
 301          *
 302          * @since 1.20
 303          *
 304          * @param array $values
 305          * @param array $conditions
 306          *
 307          * @return boolean Success indicator
 308          */
 309         public function update( array $values, array $conditions = array() );
 310
 311         /**
 312          * Computes the values of the summary fields of the objects matching the provided conditions.
 313          *
 314          * @since 1.20
 315          *
 316          * @param array|string|null $summaryFields
 317          * @param array $conditions
 318          */
 319         public function updateSummaryFields( $summaryFields = null, array $conditions = array() );
 320
 321         /**
 322          * Takes in an associative array with field names as keys and
 323          * their values as value. The field names are prefixed with the
 324          * db field prefix.
 325          *
 326          * @since 1.20
 327          *
 328          * @param array $values
 329          *
 330          * @return array
 331          */
 332         public function getPrefixedValues( array $values );
 333
 334         /**
 335          * Takes in a field or array of fields and returns an
 336          * array with their prefixed versions, ready for db usage.
 337          *
 338          * @since 1.20
 339          *
 340          * @param array|string $fields
 341          *
 342          * @return array
 343          */
 344         public function getPrefixedFields( array $fields );
 345
 346         /**
 347          * Takes in a field and returns an it's prefixed version, ready for db usage.
 348          *
 349          * @since 1.20
 350          *
 351          * @param string|array $field
 352          *
 353          * @return string
 354          */
 355         public function getPrefixedField( $field );
 356
 357         /**
 358          * Takes an array of field names with prefix and returns the unprefixed equivalent.
 359          *
 360          * @since 1.20
 361          *
 362          * @param array $fieldNames
 363          *
 364          * @return array
 365          */
 366         public function unprefixFieldNames( array $fieldNames );
 367
 368         /**
 369          * Takes a field name with prefix and returns the unprefixed equivalent.
 370          *
 371          * @since 1.20
 372          *
 373          * @param string $fieldName
 374          *
 375          * @return string
 376          */
 377         public function unprefixFieldName( $fieldName );
 378
 379         /**
 380          * Get an instance of this class.
 381          *
 382          * @since 1.20
 383          *
 384          * @return IORMTable
 385          */
 386         public static function singleton();
 387
 388         /**
 389          * Get an array with fields from a database result,
 390          * that can be fed directly to the constructor or
 391          * to setFields.
 392          *
 393          * @since 1.20
 394          *
 395          * @param stdClass $result
 396          *
 397          * @return array
 398          */
 399         public function getFieldsFromDBResult( stdClass $result );
 400
 401         /**
 402          * Get a new instance of the class from a database result.
 403          *
 404          * @since 1.20
 405          *
 406          * @param stdClass $result
 407          *
 408          * @return IORMRow
 409          */
 410         public function newFromDBResult( stdClass $result );
 411
 412         /**
 413          * Get a new instance of the class from an array.
 414          *
 415          * @since 1.20
 416          *
 417          * @param array $data
 418          * @param boolean $loadDefaults
 419          *
 420          * @return IORMRow
 421          */
 422         public function newFromArray( array $data, $loadDefaults = false );
 423
 424         /**
 425          * Return the names of the fields.
 426          *
 427          * @since 1.20
 428          *
 429          * @return array
 430          */
 431         public function getFieldNames();
 432
 433         /**
 434          * Gets if the object can take a certain field.
 435          *
 436          * @since 1.20
 437          *
 438          * @param string $name
 439          *
 440          * @return boolean
 441          */
 442         public function canHaveField( $name );
 443
 444 }