From 9238434db728c13a04cf9885ef3da7e0228f4af7 Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Fri, 29 Nov 2013 15:41:14 +0100 Subject: [PATCH] ActiveRecord Interface --- framework/yii/db/ActiveRecordInterface.php | 270 +++++++++++++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 framework/yii/db/ActiveRecordInterface.php diff --git a/framework/yii/db/ActiveRecordInterface.php b/framework/yii/db/ActiveRecordInterface.php new file mode 100644 index 0000000..0349b78 --- /dev/null +++ b/framework/yii/db/ActiveRecordInterface.php @@ -0,0 +1,270 @@ + + */ + +namespace yii\db; + +/** + * ActiveRecordInterface + * + * @author Qiang Xue + * @author Carsten Brandt + * @since 2.0 + */ +interface ActiveRecordInterface +{ + /** + * Returns the primary key **name(s)** for this AR class. + * + * Note that an array should be returned even when the record only has a single primary key. + * + * For the primary key **value** see [[getPrimaryKey()]] instead. + * + * @return string[] the primary key name(s) for this AR class. + */ + public static function primaryKey(); + + /** + * Returns the list of all attribute names of the record. + * @return array list of attribute names. + */ + public function attributes(); + + /** + * Returns the named attribute value. + * If this record is the result of a query and the attribute is not loaded, + * null will be returned. + * @param string $name the attribute name + * @return mixed the attribute value. Null if the attribute is not set or does not exist. + * @see hasAttribute() + */ + public function getAttribute($name); + + /** + * Sets the named attribute value. + * @param string $name the attribute name. + * @param mixed $value the attribute value. + * @see hasAttribute() + */ + public function setAttribute($name, $value); + + /** + * Returns a value indicating whether the record has an attribute with the specified name. + * @param string $name the name of the attribute + * @return boolean whether the record has an attribute with the specified name. + */ + public function hasAttribute($name); + + /** + * Returns the primary key value(s). + * @param boolean $asArray whether to return the primary key value as an array. If true, + * the return value will be an array with attribute names as keys and attribute values as values. + * Note that for composite primary keys, an array will always be returned regardless of this parameter value. + * @return mixed the primary key value. An array (attribute name => attribute value) is returned if the primary key + * is composite or `$asArray` is true. A string is returned otherwise (null will be returned if + * the key value is null). + */ + public function getPrimaryKey($asArray = false); + + /** + * Creates an [[ActiveQueryInterface|ActiveQuery]] instance for query purpose. + * + * This method is usually ment to be used like this: + * + * ```php + * Customer::find(1); // find one customer by primary key + * Customer::find()->all(); // find all customers + * ``` + * + * @param mixed $q the query parameter. This can be one of the followings: + * + * - a scalar value (integer or string): query by a single primary key value and return the + * corresponding record. + * - an array of name-value pairs: query by a set of attribute values and return a single record matching all of them. + * - null (not specified): return a new [[ActiveQuery]] object for further query purpose. + * + * @return ActiveQueryInterface|static|null When `$q` is null, a new [[ActiveQuery]] instance + * is returned; when `$q` is a scalar or an array, an ActiveRecord object matching it will be + * returned (null will be returned if there is no matching). + */ + public static function find($q = null); + + /** + * Updates records using the provided attribute values and conditions. + * For example, to change the status to be 1 for all customers whose status is 2: + * + * ~~~ + * Customer::updateAll(['status' => 1], ['status' => '2']); + * ~~~ + * + * @param array $attributes attribute values (name-value pairs) to be saved for the record. + * Unlike [[update()]] these are not going to be validated. + * @param array $condition the condition that matches the records that should get updated. + * Please refer to [[QueryInterface::where()]] on how to specify this parameter. + * An empty condition will match all records. + * @return integer the number of rows updated + */ + public static function updateAll($attributes, $condition = null); + + /** + * Deletes records using the provided conditions. + * WARNING: If you do not specify any condition, this method will delete ALL rows in the table. + * + * For example, to delete all customers whose status is 3: + * + * ~~~ + * Customer::deleteAll([status = 3]); + * ~~~ + * + * @param array $condition the condition that matches the records that should get deleted. + * Please refer to [[QueryInterface::where()]] on how to specify this parameter. + * An empty condition will match all records. + * @return integer the number of rows deleted + */ + public static function deleteAll($condition = null); + + /** + * Saves the current record. + * + * This method will call [[insert()]] when [[isNewRecord]] is true, or [[update()]] + * when [[isNewRecord]] is false. + * + * For example, to save a customer record: + * + * ~~~ + * $customer = new Customer; // or $customer = Customer::find($id); + * $customer->name = $name; + * $customer->email = $email; + * $customer->save(); + * ~~~ + * + * @param boolean $runValidation whether to perform validation before saving the record. + * If the validation fails, the record will not be saved to database. `false` will be returned + * in this case. + * @param array $attributes list of attributes that need to be saved. Defaults to null, + * meaning all attributes that are loaded from DB will be saved. + * @return boolean whether the saving succeeds + */ + public function save($runValidation = true, $attributes = null); + + /** + * Inserts the record into the database using the attribute values of this record. + * + * Usage example: + * + * ```php + * $customer = new Customer; + * $customer->name = $name; + * $customer->email = $email; + * $customer->insert(); + * ``` + * + * @param boolean $runValidation whether to perform validation before saving the record. + * If the validation fails, the record will not be inserted into the database. + * @param array $attributes list of attributes that need to be saved. Defaults to null, + * meaning all attributes that are loaded from DB will be saved. + * @return boolean whether the attributes are valid and the record is inserted successfully. + */ + public function insert($runValidation = true, $attributes = null); + + /** + * Saves the changes to this active record into the database. + * + * Usage example: + * + * ```php + * $customer = Customer::find($id); + * $customer->name = $name; + * $customer->email = $email; + * $customer->update(); + * ``` + * + * @param boolean $runValidation whether to perform validation before saving the record. + * If the validation fails, the record will not be inserted into the database. + * @param array $attributes list of attributes that need to be saved. Defaults to null, + * meaning all attributes that are loaded from DB will be saved. + * @return integer|boolean the number of rows affected, or false if validation fails + * or updating process is stopped for other reasons. + * Note that it is possible that the number of rows affected is 0, even though the + * update execution is successful. + */ + public function update($runValidation = true, $attributes = null); + + /** + * Deletes the record from the database. + * + * @return integer|boolean the number of rows deleted, or false if the deletion is unsuccessful for some reason. + * Note that it is possible that the number of rows deleted is 0, even though the deletion execution is successful. + */ + public function delete(); + + /** + * Returns a value indicating whether the current record is new (not saved in the database). + * @return boolean whether the record is new and should be inserted when calling [[save()]]. + */ + public function getIsNewRecord(); + + /** + * Returns a value indicating whether the given active record is the same as the current one. + * Two [[isNewRecord|new]] records are considered to be not equal. + * @param static $record record to compare to + * @return boolean whether the two active records refer to the same row in the same database table. + */ + public function equals($record); + + /** + * Creates an [[ActiveRelationInterface|ActiveRelation]] instance. + * This method is called by [[BaseActiveRecord::hasOne()]] and [[BaseActiveRecord::hasMany()]] to + * create a relation instance. + * You may override this method to return a customized relation. + * @param array $config the configuration passed to the ActiveRelation class. + * @return ActiveRelation the newly created [[ActiveRelation]] instance. + */ + public static function createActiveRelation($config = []); + + /** + * Returns the relation object with the specified name. + * A relation is defined by a getter method which returns an [[ActiveRelationInterface|ActiveRelation]] object. + * It can be declared in either the ActiveRecord class itself or one of its behaviors. + * @param string $name the relation name + * @return ActiveRelation the relation object + */ + public function getRelation($name); + + /** + * Establishes the relationship between two records. + * + * The relationship is established by setting the foreign key value(s) in one record + * to be the corresponding primary key value(s) in the other record. + * The record with the foreign key will be saved into database without performing validation. + * + * If the relationship involves a pivot table, a new row will be inserted into the + * pivot table which contains the primary key values from both records. + * + * This method requires that the primary key value is not null. + * + * @param string $name the case sensitive name of the relationship. + * @param static $model the record to be linked with the current one. + * @param array $extraColumns additional column values to be saved into the pivot table. + * This parameter is only meaningful for a relationship involving a pivot table + * (i.e., a relation set with `[[ActiveRelationInterface::via()]]`.) + */ + public function link($name, $model, $extraColumns = []); + + /** + * Destroys the relationship between two records. + * + * The record with the foreign key of the relationship will be deleted if `$delete` is true. + * Otherwise, the foreign key will be set null and the record will be saved without validation. + * + * @param string $name the case sensitive name of the relationship. + * @param static $model the model to be unlinked from the current one. + * @param boolean $delete whether to delete the model that contains the foreign key. + * If false, the model's foreign key will be set null and saved. + * If true, the model containing the foreign key will be deleted. + */ + public function unlink($name, $model, $delete = false); +} \ No newline at end of file