ORMTable.php

Go to the documentation of this file.

<?php
class ORMTable extends DBAccessBase implements IORMTable {
    protected static $instanceCache = array();
 
    protected $tableName;
 
    protected $fields = array();
 
    protected $fieldPrefix = '';
 
    protected $rowClass = 'ORMRow';
 
    protected $defaults = array();
 
    protected $readDb = DB_SLAVE;
 
    public function __construct( $tableName = '', array $fields = array(),
        array $defaults = array(), $rowClass = null, $fieldPrefix = ''
    ) {
        $this->tableName = $tableName;
        $this->fields = $fields;
        $this->defaults = $defaults;
 
        if ( is_string( $rowClass ) ) {
            $this->rowClass = $rowClass;
        }
 
        $this->fieldPrefix = $fieldPrefix;
    }
 
    public function getName() {
        if ( $this->tableName === '' ) {
            throw new MWException( 'The table name needs to be set' );
        }
 
        return $this->tableName;
    }
 
    protected function getFieldPrefix() {
        return $this->fieldPrefix;
    }
 
    public function getRowClass() {
        return $this->rowClass;
    }
 
    public function getFields() {
        if ( $this->fields === array() ) {
            throw new MWException( 'The table needs to have one or more fields' );
        }
 
        return $this->fields;
    }
 
    public function getDefaults() {
        return $this->defaults;
    }
 
    public function getSummaryFields() {
        return array();
    }
 
    public function select( $fields = null, array $conditions = array(),
        array $options = array(), $functionName = null
    ) {
        $res = $this->rawSelect( $fields, $conditions, $options, $functionName );
 
        return new ORMResult( $this, $res );
    }
 
    public function selectObjects( $fields = null, array $conditions = array(),
        array $options = array(), $functionName = null
    ) {
        $result = $this->selectFields( $fields, $conditions, $options, false, $functionName );
 
        $objects = array();
 
        foreach ( $result as $record ) {
            $objects[] = $this->newRow( $record );
        }
 
        return $objects;
    }
 
    public function rawSelect( $fields = null, array $conditions = array(),
        array $options = array(), $functionName = null
    ) {
        if ( is_null( $fields ) ) {
            $fields = array_keys( $this->getFields() );
        } else {
            $fields = (array)$fields;
        }
 
        $dbr = $this->getReadDbConnection();
        $result = $dbr->select(
            $this->getName(),
            $this->getPrefixedFields( $fields ),
            $this->getPrefixedValues( $conditions ),
            is_null( $functionName ) ? __METHOD__ : $functionName,
            $options
        );
 
        /* @var Exception $error */
        $error = null;
 
        if ( $result === false ) {
            // Database connection was in "ignoreErrors" mode. We don't like that.
            // So, we emulate the DBQueryError that should have been thrown.
            $error = new DBQueryError(
                $dbr,
                $dbr->lastError(),
                $dbr->lastErrno(),
                $dbr->lastQuery(),
                is_null( $functionName ) ? __METHOD__ : $functionName
            );
        }
 
        $this->releaseConnection( $dbr );
 
        if ( $error ) {
            // Note: construct the error before releasing the connection,
            // but throw it after.
            throw $error;
        }
 
        return $result;
    }
 
    public function selectFields( $fields = null, array $conditions = array(),
        array $options = array(), $collapse = true, $functionName = null
    ) {
        $objects = array();
 
        $result = $this->rawSelect( $fields, $conditions, $options, $functionName );
 
        foreach ( $result as $record ) {
            $objects[] = $this->getFieldsFromDBResult( $record );
        }
 
        if ( $collapse ) {
            if ( count( $fields ) === 1 ) {
                $objects = array_map( 'array_shift', $objects );
            } elseif ( count( $fields ) === 2 ) {
                $o = array();
 
                foreach ( $objects as $object ) {
                    $o[array_shift( $object )] = array_shift( $object );
                }
 
                $objects = $o;
            }
        }
 
        return $objects;
    }
 
