includes/DBDataObject.php

   1 <?php
   2
   3 /**
   4  * Abstract base class for representing objects that are stored in some DB table.
   5  * This is basically an ORM-like wrapper around rows in database tables that
   6  * aims to be both simple and very flexible. It is centered around an associative
   7  * array of fields and various methods to do common interaction with the database.
   8  *
   9  * These methods must be implemented in deriving classes:
  10  * * getDBTable
  11  * * getFieldPrefix
  12  * * getFieldTypes
  13  *
  14  * These methods are likely candidates for overriding:
  15  * * getDefaults
  16  * * remove
  17  * * insert
  18  * * saveExisting
  19  * * loadSummaryFields
  20  * * getSummaryFields
  21  *
  22  * Main instance methods:
  23  * * getField(s)
  24  * * setField(s)
  25  * * save
  26  * * remove
  27  *
  28  * Main static methods:
  29  * * select
  30  * * update
  31  * * delete
  32  * * count
  33  * * has
  34  * * selectRow
  35  * * selectFields
  36  * * selectFieldsRow
  37  *
  38  * @since 1.20
  39  *
  40  * @file DBDataObject.php
  41  *
  42  * @licence GNU GPL v2 or later
  43  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  44  */
  45 abstract class DBDataObject {
  46
  47         /**
  48          * The fields of the object.
  49          * field name (w/o prefix) => value
  50          *
  51          * @since 1.20
  52          * @var array
  53          */
  54         protected $fields = array( 'id' => null );
  55
  56         /**
  57          * If the object should update summaries of linked items when changed.
  58          * For example, update the course_count field in universities when a course in courses is deleted.
  59          * Settings this to false can prevent needless updating work in situations
  60          * such as deleting a university, which will then delete all it's courses.
  61          *
  62          * @since 1.20
  63          * @var bool
  64          */
  65         protected $updateSummaries = true;
  66
  67         /**
  68          * Indicates if the object is in summary mode.
  69          * This mode indicates that only summary fields got updated,
  70          * which allows for optimizations.
  71          *
  72          * @since 1.20
  73          * @var bool
  74          */
  75         protected $inSummaryMode = false;
  76
  77
  78         /**
  79          * The database connection to use for read operations.
  80          * Can be changed via @see setReadDb.
  81          *
  82          * @since 1.20
  83          * @var integer DB_ enum
  84          */
  85         protected static $readDb = DB_SLAVE;
  86
  87         /**
  88          * Returns the name of the database table objects of this type are stored in.
  89          *
  90          * @since 1.20
  91          *
  92          * @throws MWException
  93          * @return string
  94          */
  95         public static function getDBTable() {
  96                 throw new MWException( 'Class "' . get_called_class() . '" did not implement getDBTable' );
  97         }
  98
  99         /**
 100          * Gets the db field prefix.
 101          *
 102          * @since 1.20
 103          *
 104          * @throws MWException
 105          * @return string
 106          */
 107         protected static function getFieldPrefix() {
 108                 throw new MWException( 'Class "' . get_called_class() . '" did not implement getFieldPrefix' );
 109         }
 110
 111         /**
 112          * Returns an array with the fields and their types this object contains.
 113          * This corresponds directly to the fields in the database, without prefix.
 114          *
 115          * field name => type
 116          *
 117          * Allowed types:
 118          * * id
 119          * * str
 120          * * int
 121          * * float
 122          * * bool
 123          * * array
 124          *
 125          * @since 1.20
 126          *
 127          * @throws MWException
 128          * @return array
 129          */
 130         protected static function getFieldTypes() {
 131                 throw new MWException( 'Class did not implement getFieldTypes' );
 132         }
 133
 134         /**
 135          * Returns a list of default field values.
 136          * field name => field value
 137          *
 138          * @since 1.20
 139          *
 140          * @return array
 141          */
 142         public static function getDefaults() {
 143                 return array();
 144         }
 145
 146         /**
 147          * Returns a list of the summary fields.
 148          * These are fields that cache computed values, such as the amount of linked objects of $type.
 149          * This is relevant as one might not want to do actions such as log changes when these get updated.
 150          *
 151          * @since 1.20
 152          *
 153          * @return array
 154          */
 155         public static function getSummaryFields() {
 156                 return array();
 157         }
 158
 159         /**
 160          * Constructor.
 161          *
 162          * @since 1.20
 163          *
 164          * @param array|null $fields
 165          * @param boolean $loadDefaults
 166          */
 167         public function __construct( $fields = null, $loadDefaults = false ) {
 168                 if ( !is_array( $fields ) ) {
 169                         $fields = array();
 170                 }
 171
 172                 if ( $loadDefaults ) {
 173                         $fields = array_merge( $this->getDefaults(), $fields );
 174                 }
 175
 176                 $this->setFields( $fields );
 177         }
 178
 179         /**
 180          * Load the specified fields from the database.
 181          *
 182          * @since 1.20
 183          *
 184          * @param array|null $fields
 185          * @param boolean $override
 186          * @param boolean $skipLoaded
 187          *
 188          * @return bool Success indicator
 189          */
 190         public function loadFields( $fields = null, $override = true, $skipLoaded = false ) {
 191                 if ( is_null( $this->getId() ) ) {
 192                         return false;
 193                 }
 194
 195                 if ( is_null( $fields ) ) {
 196                         $fields = array_keys( $this->getFieldTypes() );
 197                 }
 198
 199                 if ( $skipLoaded ) {
 200                         $fields = array_diff( $fields, array_keys( $this->fields ) );
 201                 }
 202
 203                 if ( count( $fields ) > 0 ) {
 204                         $result = $this->rawSelectRow(
 205                                 $this->getPrefixedFields( $fields ),
 206                                 array( $this->getPrefixedField( 'id' ) => $this->getId() ),
 207                                 array( 'LIMIT' => 1 )
 208                         );
 209
 210                         if ( $result !== false ) {
 211                                 $this->setFields( $this->getFieldsFromDBResult( $result ), $override );
 212                                 return true;
 213                         }
 214
 215                         return false;
 216                 }
 217
 218                 return true;
 219         }
 220
 221         /**
 222          * Gets the value of a field.
 223          *
 224          * @since 1.20
 225          *
 226          * @param string $name
 227          * @param mixed $default
 228          *
 229          * @throws MWException
 230          * @return mixed
 231          */
 232         public function getField( $name, $default = null ) {
 233                 if ( $this->hasField( $name ) ) {
 234                         return $this->fields[$name];
 235                 } elseif ( !is_null( $default ) ) {
 236                         return $default;
 237                 } else {
 238                         throw new MWException( 'Attempted to get not-set field ' . $name );
 239                 }
 240         }
 241
 242         /**
 243          * Gets the value of a field but first loads it if not done so already.
 244          *
 245          * @since 1.20
 246          *
 247          * @param string$name
 248          *
 249          * @return mixed
 250          */
 251         public function loadAndGetField( $name ) {
 252                 if ( !$this->hasField( $name ) ) {
 253                         $this->loadFields( array( $name ) );
 254                 }
 255
 256                 return $this->getField( $name );
 257         }
 258
 259         /**
 260          * Remove a field.
 261          *
 262          * @since 1.20
 263          *
 264          * @param string $name
 265          */
 266         public function removeField( $name ) {
 267                 unset( $this->fields[$name] );
 268         }
 269
 270         /**
 271          * Returns the objects database id.
 272          *
 273          * @since 1.20
 274          *
 275          * @return integer|null
 276          */
 277         public function getId() {
 278                 return $this->getField( 'id' );
 279         }
 280
 281         /**
 282          * Sets the objects database id.
 283          *
 284          * @since 1.20
 285          *
 286          * @param integer|null $id
 287          */
 288         public function setId( $id ) {
 289                 return $this->setField( 'id', $id );
 290         }
 291
 292         /**
 293          * Gets if a certain field is set.
 294          *
 295          * @since 1.20
 296          *
 297          * @param string $name
 298          *
 299          * @return boolean
 300          */
 301         public function hasField( $name ) {
 302                 return array_key_exists( $name, $this->fields );
 303         }
 304
 305         /**
 306          * Gets if the id field is set.
 307          *
 308          * @since 1.20
 309          *
 310          * @return boolean
 311          */
 312         public function hasIdField() {
 313                 return $this->hasField( 'id' )
 314                         && !is_null( $this->getField( 'id' ) );
 315         }
 316
 317         /**
 318          * Sets multiple fields.
 319          *
 320          * @since 1.20
 321          *
 322          * @param array $fields The fields to set
 323          * @param boolean $override Override already set fields with the provided values?
 324          */
 325         public function setFields( array $fields, $override = true ) {
 326                 foreach ( $fields as $name => $value ) {
 327                         if ( $override || !$this->hasField( $name ) ) {
 328                                 $this->setField( $name, $value );
 329                         }
 330                 }
 331         }
 332
 333         /**
 334          * Gets the fields => values to write to the table.
 335          *
 336          * @since 1.20
 337          *
 338          * @return array
 339          */
 340         protected function getWriteValues() {
 341                 $values = array();
 342
 343                 foreach ( $this->getFieldTypes() as $name => $type ) {
 344                         if ( array_key_exists( $name, $this->fields ) ) {
 345                                 $value = $this->fields[$name];
 346
 347                                 switch ( $type ) {
 348                                         case 'array':
 349                                                 $value = (array)$value;
 350                                         case 'blob':
 351                                                 $value = serialize( $value );
 352                                 }
 353
 354                                 $values[$this->getFieldPrefix() . $name] = $value;
 355                         }
 356                 }
 357
 358                 return $values;
 359         }
 360
 361         /**
 362          * Serializes the object to an associative array which
 363          * can then easily be converted into JSON or similar.
 364          *
 365          * @since 1.20
 366          *
 367          * @param null|array $fields
 368          * @param boolean $incNullId
 369          *
 370          * @return array
 371          */
 372         public function toArray( $fields = null, $incNullId = false ) {
 373                 $data = array();
 374                 $setFields = array();
 375
 376                 if ( !is_array( $fields ) ) {
 377                         $setFields = $this->getSetFieldNames();
 378                 } else {
 379                         foreach ( $fields as $field ) {
 380                                 if ( $this->hasField( $field ) ) {
 381                                         $setFields[] = $field;
 382                                 }
 383                         }
 384                 }
 385
 386                 foreach ( $setFields as $field ) {
 387                         if ( $incNullId || $field != 'id' || $this->hasIdField() ) {
 388                                 $data[$field] = $this->getField( $field );
 389                         }
 390                 }
 391
 392                 return $data;
 393         }
 394
 395         /**
 396          * Load the default values, via getDefaults.
 397          *
 398          *  @since 1.20
 399          *
 400          * @param boolean $override
 401          */
 402         public function loadDefaults( $override = true ) {
 403                 $this->setFields( $this->getDefaults(), $override );
 404         }
 405
 406         /**
 407          * Writes the answer to the database, either updating it
 408          * when it already exists, or inserting it when it doesn't.
 409          *
 410          * @since 1.20
 411          *
 412          * @return boolean Success indicator
 413          */
 414         public function save() {
 415                 if ( $this->hasIdField() ) {
 416                         return $this->saveExisting();
 417                 } else {
 418                         return $this->insert();
 419                 }
 420         }
 421
 422         /**
 423          * Updates the object in the database.
 424          *
 425          * @since 1.20
 426          *
 427          * @return boolean Success indicator
 428          */
 429         protected function saveExisting() {
 430                 $dbw = wfGetDB( DB_MASTER );
 431
 432                 $success = $dbw->update(
 433                         $this->getDBTable(),
 434                         $this->getWriteValues(),
 435                         array( $this->getFieldPrefix() . 'id' => $this->getId() ),
 436                         __METHOD__
 437                 );
 438
 439                 return $success;
 440         }
 441
 442         /**
 443          * Inserts the object into the database.
 444          *
 445          * @since 1.20
 446          *
 447          * @return boolean Success indicator
 448          */
 449         protected function insert() {
 450                 $dbw = wfGetDB( DB_MASTER );
 451
 452                 $result = $dbw->insert(
 453                         $this->getDBTable(),
 454                         $this->getWriteValues(),
 455                         __METHOD__,
 456                         array( 'IGNORE' )
 457                 );
 458
 459                 if ( $result ) {
 460                         $this->setField( 'id', $dbw->insertId() );
 461                 }
 462
 463                 return $result;
 464         }
 465
 466         /**
 467          * Removes the object from the database.
 468          *
 469          * @since 1.20
 470          *
 471          * @return boolean Success indicator
 472          */
 473         public function remove() {
 474                 $this->beforeRemove();
 475
 476                 $success = static::delete( array( 'id' => $this->getId() ) );
 477
 478                 if ( $success ) {
 479                         $this->onRemoved();
 480                 }
 481
 482                 return $success;
 483         }
 484
 485         /**
 486          * Gets called before an object is removed from the database.
 487          *
 488          * @since 1.20
 489          */
 490         protected function beforeRemove() {
 491                 $this->loadFields( $this->getBeforeRemoveFields(), false, true );
 492         }
 493
 494         /**
 495          * Before removal of an object happens, @see beforeRemove gets called.
 496          * This method loads the fields of which the names have been returned by this one (or all fields if null is returned).
 497          * This allows for loading info needed after removal to get rid of linked data and the like.
 498          *
 499          * @since 1.20
 500          *
 501          * @return array|null
 502          */
 503         protected function getBeforeRemoveFields() {
 504                 return array();
 505         }
 506
 507         /**
 508          * Gets called after successfull removal.
 509          * Can be overriden to get rid of linked data.
 510          *
 511          * @since 1.20
 512          */
 513         protected function onRemoved() {
 514                 $this->setField( 'id', null );
 515         }
 516
 517         /**
 518          * Return the names and values of the fields.
 519          *
 520          * @since 1.20
 521          *
 522          * @return array
 523          */
 524         public function getFields() {
 525                 return $this->fields;
 526         }
 527
 528         /**
 529          * Return the names of the fields.
 530          *
 531          * @since 1.20
 532          *
 533          * @return array
 534          */
 535         public function getSetFieldNames() {
 536                 return array_keys( $this->fields );
 537         }
 538
 539         /**
 540          * Sets the value of a field.
 541          * Strings can be provided for other types,
 542          * so this method can be called from unserialization handlers.
 543          *
 544          * @since 1.20
 545          *
 546          * @param string $name
 547          * @param mixed $value
 548          *
 549          * @throws MWException
 550          */
 551         public function setField( $name, $value ) {
 552                 $fields = $this->getFieldTypes();
 553
 554                 if ( array_key_exists( $name, $fields ) ) {
 555                         switch ( $fields[$name] ) {
 556                                 case 'int':
 557                                         $value = (int)$value;
 558                                         break;
 559                                 case 'float':
 560                                         $value = (float)$value;
 561                                         break;
 562                                 case 'bool':
 563                                         if ( is_string( $value ) ) {
 564                                                 $value = $value !== '0';
 565                                         } elseif ( is_int( $value ) ) {
 566                                                 $value = $value !== 0;
 567                                         }
 568                                         break;
 569                                 case 'array':
 570                                         if ( is_string( $value ) ) {
 571                                                 $value = unserialize( $value );
 572                                         }
 573
 574                                         if ( !is_array( $value ) ) {
 575                                                 $value = array();
 576                                         }
 577                                         break;
 578                                 case 'blob':
 579                                         if ( is_string( $value ) ) {
 580                                                 $value = unserialize( $value );
 581                                         }
 582                                         break;
 583                                 case 'id':
 584                                         if ( is_string( $value ) ) {
 585                                                 $value = (int)$value;
 586                                         }
 587                                         break;
 588                         }
 589
 590                         $this->fields[$name] = $value;
 591                 } else {
 592                         throw new MWException( 'Attempted to set unknown field ' . $name );
 593                 }
 594         }
 595
 596         /**
 597          * Get a new instance of the class from an array.
 598          *
 599          * @since 1.20
 600          *
 601          * @param array $data
 602          * @param boolean $loadDefaults
 603          *
 604          * @return DBDataObject
 605          */
 606         public static function newFromArray( array $data, $loadDefaults = false ) {
 607                 return new static( $data, $loadDefaults );
 608         }
 609
 610         /**
 611          * Get the database type used for read operations.
 612          *
 613          * @since 1.20
 614          * @return integer DB_ enum
 615          */
 616         public static function getReadDb() {
 617                 return self::$readDb;
 618         }
 619
 620         /**
 621          * Set the database type to use for read operations.
 622          *
 623          * @param integer $db
 624          *
 625          * @since 1.20
 626          */
 627         public static function setReadDb( $db ) {
 628                 self::$readDb = $db;
 629         }
 630
 631         /**
 632          * Gets if the object can take a certain field.
 633          *
 634          * @since 1.20
 635          *
 636          * @param string $name
 637          *
 638          * @return boolean
 639          */
 640         public static function canHaveField( $name ) {
 641                 return array_key_exists( $name, static::getFieldTypes() );
 642         }
 643
 644         /**
 645          * Takes in a field or array of fields and returns an
 646          * array with their prefixed versions, ready for db usage.
 647          *
 648          * @since 1.20
 649          *
 650          * @param array|string $fields
 651          *
 652          * @return array
 653          */
 654         public static function getPrefixedFields( array $fields ) {
 655                 foreach ( $fields as &$field ) {
 656                         $field = static::getPrefixedField( $field );
 657                 }
 658
 659                 return $fields;
 660         }
 661
 662         /**
 663          * Takes in a field and returns an it's prefixed version, ready for db usage.
 664          *
 665          * @since 1.20
 666          *
 667          * @param string|array $field
 668          *
 669          * @return string
 670          * @throws MWException
 671          */
 672         public static function getPrefixedField( $field ) {
 673                 return static::getFieldPrefix() . $field;
 674         }
 675
 676         /**
 677          * Takes in an associative array with field names as keys and
 678          * their values as value. The field names are prefixed with the
 679          * db field prefix.
 680          *
 681          * Field names can also be provided as an array with as first element a table name, such as
 682          * $conditions = array(
 683          *       array( array( 'tablename', 'fieldname' ), $value ),
 684          * );
 685          *
 686          * @since 1.20
 687          *
 688          * @param array $values
 689          *
 690          * @return array
 691          */
 692         public static function getPrefixedValues( array $values ) {
 693                 $prefixedValues = array();
 694
 695                 foreach ( $values as $field => $value ) {
 696                         if ( is_integer( $field ) ) {
 697                                 if ( is_array( $value ) ) {
 698                                         $field = $value[0];
 699                                         $value = $value[1];
 700                                 }
 701                                 else {
 702                                         $value = explode( ' ', $value, 2 );
 703                                         $value[0] = static::getPrefixedField( $value[0] );
 704                                         $prefixedValues[] = implode( ' ', $value );
 705                                         continue;
 706                                 }
 707                         }
 708
 709                         $prefixedValues[static::getPrefixedField( $field )] = $value;
 710                 }
 711
 712                 return $prefixedValues;
 713         }
 714
 715         /**
 716          * Get an array with fields from a database result,
 717          * that can be fed directly to the constructor or
 718          * to setFields.
 719          *
 720          * @since 1.20
 721          *
 722          * @param object $result
 723          *
 724          * @return array
 725          */
 726         public static function getFieldsFromDBResult( $result ) {
 727                 $result = (array)$result;
 728                 return array_combine(
 729                         static::unprefixFieldNames( array_keys( $result ) ),
 730                         array_values( $result )
 731                 );
 732         }
 733
 734         /**
 735          * Takes a field name with prefix and returns the unprefixed equivalent.
 736          *
 737          * @since 1.20
 738          *
 739          * @param string $fieldName
 740          *
 741          * @return string
 742          */
 743         public static function unprefixFieldName( $fieldName ) {
 744                 return substr( $fieldName, strlen( static::getFieldPrefix() ) );
 745         }
 746
 747         /**
 748          * Takes an array of field names with prefix and returns the unprefixed equivalent.
 749          *
 750          * @since 1.20
 751          *
 752          * @param array $fieldNames
 753          *
 754          * @return array
 755          */
 756         public static function unprefixFieldNames( array $fieldNames ) {
 757                 return array_map( 'static::unprefixFieldName', $fieldNames );
 758         }
 759
 760         /**
 761          * Get a new instance of the class from a database result.
 762          *
 763          * @since 1.20
 764          *
 765          * @param stdClass $result
 766          *
 767          * @return DBDataObject
 768          */
 769         public static function newFromDBResult( stdClass $result ) {
 770                 return static::newFromArray( static::getFieldsFromDBResult( $result ) );
 771         }
 772
 773         /**
 774          * Removes the object from the database.
 775          *
 776          * @since 1.20
 777          *
 778          * @param array $conditions
 779          *
 780          * @return boolean Success indicator
 781          */
 782         public static function delete( array $conditions ) {
 783                 return wfGetDB( DB_MASTER )->delete(
 784                         static::getDBTable(),
 785                         static::getPrefixedValues( $conditions )
 786                 );
 787         }
 788
 789         /**
 790          * Add an amount (can be negative) to the specified field (needs to be numeric).
 791          *
 792          * @since 1.20
 793          *
 794          * @param string $field
 795          * @param integer $amount
 796          *
 797          * @return boolean Success indicator
 798          */
 799         public static function addToField( $field, $amount ) {
 800                 if ( $amount == 0 ) {
 801                         return true;
 802                 }
 803
 804                 if ( !static::hasIdField() ) {
 805                         return false;
 806                 }
 807
 808                 $absoluteAmount = abs( $amount );
 809                 $isNegative = $amount < 0;
 810
 811                 $dbw = wfGetDB( DB_MASTER );
 812
 813                 $fullField = static::getPrefixedField( $field );
 814
 815                 $success = $dbw->update(
 816                         static::getDBTable(),
 817                         array( "$fullField=$fullField" . ( $isNegative ? '-' : '+' ) . $absoluteAmount ),
 818                         array( static::getPrefixedField( 'id' ) => static::getId() ),
 819                         __METHOD__
 820                 );
 821
 822                 if ( $success && static::hasField( $field ) ) {
 823                         static::setField( $field, static::getField( $field ) + $amount );
 824                 }
 825
 826                 return $success;
 827         }
 828
 829         /**
 830          * Selects the the specified fields of the records matching the provided
 831          * conditions and returns them as DBDataObject. Field names get prefixed.
 832          *
 833          * @since 1.20
 834          *
 835          * @param array|string|null $fields
 836          * @param array $conditions
 837          * @param array $options
 838          *
 839          * @return array of self
 840          */
 841         public static function select( $fields = null, array $conditions = array(), array $options = array() ) {
 842                 $result = static::selectFields( $fields, $conditions, $options, false );
 843
 844                 $objects = array();
 845
 846                 foreach ( $result as $record ) {
 847                         $objects[] = static::newFromArray( $record );
 848                 }
 849
 850                 return $objects;
 851         }
 852
 853         /**
 854          * Selects the the specified fields of the records matching the provided
 855          * conditions and returns them as associative arrays.
 856          * Provided field names get prefixed.
 857          * Returned field names will not have a prefix.
 858          *
 859          * When $collapse is true:
 860          * If one field is selected, each item in the result array will be this field.
 861          * If two fields are selected, each item in the result array will have as key
 862          * the first field and as value the second field.
 863          * If more then two fields are selected, each item will be an associative array.
 864          *
 865          * @since 1.20
 866          *
 867          * @param array|string|null $fields
 868          * @param array $conditions
 869          * @param array $options
 870          * @param boolean $collapse Set to false to always return each result row as associative array.
 871          *
 872          * @return array of array
 873          */
 874         public static function selectFields( $fields = null, array $conditions = array(), array $options = array(), $collapse = true ) {
 875                 if ( is_null( $fields ) ) {
 876                         $fields = array_keys( static::getFieldTypes() );
 877                 }
 878                 else {
 879                         $fields = (array)$fields;
 880                 }
 881
 882                 $dbr = wfGetDB( static::getReadDb() );
 883                 $result = $dbr->select(
 884                         static::getDBTable(),
 885                         static::getPrefixedFields( $fields ),
 886                         static::getPrefixedValues( $conditions ),
 887                         __METHOD__,
 888                         $options
 889                 );
 890
 891                 $objects = array();
 892
 893                 foreach ( $result as $record ) {
 894                         $objects[] = static::getFieldsFromDBResult( $record );
 895                 }
 896
 897                 if ( $collapse ) {
 898                         if ( count( $fields ) === 1 ) {
 899                                 $objects = array_map( 'array_shift', $objects );
 900                         }
 901                         elseif ( count( $fields ) === 2 ) {
 902                                 $o = array();
 903
 904                                 foreach ( $objects as $object ) {
 905                                         $o[array_shift( $object )] = array_shift( $object );
 906                                 }
 907
 908                                 $objects = $o;
 909                         }
 910                 }
 911
 912                 return $objects;
 913         }
 914
 915         /**
 916          * Selects the the specified fields of the first matching record.
 917          * Field names get prefixed.
 918          *
 919          * @since 1.20
 920          *
 921          * @param array|string|null $fields
 922          * @param array $conditions
 923          * @param array $options
 924          *
 925          * @return DBObject|bool False on failure
 926          */
 927         public static function selectRow( $fields = null, array $conditions = array(), array $options = array() ) {
 928                 $options['LIMIT'] = 1;
 929
 930                 $objects = static::select( $fields, $conditions, $options );
 931
 932                 return count( $objects ) > 0 ? $objects[0] : false;
 933         }
 934
 935         /**
 936          * Selects the the specified fields of the first record matching the provided
 937          * conditions and returns it as an associative array, or false when nothing matches.
 938          * This method makes use of selectFields and expects the same parameters and
 939          * returns the same results (if there are any, if there are none, this method returns false).
 940          * @see DBDataObject::selectFields
 941          *
 942          * @since 1.20
 943          *
 944          * @param array|string|null $fields
 945          * @param array $conditions
 946          * @param array $options
 947          * @param boolean $collapse Set to false to always return each result row as associative array.
 948          *
 949          * @return mixed|array|bool False on failure
 950          */
 951         public static function selectFieldsRow( $fields = null, array $conditions = array(), array $options = array(), $collapse = true ) {
 952                 $options['LIMIT'] = 1;
 953
 954                 $objects = static::selectFields( $fields, $conditions, $options, $collapse );
 955
 956                 return count( $objects ) > 0 ? $objects[0] : false;
 957         }
 958
 959         /**
 960          * Returns if there is at least one record matching the provided conditions.
 961          * Condition field names get prefixed.
 962          *
 963          * @since 1.20
 964          *
 965          * @param array $conditions
 966          *
 967          * @return boolean
 968          */
 969         public static function has( array $conditions = array() ) {
 970                 return static::selectRow( array( 'id' ), $conditions ) !== false;
 971         }
 972
 973         /**
 974          * Returns the amount of matching records.
 975          * Condition field names get prefixed.
 976          *
 977          * @since 1.20
 978          *
 979          * @param array $conditions
 980          * @param array $options
 981          *
 982          * @return integer
 983          */
 984         public static function count( array $conditions = array(), array $options = array() ) {
 985                 $res = static::rawSelectRow(
 986                         array( 'COUNT(*) AS rowcount' ),
 987                         static::getPrefixedValues( $conditions ),
 988                         $options
 989                 );
 990
 991                 return $res->rowcount;
 992         }
 993
 994         /**
 995          * Selects the the specified fields of the records matching the provided
 996          * conditions. Field names do NOT get prefixed.
 997          *
 998          * @since 1.20
 999          *
1000          * @param array $fields
1001          * @param array $conditions
1002          * @param array $options
1003          *
1004          * @return ResultWrapper
1005          */
1006         protected static function rawSelectRow( array $fields, array $conditions = array(), array $options = array() ) {
1007                 $dbr = wfGetDB( static::getReadDb() );
1008
1009                 return $dbr->selectRow(
1010                         static::getDBTable(),
1011                         $fields,
1012                         $conditions,
1013                         __METHOD__,
1014                         $options
1015                 );
1016         }
1017
1018         /**
1019          * Update the records matching the provided conditions by
1020          * setting the fields that are keys in the $values param to
1021          * their corresponding values.
1022          *
1023          * @since 1.20
1024          *
1025          * @param array $values
1026          * @param array $conditions
1027          *
1028          * @return boolean Success indicator
1029          */
1030         public static function update( array $values, array $conditions = array() ) {
1031                 $dbw = wfGetDB( DB_MASTER );
1032
1033                 return $dbw->update(
1034                         static::getDBTable(),
1035                         static::getPrefixedValues( $values ),
1036                         static::getPrefixedValues( $conditions ),
1037                         __METHOD__
1038                 );
1039         }
1040
1041         /**
1042          * Return the names of the fields.
1043          *
1044          * @since 1.20
1045          *
1046          * @return array
1047          */
1048         public static function getFieldNames() {
1049                 return array_keys( static::getFieldTypes() );
1050         }
1051
1052         /**
1053          * Returns an array with the fields and their descriptions.
1054          *
1055          * field name => field description
1056          *
1057          * @since 1.20
1058          *
1059          * @return array
1060          */
1061         public static function getFieldDescriptions() {
1062                 return array();
1063         }
1064
1065         /**
1066          * Get API parameters for the fields supported by this object.
1067          *
1068          * @since 1.20
1069          *
1070          * @param boolean $requireParams
1071          * @param boolean $setDefaults
1072          *
1073          * @return array
1074          */
1075         public static function getAPIParams( $requireParams = false, $setDefaults = false ) {
1076                 $typeMap = array(
1077                         'id' => 'integer',
1078                         'int' => 'integer',
1079                         'float' => 'NULL',
1080                         'str' => 'string',
1081                         'bool' => 'integer',
1082                         'array' => 'string',
1083                         'blob' => 'string',
1084                 );
1085
1086                 $params = array();
1087                 $defaults = static::getDefaults();
1088
1089                 foreach ( static::getFieldTypes() as $field => $type ) {
1090                         if ( $field == 'id' ) {
1091                                 continue;
1092                         }
1093
1094                         $hasDefault = array_key_exists( $field, $defaults );
1095
1096                         $params[$field] = array(
1097                                 ApiBase::PARAM_TYPE => $typeMap[$type],
1098                                 ApiBase::PARAM_REQUIRED => $requireParams && !$hasDefault
1099                         );
1100
1101                         if ( $type == 'array' ) {
1102                                 $params[$field][ApiBase::PARAM_ISMULTI] = true;
1103                         }
1104
1105                         if ( $setDefaults && $hasDefault ) {
1106                                 $default = is_array( $defaults[$field] ) ? implode( '|', $defaults[$field] ) : $defaults[$field];
1107                                 $params[$field][ApiBase::PARAM_DFLT] = $default;
1108                         }
1109                 }
1110
1111                 return $params;
1112         }
1113
1114         /**
1115          * Computes and updates the values of the summary fields.
1116          *
1117          * @since 1.20
1118          *
1119          * @param array|string|null $summaryFields
1120          */
1121         public function loadSummaryFields( $summaryFields = null ) {
1122
1123         }
1124
1125         /**
1126          * Computes the values of the summary fields of the objects matching the provided conditions.
1127          *
1128          * @since 1.20
1129          *
1130          * @param array|string|null $summaryFields
1131          * @param array $conditions
1132          */
1133         public static function updateSummaryFields( $summaryFields = null, array $conditions = array() ) {
1134                 self::setReadDb( DB_MASTER );
1135
1136                 foreach ( self::select( null, $conditions ) as /* DBDataObject */ $item ) {
1137                         $item->loadSummaryFields( $summaryFields );
1138                         $item->setSummaryMode( true );
1139                         $item->saveExisting();
1140                 }
1141
1142                 self::setReadDb( DB_SLAVE );
1143         }
1144
1145         /**
1146          * Sets the value for the @see $updateSummaries field.
1147          *
1148          * @since 1.20
1149          *
1150          * @param boolean $update
1151          */
1152         public function setUpdateSummaries( $update ) {
1153                 $this->updateSummaries = $update;
1154         }
1155
1156         /**
1157          * Sets the value for the @see $inSummaryMode field.
1158          *
1159          * @since 1.20
1160          *
1161          * @param boolean $summaryMode
1162          */
1163         public function setSummaryMode( $summaryMode ) {
1164                 $this->inSummaryMode = $summaryMode;
1165         }
1166
1167         /**
1168          * Return if any fields got changed.
1169          *
1170          * @since 1.20
1171          *
1172          * @param DBDataObject $object
1173          * @param boolean $excludeSummaryFields When set to true, summary field changes are ignored.
1174          *
1175          * @return boolean
1176          */
1177         protected function fieldsChanged( DBDataObject $object, $excludeSummaryFields = false ) {
1178                 foreach ( $this->fields as $name => $value ) {
1179                         $excluded = $excludeSummaryFields && in_array( $name, $this->getSummaryFields() );
1180
1181                         if ( !$excluded && $object->getField( $name ) !== $value ) {
1182                                 return true;
1183                         }
1184                 }
1185
1186                 return false;
1187         }
1188
1189 }