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          * @since 1.20
 101          *
 102          * @param array|string|null $fields
 103          * @param array $conditions
 104          * @param array $options
 105          * @param string|null $functionName
 106          *
 107          * @return ORMResult
 108          */
 109         public function select( $fields = null, array $conditions = array(),
 110                                                         array $options = array(), $functionName = null );
 111
 112         /**
 113          * Selects the the specified fields of the records matching the provided
 114          * conditions and returns them as DBDataObject. Field names get prefixed.
 115          *
 116          * @since 1.20
 117          *
 118          * @param array|string|null $fields
 119          * @param array $conditions
 120          * @param array $options
 121          * @param string|null $functionName
 122          *
 123          * @return array of self
 124          */
 125         public function selectObjects( $fields = null, array $conditions = array(),
 126                                                                    array $options = array(), $functionName = null );
 127
 128         /**
 129          * Do the actual select.
 130          *
 131          * @since 1.20
 132          *
 133          * @param null|string|array $fields
 134          * @param array $conditions
 135          * @param array $options
 136          * @param null|string $functionName
 137          *
 138          * @return ResultWrapper
 139          */
 140         public function rawSelect( $fields = null, array $conditions = array(),
 141                                                            array $options = array(), $functionName = null );
 142
 143         /**
 144          * Selects the the specified fields of the records matching the provided
 145          * conditions and returns them as associative arrays.
 146          * Provided field names get prefixed.
 147          * Returned field names will not have a prefix.
 148          *
 149          * When $collapse is true:
 150          * If one field is selected, each item in the result array will be this field.
 151          * If two fields are selected, each item in the result array will have as key
 152          * the first field and as value the second field.
 153          * If more then two fields are selected, each item will be an associative array.
 154          *
 155          * @since 1.20
 156          *
 157          * @param array|string|null $fields
 158          * @param array $conditions
 159          * @param array $options
 160          * @param boolean $collapse Set to false to always return each result row as associative array.
 161          * @param string|null $functionName
 162          *
 163          * @return array of array
 164          */
 165         public function selectFields( $fields = null, array $conditions = array(),
 166                                                                   array $options = array(), $collapse = true, $functionName = null );
 167
 168         /**
 169          * Selects the the specified fields of the first matching record.
 170          * Field names get prefixed.
 171          *
 172          * @since 1.20
 173          *
 174          * @param array|string|null $fields
 175          * @param array $conditions
 176          * @param array $options
 177          * @param string|null $functionName
 178          *
 179          * @return IORMRow|bool False on failure
 180          */
 181         public function selectRow( $fields = null, array $conditions = array(),
 182                                                            array $options = array(), $functionName = null );
 183
 184         /**
 185          * Selects the the specified fields of the records matching the provided
 186          * conditions. Field names do NOT get prefixed.
 187          *
 188          * @since 1.20
 189          *
 190          * @param array $fields
 191          * @param array $conditions
 192          * @param array $options
 193          * @param string|null $functionName
 194          *
 195          * @return ResultWrapper
 196          */
 197         public function rawSelectRow( array $fields, array $conditions = array(),
 198                                                                   array $options = array(), $functionName = null );
 199
 200         /**
 201          * Selects the the specified fields of the first record matching the provided
 202          * conditions and returns it as an associative array, or false when nothing matches.
 203          * This method makes use of selectFields and expects the same parameters and
 204          * returns the same results (if there are any, if there are none, this method returns false).
 205          * @see IORMTable::selectFields
 206          *
 207          * @since 1.20
 208          *
 209          * @param array|string|null $fields
 210          * @param array $conditions
 211          * @param array $options
 212          * @param boolean $collapse Set to false to always return each result row as associative array.
 213          * @param string|null $functionName
 214          *
 215          * @return mixed|array|bool False on failure
 216          */
 217         public function selectFieldsRow( $fields = null, array $conditions = array(),
 218                                                                          array $options = array(), $collapse = true, $functionName = null );
 219
 220         /**
 221          * Returns if there is at least one record matching the provided conditions.
 222          * Condition field names get prefixed.
 223          *
 224          * @since 1.20
 225          *
 226          * @param array $conditions
 227          *
 228          * @return boolean
 229          */
 230         public function has( array $conditions = array() );
 231
 232         /**
 233          * Checks if the table exists
 234          *
 235          * @since 1.21
 236          *
 237          * @return boolean
 238          */
 239         public function exists();
 240
 241         /**
 242          * Returns the amount of matching records.
 243          * Condition field names get prefixed.
 244          *
 245          * Note that this can be expensive on large tables.
 246          * In such cases you might want to use DatabaseBase::estimateRowCount instead.
 247          *
 248          * @since 1.20
 249          *
 250          * @param array $conditions
 251          * @param array $options
 252          *
 253          * @return integer
 254          */
 255         public function count( array $conditions = array(), array $options = array() );
 256
 257         /**
 258          * Removes the object from the database.
 259          *
 260          * @since 1.20
 261          *
 262          * @param array $conditions
 263          * @param string|null $functionName
 264          *
 265          * @return boolean Success indicator
 266          */
 267         public function delete( array $conditions, $functionName = null );
 268
 269         /**
 270          * Get API parameters for the fields supported by this object.
 271          *
 272          * @since 1.20
 273          *
 274          * @param boolean $requireParams
 275          * @param boolean $setDefaults
 276          *
 277          * @return array
 278          */
 279         public function getAPIParams( $requireParams = false, $setDefaults = false );
 280
 281         /**
 282          * Returns an array with the fields and their descriptions.
 283          *
 284          * field name => field description
 285          *
 286          * @since 1.20
 287          *
 288          * @return array
 289          */
 290         public function getFieldDescriptions();
 291
 292         /**
 293          * Get the database type used for read operations.
 294          *
 295          * @since 1.20
 296          *
 297          * @return integer DB_ enum
 298          */
 299         public function getReadDb();
 300
 301         /**
 302          * Set the database type to use for read operations.
 303          *
 304          * @param integer $db
 305          *
 306          * @since 1.20
 307          */
 308         public function setReadDb( $db );
 309
 310
 311         /**
 312          * Get the ID of the any foreign wiki to use as a target for database operations
 313          *
 314          * @since 1.20
 315          *
 316          * @return String|bool The target wiki, in a form that  LBFactory understands (or false if the local wiki is used)
 317          */
 318         public function getTargetWiki();
 319
 320         /**
 321          * Set the ID of the any foreign wiki to use as a target for database operations
 322          *
 323          * @param String|bool $wiki The target wiki, in a form that  LBFactory understands (or false if the local wiki shall be used)
 324          *
 325          * @since 1.20
 326          */
 327         public function setTargetWiki( $wiki );
 328
 329         /**
 330          * Get the database type used for read operations.
 331          * This is to be used instead of wfGetDB.
 332          *
 333          * @see LoadBalancer::getConnection
 334          *
 335          * @since 1.20
 336          *
 337          * @return DatabaseBase The database object
 338          */
 339         public function getReadDbConnection();
 340
 341         /**
 342          * Get the database type used for read operations.
 343          * This is to be used instead of wfGetDB.
 344          *
 345          * @see LoadBalancer::getConnection
 346          *
 347          * @since 1.20
 348          *
 349          * @return DatabaseBase The database object
 350          */
 351         public function getWriteDbConnection();
 352
 353         /**
 354          * Get the database type used for read operations.
 355          *
 356          * @see wfGetLB
 357          *
 358          * @since 1.20
 359          *
 360          * @return LoadBalancer The database load balancer object
 361          */
 362         public function getLoadBalancer();
 363
 364         /**
 365          * Releases the lease on the given database connection. This is useful mainly
 366          * for connections to a foreign wiki. It does nothing for connections to the local wiki.
 367          *
 368          * @see LoadBalancer::reuseConnection
 369          *
 370          * @param DatabaseBase $db the database
 371          *
 372          * @since 1.20
 373          */
 374         public function releaseConnection( DatabaseBase $db );
 375
 376         /**
 377          * Update the records matching the provided conditions by
 378          * setting the fields that are keys in the $values param to
 379          * their corresponding values.
 380          *
 381          * @since 1.20
 382          *
 383          * @param array $values
 384          * @param array $conditions
 385          *
 386          * @return boolean Success indicator
 387          */
 388         public function update( array $values, array $conditions = array() );
 389
 390         /**
 391          * Computes the values of the summary fields of the objects matching the provided conditions.
 392          *
 393          * @since 1.20
 394          *
 395          * @param array|string|null $summaryFields
 396          * @param array $conditions
 397          */
 398         public function updateSummaryFields( $summaryFields = null, array $conditions = array() );
 399
 400         /**
 401          * Takes in an associative array with field names as keys and
 402          * their values as value. The field names are prefixed with the
 403          * db field prefix.
 404          *
 405          * @since 1.20
 406          *
 407          * @param array $values
 408          *
 409          * @return array
 410          */
 411         public function getPrefixedValues( array $values );
 412
 413         /**
 414          * Takes in a field or array of fields and returns an
 415          * array with their prefixed versions, ready for db usage.
 416          *
 417          * @since 1.20
 418          *
 419          * @param array|string $fields
 420          *
 421          * @return array
 422          */
 423         public function getPrefixedFields( array $fields );
 424
 425         /**
 426          * Takes in a field and returns an it's prefixed version, ready for db usage.
 427          *
 428          * @since 1.20
 429          *
 430          * @param string|array $field
 431          *
 432          * @return string
 433          */
 434         public function getPrefixedField( $field );
 435
 436         /**
 437          * Takes an array of field names with prefix and returns the unprefixed equivalent.
 438          *
 439          * @since 1.20
 440          *
 441          * @param array $fieldNames
 442          *
 443          * @return array
 444          */
 445         public function unprefixFieldNames( array $fieldNames );
 446
 447         /**
 448          * Takes a field name with prefix and returns the unprefixed equivalent.
 449          *
 450          * @since 1.20
 451          *
 452          * @param string $fieldName
 453          *
 454          * @return string
 455          */
 456         public function unprefixFieldName( $fieldName );
 457
 458         /**
 459          * Get an instance of this class.
 460          *
 461          * @since 1.20
 462          *
 463          * @return IORMTable
 464          */
 465         public static function singleton();
 466
 467         /**
 468          * Get an array with fields from a database result,
 469          * that can be fed directly to the constructor or
 470          * to setFields.
 471          *
 472          * @since 1.20
 473          *
 474          * @param stdClass $result
 475          *
 476          * @return array
 477          */
 478         public function getFieldsFromDBResult( stdClass $result );
 479
 480         /**
 481          * Get a new instance of the class from a database result.
 482          *
 483          * @since 1.20
 484          *
 485          * @param stdClass $result
 486          *
 487          * @return IORMRow
 488          */
 489         public function newRowFromDBResult( stdClass $result );
 490
 491         /**
 492          * Get a new instance of the class from an array.
 493          *
 494          * @since 1.20
 495          *
 496          * @param array $data
 497          * @param boolean $loadDefaults
 498          *
 499          * @return IORMRow
 500          */
 501         public function newRow( array $data, $loadDefaults = false );
 502
 503         /**
 504          * Return the names of the fields.
 505          *
 506          * @since 1.20
 507          *
 508          * @return array
 509          */
 510         public function getFieldNames();
 511
 512         /**
 513          * Gets if the object can take a certain field.
 514          *
 515          * @since 1.20
 516          *
 517          * @param string $name
 518          *
 519          * @return boolean
 520          */
 521         public function canHaveField( $name );
 522
 523 }