    public function selectRow( $fields = null, array $conditions = array(),
        array $options = array(), $functionName = null
    ) {
        $options['LIMIT'] = 1;
 
        $objects = $this->select( $fields, $conditions, $options, $functionName );
 
        return ( !$objects || $objects->isEmpty() ) ? false : $objects->current();
    }
 
    public function rawSelectRow( array $fields, array $conditions = array(),
        array $options = array(), $functionName = null
    ) {
        $dbr = $this->getReadDbConnection();
 
        $result = $dbr->selectRow(
            $this->getName(),
            $fields,
            $conditions,
            is_null( $functionName ) ? __METHOD__ : $functionName,
            $options
        );
 
        $this->releaseConnection( $dbr );
 
        return $result;
    }
 
    public function selectFieldsRow( $fields = null, array $conditions = array(),
        array $options = array(), $collapse = true, $functionName = null
    ) {
        $options['LIMIT'] = 1;
 
        $objects = $this->selectFields( $fields, $conditions, $options, $collapse, $functionName );
 
        return empty( $objects ) ? false : $objects[0];
    }
 
    public function has( array $conditions = array() ) {
        return $this->selectRow( array( 'id' ), $conditions ) !== false;
    }
 
    public function exists() {
        $dbr = $this->getReadDbConnection();
        $exists = $dbr->tableExists( $this->getName() );
        $this->releaseConnection( $dbr );
 
        return $exists;
    }
 
    public function count( array $conditions = array(), array $options = array() ) {
        $res = $this->rawSelectRow(
            array( 'rowcount' => 'COUNT(*)' ),
            $this->getPrefixedValues( $conditions ),
            $options,
            __METHOD__
        );
 
        return $res->rowcount;
    }
 
    public function delete( array $conditions, $functionName = null ) {
        $dbw = $this->getWriteDbConnection();
 
        $result = $dbw->delete(
            $this->getName(),
            $conditions === array() ? '*' : $this->getPrefixedValues( $conditions ),
            is_null( $functionName ) ? __METHOD__ : $functionName
        ) !== false; // DatabaseBase::delete does not always return true for success as documented...
 
        $this->releaseConnection( $dbw );
 
        return $result;
    }
 
    public function getAPIParams( $requireParams = false, $setDefaults = false ) {
        $typeMap = array(
            'id' => 'integer',
            'int' => 'integer',
            'float' => 'NULL',
            'str' => 'string',
            'bool' => 'integer',
            'array' => 'string',
            'blob' => 'string',
        );
 
        $params = array();
        $defaults = $this->getDefaults();
 
        foreach ( $this->getFields() as $field => $type ) {
            if ( $field == 'id' ) {
                continue;
            }
 
            $hasDefault = array_key_exists( $field, $defaults );
 
            $params[$field] = array(
                ApiBase::PARAM_TYPE => $typeMap[$type],
                ApiBase::PARAM_REQUIRED => $requireParams && !$hasDefault
            );
 
            if ( $type == 'array' ) {
                $params[$field][ApiBase::PARAM_ISMULTI] = true;
            }
 
            if ( $setDefaults && $hasDefault ) {
                $default = is_array( $defaults[$field] )
                    ? implode( '|', $defaults[$field] )
                    : $defaults[$field];
                $params[$field][ApiBase::PARAM_DFLT] = $default;
            }
        }
 
        return $params;
    }
 
    public function getFieldDescriptions() {
        return array();
    }
 
    public function getReadDb() {
        return $this->readDb;
    }
 
    public function setReadDb( $db ) {
        $this->readDb = $db;
    }
 
    public function getTargetWiki() {
        return $this->wiki;
    }
 
    public function setTargetWiki( $wiki ) {
        $this->wiki = $wiki;
    }
 
