includes/db/ORMRow.php

   1 <?php
   2 /**
   3  * Abstract base class for representing objects that are stored in some DB table.
   4  * This is basically an ORM-like wrapper around rows in database tables that
   5  * aims to be both simple and very flexible. It is centered around an associative
   6  * array of fields and various methods to do common interaction with the database.
   7  *
   8  * Documentation inline and at https://www.mediawiki.org/wiki/Manual:ORMTable
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  *
  25  * @since 1.20
  26  *
  27  * @file ORMRow.php
  28  * @ingroup ORM
  29  *
  30  * @license GNU GPL v2 or later
  31  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  32  */
  33
  34 abstract class ORMRow implements IORMRow {
  35
  36         /**
  37          * The fields of the object.
  38          * field name (w/o prefix) => value
  39          *
  40          * @since 1.20
  41          * @var array
  42          */
  43         protected $fields = array( 'id' => null );
  44
  45         /**
  46          * @since 1.20
  47          * @var ORMTable
  48          */
  49         protected $table;
  50
  51         /**
  52          * If the object should update summaries of linked items when changed.
  53          * For example, update the course_count field in universities when a course in courses is deleted.
  54          * Settings this to false can prevent needless updating work in situations
  55          * such as deleting a university, which will then delete all it's courses.
  56          *
  57          * @since 1.20
  58          * @var bool
  59          */
  60         protected $updateSummaries = true;
  61
  62         /**
  63          * Indicates if the object is in summary mode.
  64          * This mode indicates that only summary fields got updated,
  65          * which allows for optimizations.
  66          *
  67          * @since 1.20
  68          * @var bool
  69          */
  70         protected $inSummaryMode = false;
  71
  72         /**
  73          * Constructor.
  74          *
  75          * @since 1.20
  76          *
  77          * @param IORMTable $table
  78          * @param array|null $fields
  79          * @param boolean $loadDefaults
  80          */
  81         public function __construct( IORMTable $table, $fields = null, $loadDefaults = false ) {
  82                 $this->table = $table;
  83
  84                 if ( !is_array( $fields ) ) {
  85                         $fields = array();
  86                 }
  87
  88                 if ( $loadDefaults ) {
  89                         $fields = array_merge( $this->table->getDefaults(), $fields );
  90                 }
  91
  92                 $this->setFields( $fields );
  93         }
  94
  95         /**
  96          * Load the specified fields from the database.
  97          *
  98          * @since 1.20
  99          *
 100          * @param array|null $fields
 101          * @param boolean $override
 102          * @param boolean $skipLoaded
 103          *
 104          * @return bool Success indicator
 105          */
 106         public function loadFields( $fields = null, $override = true, $skipLoaded = false ) {
 107                 if ( is_null( $this->getId() ) ) {
 108                         return false;
 109                 }
 110
 111                 if ( is_null( $fields ) ) {
 112                         $fields = array_keys( $this->table->getFields() );
 113                 }
 114
 115                 if ( $skipLoaded ) {
 116                         $fields = array_diff( $fields, array_keys( $this->fields ) );
 117                 }
 118
 119                 if ( !empty( $fields ) ) {
 120                         $result = $this->table->rawSelectRow(
 121                                 $this->table->getPrefixedFields( $fields ),
 122                                 array( $this->table->getPrefixedField( 'id' ) => $this->getId() ),
 123                                 array( 'LIMIT' => 1 ),
 124                                 __METHOD__
 125                         );
 126
 127                         if ( $result !== false ) {
 128                                 $this->setFields( $this->table->getFieldsFromDBResult( $result ), $override );
 129                                 return true;
 130                         }
 131                         return false;
 132                 }
 133
 134                 return true;
 135         }
 136
 137         /**
 138          * Gets the value of a field.
 139          *
 140          * @since 1.20
 141          *
 142          * @param $name string: Field name
 143          * @param $default mixed: Default value to return when none is found
 144          * (default: null)
 145          *
 146          * @throws MWException
 147          * @return mixed
 148          */
 149         public function getField( $name, $default = null ) {
 150                 if ( $this->hasField( $name ) ) {
 151                         return $this->fields[$name];
 152                 } elseif ( !is_null( $default ) ) {
 153                         return $default;
 154                 } else {
 155                         throw new MWException( 'Attempted to get not-set field ' . $name );
 156                 }
 157         }
 158
 159         /**
 160          * Gets the value of a field but first loads it if not done so already.
 161          *
 162          * @since 1.20
 163          *
 164          * @param $name string
 165          *
 166          * @return mixed
 167          */
 168         public function loadAndGetField( $name ) {
 169                 if ( !$this->hasField( $name ) ) {
 170                         $this->loadFields( array( $name ) );
 171                 }
 172
 173                 return $this->getField( $name );
 174         }
 175
 176         /**
 177          * Remove a field.
 178          *
 179          * @since 1.20
 180          *
 181          * @param string $name
 182          */
 183         public function removeField( $name ) {
 184                 unset( $this->fields[$name] );
 185         }
 186
 187         /**
 188          * Returns the objects database id.
 189          *
 190          * @since 1.20
 191          *
 192          * @return integer|null
 193          */
 194         public function getId() {
 195                 return $this->getField( 'id' );
 196         }
 197
 198         /**
 199          * Sets the objects database id.
 200          *
 201          * @since 1.20
 202          *
 203          * @param integer|null $id
 204          */
 205         public function setId( $id ) {
 206                 $this->setField( 'id', $id );
 207         }
 208
 209         /**
 210          * Gets if a certain field is set.
 211          *
 212          * @since 1.20
 213          *
 214          * @param string $name
 215          *
 216          * @return boolean
 217          */
 218         public function hasField( $name ) {
 219                 return array_key_exists( $name, $this->fields );
 220         }
 221
 222         /**
 223          * Gets if the id field is set.
 224          *
 225          * @since 1.20
 226          *
 227          * @return boolean
 228          */
 229         public function hasIdField() {
 230                 return $this->hasField( 'id' )
 231                         && !is_null( $this->getField( 'id' ) );
 232         }
 233
 234         /**
 235          * Sets multiple fields.
 236          *
 237          * @since 1.20
 238          *
 239          * @param array $fields The fields to set
 240          * @param boolean $override Override already set fields with the provided values?
 241          */
 242         public function setFields( array $fields, $override = true ) {
 243                 foreach ( $fields as $name => $value ) {
 244                         if ( $override || !$this->hasField( $name ) ) {
 245                                 $this->setField( $name, $value );
 246                         }
 247                 }
 248         }
 249
 250         /**
 251          * Gets the fields => values to write to the table.
 252          *
 253          * @since 1.20
 254          *
 255          * @return array
 256          */
 257         protected function getWriteValues() {
 258                 $values = array();
 259
 260                 foreach ( $this->table->getFields() as $name => $type ) {
 261                         if ( array_key_exists( $name, $this->fields ) ) {
 262                                 $value = $this->fields[$name];
 263
 264                                 switch ( $type ) {
 265                                         case 'array':
 266                                                 $value = (array)$value;
 267                                                 // fall-through!
 268                                         case 'blob':
 269                                                 $value = serialize( $value );
 270                                                 // fall-through!
 271                                 }
 272
 273                                 $values[$this->table->getPrefixedField( $name )] = $value;
 274                         }
 275                 }
 276
 277                 return $values;
 278         }
 279
 280         /**
 281          * Serializes the object to an associative array which
 282          * can then easily be converted into JSON or similar.
 283          *
 284          * @since 1.20
 285          *
 286          * @param null|array $fields
 287          * @param boolean $incNullId
 288          *
 289          * @return array
 290          */
 291         public function toArray( $fields = null, $incNullId = false ) {
 292                 $data = array();
 293                 $setFields = array();
 294
 295                 if ( !is_array( $fields ) ) {
 296                         $setFields = $this->getSetFieldNames();
 297                 } else {
 298                         foreach ( $fields as $field ) {
 299                                 if ( $this->hasField( $field ) ) {
 300                                         $setFields[] = $field;
 301                                 }
 302                         }
 303                 }
 304
 305                 foreach ( $setFields as $field ) {
 306                         if ( $incNullId || $field != 'id' || $this->hasIdField() ) {
 307                                 $data[$field] = $this->getField( $field );
 308                         }
 309                 }
 310
 311                 return $data;
 312         }
 313
 314         /**
 315          * Load the default values, via getDefaults.
 316          *
 317          * @since 1.20
 318          *
 319          * @param boolean $override
 320          */
 321         public function loadDefaults( $override = true ) {
 322                 $this->setFields( $this->table->getDefaults(), $override );
 323         }
 324
 325         /**
 326          * Writes the answer to the database, either updating it
 327          * when it already exists, or inserting it when it doesn't.
 328          *
 329          * @since 1.20
 330          *
 331          * @param string|null $functionName
 332          *
 333          * @return boolean Success indicator
 334          */
 335         public function save( $functionName = null ) {
 336                 if ( $this->hasIdField() ) {
 337                         return $this->saveExisting( $functionName );
 338                 } else {
 339                         return $this->insert( $functionName );
 340                 }
 341         }
 342
 343         /**
 344          * Updates the object in the database.
 345          *
 346          * @since 1.20
 347          *
 348          * @param string|null $functionName
 349          *
 350          * @return boolean Success indicator
 351          */
 352         protected function saveExisting( $functionName = null ) {
 353                 $dbw = $this->table->getWriteDbConnection();
 354
 355                 $success = $dbw->update(
 356                         $this->table->getName(),
 357                         $this->getWriteValues(),
 358                         $this->table->getPrefixedValues( $this->getUpdateConditions() ),
 359                         is_null( $functionName ) ? __METHOD__ : $functionName
 360                 );
 361
 362                 $this->table->releaseConnection( $dbw );
 363
 364                 // DatabaseBase::update does not always return true for success as documented...
 365                 return $success !== false;
 366         }
 367
 368         /**
 369          * Returns the WHERE considtions needed to identify this object so
 370          * it can be updated.
 371          *
 372          * @since 1.20
 373          *
 374          * @return array
 375          */
 376         protected function getUpdateConditions() {
 377                 return array( 'id' => $this->getId() );
 378         }
 379
 380         /**
 381          * Inserts the object into the database.
 382          *
 383          * @since 1.20
 384          *
 385          * @param string|null $functionName
 386          * @param array|null $options
 387          *
 388          * @return boolean Success indicator
 389          */
 390         protected function insert( $functionName = null, array $options = null ) {
 391                 $dbw = $this->table->getWriteDbConnection();
 392
 393                 $success = $dbw->insert(
 394                         $this->table->getName(),
 395                         $this->getWriteValues(),
 396                         is_null( $functionName ) ? __METHOD__ : $functionName,
 397                         $options
 398                 );
 399
 400                 // DatabaseBase::insert does not always return true for success as documented...
 401                 $success = $success !== false;
 402
 403                 if ( $success ) {
 404                         $this->setField( 'id', $dbw->insertId() );
 405                 }
 406
 407                 $this->table->releaseConnection( $dbw );
 408
 409                 return $success;
 410         }
 411
 412         /**
 413          * Removes the object from the database.
 414          *
 415          * @since 1.20
 416          *
 417          * @return boolean Success indicator
 418          */
 419         public function remove() {
 420                 $this->beforeRemove();
 421
 422                 $success = $this->table->delete( array( 'id' => $this->getId() ), __METHOD__ );
 423
 424                 // DatabaseBase::delete does not always return true for success as documented...
 425                 $success = $success !== false;
 426
 427                 if ( $success ) {
 428                         $this->onRemoved();
 429                 }
 430
 431                 return $success;
 432         }
 433
 434         /**
 435          * Gets called before an object is removed from the database.
 436          *
 437          * @since 1.20
 438          */
 439         protected function beforeRemove() {
 440                 $this->loadFields( $this->getBeforeRemoveFields(), false, true );
 441         }
 442
 443         /**
 444          * Before removal of an object happens, @see beforeRemove gets called.
 445          * This method loads the fields of which the names have been returned by this one (or all fields if null is returned).
 446          * This allows for loading info needed after removal to get rid of linked data and the like.
 447          *
 448          * @since 1.20
 449          *
 450          * @return array|null
 451          */
 452         protected function getBeforeRemoveFields() {
 453                 return array();
 454         }
 455
 456         /**
 457          * Gets called after successful removal.
 458          * Can be overridden to get rid of linked data.
 459          *
 460          * @since 1.20
 461          */
 462         protected function onRemoved() {
 463                 $this->setField( 'id', null );
 464         }
 465
 466         /**
 467          * Return the names and values of the fields.
 468          *
 469          * @since 1.20
 470          *
 471          * @return array
 472          */
 473         public function getFields() {
 474                 return $this->fields;
 475         }
 476
 477         /**
 478          * Return the names of the fields.
 479          *
 480          * @since 1.20
 481          *
 482          * @return array
 483          */
 484         public function getSetFieldNames() {
 485                 return array_keys( $this->fields );
 486         }
 487
 488         /**
 489          * Sets the value of a field.
 490          * Strings can be provided for other types,
 491          * so this method can be called from unserialization handlers.
 492          *
 493          * @since 1.20
 494          *
 495          * @param string $name
 496          * @param mixed $value
 497          *
 498          * @throws MWException
 499          */
 500         public function setField( $name, $value ) {
 501                 $fields = $this->table->getFields();
 502
 503                 if ( array_key_exists( $name, $fields ) ) {
 504                         switch ( $fields[$name] ) {
 505                                 case 'int':
 506                                         $value = (int)$value;
 507                                         break;
 508                                 case 'float':
 509                                         $value = (float)$value;
 510                                         break;
 511                                 case 'bool':
 512                                         if ( is_string( $value ) ) {
 513                                                 $value = $value !== '0';
 514                                         } elseif ( is_int( $value ) ) {
 515                                                 $value = $value !== 0;
 516                                         }
 517                                         break;
 518                                 case 'array':
 519                                         if ( is_string( $value ) ) {
 520                                                 $value = unserialize( $value );
 521                                         }
 522
 523                                         if ( !is_array( $value ) ) {
 524                                                 $value = array();
 525                                         }
 526                                         break;
 527                                 case 'blob':
 528                                         if ( is_string( $value ) ) {
 529                                                 $value = unserialize( $value );
 530                                         }
 531                                         break;
 532                                 case 'id':
 533                                         if ( is_string( $value ) ) {
 534                                                 $value = (int)$value;
 535                                         }
 536                                         break;
 537                         }
 538
 539                         $this->fields[$name] = $value;
 540                 } else {
 541                         throw new MWException( 'Attempted to set unknown field ' . $name );
 542                 }
 543         }
 544
 545         /**
 546          * Add an amount (can be negative) to the specified field (needs to be numeric).
 547          * TODO: most off this stuff makes more sense in the table class
 548          *
 549          * @since 1.20
 550          *
 551          * @param string $field
 552          * @param integer $amount
 553          *
 554          * @return boolean Success indicator
 555          */
 556         public function addToField( $field, $amount ) {
 557                 if ( $amount == 0 ) {
 558                         return true;
 559                 }
 560
 561                 if ( !$this->hasIdField() ) {
 562                         return false;
 563                 }
 564
 565                 $absoluteAmount = abs( $amount );
 566                 $isNegative = $amount < 0;
 567
 568                 $dbw = $this->table->getWriteDbConnection();
 569
 570                 $fullField = $this->table->getPrefixedField( $field );
 571
 572                 $success = $dbw->update(
 573                         $this->table->getName(),
 574                         array( "$fullField=$fullField" . ( $isNegative ? '-' : '+' ) . $absoluteAmount ),
 575                         array( $this->table->getPrefixedField( 'id' ) => $this->getId() ),
 576                         __METHOD__
 577                 );
 578
 579                 if ( $success && $this->hasField( $field ) ) {
 580                         $this->setField( $field, $this->getField( $field ) + $amount );
 581                 }
 582
 583                 $this->table->releaseConnection( $dbw );
 584
 585                 return $success;
 586         }
 587
 588         /**
 589          * Return the names of the fields.
 590          *
 591          * @since 1.20
 592          *
 593          * @return array
 594          */
 595         public function getFieldNames() {
 596                 return array_keys( $this->table->getFields() );
 597         }
 598
 599         /**
 600          * Computes and updates the values of the summary fields.
 601          *
 602          * @since 1.20
 603          *
 604          * @param array|string|null $summaryFields
 605          */
 606         public function loadSummaryFields( $summaryFields = null ) {
 607
 608         }
 609
 610         /**
 611          * Sets the value for the @see $updateSummaries field.
 612          *
 613          * @since 1.20
 614          *
 615          * @param boolean $update
 616          */
 617         public function setUpdateSummaries( $update ) {
 618                 $this->updateSummaries = $update;
 619         }
 620
 621         /**
 622          * Sets the value for the @see $inSummaryMode field.
 623          *
 624          * @since 1.20
 625          *
 626          * @param boolean $summaryMode
 627          */
 628         public function setSummaryMode( $summaryMode ) {
 629                 $this->inSummaryMode = $summaryMode;
 630         }
 631
 632         /**
 633          * Return if any fields got changed.
 634          *
 635          * @since 1.20
 636          *
 637          * @param IORMRow $object
 638          * @param boolean|array $excludeSummaryFields
 639          *  When set to true, summary field changes are ignored.
 640          *  Can also be an array of fields to ignore.
 641          *
 642          * @return boolean
 643          */
 644         protected function fieldsChanged( IORMRow $object, $excludeSummaryFields = false ) {
 645                 $exclusionFields = array();
 646
 647                 if ( $excludeSummaryFields !== false ) {
 648                         $exclusionFields = is_array( $excludeSummaryFields ) ? $excludeSummaryFields : $this->table->getSummaryFields();
 649                 }
 650
 651                 foreach ( $this->fields as $name => $value ) {
 652                         $excluded = $excludeSummaryFields && in_array( $name, $exclusionFields );
 653
 654                         if ( !$excluded && $object->getField( $name ) !== $value ) {
 655                                 return true;
 656                         }
 657                 }
 658
 659                 return false;
 660         }
 661
 662         /**
 663          * Returns the table this IORMRow is a row in.
 664          *
 665          * @since 1.20
 666          *
 667          * @return IORMTable
 668          */
 669         public function getTable() {
 670                 return $this->table;
 671         }
 672
 673 }