diff --git a/src/ArrayAccessTrait.php b/src/ArrayAccessTrait.php index f5ed316..2ce6105 100644 --- a/src/ArrayAccessTrait.php +++ b/src/ArrayAccessTrait.php @@ -22,7 +22,7 @@ trait ArrayAccessTrait * This method is required by the SPL interface {@see \IteratorAggregate}. * It will be implicitly called when you use `foreach` to traverse the collection. * - * @return ArrayIterator an iterator for traversing the cookies in the collection. + * @return ArrayIterator An iterator for traversing the cookies in the collection. */ public function getIterator(): ArrayIterator { @@ -33,7 +33,7 @@ public function getIterator(): ArrayIterator * Returns the number of data items. * This method is required by Countable interface. * - * @return int number of data elements. + * @return int Number of data elements. */ public function count(): int { @@ -43,7 +43,7 @@ public function count(): int /** * This method is required by the interface {@see \ArrayAccess}. * - * @param mixed $offset the offset to check on + * @param mixed $offset The offset to check on. * * @return bool */ @@ -55,9 +55,9 @@ public function offsetExists($offset): bool /** * This method is required by the interface {@see \ArrayAccess}. * - * @param mixed $offset the offset to retrieve element. + * @param mixed $offset The offset to retrieve element. * - * @return mixed the element at the offset, null if no element is found at the offset + * @return mixed The element at the offset, null if no element is found at the offset. */ public function offsetGet($offset) { @@ -67,8 +67,8 @@ public function offsetGet($offset) /** * This method is required by the interface {@see \ArrayAccess}. * - * @param mixed $offset the offset to set element - * @param mixed $value the element value + * @param mixed $offset The offset to set element. + * @param mixed $value The element value. */ public function offsetSet($offset, $value): void { @@ -82,7 +82,7 @@ public function offsetSet($offset, $value): void /** * This method is required by the interface {@see \ArrayAccess}. * - * @param mixed $offset the offset to unset element + * @param mixed $offset The offset to unset element. */ public function offsetUnset($offset): void { diff --git a/src/ArrayHelper.php b/src/ArrayHelper.php index 642a494..9a3d0f1 100644 --- a/src/ArrayHelper.php +++ b/src/ArrayHelper.php @@ -55,19 +55,19 @@ class ArrayHelper * ] * ``` * - * @param array|object|string $object the object to be converted into an array. + * @param array|object|string $object The object to be converted into an array. * * It is possible to provide default way of converting object to array for a specific class by implementing - * `Yiisoft\Arrays\ArrayableInterface` interface in that class. - * @param array $properties a mapping from object class names to the properties that need to put into + * {@see \Yiisoft\Arrays\ArrayableInterface} in its class. + * @param array $properties A mapping from object class names to the properties that need to put into * the resulting arrays. The properties specified for each class is an array of the following format: * * - A field name to include as is. * - A key-value pair of desired array key name and model column name to take value from. * - A key-value pair of desired array key name and a callback which returns value. - * @param bool $recursive whether to recursively converts properties which are objects into arrays. + * @param bool $recursive Whether to recursively converts properties which are objects into arrays. * - * @return array the array representation of the object + * @return array The array representation of the object. */ public static function toArray($object, array $properties = [], bool $recursive = true): array { @@ -129,15 +129,15 @@ public static function toArray($object, array $properties = [], bool $recursive /** * Merges two or more arrays into one recursively. * If each array has an element with the same string key value, the latter - * will overwrite the former (different from `array_merge_recursive`). + * will overwrite the former (different from {@see array_merge_recursive()}). * Recursive merging will be conducted if both arrays have an element of array * type and are having the same key. * For integer-keyed elements, the elements from the latter array will * be appended to the former array. * - * @param array ...$arrays arrays to be merged + * @param array ...$arrays Arrays to be merged. * - * @return array the merged array (the original arrays are not changed) + * @return array The merged array (the original arrays are not changed). */ public static function merge(...$arrays): array { @@ -173,29 +173,32 @@ public static function merge(...$arrays): array * Below are some usage examples, * * ```php - * // working with array + * // Working with array: * $username = \Yiisoft\Arrays\ArrayHelper::getValue($_POST, 'username'); - * // working with object + * + * // Working with object: * $username = \Yiisoft\Arrays\ArrayHelper::getValue($user, 'username'); - * // working with anonymous function + * + * // Working with anonymous function: * $fullName = \Yiisoft\Arrays\ArrayHelper::getValue($user, function ($user, $defaultValue) { * return $user->firstName . ' ' . $user->lastName; * }); - * // using an array of keys to retrieve the value + * + * // Using an array of keys to retrieve the value: * $value = \Yiisoft\Arrays\ArrayHelper::getValue($versions, ['1.0', 'date']); * ``` * - * @param array|object $array array or object to extract value from - * @param array|Closure|float|int|string $key key name of the array element, + * @param array|object $array Array or object to extract value from. + * @param array|Closure|float|int|string $key Key name of the array element, * an array of keys or property name of the object, or an anonymous function * returning the value. The anonymous function signature should be: * `function($array, $defaultValue)`. - * @param mixed $default the default value to be returned if the specified array key does not exist. Not used when + * @param mixed $default The default value to be returned if the specified array key does not exist. Not used when * getting value from an object. * * @psalm-param ArrayKey|Closure $key * - * @return mixed the value of the element if found, default value otherwise + * @return mixed The value of the element if found, default value otherwise. */ public static function getValue($array, $key, $default = null) { @@ -224,12 +227,12 @@ public static function getValue($array, $key, $default = null) } /** - * @param mixed $array array or object to extract value from, otherwise method will return $default - * @param float|int|string $key key name of the array element or property name of the object, - * @param mixed $default the default value to be returned if the specified array key does not exist. Not used when + * @param mixed $array Array or object to extract value from, otherwise method will return $default. + * @param float|int|string $key Key name of the array element or property name of the object. + * @param mixed $default The default value to be returned if the specified array key does not exist. Not used when * getting value from an object. * - * @return mixed the value of the element if found, default value otherwise + * @return mixed The value of the element if found, default value otherwise. */ private static function getRootValue($array, $key, $default) { @@ -242,8 +245,8 @@ private static function getRootValue($array, $key, $default) try { return $array::$$key; } catch (Throwable $e) { - // this is expected to fail if the property does not exist, or __get() is not implemented - // it is not reliably possible to check whether a property is accessible beforehand + // This is expected to fail if the property does not exist, or __get() is not implemented. + // It is not reliably possible to check whether a property is accessible beforehand. return $array->$key; } } @@ -266,24 +269,25 @@ private static function getRootValue($array, $key, $default) * Below are some usage examples, * * ```php - * // using separated format to retrieve the property of embedded object + * // Using separated format to retrieve the property of embedded object: * $street = \Yiisoft\Arrays\ArrayHelper::getValue($users, 'address.street'); - * // using an array of keys to retrieve the value + * + * // Using an array of keys to retrieve the value: * $value = \Yiisoft\Arrays\ArrayHelper::getValue($versions, ['1.0', 'date']); * ``` * - * @param array|object $array array or object to extract value from - * @param array|Closure|float|int|string $path key name of the array element, an array of keys or property name + * @param array|object $array Array or object to extract value from. + * @param array|Closure|float|int|string $path Key name of the array element, an array of keys or property name * of the object, or an anonymous function returning the value. The anonymous function signature should be: * `function($array, $defaultValue)`. - * @param mixed $default the default value to be returned if the specified array key does not exist. Not used when + * @param mixed $default The default value to be returned if the specified array key does not exist. Not used when * getting value from an object. - * @param string $delimiter a separator, used to parse string $key for embedded object property retrieving. Defaults + * @param string $delimiter A separator, used to parse string $key for embedded object property retrieving. Defaults * to "." (dot). * * @psalm-param ArrayPath|Closure $path * - * @return mixed the value of the element if found, default value otherwise + * @return mixed The value of the element if found, default value otherwise. */ public static function getValueByPath($array, $path, $default = null, string $delimiter = '.') { @@ -323,14 +327,13 @@ public static function getValueByPath($array, $path, $default = null, string $de * ] * ``` * - * @param array $array the array to write the value to - * @param array|float|int|string|null $key the path of where do you want to write a value to `$array` - * the path can be described by an array of keys - * if the path is null then `$array` will be assigned the `$value` + * @param array $array The array to write the value to. + * @param array|float|int|string|null $key The path of where do you want to write a value to `$array` + * the path can be described by an array of keys. If the path is null then `$array` will be assigned the `$value`. * * @psalm-param ArrayKey|null $key * - * @param mixed $value the value to be written + * @param mixed $value The value to be written. */ public static function setValue(array &$array, $key, $value): void { @@ -402,13 +405,14 @@ public static function setValue(array &$array, $key, $value): void * ] * ``` * - * @param array $array the array to write the value to - * @param array|float|int|string|null $path the path of where do you want to write a value to `$array` - * the path can be described by a string when each key should be separated by a dot - * you can also describe the path as an array of keys - * if the path is null then `$array` will be assigned the `$value` - * @param mixed $value the value to be written - * @param string $delimiter + * @param array $array The array to write the value to. + * @param array|float|int|string|null $path The path of where do you want to write a value to `$array`. + * The path can be described by a string when each key should be separated by a dot. + * You can also describe the path as an array of keys. If the path is null then `$array` will be assigned + * the `$value`. + * @param mixed $value The value to be written. + * @param string $delimiter A separator, used to parse string $key for embedded object property retrieving. Defaults + * to "." (dot). * * @psalm-param ArrayPath|null $path */ @@ -418,8 +422,11 @@ public static function setValueByPath(array &$array, $path, $value, string $deli } /** - * @param array|float|int|string $path - * @param string $delimiter + * @param array|float|int|string $path The path of where do you want to write a value to `$array`. + * The path can be described by a string when each key should be separated by delimiter. + * You can also describe the path as an array of keys. + * @param string $delimiter A separator, used to parse string $key for embedded object property retrieving. Defaults + * to "." (dot). * * @psalm-param ArrayPath $path * @@ -455,19 +462,21 @@ private static function parsePath($path, string $delimiter) * * ```php * // $array = ['type' => 'A', 'options' => [1, 2]]; - * // working with array + * + * // Working with array: * $type = \Yiisoft\Arrays\ArrayHelper::remove($array, 'type'); + * * // $array content * // $array = ['options' => [1, 2]]; * ``` * - * @param array $array the array to extract value from - * @param array|float|int|string $key key name of the array element or associative array at the key path specified - * @param mixed $default the default value to be returned if the specified key does not exist + * @param array $array The array to extract value from. + * @param array|float|int|string $key Key name of the array element or associative array at the key path specified. + * @param mixed $default The default value to be returned if the specified key does not exist. * * @psalm-param ArrayKey $key * - * @return mixed the value of the element if found, default value otherwise + * @return mixed The value of the element if found, default value otherwise. */ public static function remove(array &$array, $key, $default = null) { @@ -500,21 +509,24 @@ public static function remove(array &$array, $key, $default = null) * * ```php * // $array = ['type' => 'A', 'options' => [1, 2]]; - * // working with array + * + * // Working with array: * $type = \Yiisoft\Arrays\ArrayHelper::remove($array, 'type'); + * * // $array content * // $array = ['options' => [1, 2]]; * ``` * - * @param array $array the array to extract value from - * @param array|float|int|string $path key name of the array element or associative array at the key path specified - * the path can be described by a string when each key should be separated by a delimiter (default is dot) - * @param mixed $default the default value to be returned if the specified key does not exist - * @param string $delimiter + * @param array $array The array to extract value from. + * @param array|float|int|string $path Key name of the array element or associative array at the key path specified. + * The path can be described by a string when each key should be separated by a delimiter (default is dot). + * @param mixed $default The default value to be returned if the specified key does not exist. + * @param string $delimiter A separator, used to parse string $key for embedded object property retrieving. Defaults + * to "." (dot). * * @psalm-param ArrayPath $path * - * @return mixed the value of the element if found, default value otherwise + * @return mixed The value of the element if found, default value otherwise. */ public static function removeByPath(array &$array, $path, $default = null, string $delimiter = '.') { @@ -534,10 +546,10 @@ public static function removeByPath(array &$array, $path, $default = null, strin * // $removed = ['Michael' => 'Jackson', 'Janet' => 'Jackson']; * ``` * - * @param array $array the array where to look the value from - * @param mixed $value the value to remove from the array + * @param array $array The array where to look the value from. + * @param mixed $value The value to remove from the array. * - * @return array the items that were removed from the array + * @return array The items that were removed from the array. */ public static function removeValue(array &$array, $value): array { @@ -646,17 +658,17 @@ public static function removeValue(array &$array, $value): array * ] * ``` * - * @param array $array the array that needs to be indexed or grouped - * @param Closure|string|null $key the column name or anonymous function which result will be used - * to index the array - * @param Closure[]|string|string[]|null $groups the array of keys, that will be used to group the input array + * @param array $array The array that needs to be indexed or grouped. + * @param Closure|string|null $key The column name or anonymous function which result will be used + * to index the array. + * @param Closure[]|string|string[]|null $groups The array of keys, that will be used to group the input array * by one or more keys. If the $key attribute or its value for the particular element is null and $groups is not * defined, the array element will be discarded. Otherwise, if $groups is specified, array element will be added * to the result array without any key. * * @psalm-param array $array * - * @return array the indexed and/or grouped array + * @return array The indexed and/or grouped array. */ public static function index(array $array, $key, $groups = []): array { @@ -721,12 +733,12 @@ public static function index(array $array, $key, $groups = []): array * }); * ``` * - * @param array $array - * @param Closure|string $name - * @param bool $keepKeys whether to maintain the array keys. If false, the resulting array + * @param array $array The array to get column from. + * @param Closure|string $name Column name or a closure returning column name. + * @param bool $keepKeys Whether to maintain the array keys. If false, the resulting array * will be re-indexed with integers. * - * @return array the list of column values + * @return array The list of column values. */ public static function getColumn(array $array, $name, bool $keepKeys = true): array { @@ -781,14 +793,14 @@ public static function getColumn(array $array, $name, bool $keepKeys = true): ar * // ] * ``` * - * @param array $array - * @param Closure|string $from - * @param Closure|string $to - * @param Closure|string|null $group + * @param array $array Array to build map from. + * @param Closure|string $from Key or property name to map from. + * @param Closure|string $to Key or property name to map to. + * @param Closure|string|null $group Key or property to group the map. * * @psalm-param array $array * - * @return array + * @return array Resulting map. */ public static function map(array $array, $from, $to, $group = null): array { @@ -823,13 +835,13 @@ public static function map(array $array, $from, $to, $group = null): array * This method enhances the `array_key_exists()` function by supporting case-insensitive * key comparison. * - * @param array $array the array with keys to check - * @param array|float|int|string $key the key to check - * @param bool $caseSensitive whether the key comparison should be case-sensitive + * @param array $array The array with keys to check. + * @param array|float|int|string $key The key to check. + * @param bool $caseSensitive Whether the key comparison should be case-sensitive. * * @psalm-param ArrayKey $key * - * @return bool whether the array contains the specified key + * @return bool Whether the array contains the specified key. */ public static function keyExists(array $array, $key, bool $caseSensitive = true): bool { @@ -893,7 +905,7 @@ private static function getExistsKeys(array $array, $key, bool $caseSensitive): return array_filter( array_keys($array), - fn ($k) => strcasecmp($key, (string)$k) === 0 + static fn ($k) => strcasecmp($key, (string)$k) === 0 ); } @@ -904,10 +916,12 @@ private static function getExistsKeys(array $array, $key, bool $caseSensitive): * This method enhances the `array_key_exists()` function by supporting case-insensitive * key comparison. * - * @param array $array - * @param array|float|int|string $path - * @param bool $caseSensitive - * @param string $delimiter + * @param array $array The array to check path in. + * @param array|float|int|string $path The key path. Can be described by a string when each key should be separated + * by delimiter. You can also describe the path as an array of keys. + * @param bool $caseSensitive Whether the key comparison should be case-sensitive. + * @param string $delimiter A separator, used to parse string $key for embedded object property retrieving. Defaults + * to "." (dot). * * @psalm-param ArrayPath $path * @@ -928,14 +942,14 @@ public static function pathExists( * If a value is an array, this method will also encode it recursively. * Only string values will be encoded. * - * @param array $data data to be encoded - * @param bool $valuesOnly whether to encode array values only. If false, + * @param array $data Data to be encoded. + * @param bool $valuesOnly Whether to encode array values only. If false, * both the array keys and array values will be encoded. * @param string|null $encoding The encoding to use, defaults to `ini_get('default_charset')`. * * @psalm-param array $data * - * @return array the encoded data + * @return array The encoded data. * * @link https://www.php.net/manual/en/function.htmlspecialchars.php */ @@ -968,35 +982,35 @@ public static function htmlEncode(array $data, bool $valuesOnly = true, string $ * If a value is an array, this method will also decode it recursively. * Only string values will be decoded. * - * @param array $data data to be decoded - * @param bool $valuesOnly whether to decode array values only. If false, + * @param array $data Data to be decoded. + * @param bool $valuesOnly Whether to decode array values only. If false, * both the array keys and array values will be decoded. * * @psalm-param array $data * - * @return array the decoded data + * @return array The decoded data. * * @link https://www.php.net/manual/en/function.htmlspecialchars-decode.php */ public static function htmlDecode(array $data, bool $valuesOnly = true): array { - $d = []; + $decoded = []; /** @psalm-var mixed $value */ foreach ($data as $key => $value) { if (!$valuesOnly && is_string($key)) { $key = htmlspecialchars_decode($key, ENT_QUOTES); } if (is_string($value)) { - $d[$key] = htmlspecialchars_decode($value, ENT_QUOTES); + $decoded[$key] = htmlspecialchars_decode($value, ENT_QUOTES); } elseif (is_array($value)) { - $d[$key] = static::htmlDecode($value); + $decoded[$key] = static::htmlDecode($value); } else { /** @var mixed */ - $d[$key] = $value; + $decoded[$key] = $value; } } - return $d; + return $decoded; } /** @@ -1007,11 +1021,11 @@ public static function htmlDecode(array $data, bool $valuesOnly = true): array * * Note that an empty array will NOT be considered associative. * - * @param array $array the array being checked - * @param bool $allStrings whether the array keys must be all strings in order for + * @param array $array The array being checked. + * @param bool $allStrings Whether the array keys must be all strings in order for * the array to be treated as associative. * - * @return bool whether the array is associative + * @return bool Whether the array is associative. */ public static function isAssociative(array $array, bool $allStrings = true): bool { @@ -1048,11 +1062,11 @@ public static function isAssociative(array $array, bool $allStrings = true): boo * * Note that an empty array will be considered indexed. * - * @param array $array the array being checked - * @param bool $consecutive whether the array keys must be a consecutive sequence + * @param array $array The array being checked. + * @param bool $consecutive Whether the array keys must be a consecutive sequence * in order for the array to be treated as indexed. * - * @return bool whether the array is indexed + * @return bool Whether the array is indexed. */ public static function isIndexed(array $array, bool $consecutive = false): bool { @@ -1077,8 +1091,8 @@ public static function isIndexed(array $array, bool $consecutive = false): bool /** * Check whether an array or `\Traversable` contains an element. * - * This method does the same as the PHP function [in_array()](https://php.net/manual/en/function.in-array.php) - * but additionally works for objects that implement the `\Traversable` interface. + * This method does the same as the PHP function {@see in_array()} + * but additionally works for objects that implement the {@see \Traversable} interface. * * @param mixed $needle The value to look for. * @param iterable $haystack The set of values to search. @@ -1107,7 +1121,7 @@ public static function isIn($needle, iterable $haystack, bool $strict = false): } /** - * Checks whether an array or `\Traversable` is a subset of another array or `\Traversable`. + * Checks whether an array or {@see \Traversable} is a subset of another array or {@see \Traversable}. * * This method will return `true`, if all elements of `$needles` are contained in * `$haystack`. If at least one element is missing, `false` will be returned. @@ -1167,14 +1181,14 @@ public static function isSubset(iterable $needles, iterable $haystack, bool $str * // ] * ``` * - * @param array $array Source array + * @param array $array Source array. * @param list $filters Rules that define array keys which should be left or removed from results. * Each rule is: * - `var` - `$array['var']` will be left in result. * - `var.key` = only `$array['var']['key']` will be left in result. * - `!var.key` = `$array['var']['key']` will be removed from result. * - * @return array Filtered array + * @return array Filtered array. */ public static function filter(array $array, array $filters): array { @@ -1187,17 +1201,17 @@ public static function filter(array $array, array $filters): array continue; } - $nodeValue = $array; // set $array as root node + $nodeValue = $array; // Set $array as root node. $keys = explode('.', $filter); foreach ($keys as $key) { if (!is_array($nodeValue) || !array_key_exists($key, $nodeValue)) { - continue 2; // Jump to next filter + continue 2; // Jump to next filter. } /** @var mixed */ $nodeValue = $nodeValue[$key]; } - //We've found a value now let's insert it + // We've found a value now let's insert it. $resultNode = &$result; foreach ($keys as $key) { if (!array_key_exists($key, $resultNode)) { @@ -1217,7 +1231,7 @@ public static function filter(array $array, array $filters): array $numNestedKeys = count($keys) - 1; foreach ($keys as $i => $key) { if (!is_array($excludeNode) || !array_key_exists($key, $excludeNode)) { - continue 2; // Jump to next filter + continue 2; // Jump to next filter. } if ($i < $numNestedKeys) { diff --git a/src/ArraySorter.php b/src/ArraySorter.php index ec02d37..2402e0e 100644 --- a/src/ArraySorter.php +++ b/src/ArraySorter.php @@ -35,20 +35,20 @@ class ArraySorter * ]; * ``` * - * @param array $array the array to be sorted. The array will be modified after calling + * @param array $array The array to be sorted. The array will be modified after calling * this method. - * @param array|Closure|string $key the key(s) to be sorted by. This refers to a key + * @param array|Closure|string $key The key(s) to be sorted by. This refers to a key * name of the sub-array elements, a property name of the objects, or an anonymous function returning the values * for comparison purpose. The anonymous function signature should be: `function($item)`. * To sort by multiple keys, provide an array of keys here. - * @param array|int $direction the sorting direction. It can be either `SORT_ASC` or `SORT_DESC`. + * @param array|int $direction The sorting direction. It can be either `SORT_ASC` or `SORT_DESC`. * When sorting by multiple keys with different sorting directions, use an array of sorting directions. - * @param array|int $sortFlag the PHP sort flag. Valid values include + * @param array|int $sortFlag The PHP sort flag. Valid values include * `SORT_REGULAR`, `SORT_NUMERIC`, `SORT_STRING`, `SORT_LOCALE_STRING`, `SORT_NATURAL` and `SORT_FLAG_CASE`. * Please refer to [PHP manual](http://php.net/manual/en/function.sort.php) * for more details. When sorting by multiple keys with different sort flags, use an array of sort flags. * - * @throws InvalidArgumentException if the `$direction` or `$sortFlag` parameters do not have + * @throws InvalidArgumentException If the `$direction` or `$sortFlag` parameters do not have * correct number of elements as that of $key.` */ public static function multisort(array &$array, $key, $direction = SORT_ASC, $sortFlag = SORT_REGULAR): void @@ -78,15 +78,15 @@ public static function multisort(array &$array, $key, $direction = SORT_ASC, $so } /** - * Get keys for get arguments + * Get keys for get arguments. * - * @param array $array the array to be sorted - * @param array|Closure|string $key the keys to be sorted by. This refers to a key name + * @param array $array The array to be sorted. + * @param array|Closure|string $key The keys to be sorted by. This refers to a key name * of the sub-array elements, a property name of the objects, or an anonymous function returning the values for * comparison purpose. The anonymous function signature should be: `function($item)`. * To sort by multiple keys, provide an array of keys here. * - * @return array return the keys + * @return array The keys. */ private static function getKeys(array $array, $key): array { @@ -99,14 +99,14 @@ private static function getKeys(array $array, $key): array } /** - * Get arguments for multisort + * Get arguments for multisort. * - * @param array $array the array to be sorted - * @param array $keys array of keys - * @param array $direction array of sorting directions - * @param array $sortFlags array of sort flags + * @param array $array The array to be sorted. + * @param array $keys Array of keys. + * @param array $direction Array of sorting directions. + * @param array $sortFlags Array of sort flags. * - * @return array{array, int, int} return the arguments + * @return array{array, int, int} The arguments. */ private static function getArguments(array $array, array $keys, array $direction, array $sortFlags): array { @@ -118,7 +118,7 @@ private static function getArguments(array $array, array $keys, array $direction $args[] = $flag; } - // This fix is used for cases when main sorting specified by columns has equal values + // This fix is used for cases when main sorting specified by columns has equal values. // Without it it will lead to Fatal Error: Nesting level too deep - recursive dependency? $args[] = range(1, count($array)); $args[] = SORT_ASC; diff --git a/src/ArrayableInterface.php b/src/ArrayableInterface.php index 04af075..7a2c111 100644 --- a/src/ArrayableInterface.php +++ b/src/ArrayableInterface.php @@ -5,7 +5,7 @@ namespace Yiisoft\Arrays; /** - * ArrayableInterface should be implemented by classes who want to support customizable representation + * ArrayableInterface should be implemented by classes that want to support customizable representation * of their instances. * * For example, if a class implements ArrayableInterface, by calling {@see ArrayableInterface::toArray()}, @@ -55,7 +55,7 @@ interface ArrayableInterface * ]; * ``` * - * @return array the list of field names or field definitions. + * @return array The list of field names or field definitions. * * @see toArray() */ @@ -69,7 +69,7 @@ public function fields(): array; * by this method are not returned by default by {@see toArray()}. Only when a field in the list * is explicitly requested, will it be included in the result of {@see toArray()}. * - * @return array the list of expandable field names or field definitions. Please refer + * @return array The list of expandable field names or field definitions. Please refer * to {@see fields()} on the format of the return value. * * @see toArray() @@ -86,9 +86,9 @@ public function extraFields(): array; * @param array $expand the additional fields that the output array should contain. * Fields not specified in {@see extraFields()} will be ignored. If this parameter is empty, no extra fields * will be returned. - * @param bool $recursive whether to recursively return array representation of embedded objects. + * @param bool $recursive Whether to recursively return array representation of embedded objects. * - * @return array the array representation of the object + * @return array The array representation of the object. */ public function toArray(array $fields = [], array $expand = [], bool $recursive = true): array; } diff --git a/src/ArrayableTrait.php b/src/ArrayableTrait.php index 8deb9bd..a76cf71 100644 --- a/src/ArrayableTrait.php +++ b/src/ArrayableTrait.php @@ -4,6 +4,12 @@ namespace Yiisoft\Arrays; +use function array_key_exists; +use function in_array; +use function is_array; +use function is_int; +use function is_string; + /** * ArrayableTrait provides a common implementation of the {@see ArrayableInterface} interface. * @@ -55,7 +61,7 @@ trait ArrayableTrait * * 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 The list of field names or field definitions. * * @see toArray() */ @@ -78,7 +84,7 @@ public function fields(): 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 + * @return array The list of expandable field names or field definitions. Please refer * to {@see ArrayableInterface::fields()} on the format of the return value. * * @see toArray() @@ -98,19 +104,19 @@ public function extraFields(): array * When embedded objects are {@see ArrayableInterface}, their respective nested fields * will be extracted and passed to {@see ArrayableInterface::toArray()}. * - * @param array $fields the fields being requested. + * @param array $fields The fields being requested. * If empty or if it contains '*', all fields as specified by {@see 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. - * @param array $expand the additional fields being requested for exporting. Only fields declared + * @param array $expand The additional fields being requested for exporting. Only fields declared * in {@see 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. - * @param bool $recursive whether to recursively return array representation of embedded objects. + * @param bool $recursive Whether to recursively return array representation of embedded objects. * - * @return array the array representation of the object + * @return array The array representation of the object. */ public function toArray(array $fields = [], array $expand = [], bool $recursive = true): array { @@ -144,7 +150,7 @@ private function filterAndExpand(array $array, array $fields = [], array $expand $nestedFields = $this->extractFieldsFor($fields, $field); $nestedExpand = $this->extractFieldsFor($expand, $field); if ($attribute instanceof ArrayableInterface) { - $attribute = $attribute->toArray($nestedFields, $nestedExpand, true); + $attribute = $attribute->toArray($nestedFields, $nestedExpand); } elseif (is_array($attribute) && ($nestedExpand || $nestedFields)) { $attribute = $this->filterAndExpand($attribute, $nestedFields, $nestedExpand); } @@ -161,14 +167,14 @@ private function filterAndExpand(array $array, array $fields = [], array $expand * * @param array $fields The fields requested for extraction * - * @return array root fields extracted from the given nested fields + * @return array root Fields extracted from the given nested fields. */ protected function extractRootFields(array $fields): array { $result = []; foreach ($fields as $field) { - $result[] = stristr($field . '.', '.', true); + $result[] = strstr($field . '.', '.', true); } if (in_array('*', $result, true)) { @@ -183,10 +189,10 @@ protected function extractRootFields(array $fields): array * Nested fields are separated with dots (.). e.g: "item.id" * The previous example would extract "id". * - * @param array $fields The fields requested for extraction - * @param string $rootField The root field for which we want to extract the nested fields + * @param array $fields The fields requested for extraction. + * @param string $rootField The root field for which we want to extract the nested fields. * - * @return array nested fields extracted for the given field + * @return array Nested fields extracted for the given field. */ protected function extractFieldsFor(array $fields, string $rootField): array { @@ -207,10 +213,10 @@ protected function extractFieldsFor(array $fields, string $rootField): array * Then it will check the requested root fields against those declared in {@see ArrayableInterface::fields()} * and {@see ArrayableInterface::extraFields()} to determine which fields can be returned. * - * @param array $fields the fields being requested for exporting - * @param array $expand the additional fields being requested for exporting + * @param array $fields The fields being requested for exporting. + * @param array $expand 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 + * @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. */ protected function resolveFields(array $fields, array $expand): array