    public function getReadDbConnection() {
        return $this->getConnection( $this->getReadDb(), array() );
    }
 
    public function getWriteDbConnection() {
        return $this->getConnection( DB_MASTER, array() );
    }
 
    // @codingStandardsIgnoreStart Suppress "useless method overriding" sniffer warning
    public function releaseConnection( DatabaseBase $db ) {
        parent::releaseConnection( $db ); // just make it public
    }
    // @codingStandardsIgnoreEnd
 
    public function update( array $values, array $conditions = array() ) {
        $dbw = $this->getWriteDbConnection();
 
        $result = $dbw->update(
            $this->getName(),
            $this->getPrefixedValues( $values ),
            $this->getPrefixedValues( $conditions ),
            __METHOD__
        ) !== false; // DatabaseBase::update does not always return true for success as documented...
 
        $this->releaseConnection( $dbw );
 
        return $result;
    }
 
    public function updateSummaryFields( $summaryFields = null, array $conditions = array() ) {
        $slave = $this->getReadDb();
        $this->setReadDb( DB_MASTER );
 
        foreach ( $this->select( null, $conditions ) as $item ) {
            $item->loadSummaryFields( $summaryFields );
            $item->setSummaryMode( true );
            $item->save();
        }
 
        $this->setReadDb( $slave );
    }
 
    public function getPrefixedValues( array $values ) {
        $prefixedValues = array();
 
        foreach ( $values as $field => $value ) {
            if ( is_integer( $field ) ) {
                if ( is_array( $value ) ) {
                    $field = $value[0];
                    $value = $value[1];
                } else {
                    $value = explode( ' ', $value, 2 );
                    $value[0] = $this->getPrefixedField( $value[0] );
                    $prefixedValues[] = implode( ' ', $value );
                    continue;
                }
            }
 
            $prefixedValues[$this->getPrefixedField( $field )] = $value;
        }
 
        return $prefixedValues;
    }
 
    public function getPrefixedFields( array $fields ) {
        foreach ( $fields as &$field ) {
            $field = $this->getPrefixedField( $field );
        }
 
        return $fields;
    }
 
    public function getPrefixedField( $field ) {
        return $this->getFieldPrefix() . $field;
    }
 
    public function unprefixFieldNames( array $fieldNames ) {
        return array_map( array( $this, 'unprefixFieldName' ), $fieldNames );
    }
 
    public function unprefixFieldName( $fieldName ) {
        return substr( $fieldName, strlen( $this->getFieldPrefix() ) );
    }
 
    public static function singleton() {
        $class = get_called_class();
 
        if ( !array_key_exists( $class, self::$instanceCache ) ) {
            self::$instanceCache[$class] = new $class;
        }
 
        return self::$instanceCache[$class];
    }
 
    public function getFieldsFromDBResult( stdClass $result ) {
        $result = (array)$result;
 
        $rawFields = array_combine(
            $this->unprefixFieldNames( array_keys( $result ) ),
            array_values( $result )
        );
 
        $fieldDefinitions = $this->getFields();
        $fields = array();
 
        foreach ( $rawFields as $name => $value ) {
            if ( array_key_exists( $name, $fieldDefinitions ) ) {
                switch ( $fieldDefinitions[$name] ) {
                    case 'int':
                        $value = (int)$value;
                        break;
                    case 'float':
                        $value = (float)$value;
                        break;
                    case 'bool':
                        if ( is_string( $value ) ) {
                            $value = $value !== '0';
                        } elseif ( is_int( $value ) ) {
                            $value = $value !== 0;
                        }
                        break;
                    case 'array':
                        if ( is_string( $value ) ) {
                            $value = unserialize( $value );
                        }
 
                        if ( !is_array( $value ) ) {
                            $value = array();
                        }
                        break;
                    case 'blob':
                        if ( is_string( $value ) ) {
                            $value = unserialize( $value );
                        }
                        break;
                    case 'id':
                        if ( is_string( $value ) ) {
                            $value = (int)$value;
                        }
                        break;
                }
 
                $fields[$name] = $value;
            } else {
                throw new MWException( 'Attempted to set unknown field ' . $name );
            }
        }
 
        return $fields;
    }
 
