From 9dd3d9b978bf2824da95c68368e760fed572b21f Mon Sep 17 00:00:00 2001 From: wakasann Date: Thu, 30 Jul 2015 10:32:52 +0800 Subject: [PATCH 1/6] helper-array file translated --- docs/guide-zh-CN/helper-array.md | 303 +++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 docs/guide-zh-CN/helper-array.md diff --git a/docs/guide-zh-CN/helper-array.md b/docs/guide-zh-CN/helper-array.md new file mode 100644 index 0000000000..e640547693 --- /dev/null +++ b/docs/guide-zh-CN/helper-array.md @@ -0,0 +1,303 @@ +ArrayHelper +=========== + +[丰富设置的PHP](http://php.net/manual/zh/book.array.php)附加的数组函数，Yii 数组辅助函数提供了额外的静态方法让你更有效率的处理数组。 + +## Getting Values + +## 获取值 + +从一个数组中再获得值， 一个对象或者使用标准PHP是完全的反复由一个复杂结构组成.你不得不首先使用`isset`检查key是否存在,然后如果存在你就获取到了它，如果不存在， +预设默认值 + + +```php +class User +{ + public $name = 'Alex'; +} + +$array = [ + 'foo' => [ + 'bar' => new User(), + ] +]; + +$value = isset($array['foo']['bar']->name) ? $array['foo']['bar']->name : null; +``` + +Yii 提供了一个非常方便的方法来处理它: + +```php +$value = ArrayHelper::getValue($array, 'foo.bar.name'); +``` + +第一个方法参数是我们从哪里获取值.第二个参数定义如何去获取数据.它可以为一下的其中一个: + +- 数组键名或者获得值对象的属性名称 +- 使用点号分割的数组key或者对象的属性名称。这个我们已经在上面的案列使用过了 +- 一个回调函数返回一个值 + +这个回调函数应该是下列的: + + +```php +$fullName = ArrayHelper::getValue($user, function ($user, $defaultValue) { + return $user->firstName . ' ' . $user->lastName; +}); +``` + +第三个可选择的参数是默认值，如果没有指定第三个参数，默认值是`null`.也可以使用下列的: + +```php +$username = ArrayHelper::getValue($comment, 'user.username', 'Unknown'); +``` + + +假设你想要获取值和然后马上从数组中移除它,你可以使用`remove`方法: + +```php +$array = ['type' => 'A', 'options' => [1, 2]]; +$type = ArrayHelper::remove($array, 'type'); +``` + +在执行了代码之后,`$array` 将会等于 `['options' => [1, 2]]` 和 `$type` 将会是 `A`.注意这和`getValue`方法不同,`remove`方法只支持简单的键名. + +## 检查键名存在 + +`ArrayHelper::keyExists` 工作原理和[array_key_exists](http://php.net/manual/en/function.array-key-exists.php)差不多,除了 +`array_key_exists`同样支持区分大小写键名进行比较.比如: + +```php +$data1 = [ + 'userName' => 'Alex', +]; + +$data2 = [ + 'username' => 'Carsten', +]; + +if (!ArrayHelper::keyExists('username', $data1, false) || !ArrayHelper::keyExists('username', $data2, false)) { + echo "Please provide username."; +} +``` + +## 检索列 + +你经常需要从由数据行组成的数组或者对象中获取一列值.通常情况下是根据许多id获取一列数据. + +```php +$data = [ + ['id' => '123', 'data' => 'abc'], + ['id' => '345', 'data' => 'def'], +]; +$ids = ArrayHelper::getColumn($array, 'id'); +``` + +结果将是 `['123', '345']`. + +如果额外的数据装换是必须的或者获取数据的方式是复杂的,第二个参数可以是一个匿名函数: + +```php +$result = ArrayHelper::getColumn($array, function ($element) { + return $element['id']; +}); +``` + + +## 数组索引重建 + +为了索引一个数组是根据一个指定的键名,那`index`方法可以使用.输入的数组应该是多维的或者一个对象数组.这键名可以是每个子数组中的键名,一个对象的属性名, +或者一个匿名函数返回给定的键值数组元素。 + +如果一个键名的值是null,相应的数组元素将会是丢弃的和不会放入到结果中.例如, + +```php +$array = [ + ['id' => '123', 'data' => 'abc'], + ['id' => '345', 'data' => 'def'], +]; +$result = ArrayHelper::index($array, 'id'); +// the result is: +// [ +// '123' => ['id' => '123', 'data' => 'abc'], +// '345' => ['id' => '345', 'data' => 'def'], +// ] + +// using anonymous function +$result = ArrayHelper::index($array, function ($element) { + return $element['id']; +}); +``` + + +## 建立 Maps + + +为了从一个多维数组或者一个对象数组中建立一个map(键值对),你可以使用`map`方法.`$from` 和 `$to` 参数指定键名或者属性名称来组建这个map. +视需要,一个可以进一步地根据一个分组字段`$group`来分组map. + +```php +$array = [ + ['id' => '123', 'name' => 'aaa', 'class' => 'x'], + ['id' => '124', 'name' => 'bbb', 'class' => 'x'], + ['id' => '345', 'name' => 'ccc', 'class' => 'y'], +); + +$result = ArrayHelper::map($array, 'id', 'name'); +// the result is: +// [ +// '123' => 'aaa', +// '124' => 'bbb', +// '345' => 'ccc', +// ] + +$result = ArrayHelper::map($array, 'id', 'name', 'class'); +// the result is: +// [ +// 'x' => [ +// '123' => 'aaa', +// '124' => 'bbb', +// ], +// 'y' => [ +// '345' => 'ccc', +// ], +// ] +``` + + +## 多维排序 + +`multisort` method helps to sort an array of objects or nested arrays by one or several keys. For example, +`multisort` 方法帮助排序一个对象数组或者嵌套的数组,或者几个键名.比如, + +```php +$data = [ + ['age' => 30, 'name' => 'Alexander'], + ['age' => 30, 'name' => 'Brian'], + ['age' => 19, 'name' => 'Barney'], +]; +ArrayHelper::multisort($data, ['age', 'name'], [SORT_ASC, SORT_DESC]); +``` + +排序之后我们将会在`$data`中获取下列的: + +```php +[ + ['age' => 19, 'name' => 'Barney'], + ['age' => 30, 'name' => 'Brian'], + ['age' => 30, 'name' => 'Alexander'], +]; +``` + +第二个参数指定键名来排序,如果它是一个单一的键名,可以是一个字符串,假设很多键名,可以是一个数组,或者一个匿名函数像下列的一个: + +```php +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. + +第三个参数是引导.假设根据一个单一的键名进行排序,它可以是`SORT_ASC`或者`SORT_DESC`中两者之中任一的. +如果是根据多个值进行排序，你可以排序每一个值通过提供一个排序引导数组。 + +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']; +echo ArrayHelper::isIndexed($indexed); + +// all keys are strings +$associative = ['framework' => 'Yii', 'version' => '2.0']; +echo ArrayHelper::isAssociative($associative); +``` + + +## HTML Encoding and Decoding Values + +In order to encode or decode special characters in an array of strings into HTML entities you can use the following: + +```php +$encoded = ArrayHelper::htmlEncode($data); +$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.) + */ + 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 +models in order to serve data arrays via REST API or use it otherwise. The following code could be used to do it: + +```php +$posts = Post::find()->limit(10)->all(); +$data = ArrayHelper::toArray($posts, [ + 'app\models\Post' => [ + 'id', + 'title', + // the key name in array result => property name + 'createTime' => 'created_at', + // the key name in array result => anonymous function + 'length' => function ($post) { + return strlen($post->content); + }, + ], +]); +``` + +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. +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, + 'title' => 'test', + 'createTime' => '2013-01-01 12:00AM', + 'length' => 301, +] +``` + +It is possible to provide default way of converting object to array for a specific class by implementing +[[yii\base\Arrayable|Arrayable]] interface in that class. From 88544d23d7c1296c002c30bac90ca64d99dbaffc Mon Sep 17 00:00:00 2001 From: Xiao Fo Song Date: Fri, 31 Jul 2015 14:23:33 +0800 Subject: [PATCH 2/6] Update helper-array.md --- docs/guide-zh-CN/helper-array.md | 53 +++++++++++--------------------- 1 file changed, 18 insertions(+), 35 deletions(-) diff --git a/docs/guide-zh-CN/helper-array.md b/docs/guide-zh-CN/helper-array.md index e640547693..1642207752 100644 --- a/docs/guide-zh-CN/helper-array.md +++ b/docs/guide-zh-CN/helper-array.md @@ -3,8 +3,6 @@ ArrayHelper [丰富设置的PHP](http://php.net/manual/zh/book.array.php)附加的数组函数，Yii 数组辅助函数提供了额外的静态方法让你更有效率的处理数组。 -## Getting Values - ## 获取值 从一个数组中再获得值， 一个对象或者使用标准PHP是完全的反复由一个复杂结构组成.你不得不首先使用`isset`检查key是否存在,然后如果存在你就获取到了它，如果不存在， @@ -168,7 +166,6 @@ $result = ArrayHelper::map($array, 'id', 'name', 'class'); ## 多维排序 -`multisort` method helps to sort an array of objects or nested arrays by one or several keys. For example, `multisort` 方法帮助排序一个对象数组或者嵌套的数组,或者几个键名.比如, ```php @@ -198,21 +195,14 @@ ArrayHelper::multisort($data, function($item) { }); ``` -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. - 第三个参数是引导.假设根据一个单一的键名进行排序,它可以是`SORT_ASC`或者`SORT_DESC`中两者之中任一的. -如果是根据多个值进行排序，你可以排序每一个值通过提供一个排序引导数组。 +如果是根据多个值进行排序，你可以提供一个改变排序引导的数组，排序每一个值. -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). +最后一个参数是PHP sort flag，你可以通过PHP[sort()](http://php.net/manual/zh/function.sort.php) 中拿相同的值作为其中一个sort flag. +## 检测数组类型 -## 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']; @@ -224,20 +214,16 @@ echo ArrayHelper::isAssociative($associative); ``` -## HTML Encoding and Decoding Values - -In order to encode or decode special characters in an array of strings into HTML entities you can use the following: - +## HTML 编码和解码值 +为了编码或者解码数组中的特殊字符串变成HTML实体,你可以使用下列: ```php $encoded = ArrayHelper::htmlEncode($data); $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. +只有值将会默认为编码的.通过第二个参数诸如`false`,你也可以同样的编码数组的键名.编码将会使用程序的字符集和也可以通过第三个参数修改字符集. - -## Merging Arrays +## 合并数组 ```php /** @@ -257,10 +243,9 @@ Encoding will use application charset and could be changed via third argument. ``` -## 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 -models in order to serve data arrays via REST API or use it otherwise. The following code could be used to do it: +你经常需要将一个对象或者对象数组转换成一个数组.最常见的情况是通过REST API或者在其它方面是为了转换active record模型成服务数据数组.下列的代码可以用来做: ```php $posts = Post::find()->limit(10)->all(); @@ -278,17 +263,16 @@ $data = ArrayHelper::toArray($posts, [ ]); ``` -The first argument contains the data we want to convert. In our case we're converting a `Post` AR model. +这第一个参数包含我们想要转换的数据.在我们的案例中,我们在转换一个`Post` AR 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: +这第二个参数是转换映射每个类.我们设置了一个`Post` model的映射. +每个映射数组包含一系列的映射.每个映射可以是: -- 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 [ @@ -299,5 +283,4 @@ The result of conversion above will be: ] ``` -It is possible to provide default way of converting object to array for a specific class by implementing -[[yii\base\Arrayable|Arrayable]] interface in that class. +它也可能提供对象转换成数组的默认方式是在一个指定类通过继承[[yii\base\Arrayable|Arrayable]]接口. From edd20c3003b567c31d647d181de0839643b03fa2 Mon Sep 17 00:00:00 2001 From: Xiao Fo Song Date: Fri, 31 Jul 2015 14:58:11 +0800 Subject: [PATCH 3/6] Update helper-array.md --- docs/guide-zh-CN/helper-array.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide-zh-CN/helper-array.md b/docs/guide-zh-CN/helper-array.md index 1642207752..da8ba90d52 100644 --- a/docs/guide-zh-CN/helper-array.md +++ b/docs/guide-zh-CN/helper-array.md @@ -5,7 +5,7 @@ ArrayHelper ## 获取值 -从一个数组中再获得值， 一个对象或者使用标准PHP是完全的反复由一个复杂结构组成.你不得不首先使用`isset`检查key是否存在,然后如果存在你就获取到了它，如果不存在， +用原生PHP从一个对象、数组、或者包含这两者的一个复杂数据结构中获取数据是非常繁琐的.你不得不首先使用`isset`检查key是否存在,然后如果存在你就获取到了它，如果不存在， 预设默认值 From 9106a22be4f074adbde1528b9e7e4fed50b7cc77 Mon Sep 17 00:00:00 2001 From: fengyh Date: Mon, 3 Aug 2015 16:43:13 +0800 Subject: [PATCH 4/6] Test push --- docs/guide-zh-CN/helper-array.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) mode change 100644 => 100755 docs/guide-zh-CN/helper-array.md diff --git a/docs/guide-zh-CN/helper-array.md b/docs/guide-zh-CN/helper-array.md old mode 100644 new mode 100755 index da8ba90d52..5b1db79019 --- a/docs/guide-zh-CN/helper-array.md +++ b/docs/guide-zh-CN/helper-array.md @@ -1,7 +1,7 @@ ArrayHelper =========== -[丰富设置的PHP](http://php.net/manual/zh/book.array.php)附加的数组函数，Yii 数组辅助函数提供了额外的静态方法让你更有效率的处理数组。 +除了[PHP中丰富的数组函数集](http://php.net/manual/zh/book.array.php)外，Yii 数组辅助类提供了额外的静态方法，让你更有效率的处理数组。 ## 获取值 From 92c79a38cec722f1effa37329a83104ff4373ecf Mon Sep 17 00:00:00 2001 From: fengyh Date: Mon, 3 Aug 2015 22:20:41 +0800 Subject: [PATCH 5/6] 1st time revision --- docs/guide-zh-CN/helper-array.md | 119 +++++++++++++++---------------- 1 file changed, 59 insertions(+), 60 deletions(-) diff --git a/docs/guide-zh-CN/helper-array.md b/docs/guide-zh-CN/helper-array.md index 5b1db79019..54162d96d7 100755 --- a/docs/guide-zh-CN/helper-array.md +++ b/docs/guide-zh-CN/helper-array.md @@ -1,13 +1,12 @@ -ArrayHelper +ArrayHelper(数组辅助类) =========== 除了[PHP中丰富的数组函数集](http://php.net/manual/zh/book.array.php)外，Yii 数组辅助类提供了额外的静态方法，让你更有效率的处理数组。 + ## 获取值 -用原生PHP从一个对象、数组、或者包含这两者的一个复杂数据结构中获取数据是非常繁琐的.你不得不首先使用`isset`检查key是否存在,然后如果存在你就获取到了它，如果不存在， -预设默认值 - +用原生PHP从一个对象、数组、或者包含这两者的一个复杂数据结构中获取数据是非常繁琐的。你首先得使用`isset` 检查key是否存在, 然后如果存在你就获取它，如果不存在，则提供一个默认值： ```php class User @@ -24,20 +23,19 @@ $array = [ $value = isset($array['foo']['bar']->name) ? $array['foo']['bar']->name : null; ``` -Yii 提供了一个非常方便的方法来处理它: +Yii 提供了一个非常方便的方法来做这件事: ```php $value = ArrayHelper::getValue($array, 'foo.bar.name'); ``` -第一个方法参数是我们从哪里获取值.第二个参数定义如何去获取数据.它可以为一下的其中一个: +方法的第一个参数是我们从哪里获取值。第二个参数指定了如何获取数据，它可以是下述其中的一个： -- 数组键名或者获得值对象的属性名称 -- 使用点号分割的数组key或者对象的属性名称。这个我们已经在上面的案列使用过了 -- 一个回调函数返回一个值 - -这个回调函数应该是下列的: +- 数组键名或者欲从中取值的对象的属性名称； +- 以点号分割的数组键名或者对象属性名称组成的串，上例中使用的参数类型； +- 返回一个值的回调函数。 +该回调函数如下例所示： ```php $fullName = ArrayHelper::getValue($user, function ($user, $defaultValue) { @@ -45,26 +43,26 @@ $fullName = ArrayHelper::getValue($user, function ($user, $defaultValue) { }); ``` -第三个可选择的参数是默认值，如果没有指定第三个参数，默认值是`null`.也可以使用下列的: +第三个可选的参数如果没有给值的话，默认为`null` ，如下例所示: ```php $username = ArrayHelper::getValue($comment, 'user.username', 'Unknown'); ``` - -假设你想要获取值和然后马上从数组中移除它,你可以使用`remove`方法: +对于取到值后想立即从数组中删除的情况，你可以使用 `remove` 方法： ```php $array = ['type' => 'A', 'options' => [1, 2]]; $type = ArrayHelper::remove($array, 'type'); ``` -在执行了代码之后,`$array` 将会等于 `['options' => [1, 2]]` 和 `$type` 将会是 `A`.注意这和`getValue`方法不同,`remove`方法只支持简单的键名. +执行了上述代码之后， `$array` 将包含 `['options' => [1, 2]]` 并且 `$type` 将会是 `A` 。注意这和 `getValue` 方法不同， `remove` 方法只支持简单的键名。 -## 检查键名存在 -`ArrayHelper::keyExists` 工作原理和[array_key_exists](http://php.net/manual/en/function.array-key-exists.php)差不多,除了 -`array_key_exists`同样支持区分大小写键名进行比较.比如: +## 检查键名的存在 + +`ArrayHelper::keyExists` 工作原理和[array_key_exists](http://php.net/manual/en/function.array-key-exists.php)差不多，除了 +它还支持大小写不敏感的键名进行比较，比如： ```php $data1 = [ @@ -82,7 +80,7 @@ if (!ArrayHelper::keyExists('username', $data1, false) || !ArrayHelper::keyExist ## 检索列 -你经常需要从由数据行组成的数组或者对象中获取一列值.通常情况下是根据许多id获取一列数据. +通常你要从多行数据或者对象构成的数组中获取某列的值，一个普通的例子是获取id值列表。 ```php $data = [ @@ -94,7 +92,7 @@ $ids = ArrayHelper::getColumn($array, 'id'); 结果将是 `['123', '345']`. -如果额外的数据装换是必须的或者获取数据的方式是复杂的,第二个参数可以是一个匿名函数: +如果需要额外的转换或者取值的方法比较复杂，第二参数可以指定一个匿名函数： ```php $result = ArrayHelper::getColumn($array, function ($element) { @@ -103,12 +101,12 @@ $result = ArrayHelper::getColumn($array, function ($element) { ``` -## 数组索引重建 +## 重建数组索引 -为了索引一个数组是根据一个指定的键名,那`index`方法可以使用.输入的数组应该是多维的或者一个对象数组.这键名可以是每个子数组中的键名,一个对象的属性名, -或者一个匿名函数返回给定的键值数组元素。 +按一个指定的键名重新索引一个数组，可以用 `index` 方法。输入的数组应该是多维数组或者是一个对象数组。键名（译者注：第二个参数）可以是子数组 +的键名、对象的属性名，也可以是一个返回给定元素数组键值的匿名函数。 -如果一个键名的值是null,相应的数组元素将会是丢弃的和不会放入到结果中.例如, +如果一个键值（译者注：第二个参数对应的键值）是null，相应的数组元素将被丢弃并且不会放入到结果中，例如， ```php $array = [ @@ -129,11 +127,11 @@ $result = ArrayHelper::index($array, function ($element) { ``` -## 建立 Maps +## 建立哈希表 -为了从一个多维数组或者一个对象数组中建立一个map(键值对),你可以使用`map`方法.`$from` 和 `$to` 参数指定键名或者属性名称来组建这个map. -视需要,一个可以进一步地根据一个分组字段`$group`来分组map. +为了从一个多维数组或者一个对象数组中建立一个哈希表(键值对)，你可以使用`map`方法.`$from` 和 `$to` 参数分别指定了欲构建的哈希表的键名和属性名。 +根据需要，你可以按照一个分组字段 `$group` 将map进行分组，例如。 ```php $array = [ @@ -143,7 +141,7 @@ $array = [ ); $result = ArrayHelper::map($array, 'id', 'name'); -// the result is: +// 结果是： // [ // '123' => 'aaa', // '124' => 'bbb', @@ -151,7 +149,7 @@ $result = ArrayHelper::map($array, 'id', 'name'); // ] $result = ArrayHelper::map($array, 'id', 'name', 'class'); -// the result is: +// 结果是： // [ // 'x' => [ // '123' => 'aaa', @@ -166,7 +164,7 @@ $result = ArrayHelper::map($array, 'id', 'name', 'class'); ## 多维排序 -`multisort` 方法帮助排序一个对象数组或者嵌套的数组,或者几个键名.比如, +`multisort` 方法可用来对嵌套数组或者对象数组进行排序，可按一到多个键名排序，比如， ```php $data = [ @@ -177,7 +175,7 @@ $data = [ ArrayHelper::multisort($data, ['age', 'name'], [SORT_ASC, SORT_DESC]); ``` -排序之后我们将会在`$data`中获取下列的: +排序之后我们在 `$data` 中得到的值如下所示： ```php [ @@ -187,7 +185,7 @@ ArrayHelper::multisort($data, ['age', 'name'], [SORT_ASC, SORT_DESC]); ]; ``` -第二个参数指定键名来排序,如果它是一个单一的键名,可以是一个字符串,假设很多键名,可以是一个数组,或者一个匿名函数像下列的一个: +第二个参数指定排序的键名，如果是单键名的话可以是字符串，如果是多键名则是一个数组，或者是如下例所示的一个匿名函数： ```php ArrayHelper::multisort($data, function($item) { @@ -195,57 +193,59 @@ ArrayHelper::multisort($data, function($item) { }); ``` -第三个参数是引导.假设根据一个单一的键名进行排序,它可以是`SORT_ASC`或者`SORT_DESC`中两者之中任一的. +第三个参数表示顺序。单键排序时，它可以是`SORT_ASC`或者`SORT_DESC`之一。如果是按多个键名排序，你可以用一个数组为各个键指定不同的顺序。 如果是根据多个值进行排序，你可以提供一个改变排序引导的数组，排序每一个值. -最后一个参数是PHP sort flag，你可以通过PHP[sort()](http://php.net/manual/zh/function.sort.php) 中拿相同的值作为其中一个sort flag. +最后一个参数（译者注：第四个参数）是PHP的排序标识(sort flag)，可使用的值和调用PHP[sort()](http://php.net/manual/zh/function.sort.php) 函数时传递的值一样。 ## 检测数组类型 -这能够方便的知道一个数组是索引数组还是联合数组.这是一个案例: + +想知道一个数组是索引数组还是联合数组很方便，这有个例子： + ```php -// no keys specified +// 不指定键的数组 $indexed = ['Qiang', 'Paul']; echo ArrayHelper::isIndexed($indexed); -// all keys are strings +// 所有键名都是字符串 $associative = ['framework' => 'Yii', 'version' => '2.0']; echo ArrayHelper::isAssociative($associative); ``` ## HTML 编码和解码值 -为了编码或者解码数组中的特殊字符串变成HTML实体,你可以使用下列: + +为了将字符串数组中的特殊字符做 HTML 编解码，你可以使用下列方法： + ```php $encoded = ArrayHelper::htmlEncode($data); $decoded = ArrayHelper::htmlDecode($data); ``` -只有值将会默认为编码的.通过第二个参数诸如`false`,你也可以同样的编码数组的键名.编码将会使用程序的字符集和也可以通过第三个参数修改字符集. +默认情况只会对值做编码（译者注：原文中是编码，应为编解码）。通过给第二个参数传 `false` ，你也可以对键名做编码。编码将使用应用程序的字符集， +你可以通过第三个参数指定该字符集。 ## 合并数组 + ```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.) + * 将两个或者多个数组递归式的合并为要贯彻。 + * 如果每个数组有一个元素的键名相同，那么后面元素的将覆盖前面的元素（不同于 array_merge_recursive）。 + * 如果两个数组都有相同键名的数组元素（译者注：嵌套数组）则将引发递归合并。 + * 对数值型键名的元素，后面数组中的这些元素会被追加到前面数组中。 + * @param array $a 合并的数组 + * @param array $b 被合并的数组，你可以在第三、第四个参数中指定另外的被合并数组，等等 + * @return 合并的结果数组 (原始数组不会被改变) */ public static function merge($a, $b) ``` -## 对象转换数组 +## 对象转换为数组 -你经常需要将一个对象或者对象数组转换成一个数组.最常见的情况是通过REST API或者在其它方面是为了转换active record模型成服务数据数组.下列的代码可以用来做: +你经常要将一个对象或者对象的数组转换成一个数组，常见的情形是，为了通过REST API提供数据数组或其他使用方式，将AR模型(活动记录模型)转换成数组。如下代码可完成这个工作： ```php $posts = Post::find()->limit(10)->all(); @@ -263,14 +263,14 @@ $data = ArrayHelper::toArray($posts, [ ]); ``` -这第一个参数包含我们想要转换的数据.在我们的案例中,我们在转换一个`Post` AR model. +第一个参数包含我们想要转换的数据，在本例中，我们要转换一个叫 `Post` 的 AR 模型. -这第二个参数是转换映射每个类.我们设置了一个`Post` model的映射. -每个映射数组包含一系列的映射.每个映射可以是: +第二个参数是每个类的转换映射表，我们在此设置了一个`Post` 模型的映射. +每个映射数组包含一组的映射，每个映射可以是: -- 一个字段名称来包含它. -- 一个从哪里拿想要得到的数组名称和模型列的值名称的键-值对 -- 一个键-值对想要获取的数组键名称和一个回调哪些返回值. +- 一个要包含的照原样的字段名（和类中属性的名称一致）； +- 一个由你可随意取名的键名和你想从中取值的模型列名组成的键值对； +- 一个由你可随意取名的键名和有返回值的回调函数组成的键值对； 这上面的转换结果将会是: @@ -282,5 +282,4 @@ $data = ArrayHelper::toArray($posts, [ 'length' => 301, ] ``` - -它也可能提供对象转换成数组的默认方式是在一个指定类通过继承[[yii\base\Arrayable|Arrayable]]接口. +也可以在一个特定的类中实现[[yii\base\Arrayable|Arrayable]]接口，从而为其对象提供默认的转换成数组的方法。 From fb8a9551f6d8c011949c95c4ff46c8bed26a116e Mon Sep 17 00:00:00 2001 From: fengyh Date: Mon, 3 Aug 2015 22:43:16 +0800 Subject: [PATCH 6/6] 2nd time revision --- docs/guide-zh-CN/helper-array.md | 39 ++++++++++++++++---------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/docs/guide-zh-CN/helper-array.md b/docs/guide-zh-CN/helper-array.md index 54162d96d7..357a2e7d8e 100755 --- a/docs/guide-zh-CN/helper-array.md +++ b/docs/guide-zh-CN/helper-array.md @@ -1,12 +1,12 @@ ArrayHelper(数组辅助类) =========== -除了[PHP中丰富的数组函数集](http://php.net/manual/zh/book.array.php)外，Yii 数组辅助类提供了额外的静态方法，让你更有效率的处理数组。 +除了[PHP中丰富的数组函数集](http://php.net/manual/zh/book.array.php)，Yii 数组辅助类提供了额外的静态方法，让你更高效地处理数组。 ## 获取值 -用原生PHP从一个对象、数组、或者包含这两者的一个复杂数据结构中获取数据是非常繁琐的。你首先得使用`isset` 检查key是否存在, 然后如果存在你就获取它，如果不存在，则提供一个默认值： +用原生PHP从一个对象、数组、或者包含这两者的一个复杂数据结构中获取数据是非常繁琐的。你首先得使用`isset` 检查key是否存在, 然后如果存在你就获取它，如果不存在，则提供一个默认返回值： ```php class User @@ -29,13 +29,13 @@ Yii 提供了一个非常方便的方法来做这件事: $value = ArrayHelper::getValue($array, 'foo.bar.name'); ``` -方法的第一个参数是我们从哪里获取值。第二个参数指定了如何获取数据，它可以是下述其中的一个： +方法的第一个参数是我们从哪里获取值。第二个参数指定了如何获取数据，它可以是下述几种类型中的一个： - 数组键名或者欲从中取值的对象的属性名称； -- 以点号分割的数组键名或者对象属性名称组成的串，上例中使用的参数类型； +- 以点号分割的数组键名或者对象属性名称组成的字符串，上例中使用的参数类型就是该类型； - 返回一个值的回调函数。 -该回调函数如下例所示： +回调函数如下例所示： ```php $fullName = ArrayHelper::getValue($user, function ($user, $defaultValue) { @@ -43,26 +43,26 @@ $fullName = ArrayHelper::getValue($user, function ($user, $defaultValue) { }); ``` -第三个可选的参数如果没有给值的话，默认为`null` ，如下例所示: +第三个可选的参数如果没有给定值，则默认为`null` ，如下例所示: ```php $username = ArrayHelper::getValue($comment, 'user.username', 'Unknown'); ``` -对于取到值后想立即从数组中删除的情况，你可以使用 `remove` 方法： +对于取到值后想要立即从数组中删除的情况，你可以使用 `remove` 方法： ```php $array = ['type' => 'A', 'options' => [1, 2]]; $type = ArrayHelper::remove($array, 'type'); ``` -执行了上述代码之后， `$array` 将包含 `['options' => [1, 2]]` 并且 `$type` 将会是 `A` 。注意这和 `getValue` 方法不同， `remove` 方法只支持简单的键名。 +执行了上述代码之后， `$array` 将包含 `['options' => [1, 2]]` 并且 `$type` 将会是 `A` 。注意和 `getValue` 方法不同的是， `remove` 方法只支持简单键名。 ## 检查键名的存在 `ArrayHelper::keyExists` 工作原理和[array_key_exists](http://php.net/manual/en/function.array-key-exists.php)差不多，除了 -它还支持大小写不敏感的键名进行比较，比如： +它还可支持大小写不敏感的键名比较，比如： ```php $data1 = [ @@ -80,7 +80,7 @@ if (!ArrayHelper::keyExists('username', $data1, false) || !ArrayHelper::keyExist ## 检索列 -通常你要从多行数据或者对象构成的数组中获取某列的值，一个普通的例子是获取id值列表。 +通常你要从多行数据或者多个对象构成的数组中获取某列的值，一个普通的例子是获取id值列表。 ```php $data = [ @@ -106,7 +106,7 @@ $result = ArrayHelper::getColumn($array, function ($element) { 按一个指定的键名重新索引一个数组，可以用 `index` 方法。输入的数组应该是多维数组或者是一个对象数组。键名（译者注：第二个参数）可以是子数组 的键名、对象的属性名，也可以是一个返回给定元素数组键值的匿名函数。 -如果一个键值（译者注：第二个参数对应的键值）是null，相应的数组元素将被丢弃并且不会放入到结果中，例如， +如果一个键值（译者注：第二个参数对应的值）是null，相应的数组元素将被丢弃并且不会放入到结果中，例如， ```php $array = [ @@ -130,8 +130,8 @@ $result = ArrayHelper::index($array, function ($element) { ## 建立哈希表 -为了从一个多维数组或者一个对象数组中建立一个哈希表(键值对)，你可以使用`map`方法.`$from` 和 `$to` 参数分别指定了欲构建的哈希表的键名和属性名。 -根据需要，你可以按照一个分组字段 `$group` 将map进行分组，例如。 +为了从一个多维数组或者一个对象数组中建立一个映射表(键值对)，你可以使用`map`方法.`$from` 和 `$to` 参数分别指定了欲构建的映射表的键名和属性名。 +根据需要，你可以按照一个分组字段 `$group` 将映射表进行分组，例如。 ```php $array = [ @@ -193,8 +193,7 @@ ArrayHelper::multisort($data, function($item) { }); ``` -第三个参数表示顺序。单键排序时，它可以是`SORT_ASC`或者`SORT_DESC`之一。如果是按多个键名排序，你可以用一个数组为各个键指定不同的顺序。 -如果是根据多个值进行排序，你可以提供一个改变排序引导的数组，排序每一个值. +第三个参数表示增降顺序。单键排序时，它可以是`SORT_ASC`或者`SORT_DESC`之一。如果是按多个键名排序，你可以用一个数组为各个键指定不同的顺序。 最后一个参数（译者注：第四个参数）是PHP的排序标识(sort flag)，可使用的值和调用PHP[sort()](http://php.net/manual/zh/function.sort.php) 函数时传递的值一样。 @@ -204,7 +203,7 @@ ArrayHelper::multisort($data, function($item) { 想知道一个数组是索引数组还是联合数组很方便，这有个例子： ```php -// 不指定键的数组 +// 不指定键名的数组 $indexed = ['Qiang', 'Paul']; echo ArrayHelper::isIndexed($indexed); @@ -223,7 +222,7 @@ $encoded = ArrayHelper::htmlEncode($data); $decoded = ArrayHelper::htmlDecode($data); ``` -默认情况只会对值做编码（译者注：原文中是编码，应为编解码）。通过给第二个参数传 `false` ，你也可以对键名做编码。编码将使用应用程序的字符集， +默认情况只会对值做编码（译者注：原文中是编码，应为编解码）。通过给第二个参数传 `false` ，你也可以对键名做编码。编码将默认使用应用程序的字符集， 你可以通过第三个参数指定该字符集。 ## 合并数组 @@ -235,8 +234,8 @@ $decoded = ArrayHelper::htmlDecode($data); * 如果每个数组有一个元素的键名相同，那么后面元素的将覆盖前面的元素（不同于 array_merge_recursive）。 * 如果两个数组都有相同键名的数组元素（译者注：嵌套数组）则将引发递归合并。 * 对数值型键名的元素，后面数组中的这些元素会被追加到前面数组中。 - * @param array $a 合并的数组 - * @param array $b 被合并的数组，你可以在第三、第四个参数中指定另外的被合并数组，等等 + * @param array $a 被合并的数组 + * @param array $b 合并的数组，你可以在第三、第四个参数中指定另外的合并数组，等等 * @return 合并的结果数组 (原始数组不会被改变) */ public static function merge($a, $b) @@ -245,7 +244,7 @@ $decoded = ArrayHelper::htmlDecode($data); ## 对象转换为数组 -你经常要将一个对象或者对象的数组转换成一个数组，常见的情形是，为了通过REST API提供数据数组或其他使用方式，将AR模型(活动记录模型)转换成数组。如下代码可完成这个工作： +你经常要将一个对象或者对象的数组转换成一个数组，常见的情形是，为了通过REST API提供数据数组（或其他使用方式），将AR模型(活动记录模型)转换成数组。如下代码可完成这个工作： ```php $posts = Post::find()->limit(10)->all();