ActiveRecordInterface.php 16.5 KB
Newer Older
Carsten Brandt committed
1 2
<?php
/**
Carsten Brandt committed
3 4 5
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
Carsten Brandt committed
6 7 8 9 10 11 12 13 14 15 16 17 18
 */

namespace yii\db;

/**
 * ActiveRecordInterface
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @author Carsten Brandt <mail@cebe.cc>
 * @since 2.0
 */
interface ActiveRecordInterface
{
19 20 21 22 23 24 25 26 27 28
    /**
     * 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();
Carsten Brandt committed
29

30 31 32 33 34
    /**
     * Returns the list of all attribute names of the record.
     * @return array list of attribute names.
     */
    public function attributes();
Carsten Brandt committed
35

36 37 38 39
    /**
     * Returns the named attribute value.
     * If this record is the result of a query and the attribute is not loaded,
     * null will be returned.
40 41
     * @param string $name the attribute name
     * @return mixed the attribute value. Null if the attribute is not set or does not exist.
42 43 44
     * @see hasAttribute()
     */
    public function getAttribute($name);
Carsten Brandt committed
45

46 47
    /**
     * Sets the named attribute value.
48 49
     * @param string $name the attribute name.
     * @param mixed $value the attribute value.
50 51 52
     * @see hasAttribute()
     */
    public function setAttribute($name, $value);
Carsten Brandt committed
53

54 55
    /**
     * Returns a value indicating whether the record has an attribute with the specified name.
56
     * @param string $name the name of the attribute
57 58 59
     * @return boolean whether the record has an attribute with the specified name.
     */
    public function hasAttribute($name);
Carsten Brandt committed
60

61 62
    /**
     * Returns the primary key value(s).
63 64 65 66 67 68
     * @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).
69 70
     */
    public function getPrimaryKey($asArray = false);
Carsten Brandt committed
71

72 73 74
    /**
     * Returns the old primary key value(s).
     * This refers to the primary key value that is populated into the record
Alexander Makarov committed
75
     * after executing a find method (e.g. find(), findOne()).
76
     * The value remains unchanged even if the primary key attribute is manually assigned with a different value.
77 78 79
     * @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.
80
     * @property mixed The old primary key value. An array (column name => column value) is
81 82 83 84 85
     * 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).
86 87
     */
    public function getOldPrimaryKey($asArray = false);
88

89 90
    /**
     * Returns a value indicating whether the given set of attributes represents the primary key for this model
91
     * @param array $keys the set of attributes to check
92 93 94
     * @return boolean whether the given set of attributes represents the primary key for this model
     */
    public static function isPrimaryKey($keys);
95

96 97 98
    /**
     * Creates an [[ActiveQueryInterface|ActiveQuery]] instance for query purpose.
     *
99 100 101
     * The returned [[ActiveQueryInterface|ActiveQuery]] instance can be further customized by calling
     * methods defined in [[ActiveQueryInterface]] before `one()` or `all()` is called to return
     * populated ActiveRecord instances. For example,
102 103
     *
     * ```php
104 105 106 107 108 109 110 111
     * // find the customer whose ID is 1
     * $customer = Customer::find()->where(['id' => 1])->one();
     *
     * // find all active customers and order them by their age:
     * $customers = Customer::find()
     *     ->where(['status' => 1])
     *     ->orderBy('age')
     *     ->all();
112 113
     * ```
     *
Alexander Makarov committed
114 115 116
     * This method is also called by [[BaseActiveRecord::hasOne()]] and [[BaseActiveRecord::hasMany()]] to
     * create a relational query.
     *
117
     * You may override this method to return a customized query. For example,
Alexander Makarov committed
118 119
     *
     * ```php
120
     * class Customer extends ActiveRecord
Alexander Makarov committed
121
     * {
122 123 124 125 126
     *     public static function find()
     *     {
     *         // use CustomerQuery instead of the default ActiveQuery
     *         return new CustomerQuery(get_called_class());
     *     }
Alexander Makarov committed
127 128 129
     * }
     * ```
     *
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
     * The following code shows how to apply a default condition for all queries:
     *
     * ```php
     * class Customer extends ActiveRecord
     * {
     *     public static function find()
     *     {
     *         return parent::find()->where(['deleted' => false]);
     *     }
     * }
     *
     * // Use andWhere()/orWhere() to apply the default condition
     * // SELECT FROM customer WHERE `deleted`=:deleted AND age>30
     * $customers = Customer::find()->andWhere('age>30')->all();
     *
     * // Use where() to ignore the default condition
     * // SELECT FROM customer WHERE age>30
     * $customers = Customer::find()->where('age>30')->all();
Alexander Makarov committed
148 149 150 151 152 153
     *
     * @return ActiveQueryInterface the newly created [[ActiveQueryInterface|ActiveQuery]] instance.
     */
    public static function find();

