```php
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\base;
use Yii;
use yii\helpers\ArrayHelper;
use yii\web\Link;
use yii\web\Linkable;
/**
* ArrayableTrait provides a common implementation of the [[Arrayable]] interface.
* ArrableTrait是[[Arrayable]]的一个实现
*
* ArrayableTrait implements [[toArray()]] by respecting the field definitions as declared
* in [[fields()]] and [[extraFields()]].
* ArrayableTrait通过在[[fields()]和[[extraFields()]]中声明的字段来实现[[toArray()]。
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
*/
trait ArrayableTrait
{
/**
* Returns the list of fields that should be returned by default by [[toArray()]] when no specific fields are specified.
* 当在[[toArray()]]中没有指定特明的字段的时候, 默认返回的字段列表
*
* A field is a named element in the returned array by [[toArray()]].
* 字段名作为[[toArray()]]方法返回的数组中的键名。
*
* This method should return an array of field names or field definitions.
* If the former, the field name will be treated as an object property name whose value will be used
* as the field value. If the latter, the array key should be the field name while the array value should be
* the corresponding field definition which can be either an object property name or a PHP callable
* returning the corresponding field value. The signature of the callable should be:
* 这个方法应当返回一个由字段名或者字段名以及他的定义组成的数组
* 如果是前者, 那么当前对象同名属性将作为数组该键名的键值. 如果是后者, 分为两种情况, 如果是字符串, 则对象中同字符串同名的属性
* 作为该键名的键值, 否则的话, 将作为一个回调来执行, 执行的结果作为该键名的键值. 函数的签名如下:
*
* ```php
* function ($model, $field) {
* // return field value
* // 返回字段的值
* }
* ```
*
* For example, the following code declares four fields:
* 举个例子, 下面的代码定义了4个字段:
*
* - `email`: the field name is the same as the property name `email`;
* - `email`: 字段名和和对象的属性名相同
*
* - `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their
* values are obtained from the `first_name` and `last_name` properties;
* - `firstName` and `lastName`: 数组的键名是`firstName`和`lastName`, 他们的键值分别从当前对象的属性`first_name`和`last_name`中获取
*
* - `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name`
* and `last_name`.
* - `fullName`: 数组的键名是`fullName`, 他的值从`first_name`以及`last_name`中获取
*
* ```php
* return [
* 'email',
* 'firstName' => 'first_name',
* 'lastName' => 'last_name',
* 'fullName' => function () {
* return $this->first_name . ' ' . $this->last_name;
* },
* ];
* ```
*
* In this method, you may also want to return different lists of fields based on some context
* information. For example, depending on the privilege of the current application user,
* you may return different sets of visible fields or filter out some fields.
* 在这个方法中, 你也可以基于当前的上下文返回不同的字段列表.
* 举个例子, 你可以依据当前应用的用户权限, 返回不同的可见字段或者过滤掉某些字段
*
* The default implementation of this method returns the public object member variables indexed by themselves.
* 这个方法的默认实现, 是返回自己公共成员变量
*
* @return array the list of field names or field definitions.
* @return array 一个字段集合或者是字段的定义
*
* @see toArray()
*/
public function fields()
{
// 这里是方法的默认实现
// 1. 通过Yii::getObjectVars($this)获取当前对象的所有公共成员
// 2. 取出这些成员数组的所有的属性名
$fields = array_keys(Yii::getObjectVars($this));
// 将上面取出的数组的键名和键值, 组成一个新数组, 键名和键值一致.
// 这里其实直接返回`$fields`, 结果是一致的
// 但是不这么操作, 个人理解是为了后面其它对象复写该方法(毕竟这里只是一个默认实现)
// 复写的时候, 如果想去掉一个默认属性, 这个方法就比较方便了, 直接unset($fields['xxx'])就可以了, 而不用再次遍历去除
// 复写的时候, 添加一个同名属性的话, 可以直接覆盖掉, 而不会包含两个元素(一个是具名的, 一个是自己复写指定的), 那么之后循环的时候, 可以少执行.
return array_combine($fields, $fields);
}
/**
* Returns the list of fields that can be expanded further and returned by [[toArray()]].
* 返回可进一步扩展并由[[toArray()]]返回的字段列表。
*
*
* This method is similar to [[fields()]] except that the list of fields returned
* by this method are not returned by default by [[toArray()]]. Only when field names
* to be expanded are explicitly specified when calling [[toArray()]], will their values
* be exported.
* 这个方法与[[fields()]]相似, 不同之处在于返回的字段列表[[toArray()]]默认情况下是不返回的.
* 只有在调用[[toArray()]]的时候显示指定这些字段的时候才会返回.
*
* The default implementation returns an empty array.
* 这个方法的默认实现是返回一个空数组
*
* You may override this method to return a list of expandable fields based on some context information
* (e.g. the current application user).
* 您可以重写此方法，以基于某些上下文信息返回可扩展字段列表.(比如当前用户)
*
* @return array the list of expandable field names or field definitions. Please refer
* to [[fields()]] on the format of the return value.
* @return array 一个可以扩展的字段或者字段的定义, 具体的返回格式可以参照[[fields()]]
*
* @see toArray()
* @see fields()
*/
public function extraFields()
{
return [];
}
/**
* Converts the model into an array.
* 将对象转换为一个数组
*
* This method will first identify which fields to be included in the resulting array by calling [[resolveFields()]].
* 该方法首先通过调用[[resolveFields()]]来标识结果数组中包含哪些字段。
*
* It will then turn the model into an array with these fields. If `$recursive` is true,
* any embedded objects will also be converted into arrays.
* 然后将模型转换为具有这些字段的数组. 如果`$recursive`为true的话, 所有嵌入的对象也将转换为数组.
*
* When embeded objects are [[Arrayable]], their respective nested fields will be extracted and passed to [[toArray()]].
* 当嵌入的对象实现了[[Arrayable]]的时候, 他们嵌套的字段将被提取并传递给[[toArray()]].
*
* If the model implements the [[Linkable]] interface, the resulting array will also have a `_link` element
* which refers to a list of links as specified by the interface.
* 如果对象实现了[[Linkable]]接口, 那么结果将会自动加上一个`_link`元素, 关联由接口指定的链接列表 .
*
* @param array $fields the fields being requested.
* @param array $fields 需要转换为数组的字段
*
* If empty or if it contains '*', all fields as specified by [[fields()]] will be returned.
* 如果为空或者包含了'*', 那么将返回所有在在[[fields()]]中定义的字段
*
* Fields can be nested, separated with dots (.). e.g.: item.field.sub-field
* 字段可以嵌套, 使用(.)隔开, 如: item.field.sub-field
*
* `$recursive` must be true for nested fields to be extracted. If `$recursive` is false, only the root fields will be extracted.
* 如果要提取嵌套的字段的话, `$recursive`必须设置为true, 如果`$recursive`设置为false, 那么只会导出根字段
*
* @param array $expand the additional fields being requested for exporting. Only fields declared in [[extraFields()]]
* will be considered.
* @param array $expand 想要导出的附加字段, 只有在[[extraFields()]]中定义的字段才会被导出
*
* Expand can also be nested, separated with dots (.). e.g.: item.expand1.expand2
* 附加字段也可以嵌套, 使用(.)分隔, 如: item.expand1.expand2
*
* `$recursive` must be true for nested expands to be extracted. If `$recursive` is false, only the root expands will be extracted.
* 如果要导出嵌套的附加字段, 那么`$recursive`必须被设为true, 否则只有根字段才会被导出
*
* @param bool $recursive whether to recursively return array representation of embedded objects.
* @param bool $recursive 是否递归导出对象
*
* @return array the array representation of the object
* @return array 对象的数组
*/
public function toArray(array $fields = [], array $expand = [], $recursive = true)
{
$data = [];
// $this->resolveFields() 用来清理不在[[fields()]]以及[[extraFields()]]中定义的元素
// 返回一个kv结构的数组, k是需要导出的数组名称, v是该元素的定义(可能是字符串, 表示是对象的属性名, 也可能是一个回调, 用来返回该元素的值)
foreach ($this->resolveFields($fields, $expand) as $field => $definition) {
// 如果定义是一个字符串, 那么将当前对象的该属性值赋值给$attribute
// 如果不是一个字符串, 那就作为一个回调, 将回调的执行结果赋值给$attribute
$attribute = is_string($definition) ? $this->$definition : $definition($this, $field);
// 如果递归处理?
if ($recursive) {
// 将`$fields`中的以`$field`作为父节点的嵌套字段取出来, 作为一个数组
// 其实取出的就是`$field.xxx` `$field.yyy`的字段, 返回["xxx","yyy"]
$nestedFields = $this->extractFieldsFor($fields, $field);
// 将扩展字段`$expand`也按照如上操作
$nestedExpand = $this->extractFieldsFor($expand, $field);
if ($attribute instanceof \JsonSerializable) {
// 如果`$attribute`实现了`\JsonSerializable`接口? 直接调用`jsonSerialize()`方法返回
$attribute = $attribute->jsonSerialize();
} elseif ($attribute instanceof Arrayable) {
// 如果`$attribute`实现了`Arrayable`接口? 继续执行`toArray()`,
$attribute = $attribute->toArray($nestedFields, $nestedExpand);
} elseif (is_array($attribute)) {
// 如果`$attribute`是一个数组?
// 使用`array_map`递归处理
$attribute = array_map(
function ($item) use ($nestedFields, $nestedExpand) {
if ($item instanceof \JsonSerializable) {
return $item->jsonSerialize();
} elseif ($item instanceof Arrayable) {
return $item->toArray($nestedFields, $nestedExpand);
}
return $item;
},
$attribute
);
}
}
// 将最后处理出来的`$attribute`赋值给数组
$data[$field] = $attribute;
}
// 处理处理结束了, `$data`里面其实已经有很多数据了.
// 检测当前对象是否实现了`Linkable`
// 如果实现了, 则添加一个['link']
if ($this instanceof Linkable) {
$data['_links'] = Link::serialize($this->getLinks());
}
// 调用ArrayHelper::toArray($data)
// 为什么这里要调用ArrayHelper::toArray()呢
// 因为上面的代码实际只处理了集中类型的数据
// 1. 实现了`Arrayable`的对象
// 2. 实现了`JsonSerializable`的数据
// 3. $attribute处理完毕的非对象的数据
// 所以其它未实现这俩接口的数据的对象, 统一交由ArrayHelper::toArray()处理(如果是递归处理的话).
// 如果不递归处理的话, 当前级别已经处理完毕了, $attrite里面的其它对象就不用管了
return $recursive ? ArrayHelper::toArray($data) : $data;
}
/**
* Extracts the root field names from nested fields.
* 从嵌套字段中提取根字段名
*
* Nested fields are separated with dots (.). e.g: "item.id"
* 嵌套字段以(.)分隔, 如: "item.id"
*
* The previous example would extract "item".
* 上面的示例将提取"item"
*
* @param array $fields The fields requested for extraction
* @param array $fields 需要被提取的字段
*
* @return array root fields extracted from the given nested fields
* @return array 从嵌套字段中提取出来的根字段
*
* @since 2.0.14
*/
protected function extractRootFields(array $fields)
{
$result = [];
foreach ($fields as $field) {
$result[] = current(explode('.', $field, 2));
}
if (in_array('*', $result, true)) {
$result = [];
}
return array_unique($result);
}
/**
* Extract nested fields from a fields collection for a given root field
* 从指定的一个字段集合中提取给定的根字段的字段名
*
* Nested fields are separated with dots (.). e.g: "item.id"
* 嵌套的字段都是以(.)分隔, 如: "item.id"
*
* The previous example would extract "id".
* 上面的示例将提取出"id"
*
*
*
* @param array $fields The fields requested for extraction
* @param array $fields 想要被提取的字段
*
* @param string $rootField The root field for which we want to extract the nested fields
* @param string $rootField 想要提取的嵌套字段的根字段
*
* @return array nested fields extracted for the given field
* @return array 指定字段从嵌套字段中提取出的下级字段
* @since 2.0.14
*/
protected function extractFieldsFor(array $fields, $rootField)
{
$result = [];
foreach ($fields as $field) {
if (0 === strpos($field, "{$rootField}.")) {
$result[] = preg_replace('/^' . preg_quote($rootField, '/') . '\./i', '', $field);
}
}
return array_unique($result);
}
/**
* Determines which fields can be returned by [[toArray()]].
* 确定哪些字段可以被[[toArray()]]返回
*
* This method will first extract the root fields from the given fields.
* 这个方法首先从给定的字段中提取出根字段
*
* Then it will check the requested root fields against those declared in [[fields()]] and [[extraFields()]]
* to determine which fields can be returned.
* 然后会再次检查[[fields()]]以及[[extraFields()]]中定义的字段, 来确定哪些字段可以被返回
*
* @param array $fields the fields being requested for exporting
* @param array $fields 即将被导出的字段
*
* @param array $expand the additional fields being requested for exporting
* @param array $expand 即将被导出的附加字段
*
* @return array the list of fields to be exported. The array keys are the field names, and the array values
* are the corresponding object property names or PHP callables returning the field values.
* @return array 将要被导出的字段集合. 数组的键名就是字段名, 数组的键值就是对象对应的属性名或者一个值的回调
*/
protected function resolveFields(array $fields, array $expand)
{
$fields = $this->extractRootFields($fields);
$expand = $this->extractRootFields($expand);
$result = [];
foreach ($this->fields() as $field => $definition) {
if (is_int($field)) {
$field = $definition;
}
if (empty($fields) || in_array($field, $fields, true)) {
$result[$field] = $definition;
}
}
if (empty($expand)) {
return $result;
}
foreach ($this->extraFields() as $field => $definition) {
if (is_int($field)) {
$field = $definition;
}
if (in_array($field, $expand, true)) {
$result[$field] = $definition;
}
}
return $result;
}
}
```
浙公网安备 33010602011771号