    public function newFromDBResult( stdClass $result ) {
        return self::newRowFromDBResult( $result );
    }
 
    public function newRowFromDBResult( stdClass $result ) {
        return $this->newRow( $this->getFieldsFromDBResult( $result ) );
    }
 
    public function newFromArray( array $data, $loadDefaults = false ) {
        return static::newRow( $data, $loadDefaults );
    }
 
    public function newRow( array $fields, $loadDefaults = false ) {
        $class = $this->getRowClass();
 
        return new $class( $this, $fields, $loadDefaults );
    }
 
    public function getFieldNames() {
        return array_keys( $this->getFields() );
    }
 
    public function canHaveField( $name ) {
        return array_key_exists( $name, $this->getFields() );
    }
 
    public function updateRow( IORMRow $row, $functionName = null ) {
        $dbw = $this->getWriteDbConnection();
 
        $success = $dbw->update(
            $this->getName(),
            $this->getWriteValues( $row ),
            $this->getPrefixedValues( array( 'id' => $row->getId() ) ),
            is_null( $functionName ) ? __METHOD__ : $functionName
        );
 
        $this->releaseConnection( $dbw );
 
        // DatabaseBase::update does not always return true for success as documented...
        return $success !== false;
    }
 
    public function insertRow( IORMRow $row, $functionName = null, array $options = null ) {
        $dbw = $this->getWriteDbConnection();
 
        $success = $dbw->insert(
            $this->getName(),
            $this->getWriteValues( $row ),
            is_null( $functionName ) ? __METHOD__ : $functionName,
            $options
        );
 
        // DatabaseBase::insert does not always return true for success as documented...
        $success = $success !== false;
 
        if ( $success ) {
            $row->setField( 'id', $dbw->insertId() );
        }
 
        $this->releaseConnection( $dbw );
 
        return $success;
    }
 
    protected function getWriteValues( IORMRow $row ) {
        $values = array();
 
        $rowFields = $row->getFields();
 
        foreach ( $this->getFields() as $name => $type ) {
            if ( array_key_exists( $name, $rowFields ) ) {
                $value = $rowFields[$name];
 
                switch ( $type ) {
                    case 'array':
                        $value = (array)$value;
                    // fall-through!
                    case 'blob':
                        $value = serialize( $value );
                    // fall-through!
                }
 
                $values[$this->getPrefixedField( $name )] = $value;
            }
        }
 
        return $values;
    }
 
    public function removeRow( IORMRow $row, $functionName = null ) {
        $success = $this->delete(
            array( 'id' => $row->getId() ),
            is_null( $functionName ) ? __METHOD__ : $functionName
        );
 
        // DatabaseBase::delete does not always return true for success as documented...
        return $success !== false;
    }
 
    public function addToField( array $conditions, $field, $amount ) {
        if ( !array_key_exists( $field, $this->fields ) ) {
            throw new MWException( 'Unknown field "' . $field . '" provided' );
        }
 
        if ( $amount == 0 ) {
            return true;
        }
 
        $absoluteAmount = abs( $amount );
        $isNegative = $amount < 0;
 
        $fullField = $this->getPrefixedField( $field );
 
        $dbw = $this->getWriteDbConnection();
 
        $success = $dbw->update(
            $this->getName(),
            array( "$fullField=$fullField" . ( $isNegative ? '-' : '+' ) . $absoluteAmount ),
            $this->getPrefixedValues( $conditions ),
            __METHOD__
        ) !== false; // DatabaseBase::update does not always return true for success as documented...
 
        $this->releaseConnection( $dbw );
 
        return $success;
    }
}