[Summary view] [Print] [Text view]

   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 < [email protected] >
  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 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 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 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 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 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       *
 446       * @param array $fieldNames
 447       *
 448       * @return array
 449       */
 450  	public function unprefixFieldNames( array $fieldNames );
 451  
 452      /**
 453       * Takes a field name with prefix and returns the unprefixed equivalent.
 454       *
 455       * @since 1.20
 456       *
 457       * @param string $fieldName
 458       *
 459       * @return string
 460       */
 461  	public function unprefixFieldName( $fieldName );
 462  
 463      /**
 464       * Get an array with fields from a database result,
 465       * that can be fed directly to the constructor or
 466       * to setFields.
 467       *
 468       * @since 1.20
 469       *
 470       * @param stdClass $result
 471       *
 472       * @return array
 473       */
 474  	public function getFieldsFromDBResult( stdClass $result );
 475  
 476      /**
 477       * Get a new instance of the class from a database result.
 478       *
 479       * @since 1.20
 480       *
 481       * @param stdClass $result
 482       *
 483       * @return IORMRow
 484       */
 485  	public function newRowFromDBResult( stdClass $result );
 486  
 487      /**
 488       * Get a new instance of the class from an array.
 489       *
 490       * @since 1.20
 491       *
 492       * @param array $data
 493       * @param bool $loadDefaults
 494       *
 495       * @return IORMRow
 496       */
 497  	public function newRow( array $data, $loadDefaults = false );
 498  
 499      /**
 500       * Return the names of the fields.
 501       *
 502       * @since 1.20
 503       *
 504       * @return array
 505       */
 506  	public function getFieldNames();
 507  
 508      /**
 509       * Gets if the object can take a certain field.
 510       *
 511       * @since 1.20
 512       *
 513       * @param string $name
 514       *
 515       * @return bool
 516       */
 517  	public function canHaveField( $name );
 518  }