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