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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
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
266
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
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
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);
/**
* 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(), findOne()).
* 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);
/**
* Returns a value indicating whether the given set of attributes represents the primary key for this model
* @param array $keys the set of attributes to check
* @return boolean whether the given set of attributes represents the primary key for this model
*/
public static function isPrimaryKey($keys);
/**
* Creates an [[ActiveQueryInterface|ActiveQuery]] instance for query purpose.
*
* 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,
*
* ```php
* // 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();
* ```
*
* This method is also called by [[BaseActiveRecord::hasOne()]] and [[BaseActiveRecord::hasMany()]] to
* create a relational query.
*
* You may override this method to return a customized query. For example,
*
* ```php
* class Customer extends ActiveRecord
* {
* public static function find()
* {
* // use CustomerQuery instead of the default ActiveQuery
* return new CustomerQuery(get_called_class());
* }
* }
* ```
*
* 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();
*
* @return static|ActiveQueryInterface the newly created [[ActiveQueryInterface|ActiveQuery]] instance.
*/
public static function find();
/**
* Returns a single active record model instance by a primary key or an array of column values.
*
* The method accepts:
*
* - a scalar value (integer or string): query by a single primary key value and return the
* 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).
*
* Note that this method will automatically call the `one()` method and return an
* [[ActiveRecordInterface|ActiveRecord]] instance. For example,
*
* ```php
* // find a single customer whose primary key value is 10
* $customer = Customer::findOne(10);
*
* // the above code is equivalent to:
* $customer = Customer::find()->where(['id' => 10])->one();
*
* // find the first customer whose age is 30 and whose status is 1
* $customer = Customer::findOne(['age' => 30, 'status' => 1]);
*
* // the above code is equivalent to:
* $customer = Customer::find()->where(['age' => 30, 'status' => 1])->one();
* ```
*
* @param mixed $condition primary key value or a set of column values
* @return static ActiveRecord instance matching the condition, or null if nothing matches.
*/
public static function findOne($condition);
/**
* Returns a list of active record models that match the specified primary key value(s) or a set of column values.
*
* The method accepts:
*
* - 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).
*
* Note that this method will automatically call the `all()` method and return an array of
* [[ActiveRecordInterface|ActiveRecord]] instances. For example,
*
* ```php
* // 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();
*
* // find the customers whose primary key value is 10, 11 or 12.
* $customers = Customer::findAll([10, 11, 12]);
*
* // 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
* $customers = Customer::findAll(['age' => 30, 'status' => 1]);
*
* // 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.
*/
public static function findAll($condition);
/**
* 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 [[getIsNewRecord()|isNewRecord]] is true, or [[update()]]
* when [[getIsNewRecord()|isNewRecord]] is false.
*
* For example, to save a customer record:
*
* ~~~
* $customer = new Customer; // or $customer = Customer::findOne($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 $attributeNames 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, $attributeNames = 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::findOne($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 $attributeNames 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, $attributeNames = 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 [[getIsNewRecord()|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);
/**
* 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.
* @param string $name the relation name
* @param boolean $throwException whether to throw exception if the relation does not exist.
* @return ActiveQueryInterface the relational query object
*/
public function getRelation($name, $throwException = true);
/**
* 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 `[[ActiveQueryInterface::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);
/**
* Returns the connection used by this AR class.
* @return mixed the database connection used by this AR class.
*/
public static function getDb();
}