Ви не можете вибрати більше 25 тем Теми мають розпочинатися з літери або цифри, можуть містити дефіси (-) і не повинні перевищувати 35 символів.

93 lines
3.9KB

  1. <?php
  2. /**
  3. * @link http://www.yiiframework.com/
  4. * @copyright Copyright (c) 2008 Yii Software LLC
  5. * @license http://www.yiiframework.com/license/
  6. */
  7. namespace yii\base;
  8. /**
  9. * Arrayable is the interface that should be implemented by classes who want to support customizable representation of their instances.
  10. *
  11. * For example, if a class implements Arrayable, by calling [[toArray()]], an instance of this class
  12. * can be turned into an array (including all its embedded objects) which can then be further transformed easily
  13. * into other formats, such as JSON, XML.
  14. *
  15. * The methods [[fields()]] and [[extraFields()]] allow the implementing classes to customize how and which of their data
  16. * should be formatted and put into the result of [[toArray()]].
  17. *
  18. * @author Qiang Xue <qiang.xue@gmail.com>
  19. * @since 2.0
  20. */
  21. interface Arrayable
  22. {
  23. /**
  24. * Returns the list of fields that should be returned by default by [[toArray()]] when no specific fields are specified.
  25. *
  26. * A field is a named element in the returned array by [[toArray()]].
  27. *
  28. * This method should return an array of field names or field definitions.
  29. * If the former, the field name will be treated as an object property name whose value will be used
  30. * as the field value. If the latter, the array key should be the field name while the array value should be
  31. * the corresponding field definition which can be either an object property name or a PHP callable
  32. * returning the corresponding field value. The signature of the callable should be:
  33. *
  34. * ```php
  35. * function ($model, $field) {
  36. * // return field value
  37. * }
  38. * ```
  39. *
  40. * For example, the following code declares four fields:
  41. *
  42. * - `email`: the field name is the same as the property name `email`;
  43. * - `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their
  44. * values are obtained from the `first_name` and `last_name` properties;
  45. * - `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name`
  46. * and `last_name`.
  47. *
  48. * ```php
  49. * return [
  50. * 'email',
  51. * 'firstName' => 'first_name',
  52. * 'lastName' => 'last_name',
  53. * 'fullName' => function ($model) {
  54. * return $model->first_name . ' ' . $model->last_name;
  55. * },
  56. * ];
  57. * ```
  58. *
  59. * @return array the list of field names or field definitions.
  60. * @see toArray()
  61. */
  62. public function fields();
  63. /**
  64. * Returns the list of additional fields that can be returned by [[toArray()]] in addition to those listed in [[fields()]].
  65. *
  66. * This method is similar to [[fields()]] except that the list of fields declared
  67. * by this method are not returned by default by [[toArray()]]. Only when a field in the list
  68. * is explicitly requested, will it be included in the result of [[toArray()]].
  69. *
  70. * @return array the list of expandable field names or field definitions. Please refer
  71. * to [[fields()]] on the format of the return value.
  72. * @see toArray()
  73. * @see fields()
  74. */
  75. public function extraFields();
  76. /**
  77. * Converts the object into an array.
  78. *
  79. * @param array $fields the fields that the output array should contain. Fields not specified
  80. * in [[fields()]] will be ignored. If this parameter is empty, all fields as specified in [[fields()]] will be returned.
  81. * @param array $expand the additional fields that the output array should contain.
  82. * Fields not specified in [[extraFields()]] will be ignored. If this parameter is empty, no extra fields
  83. * will be returned.
  84. * @param boolean $recursive whether to recursively return array representation of embedded objects.
  85. * @return array the array representation of the object
  86. */
  87. public function toArray(array $fields = [], array $expand = [], $recursive = true);
  88. }