* Arrayable is the interface that should be implemented by classes who want to support customizable representation of their instances. * * For example, if a class implements Arrayable, by calling [[toArray()]], an instance of this class * can be turned into an array (including all its embedded objects) which can then be further transformed easily * into other formats, such as JSON, XML. * *
| 21 | * @since 2.0 |
| 22 | */ |
| 23 | interface Arrayable |
| 24 | { |
| 25 | /** |
| 26 | * Returns the list of fields that should be returned by default by [[toArray()]] when no specific fields are specified. |
| 27 | * |
| 28 | * A field is a named element in the returned array by [[toArray()]]. |
| 29 | * |
| 30 | * This method should return an array of field names or field definitions. |
| 31 | * If the former, the field name will be treated as an object property name whose value will be used |
| 32 | * as the field value. If the latter, the array key should be the field name while the array value should be |
| 33 | * the corresponding field definition which can be either an object property name or a PHP callable |
| 34 | * returning the corresponding field value. The signature of the callable should be: |
| 35 | * |
| 36 | * ```php |
| 37 | * function ($model, $field) { |
| 38 | * // return field value |
| 39 | * } |
| 40 | * ``` |
| 41 | * |
| 42 | * For example, the following code declares four fields: |
| 43 | * |
| 44 | * - `email`: the field name is the same as the property name `email`; |
| 45 | * - `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their |
| 46 | * values are obtained from the `first_name` and `last_name` properties; |
| 47 | * - `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name` |
| 48 | * and `last_name`. |
| 49 | * |
| 50 | * ```php |
| 51 | * return [ |
| 52 | * 'email', |
| 53 | * 'firstName' => 'first_name', |
| 54 | * 'lastName' => 'last_name', |
| 55 | * 'fullName' => function ($model) { |
| 56 | * return $model->first_name . ' ' . $model->last_name; |
| 57 | * }, |
| 58 | * ]; |
| 59 | * ``` |
| 60 | * |
| 61 | * @return array the list of field names or field definitions. |
| 62 | * @see toArray() |
| 63 | */ |
| 64 | public function fields(); |
| 65 | |
| 66 | /** |
| 67 | * Returns the list of additional fields that can be returned by [[toArray()]] in addition to those listed in [[fields()]]. |
| 68 | * |
| 69 | * This method is similar to [[fields()]] except that the list of fields declared |
| 70 | * by this method are not returned by default by [[toArray()]]. Only when a field in the list |
| 71 | * is explicitly requested, will it be included in the result of [[toArray()]]. |
| 72 | * |
| 73 | * @return array the list of expandable field names or field definitions. Please refer |
| 74 | * to [[fields()]] on the format of the return value. |
| 75 | * @see toArray() |
| 76 | * @see fields() |
| 77 | */ |
| 78 | public function extraFields(); |
| 79 | |
| 80 | /** |