ActiveRecordInterface.php 12.2 KB
Newer Older
Carsten Brandt committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
<?php
/**
 * 
 * 
 * @author Carsten Brandt <mail@cebe.cc>
 */

namespace yii\db;

/**
 * ActiveRecordInterface
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @author Carsten Brandt <mail@cebe.cc>
 * @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);

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
	/**
	 * Returns the old primary key value(s).
	 * This refers to the primary key value that is populated into the record
	 * after executing a find method (e.g. find(), findAll()).
	 * The value remains unchanged even if the primary key attribute is manually assigned with a different value.
	 * @param boolean $asArray whether to return the primary key value as an array. If true,
	 * the return value will be an array with column name as key and column value as value.
	 * If this is false (default), a scalar value will be returned for non-composite primary key.
	 * @property mixed The old primary key value. An array (column name => column value) is
	 * returned if the primary key is composite. A string is returned otherwise (null will be
	 * returned if the key value is null).
	 * @return mixed the old primary key value. An array (column name => column 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 getOldPrimaryKey($asArray = false);

Carsten Brandt committed
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
	/**
	 * 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);

112 113
	/**
	 * Creates an [[ActiveQueryInterface|ActiveQuery]] instance.
114
	 *
115 116 117
	 * This method is called by [[find()]] to start a SELECT query.
	 * You may override this method to return a customized query (e.g. `CustomerQuery` specified
	 * written for querying `Customer` purpose.)
118 119 120 121 122 123 124 125 126 127 128 129 130
	 *
	 * You may also define default conditions that should apply to all queries unless overridden:
	 *
	 * ```php
	 * public static function createQuery()
	 * {
	 *     return parent::createQuery()->where(['deleted' => false]);
	 * }
	 * ```
	 *
	 * Note that all queries should use [[Query::andWhere()]] and [[Query::orWhere()]] to keep the
	 * default condition. Using [[Query::where()]] will override the default condition.
	 *
131 132 133 134
	 * @return ActiveQueryInterface the newly created [[ActiveQueryInterface|ActiveQuery]] instance.
	 */
	public static function createQuery();

Carsten Brandt committed
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265
	/**
	 * 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.
	 */
266
	public static function createRelation($config = []);
Carsten Brandt committed
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309

	/**
	 * 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);
310
}