includes/db/IORMTable.php

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