0 follower

Trait Yiisoft\Arrays\ArrayableTrait

All Classes | Methods

ArrayableTrait provides a common implementation of the {@see ArrayableInterface} interface.

ArrayableTrait implements {@see \Yiisoft\Arrays\ArrayableInterface::toArray()} by respecting the field definitions as declared in {@see \Yiisoft\Arrays\ArrayableInterface::fields()} and {@see \Yiisoft\Arrays\ArrayableInterface::extraFields()}.

Public Methods

Hide inherited methods

Method	Description	Defined By
extraFields()	Returns the list of fields that can be expanded further and returned by {@see ArrayableInterface::toArray()}.	Yiisoft\Arrays\ArrayableTrait
fields()	Returns the list of fields that should be returned by default by {@see ArrayableInterface::toArray()} when no specific fields are specified.	Yiisoft\Arrays\ArrayableTrait
toArray()	Converts the model into an array.	Yiisoft\Arrays\ArrayableTrait

Protected Methods

Hide inherited methods

Method	Description	Defined By
extractFieldsFor()	Extract nested fields from a fields collection for a given root field Nested fields are separated with dots (.). e.g: "item.id" The previous example would extract "id".	Yiisoft\Arrays\ArrayableTrait
extractRootFields()	Extracts the root field names from nested fields.	Yiisoft\Arrays\ArrayableTrait
resolveFields()	Determines which fields can be returned by {@see ArrayableInterface::toArray()}.	Yiisoft\Arrays\ArrayableTrait

Method Details

Hide inherited methods

extraFields() public method

Returns the list of fields that can be expanded further and returned by {@see ArrayableInterface::toArray()}.

This method is similar to {@see \Yiisoft\Arrays\ArrayableInterface::fields()} except that the list of fields returned by this method are not returned by default by {@see \Yiisoft\Arrays\ArrayableInterface::toArray()}. Only when field names to be expanded are explicitly specified when calling {@see \Yiisoft\Arrays\ArrayableInterface::toArray()}, will their values be exported.

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).

See also:

public array extraFields ( )
return	array	The list of expandable field names or field definitions. Please refer to {@see \Yiisoft\Arrays\ArrayableInterface::fields()} on the format of the return value.

Source code

                public function extraFields(): array
{
    return [];
}

extractFieldsFor() protected method

Extract nested fields from a fields collection for a given root field Nested fields are separated with dots (.). e.g: "item.id" The previous example would extract "id".

protected string[] extractFieldsFor ( string[] $fields, string $rootField )
$fields	string[]	The fields requested for extraction.
$rootField	string	The root field for which we want to extract the nested fields.
return	string[]	Nested fields extracted for the given field.

Source code

                protected function extractFieldsFor(array $fields, string $rootField): array
{
    $result = [];
    foreach ($fields as $field) {
        if (str_starts_with($field, "$rootField.")) {
            $result[] = substr($field, strlen($rootField) + 1);
        }
    }
    return array_unique($result);
}

extractRootFields() protected method

Extracts the root field names from nested fields.

Nested fields are separated with dots (.). e.g: "item.id" The previous example would extract "item".

protected string[] extractRootFields ( string[] $fields )
$fields	string[]	The fields requested for extraction
return	string[]	Root fields extracted from the given nested fields.

Source code

                protected function extractRootFields(array $fields): array
{
    $result = [];
    foreach ($fields as $field) {
        /** @var string */
        $result[] = strstr($field . '.', '.', true);
    }
    if (in_array('*', $result, true)) {
        $result = [];
    }
    return array_unique($result);
}

fields() public method

Returns the list of fields that should be returned by default by {@see ArrayableInterface::toArray()} when no specific fields are specified.

A field is a named element in the returned array by {@see \Yiisoft\Arrays\ArrayableInterface::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:

function ($model, $field) {
    // return field value
}

For example, the following code declares four fields:

email: the field name is the same as the property name email;
firstName and lastName: the field names are firstName and lastName, and their values are obtained from the first_name and last_name properties;
fullName: the field name is fullName. Its value is obtained by concatenating first_name and last_name.

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.

See also toArray().

public array fields ( )
return	array	The list of field names or field definitions.

Source code

                public function fields(): array
{
    $fields = array_keys(ArrayHelper::getObjectVars($this));
    return array_combine($fields, $fields);
}

resolveFields() protected method

Determines which fields can be returned by {@see ArrayableInterface::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 {@see \Yiisoft\Arrays\ArrayableInterface::fields()} and {@see \Yiisoft\Arrays\ArrayableInterface::extraFields()} to determine which fields can be returned.

protected array resolveFields ( string[] $fields, string[] $expand )
$fields	string[]	The fields being requested for exporting.
$expand	string[]	The additional fields being requested for exporting.
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.

Source code

                protected function resolveFields(array $fields, array $expand): array
{
    $fields = $this->extractRootFields($fields);
    $expand = $this->extractRootFields($expand);
    $result = [];
    foreach ($this->fields() as $field => $definition) {
        if (is_int($field)) {
            /** @var string $definition */
            $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)) {
            /** @var string $definition */
            $field = $definition;
        }
        if (in_array($field, $expand, true)) {
            $result[$field] = $definition;
        }
    }
    return $result;
}

toArray() public method

Converts the model into an array.

This method will first identify which fields to be included in the resulting array by calling {@see \Yiisoft\Arrays\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. When embedded objects are {@see \Yiisoft\Arrays\ArrayableInterface}, their respective nested fields will be extracted and passed to {@see \Yiisoft\Arrays\ArrayableInterface::toArray()}.

public array toArray ( string[] $fields = [], string[] $expand = [], boolean $recursive = true )
$fields	string[]	The fields being requested. If empty or if it contains '*', all fields as specified by {@see \Yiisoft\Arrays\ArrayableInterface::fields()} will be returned. Fields can be nested, separated with dots (.). e.g.: 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.
$expand	string[]	The additional fields being requested for exporting. Only fields declared in {@see \Yiisoft\Arrays\ArrayableInterface::extraFields()} will be considered. Expand can also be nested, separated with dots (.). e.g.: 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	boolean	Whether to recursively return array representation of embedded objects.
return	array	The array representation of the object.

Source code

                public function toArray(array $fields = [], array $expand = [], bool $recursive = true): array
{
    $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 ArrayableInterface) {
                $attribute = $attribute->toArray($nestedFields, $nestedExpand);
            } elseif (is_array($attribute) && ($nestedExpand || $nestedFields)) {
                $attribute = $this->filterAndExpand($attribute, $nestedFields, $nestedExpand);
            }
        }
        $data[$field] = $attribute;
    }
    return $recursive ? ArrayHelper::toArray($data) : $data;
}