Du kan inte välja fler än 25 ämnen Ämnen måste starta med en bokstav eller siffra, kan innehålla bindestreck ('-') och vara max 35 tecken långa.

168 lines
6.4KB

  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. use Yii;
  9. use yii\helpers\ArrayHelper;
  10. use yii\web\Link;
  11. use yii\web\Linkable;
  12. /**
  13. * ArrayableTrait provides a common implementation of the [[Arrayable]] interface.
  14. *
  15. * ArrayableTrait implements [[toArray()]] by respecting the field definitions as declared
  16. * in [[fields()]] and [[extraFields()]].
  17. *
  18. * @author Qiang Xue <qiang.xue@gmail.com>
  19. * @since 2.0
  20. */
  21. trait ArrayableTrait
  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 () {
  54. * return $this->first_name . ' ' . $this->last_name;
  55. * },
  56. * ];
  57. * ```
  58. *
  59. * In this method, you may also want to return different lists of fields based on some context
  60. * information. For example, depending on the privilege of the current application user,
  61. * you may return different sets of visible fields or filter out some fields.
  62. *
  63. * The default implementation of this method returns the public object member variables indexed by themselves.
  64. *
  65. * @return array the list of field names or field definitions.
  66. * @see toArray()
  67. */
  68. public function fields()
  69. {
  70. $fields = array_keys(Yii::getObjectVars($this));
  71. return array_combine($fields, $fields);
  72. }
  73. /**
  74. * Returns the list of fields that can be expanded further and returned by [[toArray()]].
  75. *
  76. * This method is similar to [[fields()]] except that the list of fields returned
  77. * by this method are not returned by default by [[toArray()]]. Only when field names
  78. * to be expanded are explicitly specified when calling [[toArray()]], will their values
  79. * be exported.
  80. *
  81. * The default implementation returns an empty array.
  82. *
  83. * You may override this method to return a list of expandable fields based on some context information
  84. * (e.g. the current application user).
  85. *
  86. * @return array the list of expandable field names or field definitions. Please refer
  87. * to [[fields()]] on the format of the return value.
  88. * @see toArray()
  89. * @see fields()
  90. */
  91. public function extraFields()
  92. {
  93. return [];
  94. }
  95. /**
  96. * Converts the model into an array.
  97. *
  98. * This method will first identify which fields to be included in the resulting array by calling [[resolveFields()]].
  99. * It will then turn the model into an array with these fields. If `$recursive` is true,
  100. * any embedded objects will also be converted into arrays.
  101. *
  102. * If the model implements the [[Linkable]] interface, the resulting array will also have a `_link` element
  103. * which refers to a list of links as specified by the interface.
  104. *
  105. * @param array $fields the fields being requested. If empty, all fields as specified by [[fields()]] will be returned.
  106. * @param array $expand the additional fields being requested for exporting. Only fields declared in [[extraFields()]]
  107. * will be considered.
  108. * @param boolean $recursive whether to recursively return array representation of embedded objects.
  109. * @return array the array representation of the object
  110. */
  111. public function toArray(array $fields = [], array $expand = [], $recursive = true)
  112. {
  113. $data = [];
  114. foreach ($this->resolveFields($fields, $expand) as $field => $definition) {
  115. $data[$field] = is_string($definition) ? $this->$definition : call_user_func($definition, $this, $field);
  116. }
  117. if ($this instanceof Linkable) {
  118. $data['_links'] = Link::serialize($this->getLinks());
  119. }
  120. return $recursive ? ArrayHelper::toArray($data) : $data;
  121. }
  122. /**
  123. * Determines which fields can be returned by [[toArray()]].
  124. * This method will check the requested fields against those declared in [[fields()]] and [[extraFields()]]
  125. * to determine which fields can be returned.
  126. * @param array $fields the fields being requested for exporting
  127. * @param array $expand the additional fields being requested for exporting
  128. * @return array the list of fields to be exported. The array keys are the field names, and the array values
  129. * are the corresponding object property names or PHP callables returning the field values.
  130. */
  131. protected function resolveFields(array $fields, array $expand)
  132. {
  133. $result = [];
  134. foreach ($this->fields() as $field => $definition) {
  135. if (is_int($field)) {
  136. $field = $definition;
  137. }
  138. if (empty($fields) || in_array($field, $fields, true)) {
  139. $result[$field] = $definition;
  140. }
  141. }
  142. if (empty($expand)) {
  143. return $result;
  144. }
  145. foreach ($this->extraFields() as $field => $definition) {
  146. if (is_int($field)) {
  147. $field = $definition;
  148. }
  149. if (in_array($field, $expand, true)) {
  150. $result[$field] = $definition;
  151. }
  152. }
  153. return $result;
  154. }
  155. }