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          * 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 one so
  66          *   this is just causing hassle at various locations by requiring an extra
  67          *   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 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          * @throws 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 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 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          * @throws 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 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 bool $collapse Set to false to always return each result row as associative array.
 165          * @param string|null $functionName
 166          *
 167          * @return array 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 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 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 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 bool $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 bool
 233          */
 234         public function has( array $conditions = array() );
 235
 236         /**
 237          * Checks if the table exists
 238          *
 239          * @since 1.21
 240          *
 241          * @return bool
 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 int
 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 bool 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 bool $requireParams
 279          * @param bool $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 int DB_ enum
 302          */
 303         public function getReadDb();
 304
 305         /**
 306          * Set the database type to use for read operations.
 307          *
 308          * @param int $db
 309          *
 310          * @since 1.20
 311          */
 312         public function setReadDb( $db );
 313
 314         /**
 315          * Get the ID of the any foreign wiki to use as a target for database operations
 316          *
 317          * @since 1.20
 318          *
 319          * @return string|bool The target wiki, in a form that LBFactory
 320          *   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
 328          *   understands (or false if the local wiki shall be used)
 329          *
 330          * @since 1.20
 331          */
 332         public function setTargetWiki( $wiki );
 333
 334         /**
 335          * Get the database type used for read operations.
 336          * This is to be used instead of wfGetDB.
 337          *
 338          * @see LoadBalancer::getConnection
 339          *
 340          * @since 1.20
 341          *
 342          * @return DatabaseBase The database object
 343          */
 344         public function getReadDbConnection();
 345
 346         /**
 347          * Get the database type used for read operations.
 348          * This is to be used instead of wfGetDB.
 349          *
 350          * @see LoadBalancer::getConnection
 351          *
 352          * @since 1.20
 353          *
 354          * @return DatabaseBase The database object
 355          */
 356         public function getWriteDbConnection();
 357
 358         /**
 359          * Get the database type used for read operations.
 360          *
 361          * @see wfGetLB
 362          *
 363          * @since 1.20
 364          *
 365          * @return LoadBalancer The database load balancer object
 366          */
 367         public function getLoadBalancer();
 368
 369         /**
 370          * Releases the lease on the given database connection. This is useful mainly
 371          * for connections to a foreign wiki. It does nothing for connections to the local wiki.
 372          *
 373          * @see LoadBalancer::reuseConnection
 374          *
 375          * @param DatabaseBase $db The database
 376          *
 377          * @since 1.20
 378          */
 379         public function releaseConnection( DatabaseBase $db );
 380
 381         /**
 382          * Update the records matching the provided conditions by
 383          * setting the fields that are keys in the $values param to
 384          * their corresponding values.
 385          *
 386          * @since 1.20
 387          *
 388          * @param array $values
 389          * @param array $conditions
 390          *
 391          * @return bool Success indicator
 392          */
 393         public function update( array $values, array $conditions = array() );
 394
 395         /**
 396          * Computes the values of the summary fields of the objects matching the provided conditions.
 397          *
 398          * @since 1.20
 399          *
 400          * @param array|string|null $summaryFields
 401          * @param array $conditions
 402          */
 403         public function updateSummaryFields( $summaryFields = null, array $conditions = array() );
 404
 405         /**
 406          * Takes in an associative array with field names as keys and
 407          * their values as value. The field names are prefixed with the
 408          * db field prefix.
 409          *
 410          * @since 1.20
 411          *
 412          * @param array $values
 413          *
 414          * @return array
 415          */
 416         public function getPrefixedValues( array $values );
 417
 418         /**
 419          * Takes in a field or array of fields and returns an
 420          * array with their prefixed versions, ready for db usage.
 421          *
 422          * @since 1.20
 423          *
 424          * @param array $fields
 425          *
 426          * @return array
 427          */
 428         public function getPrefixedFields( array $fields );
 429
 430         /**
 431          * Takes in a field and returns an it's prefixed version, ready for db usage.
 432          *
 433          * @since 1.20
 434          *
 435          * @param string|array $field
 436          *
 437          * @return string
 438          */
 439         public function getPrefixedField( $field );
 440
 441         /**
 442          * Takes an array of field names with prefix and returns the unprefixed equivalent.
 443          *
 444          * @since 1.20
 445          * @deprecated since 1.25, will be removed
 446          *
 447          * @param string[] $fieldNames
 448          *
 449          * @return string[]
 450          */
 451         public function unprefixFieldNames( array $fieldNames );
 452
 453         /**
 454          * Takes a field name with prefix and returns the unprefixed equivalent.
 455          *
 456          * @since 1.20
 457          * @deprecated since 1.25, will be removed
 458          *
 459          * @param string $fieldName
 460          *
 461          * @return string
 462          */
 463         public function unprefixFieldName( $fieldName );
 464
 465         /**
 466          * Get an array with fields from a database result,
 467          * that can be fed directly to the constructor or
 468          * to setFields.
 469          *
 470          * @since 1.20
 471          *
 472          * @param stdClass $result
 473          *
 474          * @return array
 475          */
 476         public function getFieldsFromDBResult( stdClass $result );
 477
 478         /**
 479          * Get a new instance of the class from a database result.
 480          *
 481          * @since 1.20
 482          *
 483          * @param stdClass $result
 484          *
 485          * @return IORMRow
 486          */
 487         public function newRowFromDBResult( stdClass $result );
 488
 489         /**
 490          * Get a new instance of the class from an array.
 491          *
 492          * @since 1.20
 493          *
 494          * @param array $data
 495          * @param bool $loadDefaults
 496          *
 497          * @return IORMRow
 498          */
 499         public function newRow( array $data, $loadDefaults = false );
 500
 501         /**
 502          * Return the names of the fields.
 503          *
 504          * @since 1.20
 505          *
 506          * @return array
 507          */
 508         public function getFieldNames();
 509
 510         /**
 511          * Gets if the object can take a certain field.
 512          *
 513          * @since 1.20
 514          *
 515          * @param string $name
 516          *
 517          * @return bool
 518          */
 519         public function canHaveField( $name );
 520 }