<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yiibase;

use Yii;
use yiihelpersArrayHelper;
use yiiwebLink;
use yiiwebLinkable;

/**
 * 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()
    {
        $fields = array_keys(Yii::getObjectVars($this));
        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 = [];
        foreach ($this->resolveFields($fields, $expand) as $field => $definition) {
            $attribute = is_string($definition) ? $this->$definition : $definition($this, $field);

            if ($recursive) {
                $nestedFields = $this->extractFieldsFor($fields, $field);
                $nestedExpand = $this->extractFieldsFor($expand, $field);
                if ($attribute instanceof JsonSerializable) {
                    $attribute = $attribute->jsonSerialize();
                } elseif ($attribute instanceof Arrayable) {
                    $attribute = $attribute->toArray($nestedFields, $nestedExpand);
                } elseif (is_array($attribute)) {
                    $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
                    );
                }
            }
            $data[$field] = $attribute;
        }

        if ($this instanceof Linkable) {
            $data['_links'] = Link::serialize($this->getLinks());
        }

        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;
    }
}