From dc16ea18a78a7f87bf313c6fe2af6a3605e943ec Mon Sep 17 00:00:00 2001 From: jeroendedauw Date: Fri, 25 May 2012 21:34:17 +0200 Subject: [PATCH] Adding interfaces for ORM row and table classes so these can be used for type hinting in a way that does not prevent doing stuff such as the decorator pattern. Also made some minor fixes in the docs Change-Id: I8ee1495a46d676062026d4d6b7acaae7bb227c42 --- includes/AutoLoader.php | 2 + includes/db/IORMRow.php | 273 +++++++++++++++++++++++ includes/db/IORMTable.php | 444 ++++++++++++++++++++++++++++++++++++++ includes/db/ORMResult.php | 13 +- includes/db/ORMRow.php | 42 +--- includes/db/ORMTable.php | 57 +---- 6 files changed, 743 insertions(+), 88 deletions(-) create mode 100644 includes/db/IORMRow.php create mode 100644 includes/db/IORMTable.php diff --git a/includes/AutoLoader.php b/includes/AutoLoader.php index d138aa7f14..889d10e7ef 100644 --- a/includes/AutoLoader.php +++ b/includes/AutoLoader.php @@ -447,6 +447,8 @@ $wgAutoloadLocalClasses = array( 'DBConnectionError' => 'includes/db/DatabaseError.php', 'DBError' => 'includes/db/DatabaseError.php', 'DBObject' => 'includes/db/DatabaseUtility.php', + 'IORMRow' => 'includes/db/IORMRow.php', + 'IORMTable' => 'includes/db/IORMTable.php', 'DBMasterPos' => 'includes/db/DatabaseUtility.php', 'DBQueryError' => 'includes/db/DatabaseError.php', 'DBUnexpectedError' => 'includes/db/DatabaseError.php', diff --git a/includes/db/IORMRow.php b/includes/db/IORMRow.php new file mode 100644 index 0000000000..a5306205e2 --- /dev/null +++ b/includes/db/IORMRow.php @@ -0,0 +1,273 @@ + + */ + +interface IORMRow { + + + /** + * Constructor. + * + * @since 1.20 + * + * @param IORMTable $table + * @param array|null $fields + * @param boolean $loadDefaults + */ + public function __construct( IORMTable $table, $fields = null, $loadDefaults = false ); + + /** + * Load the specified fields from the database. + * + * @since 1.20 + * + * @param array|null $fields + * @param boolean $override + * @param boolean $skipLoaded + * + * @return bool Success indicator + */ + public function loadFields( $fields = null, $override = true, $skipLoaded = false ); + + /** + * Gets the value of a field. + * + * @since 1.20 + * + * @param string $name + * @param mixed $default + * + * @throws MWException + * @return mixed + */ + public function getField( $name, $default = null ); + + /** + * Gets the value of a field but first loads it if not done so already. + * + * @since 1.20 + * + * @param string$name + * + * @return mixed + */ + public function loadAndGetField( $name ); + + /** + * Remove a field. + * + * @since 1.20 + * + * @param string $name + */ + public function removeField( $name ); + + /** + * Returns the objects database id. + * + * @since 1.20 + * + * @return integer|null + */ + public function getId(); + + /** + * Sets the objects database id. + * + * @since 1.20 + * + * @param integer|null $id + */ + public function setId( $id ); + + /** + * Gets if a certain field is set. + * + * @since 1.20 + * + * @param string $name + * + * @return boolean + */ + public function hasField( $name ); + + /** + * Gets if the id field is set. + * + * @since 1.20 + * + * @return boolean + */ + public function hasIdField(); + + /** + * Sets multiple fields. + * + * @since 1.20 + * + * @param array $fields The fields to set + * @param boolean $override Override already set fields with the provided values? + */ + public function setFields( array $fields, $override = true ); + + /** + * Serializes the object to an associative array which + * can then easily be converted into JSON or similar. + * + * @since 1.20 + * + * @param null|array $fields + * @param boolean $incNullId + * + * @return array + */ + public function toArray( $fields = null, $incNullId = false ); + + /** + * Load the default values, via getDefaults. + * + * @since 1.20 + * + * @param boolean $override + */ + public function loadDefaults( $override = true ); + + /** + * Writes the answer to the database, either updating it + * when it already exists, or inserting it when it doesn't. + * + * @since 1.20 + * + * @param string|null $functionName + * + * @return boolean Success indicator + */ + public function save( $functionName = null ); + + /** + * Removes the object from the database. + * + * @since 1.20 + * + * @return boolean Success indicator + */ + public function remove(); + + /** + * Return the names and values of the fields. + * + * @since 1.20 + * + * @return array + */ + public function getFields(); + + /** + * Return the names of the fields. + * + * @since 1.20 + * + * @return array + */ + public function getSetFieldNames(); + + /** + * Sets the value of a field. + * Strings can be provided for other types, + * so this method can be called from unserialization handlers. + * + * @since 1.20 + * + * @param string $name + * @param mixed $value + * + * @throws MWException + */ + public function setField( $name, $value ); + + /** + * Add an amount (can be negative) to the specified field (needs to be numeric). + * TODO: most off this stuff makes more sense in the table class + * + * @since 1.20 + * + * @param string $field + * @param integer $amount + * + * @return boolean Success indicator + */ + public function addToField( $field, $amount ); + + /** + * Return the names of the fields. + * + * @since 1.20 + * + * @return array + */ + public function getFieldNames(); + + /** + * Computes and updates the values of the summary fields. + * + * @since 1.20 + * + * @param array|string|null $summaryFields + */ + public function loadSummaryFields( $summaryFields = null ); + + /** + * Sets the value for the @see $updateSummaries field. + * + * @since 1.20 + * + * @param boolean $update + */ + public function setUpdateSummaries( $update ); + + /** + * Sets the value for the @see $inSummaryMode field. + * + * @since 1.20 + * + * @param boolean $summaryMode + */ + public function setSummaryMode( $summaryMode ); + + /** + * Returns the table this IORMRow is a row in. + * + * @since 1.20 + * + * @return IORMTable + */ + public function getTable(); + +} \ No newline at end of file diff --git a/includes/db/IORMTable.php b/includes/db/IORMTable.php new file mode 100644 index 0000000000..853e8cd253 --- /dev/null +++ b/includes/db/IORMTable.php @@ -0,0 +1,444 @@ + + */ + +interface IORMTable { + + /** + * Returns the name of the database table objects of this type are stored in. + * + * @since 1.20 + * + * @return string + */ + public function getName(); + + /** + * Returns the name of a IORMRow implementing class that + * represents single rows in this table. + * + * @since 1.20 + * + * @return string + */ + public function getRowClass(); + + /** + * Returns an array with the fields and their types this object contains. + * This corresponds directly to the fields in the database, without prefix. + * + * field name => type + * + * Allowed types: + * * id + * * str + * * int + * * float + * * bool + * * array + * * blob + * + * @since 1.20 + * + * @return array + */ + public function getFields(); + + /** + * Returns a list of default field values. + * field name => field value + * + * @since 1.20 + * + * @return array + */ + public function getDefaults(); + + /** + * Returns a list of the summary fields. + * These are fields that cache computed values, such as the amount of linked objects of $type. + * This is relevant as one might not want to do actions such as log changes when these get updated. + * + * @since 1.20 + * + * @return array + */ + public function getSummaryFields(); + + /** + * Selects the the specified fields of the records matching the provided + * conditions and returns them as DBDataObject. Field names get prefixed. + * + * @since 1.20 + * + * @param array|string|null $fields + * @param array $conditions + * @param array $options + * @param string|null $functionName + * + * @return ORMResult + */ + public function select( $fields = null, array $conditions = array(), + array $options = array(), $functionName = null ); + + /** + * Selects the the specified fields of the records matching the provided + * conditions and returns them as DBDataObject. Field names get prefixed. + * + * @since 1.20 + * + * @param array|string|null $fields + * @param array $conditions + * @param array $options + * @param string|null $functionName + * + * @return array of self + */ + public function selectObjects( $fields = null, array $conditions = array(), + array $options = array(), $functionName = null ); + + /** + * Do the actual select. + * + * @since 1.20 + * + * @param null|string|array $fields + * @param array $conditions + * @param array $options + * @param null|string $functionName + * + * @return ResultWrapper + */ + public function rawSelect( $fields = null, array $conditions = array(), + array $options = array(), $functionName = null ); + + /** + * Selects the the specified fields of the records matching the provided + * conditions and returns them as associative arrays. + * Provided field names get prefixed. + * Returned field names will not have a prefix. + * + * When $collapse is true: + * If one field is selected, each item in the result array will be this field. + * If two fields are selected, each item in the result array will have as key + * the first field and as value the second field. + * If more then two fields are selected, each item will be an associative array. + * + * @since 1.20 + * + * @param array|string|null $fields + * @param array $conditions + * @param array $options + * @param boolean $collapse Set to false to always return each result row as associative array. + * @param string|null $functionName + * + * @return array of array + */ + public function selectFields( $fields = null, array $conditions = array(), + array $options = array(), $collapse = true, $functionName = null ); + + /** + * Selects the the specified fields of the first matching record. + * Field names get prefixed. + * + * @since 1.20 + * + * @param array|string|null $fields + * @param array $conditions + * @param array $options + * @param string|null $functionName + * + * @return IORMRow|bool False on failure + */ + public function selectRow( $fields = null, array $conditions = array(), + array $options = array(), $functionName = null ); + + /** + * Selects the the specified fields of the records matching the provided + * conditions. Field names do NOT get prefixed. + * + * @since 1.20 + * + * @param array $fields + * @param array $conditions + * @param array $options + * @param string|null $functionName + * + * @return ResultWrapper + */ + public function rawSelectRow( array $fields, array $conditions = array(), + array $options = array(), $functionName = null ); + + /** + * Selects the the specified fields of the first record matching the provided + * conditions and returns it as an associative array, or false when nothing matches. + * This method makes use of selectFields and expects the same parameters and + * returns the same results (if there are any, if there are none, this method returns false). + * @see IORMTable::selectFields + * + * @since 1.20 + * + * @param array|string|null $fields + * @param array $conditions + * @param array $options + * @param boolean $collapse Set to false to always return each result row as associative array. + * @param string|null $functionName + * + * @return mixed|array|bool False on failure + */ + public function selectFieldsRow( $fields = null, array $conditions = array(), + array $options = array(), $collapse = true, $functionName = null ); + + /** + * Returns if there is at least one record matching the provided conditions. + * Condition field names get prefixed. + * + * @since 1.20 + * + * @param array $conditions + * + * @return boolean + */ + public function has( array $conditions = array() ); + + /** + * Returns the amount of matching records. + * Condition field names get prefixed. + * + * Note that this can be expensive on large tables. + * In such cases you might want to use DatabaseBase::estimateRowCount instead. + * + * @since 1.20 + * + * @param array $conditions + * @param array $options + * + * @return integer + */ + public function count( array $conditions = array(), array $options = array() ); + + /** + * Removes the object from the database. + * + * @since 1.20 + * + * @param array $conditions + * @param string|null $functionName + * + * @return boolean Success indicator + */ + public function delete( array $conditions, $functionName = null ); + + /** + * Get API parameters for the fields supported by this object. + * + * @since 1.20 + * + * @param boolean $requireParams + * @param boolean $setDefaults + * + * @return array + */ + public function getAPIParams( $requireParams = false, $setDefaults = false ); + + /** + * Returns an array with the fields and their descriptions. + * + * field name => field description + * + * @since 1.20 + * + * @return array + */ + public function getFieldDescriptions(); + + /** + * Get the database type used for read operations. + * + * @since 1.20 + * + * @return integer DB_ enum + */ + public function getReadDb(); + + /** + * Set the database type to use for read operations. + * + * @param integer $db + * + * @since 1.20 + */ + public function setReadDb( $db ); + + /** + * Update the records matching the provided conditions by + * setting the fields that are keys in the $values param to + * their corresponding values. + * + * @since 1.20 + * + * @param array $values + * @param array $conditions + * + * @return boolean Success indicator + */ + public function update( array $values, array $conditions = array() ); + + /** + * Computes the values of the summary fields of the objects matching the provided conditions. + * + * @since 1.20 + * + * @param array|string|null $summaryFields + * @param array $conditions + */ + public function updateSummaryFields( $summaryFields = null, array $conditions = array() ); + + /** + * Takes in an associative array with field names as keys and + * their values as value. The field names are prefixed with the + * db field prefix. + * + * @since 1.20 + * + * @param array $values + * + * @return array + */ + public function getPrefixedValues( array $values ); + + /** + * Takes in a field or array of fields and returns an + * array with their prefixed versions, ready for db usage. + * + * @since 1.20 + * + * @param array|string $fields + * + * @return array + */ + public function getPrefixedFields( array $fields ); + + /** + * Takes in a field and returns an it's prefixed version, ready for db usage. + * + * @since 1.20 + * + * @param string|array $field + * + * @return string + */ + public function getPrefixedField( $field ); + + /** + * Takes an array of field names with prefix and returns the unprefixed equivalent. + * + * @since 1.20 + * + * @param array $fieldNames + * + * @return array + */ + public function unprefixFieldNames( array $fieldNames ); + + /** + * Takes a field name with prefix and returns the unprefixed equivalent. + * + * @since 1.20 + * + * @param string $fieldName + * + * @return string + */ + public function unprefixFieldName( $fieldName ); + + /** + * Get an instance of this class. + * + * @since 1.20 + * + * @return IORMTable + */ + public static function singleton(); + + /** + * Get an array with fields from a database result, + * that can be fed directly to the constructor or + * to setFields. + * + * @since 1.20 + * + * @param stdClass $result + * + * @return array + */ + public function getFieldsFromDBResult( stdClass $result ); + + /** + * Get a new instance of the class from a database result. + * + * @since 1.20 + * + * @param stdClass $result + * + * @return IORMRow + */ + public function newFromDBResult( stdClass $result ); + + /** + * Get a new instance of the class from an array. + * + * @since 1.20 + * + * @param array $data + * @param boolean $loadDefaults + * + * @return IORMRow + */ + public function newFromArray( array $data, $loadDefaults = false ); + + /** + * Return the names of the fields. + * + * @since 1.20 + * + * @return array + */ + public function getFieldNames(); + + /** + * Gets if the object can take a certain field. + * + * @since 1.20 + * + * @param string $name + * + * @return boolean + */ + public function canHaveField( $name ); + +} \ No newline at end of file diff --git a/includes/db/ORMResult.php b/includes/db/ORMResult.php index 31e0c191fb..1e6b83dda8 100644 --- a/includes/db/ORMResult.php +++ b/includes/db/ORMResult.php @@ -1,6 +1,6 @@ @@ -38,20 +39,20 @@ class ORMResult implements Iterator { protected $key; /** - * @var ORMRow + * @var IORMRow */ protected $current; /** - * @var ORMTable + * @var IORMTable */ protected $table; /** - * @param ORMTable $table + * @param IORMTable $table * @param ResultWrapper $res */ - public function __construct( ORMTable $table, ResultWrapper $res ) { + public function __construct( IORMTable $table, ResultWrapper $res ) { $this->table = $table; $this->res = $res; $this->key = 0; @@ -84,7 +85,7 @@ class ORMResult implements Iterator { } /** - * @return ORMRow + * @return IORMRow */ public function current() { return $this->current; diff --git a/includes/db/ORMRow.php b/includes/db/ORMRow.php index d3a97dbb15..bebddd60b8 100644 --- a/includes/db/ORMRow.php +++ b/includes/db/ORMRow.php @@ -20,39 +20,16 @@ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * - * These methods are likely candidates for overriding: - * * getDefaults - * * remove - * * insert - * * saveExisting - * * loadSummaryFields - * * getSummaryFields - * - * Main instance methods: - * * getField(s) - * * setField(s) - * * save - * * remove - * - * Main static methods: - * * select - * * update - * * delete - * * count - * * has - * * selectRow - * * selectFields - * * selectFieldsRow - * * @since 1.20 * * @file ORMRow.php + * @ingroup ORM * * @licence GNU GPL v2 or later * @author Jeroen De Dauw < jeroendedauw@gmail.com > */ -abstract class ORMRow { +abstract class ORMRow implements IORMRow { /** * The fields of the object. @@ -95,11 +72,11 @@ abstract class ORMRow { * * @since 1.20 * - * @param ORMTable $table + * @param IORMTable $table * @param array|null $fields * @param boolean $loadDefaults */ - public function __construct( ORMTable $table, $fields = null, $loadDefaults = false ) { + public function __construct( IORMTable $table, $fields = null, $loadDefaults = false ) { $this->table = $table; if ( !is_array( $fields ) ) { @@ -331,7 +308,7 @@ abstract class ORMRow { /** * Load the default values, via getDefaults. * - * @since 1.20 + * @since 1.20 * * @param boolean $override */ @@ -550,6 +527,7 @@ abstract class ORMRow { /** * Add an amount (can be negative) to the specified field (needs to be numeric). + * TODO: most off this stuff makes more sense in the table class * * @since 1.20 * @@ -637,14 +615,14 @@ abstract class ORMRow { * * @since 1.20 * - * @param ORMRow $object + * @param IORMRow $object * @param boolean|array $excludeSummaryFields * When set to true, summary field changes are ignored. * Can also be an array of fields to ignore. * * @return boolean */ - protected function fieldsChanged( ORMRow $object, $excludeSummaryFields = false ) { + protected function fieldsChanged( IORMRow $object, $excludeSummaryFields = false ) { $exclusionFields = array(); if ( $excludeSummaryFields !== false ) { @@ -663,11 +641,11 @@ abstract class ORMRow { } /** - * Returns the table this ORMRow is a row in. + * Returns the table this IORMRow is a row in. * * @since 1.20 * - * @return ORMTable + * @return IORMTable */ public function getTable() { return $this->table; diff --git a/includes/db/ORMTable.php b/includes/db/ORMTable.php index 2f02c6b290..cc84d65d3b 100644 --- a/includes/db/ORMTable.php +++ b/includes/db/ORMTable.php @@ -20,31 +20,13 @@ * @since 1.20 * * @file ORMTable.php + * @ingroup ORM * * @licence GNU GPL v2 or later * @author Jeroen De Dauw < jeroendedauw@gmail.com > */ -abstract class ORMTable { - - /** - * Returns the name of the database table objects of this type are stored in. - * - * @since 1.20 - * - * @return string - */ - public abstract function getName(); - - /** - * Returns the name of a ORMRow deriving class that - * represents single rows in this table. - * - * @since 1.20 - * - * @return string - */ - public abstract function getRowClass(); +abstract class ORMTable implements IORMTable { /** * Gets the db field prefix. @@ -55,26 +37,6 @@ abstract class ORMTable { */ protected abstract function getFieldPrefix(); - /** - * Returns an array with the fields and their types this object contains. - * This corresponds directly to the fields in the database, without prefix. - * - * field name => type - * - * Allowed types: - * * id - * * str - * * int - * * float - * * bool - * * array - * - * @since 1.20 - * - * @return array - */ - public abstract function getFields(); - /** * Cache for instances, used by the singleton method. * @@ -252,7 +214,7 @@ abstract class ORMTable { * @param array $options * @param string|null $functionName * - * @return DBObject|bool False on failure + * @return IORMRow|bool False on failure */ public function selectRow( $fields = null, array $conditions = array(), array $options = array(), $functionName = null ) { @@ -489,7 +451,7 @@ abstract class ORMTable { public function updateSummaryFields( $summaryFields = null, array $conditions = array() ) { $this->setReadDb( DB_MASTER ); - foreach ( $this->select( null, $conditions ) as /* ORMRow */ $item ) { + foreach ( $this->select( null, $conditions ) as /* IORMRow */ $item ) { $item->loadSummaryFields( $summaryFields ); $item->setSummaryMode( true ); $item->save(); @@ -503,11 +465,6 @@ abstract class ORMTable { * their values as value. The field names are prefixed with the * db field prefix. * - * Field names can also be provided as an array with as first element a table name, such as - * $conditions = array( - * array( array( 'tablename', 'fieldname' ), $value ), - * ); - * * @since 1.20 * * @param array $values @@ -599,7 +556,7 @@ abstract class ORMTable { * * @since 1.20 * - * @return ORMTable + * @return IORMTable */ public static function singleton() { $class = function_exists( 'get_called_class' ) ? get_called_class() : self::get_called_class(); @@ -667,7 +624,7 @@ abstract class ORMTable { * * @param stdClass $result * - * @return ORMRow + * @return IORMRow */ public function newFromDBResult( stdClass $result ) { return $this->newFromArray( $this->getFieldsFromDBResult( $result ) ); @@ -681,7 +638,7 @@ abstract class ORMTable { * @param array $data * @param boolean $loadDefaults * - * @return ORMRow + * @return IORMRow */ public function newFromArray( array $data, $loadDefaults = false ) { $class = $this->getRowClass(); -- 2.20.1