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          * TODO: get rid of the id field. Every row instance needs to have
  66          * one so this is just causing hassle at various locations by requiring an extra check for field name.
  67          *
  68          * @since 1.20
  69          *
  70          * @return array
  71          */
  72         public function getFields();
  73
  74         /**
  75          * Returns a list of default field values.
  76          * field name => field value
  77          *
  78          * @since 1.20
  79          *
  80          * @return array
  81          */
  82         public function getDefaults();
  83
  84         /**
  85          * Returns a list of the summary fields.
  86          * These are fields that cache computed values, such as the amount of linked objects of $type.
  87          * This is relevant as one might not want to do actions such as log changes when these get updated.
  88          *
  89          * @since 1.20
  90          *
  91          * @return array
  92          */
  93         public function getSummaryFields();
  94
  95         /**
  96          * Selects the the specified fields of the records matching the provided
  97          * conditions and returns them as DBDataObject. Field names get prefixed.
  98          *
  99          * @since 1.20
 100          *
 101          * @param array|string|null $fields
 102          * @param array $conditions
 103          * @param array $options
 104          * @param string|null $functionName
 105          *
 106          * @return ORMResult
 107          */
 108         public function select( $fields = null, array $conditions = array(),
 109                                                         array $options = array(), $functionName = null );
 110
 111         /**
 112          * Selects the the specified fields of the records matching the provided
 113          * conditions and returns them as DBDataObject. Field names get prefixed.
 114          *
 115          * @since 1.20
 116          *
 117          * @param array|string|null $fields
 118          * @param array $conditions
 119          * @param array $options
 120          * @param string|null $functionName
 121          *
 122          * @return array of self
 123          */
 124         public function selectObjects( $fields = null, array $conditions = array(),
 125                                                                    array $options = array(), $functionName = null );
 126
 127         /**
 128          * Do the actual select.
 129          *
 130          * @since 1.20
 131          *
 132          * @param null|string|array $fields
 133          * @param array $conditions
 134          * @param array $options
 135          * @param null|string $functionName
 136          *
 137          * @return ResultWrapper
 138          */
 139         public function rawSelect( $fields = null, array $conditions = array(),
 140                                                            array $options = array(), $functionName = null );
 141
 142         /**
 143          * Selects the the specified fields of the records matching the provided
 144          * conditions and returns them as associative arrays.
 145          * Provided field names get prefixed.
 146          * Returned field names will not have a prefix.
 147          *
 148          * When $collapse is true:
 149          * If one field is selected, each item in the result array will be this field.
 150          * If two fields are selected, each item in the result array will have as key
 151          * the first field and as value the second field.
 152          * If more then two fields are selected, each item will be an associative array.
 153          *
 154          * @since 1.20
 155          *
 156          * @param array|string|null $fields
 157          * @param array $conditions
 158          * @param array $options
 159          * @param boolean $collapse Set to false to always return each result row as associative array.
 160          * @param string|null $functionName
 161          *
 162          * @return array of array
 163          */
 164         public function selectFields( $fields = null, array $conditions = array(),
 165                                                                   array $options = array(), $collapse = true, $functionName = null );
 166
 167         /**
 168          * Selects the the specified fields of the first matching record.
 169          * Field names get prefixed.
 170          *
 171          * @since 1.20
 172          *
 173          * @param array|string|null $fields
 174          * @param array $conditions
 175          * @param array $options
 176          * @param string|null $functionName
 177          *
 178          * @return IORMRow|bool False on failure
 179          */
 180         public function selectRow( $fields = null, array $conditions = array(),
 181                                                            array $options = array(), $functionName = null );
 182
 183         /**
 184          * Selects the the specified fields of the records matching the provided
 185          * conditions. Field names do NOT get prefixed.
 186          *
 187          * @since 1.20
 188          *
 189          * @param array $fields
 190          * @param array $conditions
 191          * @param array $options
 192          * @param string|null $functionName
 193          *
 194          * @return ResultWrapper
 195          */
 196         public function rawSelectRow( array $fields, array $conditions = array(),
 197                                                                   array $options = array(), $functionName = null );
 198
 199         /**
 200          * Selects the the specified fields of the first record matching the provided
 201          * conditions and returns it as an associative array, or false when nothing matches.
 202          * This method makes use of selectFields and expects the same parameters and
 203          * returns the same results (if there are any, if there are none, this method returns false).
 204          * @see IORMTable::selectFields
 205          *
 206          * @since 1.20
 207          *
 208          * @param array|string|null $fields
 209          * @param array $conditions
 210          * @param array $options
 211          * @param boolean $collapse Set to false to always return each result row as associative array.
 212          * @param string|null $functionName
 213          *
 214          * @return mixed|array|bool False on failure
 215          */
 216         public function selectFieldsRow( $fields = null, array $conditions = array(),
 217                                                                          array $options = array(), $collapse = true, $functionName = null );
 218
 219         /**
 220          * Returns if there is at least one record matching the provided conditions.
 221          * Condition field names get prefixed.
 222          *
 223          * @since 1.20
 224          *
 225          * @param array $conditions
 226          *
 227          * @return boolean
 228          */
 229         public function has( array $conditions = array() );
 230
 231         /**
 232          * Returns the amount of matching records.
 233          * Condition field names get prefixed.
 234          *
 235          * Note that this can be expensive on large tables.
 236          * In such cases you might want to use DatabaseBase::estimateRowCount instead.
 237          *
 238          * @since 1.20
 239          *
 240          * @param array $conditions
 241          * @param array $options
 242          *
 243          * @return integer
 244          */
 245         public function count( array $conditions = array(), array $options = array() );
 246
 247         /**
 248          * Removes the object from the database.
 249          *
 250          * @since 1.20
 251          *
 252          * @param array $conditions
 253          * @param string|null $functionName
 254          *
 255          * @return boolean Success indicator
 256          */
 257         public function delete( array $conditions, $functionName = null );
 258
 259         /**
 260          * Get API parameters for the fields supported by this object.
 261          *
 262          * @since 1.20
 263          *
 264          * @param boolean $requireParams
 265          * @param boolean $setDefaults
 266          *
 267          * @return array
 268          */
 269         public function getAPIParams( $requireParams = false, $setDefaults = false );
 270
 271         /**
 272          * Returns an array with the fields and their descriptions.
 273          *
 274          * field name => field description
 275          *
 276          * @since 1.20
 277          *
 278          * @return array
 279          */
 280         public function getFieldDescriptions();
 281
 282         /**
 283          * Get the database type used for read operations.
 284          *
 285          * @since 1.20
 286          *
 287          * @return integer DB_ enum
 288          */
 289         public function getReadDb();
 290
 291         /**
 292          * Set the database type to use for read operations.
 293          *
 294          * @param integer $db
 295          *
 296          * @since 1.20
 297          */
 298         public function setReadDb( $db );
 299
 300         /**
 301          * Update the records matching the provided conditions by
 302          * setting the fields that are keys in the $values param to
 303          * their corresponding values.
 304          *
 305          * @since 1.20
 306          *
 307          * @param array $values
 308          * @param array $conditions
 309          *
 310          * @return boolean Success indicator
 311          */
 312         public function update( array $values, array $conditions = array() );
 313
 314         /**
 315          * Computes the values of the summary fields of the objects matching the provided conditions.
 316          *
 317          * @since 1.20
 318          *
 319          * @param array|string|null $summaryFields
 320          * @param array $conditions
 321          */
 322         public function updateSummaryFields( $summaryFields = null, array $conditions = array() );
 323
 324         /**
 325          * Takes in an associative array with field names as keys and
 326          * their values as value. The field names are prefixed with the
 327          * db field prefix.
 328          *
 329          * @since 1.20
 330          *
 331          * @param array $values
 332          *
 333          * @return array
 334          */
 335         public function getPrefixedValues( array $values );
 336
 337         /**
 338          * Takes in a field or array of fields and returns an
 339          * array with their prefixed versions, ready for db usage.
 340          *
 341          * @since 1.20
 342          *
 343          * @param array|string $fields
 344          *
 345          * @return array
 346          */
 347         public function getPrefixedFields( array $fields );
 348
 349         /**
 350          * Takes in a field and returns an it's prefixed version, ready for db usage.
 351          *
 352          * @since 1.20
 353          *
 354          * @param string|array $field
 355          *
 356          * @return string
 357          */
 358         public function getPrefixedField( $field );
 359
 360         /**
 361          * Takes an array of field names with prefix and returns the unprefixed equivalent.
 362          *
 363          * @since 1.20
 364          *
 365          * @param array $fieldNames
 366          *
 367          * @return array
 368          */
 369         public function unprefixFieldNames( array $fieldNames );
 370
 371         /**
 372          * Takes a field name with prefix and returns the unprefixed equivalent.
 373          *
 374          * @since 1.20
 375          *
 376          * @param string $fieldName
 377          *
 378          * @return string
 379          */
 380         public function unprefixFieldName( $fieldName );
 381
 382         /**
 383          * Get an instance of this class.
 384          *
 385          * @since 1.20
 386          *
 387          * @return IORMTable
 388          */
 389         public static function singleton();
 390
 391         /**
 392          * Get an array with fields from a database result,
 393          * that can be fed directly to the constructor or
 394          * to setFields.
 395          *
 396          * @since 1.20
 397          *
 398          * @param stdClass $result
 399          *
 400          * @return array
 401          */
 402         public function getFieldsFromDBResult( stdClass $result );
 403
 404         /**
 405          * Get a new instance of the class from a database result.
 406          *
 407          * @since 1.20
 408          *
 409          * @param stdClass $result
 410          *
 411          * @return IORMRow
 412          */
 413         public function newRowFromDBResult( stdClass $result );
 414
 415         /**
 416          * Get a new instance of the class from an array.
 417          *
 418          * @since 1.20
 419          *
 420          * @param array $data
 421          * @param boolean $loadDefaults
 422          *
 423          * @return IORMRow
 424          */
 425         public function newRow( array $data, $loadDefaults = false );
 426
 427         /**
 428          * Return the names of the fields.
 429          *
 430          * @since 1.20
 431          *
 432          * @return array
 433          */
 434         public function getFieldNames();
 435
 436         /**
 437          * Gets if the object can take a certain field.
 438          *
 439          * @since 1.20
 440          *
 441          * @param string $name
 442          *
 443          * @return boolean
 444          */
 445         public function canHaveField( $name );
 446
 447 }