    /**
154
     * Returns a single active record model instance by a primary key or an array of column values.
Alexander Makarov committed
155 156
     *
     * The method accepts:
157 158
     *
     *  - a scalar value (integer or string): query by a single primary key value and return the
159 160 161 162
     *    corresponding record (or null if not found).
     *  - an array of name-value pairs: query by a set of attribute values and return a single record
     *    matching all of them (or null if not found).
     *
163
     * Note that this method will automatically call the `one()` method and return an
164 165 166 167
     * [[ActiveRecordInterface|ActiveRecord]] instance. For example,
     *
     * ```php
     * // find a single customer whose primary key value is 10
Alexander Makarov committed
168
     * $customer = Customer::findOne(10);
169 170 171 172
     *
     * // the above code is equivalent to:
     * $customer = Customer::find()->where(['id' => 10])->one();
     *
173
     * // find the first customer whose age is 30 and whose status is 1
Alexander Makarov committed
174
     * $customer = Customer::findOne(['age' => 30, 'status' => 1]);
175 176 177 178
     *
     * // the above code is equivalent to:
     * $customer = Customer::find()->where(['age' => 30, 'status' => 1])->one();
     * ```
179
     *
Alexander Makarov committed
180
     * @param mixed $condition primary key value or a set of column values
181
     * @return static ActiveRecord instance matching the condition, or null if nothing matches.
182
     */
Alexander Makarov committed
183
    public static function findOne($condition);
Carsten Brandt committed
184

185
    /**
186
     * Returns a list of active record models that match the specified primary key value(s) or a set of column values.
187
     *
188
     * The method accepts:
189
     *
190 191 192 193 194 195 196 197
     *  - a scalar value (integer or string): query by a single primary key value and return an array containing the
     *    corresponding record (or an empty array if not found).
     *  - an array of scalar values (integer or string): query by a list of primary key values and return the
     *    corresponding records (or an empty array if none was found).
     *    Note that an empty condition will result in an empty result as it will be interpreted as a search for
     *    primary keys and not an empty `WHERE` condition.
     *  - an array of name-value pairs: query by a set of attribute values and return an array of records
     *    matching all of them (or an empty array if none was found).
198
     *
199 200
     * Note that this method will automatically call the `all()` method and return an array of
     * [[ActiveRecordInterface|ActiveRecord]] instances. For example,
201 202
     *
     * ```php
203 204 205 206 207
     * // find the customers whose primary key value is 10
     * $customers = Customer::findAll(10);
     *
     * // the above code is equivalent to:
     * $customers = Customer::find()->where(['id' => 10])->all();
208
     *
209 210
     * // find the customers whose primary key value is 10, 11 or 12.
     * $customers = Customer::findAll([10, 11, 12]);
211
     *
212 213 214 215
     * // the above code is equivalent to:
     * $customers = Customer::find()->where(['id' => [10, 11, 12]])->all();
     *
     * // find customers whose age is 30 and whose status is 1
216
     * $customers = Customer::findAll(['age' => 30, 'status' => 1]);
217 218 219 220 221 222 223
     *
     * // the above code is equivalent to:
     * $customers = Customer::find()->where(['age' => 30, 'status' => 1])->all();
     * ```
     *
     * @param mixed $condition primary key value or a set of column values
     * @return array an array of ActiveRecord instance, or an empty array if nothing matches.
224
     */
225
    public static function findAll($condition);
226

227 228 229 230 231 232 233 234
    /**
     * 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']);
     * ~~~
     *
235 236 237 238 239
     * @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.
240 241 242
     * @return integer the number of rows updated
     */
    public static function updateAll($attributes, $condition = null);
Carsten Brandt committed
243

244 245 246 247 248 249 250 251 252 253
    /**
     * 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]);
     * ~~~
     *
254 255 256
     * @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.
257 258 259
     * @return integer the number of rows deleted
     */
    public static function deleteAll($condition = null);
Carsten Brandt committed
260

261 262 263
    /**
     * Saves the current record.
     *
264 265
     * This method will call [[insert()]] when [[getIsNewRecord()|isNewRecord]] is true, or [[update()]]
     * when [[getIsNewRecord()|isNewRecord]] is false.
266 267 268 269
     *
     * For example, to save a customer record:
     *
     * ~~~
270
     * $customer = new Customer; // or $customer = Customer::findOne($id);
271 272 273 274 275
     * $customer->name = $name;
     * $customer->email = $email;
     * $customer->save();
     * ~~~
     *
276 277 278
     * @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.
279
     * @param array $attributeNames list of attributes that need to be saved. Defaults to null,
280
     * meaning all attributes that are loaded from DB will be saved.
281 282
     * @return boolean whether the saving succeeds
     */
283
    public function save($runValidation = true, $attributeNames = null);
Carsten Brandt committed
284

285 286 287 288 289 290 291 292 293 294 295 296
    /**
     * 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();
     * ```
     *
297 298 299 300
     * @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.
301 302 303
     * @return boolean whether the attributes are valid and the record is inserted successfully.
     */
    public function insert($runValidation = true, $attributes = null);
Carsten Brandt committed
304

305 306 307 308 309 310
    /**
     * Saves the changes to this active record into the database.
     *
     * Usage example:
     *
     * ```php
311
     * $customer = Customer::findOne($id);
312 313 314 315 316
     * $customer->name = $name;
     * $customer->email = $email;
     * $customer->update();
     * ```
     *
317 318
     * @param boolean $runValidation whether to perform validation before saving the record.
     * If the validation fails, the record will not be inserted into the database.
319
     * @param array $attributeNames list of attributes that need to be saved. Defaults to null,
320
     * meaning all attributes that are loaded from DB will be saved.
321
     * @return integer|boolean the number of rows affected, or false if validation fails
322 323 324
     * 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.
325
     */
326
    public function update($runValidation = true, $attributeNames = null);
Carsten Brandt committed
327

328 329 330 331
    /**
     * Deletes the record from the database.
     *
     * @return integer|boolean the number of rows deleted, or false if the deletion is unsuccessful for some reason.
332
     * Note that it is possible that the number of rows deleted is 0, even though the deletion execution is successful.
333 334
     */
    public function delete();
Carsten Brandt committed
335

336 337 338 339 340
    /**
     * 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();
Carsten Brandt committed
341

342 343
    /**
     * Returns a value indicating whether the given active record is the same as the current one.
344
     * Two [[getIsNewRecord()|new]] records are considered to be not equal.
345
     * @param static $record record to compare to
346 347 348
     * @return boolean whether the two active records refer to the same row in the same database table.
     */
    public function equals($record);
Carsten Brandt committed
349

350 351 352 353 354
    /**
     * Returns the relation object with the specified name.
     * A relation is defined by a getter method which returns an object implementing the [[ActiveQueryInterface]]
     * (normally this would be a relational [[ActiveQuery]] object).
     * It can be declared in either the ActiveRecord class itself or one of its behaviors.
355 356
     * @param string $name the relation name
     * @param boolean $throwException whether to throw exception if the relation does not exist.
357 358 359
     * @return ActiveQueryInterface the relational query object
     */
    public function getRelation($name, $throwException = true);
Carsten Brandt committed
360

361 362 363 364 365 366 367 368 369 370 371 372
    /**
     * 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.
     *
373 374 375 376 377
     * @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 `[[ActiveQueryInterface::via()]]`.)
378 379
     */
    public function link($name, $model, $extraColumns = []);
Carsten Brandt committed
380

381 382 383 384 385 386
    /**
     * 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.
     *
387 388
     * @param string $name the case sensitive name of the relationship.
     * @param static $model the model to be unlinked from the current one.
389
     * @param boolean $delete whether to delete the model that contains the foreign key.
390 391
     * If false, the model's foreign key will be set null and saved.
     * If true, the model containing the foreign key will be deleted.
392 393
     */
    public function unlink($name, $model, $delete = false);
394
}