From 60ef866708428b790ac25f061c763d2c48e3e28c Mon Sep 17 00:00:00 2001 From: pana1990 Date: Mon, 5 Jan 2015 18:54:10 +0100 Subject: [PATCH] Add syntax highlighting [skip ci] --- docs/guide/helper-array.md | 84 ++++++++++++++++++++++++---------------------- 1 file changed, 43 insertions(+), 41 deletions(-) diff --git a/docs/guide/helper-array.md b/docs/guide/helper-array.md index a3a804c..d601ffa 100644 --- a/docs/guide/helper-array.md +++ b/docs/guide/helper-array.md @@ -3,14 +3,14 @@ ArrayHelper Additionally to [rich set of PHP array functions](http://php.net/manual/en/book.array.php) Yii array helper provides extra static methods allowing you to deal with arrays more efficiently. - + ## Getting Values Retrieving values from an array, an object or a complex structure consisting of both using standard PHP is quite -repetitive. You have to check if key exists with `isset` first, then if it does you're getting it, if not, +repetitive. You have to check if key exists with `isset` first, then if it does you're getting it, if not, providing default value: - + ```php class User { @@ -34,9 +34,9 @@ $value = ArrayHelper::getValue($array, 'foo.bar.name'); First method argument is where we're getting value from. Second argument specifies how to get the data. It could be one of the following: - + - Name of array key or object property to retrieve value from. -- Set of dot separated array keys or object property names. The one we've used in the example above. +- Set of dot separated array keys or object property names. The one we've used in the example above. - A callback returning a value. The callback should be the following: @@ -54,7 +54,7 @@ $username = ArrayHelper::getValue($comment, 'user.username', 'Unknown'); ``` In case you want to get the value and then immediately remove it from array you can use `remove` method: - + ```php $array = ['type' => 'A', 'options' => [1, 2]]; $type = ArrayHelper::remove($array, 'type'); @@ -96,7 +96,7 @@ $ids = ArrayHelper::getColumn($array, 'id'); ``` The result will be `['123', '345']`. - + If additional transformations are required or the way of getting value is complex, second argument could be specified as an anonymous function: @@ -106,7 +106,7 @@ $result = ArrayHelper::getColumn($array, function ($element) { }); ``` - + ## Re-indexing Arrays In order to index an array according to a specified key, the `index` method can be used. The input array should be @@ -114,7 +114,7 @@ multidimensional or an array of objects. The key can be a key name of the sub-ar an anonymous function which returns the key value given an array element. If a key value is null, the corresponding array element will be discarded and not put in the result. For example, - + ```php $array = [ ['id' => '123', 'data' => 'abc'], @@ -133,13 +133,13 @@ $result = ArrayHelper::index($array, function ($element) { }); ``` - -## Building Maps + +## Building Maps In order to build a map (key-value pairs) from a multidimensional array or an array of objects you can use `map` method. The `$from` and `$to` parameters specify the key names or property names to set up the map. Optionally, one can further group the map according to a grouping field `$group`. For example, - + ```php $array = [ ['id' => '123', 'name' => 'aaa', 'class' => 'x'], @@ -167,9 +167,9 @@ $result = ArrayHelper::map($array, 'id', 'name', 'class'); // ], // ] ``` - - -## Multidimensional Sorting + + +## Multidimensional Sorting `multisort` method helps to sort an array of objects or nested arrays by one or several keys. For example, @@ -200,19 +200,19 @@ ArrayHelper::multisort($data, function($item) { return isset($item['age']) ? ['age', 'name'] : 'name'; }); ``` - + Third argument is direction. In case of sorting by a single key it could be either `SORT_ASC` or `SORT_DESC`. If sorting by multiple values you can sort each value differently by providing an array of sort direction. Last argument is PHP sort flag that could take the same values as the ones passed to PHP [sort()](http://php.net/manual/en/function.sort.php). - + ## Detecting Array Types - + It is handy to know whether an array is indexed or an associative. Here's an example: - + ```php // no keys specified $indexed = ['Qiang', 'Paul']; @@ -222,7 +222,7 @@ echo ArrayHelper::isIndexed($indexed); $associative = ['framework' => 'Yii', 'version' => '2.0']; echo ArrayHelper::isAssociative($associative); ``` - + ## HTML Encoding and Decoding Values @@ -235,26 +235,28 @@ $decoded = ArrayHelper::htmlDecode($data); Only values will be encoded by default. By passing second argument as `false` you can encode array's keys as well. Encoding will use application charset and could be changed via third argument. - - + + ## Merging Arrays +```php /** - * 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). - * 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 $a array to be merged to - * @param array $b array to be merged from. You can specify additional - * arrays via third argument, fourth argument etc. - * @return array the merged array (the original arrays are not changed.) - */ + * 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). + * 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 $a array to be merged to + * @param array $b array to be merged from. You can specify additional + * arrays via third argument, fourth argument etc. + * @return array the merged array (the original arrays are not changed.) + */ public static function merge($a, $b) - - +``` + + ## Converting Objects to Arrays Often you need to convert an object or an array of objects into an array. The most common case is converting active record @@ -276,18 +278,18 @@ $data = ArrayHelper::toArray($post, [ ]); ``` -The first argument contains the data we want to convert. In our case we're converting a `Post` AR model. +The first argument contains the data we want to convert. In our case we're converting a `Post` AR model. -The second argument is conversion mapping per class. We're setting a mapping for `Post` model. +The second argument is conversion mapping per class. We're setting a mapping for `Post` model. Each mapping array contains a set of mappings. Each mapping could be: - + - 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. The result of conversion above will be: - - + + ```php [ 'id' => 123,