diff --git a/docs/guide-es/README.md b/docs/guide-es/README.md index 20039bc..9ba5745 100644 --- a/docs/guide-es/README.md +++ b/docs/guide-es/README.md @@ -168,7 +168,7 @@ Temas especiales * **TBD** [Plantilla aplicación avanzada](tutorial-advanced-app.md) * **TBD** [Creación de una aplicación desde cero](tutorial-start-from-scratch.md) * **TBD** [Comandos de consola](tutorial-console.md) -* **TBD** [Validadores de base](tutorial-core-validators.md) +* [Validadores del núcleo](tutorial-core-validators.md) * **TBD** [Internacionalización](tutorial-i18n.md) * **TBD** [Envío de correos electrónicos](tutorial-mailing.md) * **TBD** [Mejora del rendimiento](tutorial-performance-tuning.md) @@ -180,14 +180,14 @@ Temas especiales Widgets ------- -* GridView: link to demo page -* ListView: link to demo page -* DetailView: link to demo page -* ActiveForm: link to demo page -* Pjax: link to demo page -* Menu: link to demo page -* LinkPager: link to demo page -* LinkSorter: link to demo page +* GridView: **TBD** link to demo page +* ListView: **TBD** link to demo page +* DetailView: **TBD** link to demo page +* ActiveForm: **TBD** link to demo page +* Pjax: **TBD** link to demo page +* Menu: **TBD** link to demo page +* LinkPager: **TBD** link to demo page +* LinkSorter: **TBD** link to demo page * **TBD** [Bootstrap Widgets](bootstrap-widgets.md) * **TBD** [Jquery UI Widgets](jui-widgets.md) @@ -196,6 +196,6 @@ Clases auxiliares ----------------- * [Información general](helper-overview.md) -* **TBD** [ArrayHelper](helper-array.md) +* [ArrayHelper](helper-array.md) * [Html](helper-html.md) * [Url](helper-url.md) diff --git a/docs/guide-es/helper-array.md b/docs/guide-es/helper-array.md new file mode 100644 index 0000000..9437b88 --- /dev/null +++ b/docs/guide-es/helper-array.md @@ -0,0 +1,304 @@ +ArrayHelper +=========== + +Adicionalmente al [rico conjunto de funciones para arrays de PHP](http://php.net/manual/es/book.array.php) Yii array helper proporciona +métodos estáticos adicionales permitiendo trabajar con arrays de manera más eficiente. + + +## Devolviendo Valores <a name="getting-values"></a> + +Recuperar valores de un array, un objeto o una estructura compleja usando PHP estándar es bastante +repetitivo. Tienes que comprobar primero si una clave existe con `isset`, después devolver el valor si existe, si no, +devolver un valor por defecto: + +```php +class User +{ + public $name = 'Alex'; +} + +$array = [ + 'foo' => [ + 'bar' => new User(), + ] +]; + +$value = isset($array['foo']['bar']->name) ? $array['foo']['bar']->name : null; +``` + +Yii proviene de un método muy conveniente para hacerlo: + +```php +$value = ArrayHelper::getValue($array, 'foo.bar.name'); +``` + +El primer argumento del método es de donde vamos a obtener el valor. El segundo argumento especifica como devolver el dato. Puede ser +de la siguiente manera: + +- Nombre de la clave del array o de la propiedad del objeto para recuperar el valor. +- Conjunto de puntos separados por las claves del array o los nombres de las propiedades del objeto. Esto se ha usado en el ejemplo anterior. +- Un callback que devuelve un valor. + +El callback se debería usar de la siguiente manera: + +```php +$fullName = ArrayHelper::getValue($user, function ($user, $defaultValue) { + return $user->firstName . ' ' . $user->lastName; +}); +``` + +El tercer argumento opcional es el valor por defecto el cual es `null` si no se especifica. Podría ser utilizado de la siguiente manera: + +```php +$username = ArrayHelper::getValue($comment, 'user.username', 'Unknown'); +``` + +En caso de que quieras coger un valor y luego removerlo inmediatamente del array puedes usar el método `remove`: + +```php +$array = ['type' => 'A', 'options' => [1, 2]]; +$type = ArrayHelper::remove($array, 'type'); +``` + +Después de ejecutar el código el `$array` contendrá `['options' => [1, 2]]` y `$type` debe ser `A`. Tenga en cuenta que a diferencia del método +`getValue`, `remove` solo soporta nombres clave simples. + + +## Comprobando la Existencia de Claves <a name="checking-existence-of-keys"></a> + +`ArrayHelper::keyExists` funciona de la misma manera que [array_key_exists](http://php.net/manual/es/function.array-key-exists.php) +excepto que también soporta case-insensitive para la comparación de claves. Por ejemplo, + +```php +$data1 = [ + 'userName' => 'Alex', +]; + +$data2 = [ + 'username' => 'Carsten', +]; + +if (!ArrayHelper::keyExists('username', $data1, false) || !ArrayHelper::keyExists('username', $data2, false)) { + echo "Please provide username."; +} +``` + +## Recuperando Columnas <a name="retrieving-columns"></a> + +A menudo necesitas obtener unos valores de una columna de las filas de datos u objetos de un array. Un ejemplo común es obtener una lista de IDs. + +```php +$data = [ + ['id' => '123', 'data' => 'abc'], + ['id' => '345', 'data' => 'def'], +]; +$ids = ArrayHelper::getColumn($array, 'id'); +``` + +El resultado será `['123', '345']`. + +Si se requieren transformaciones adicionales o la manera de obtener el valor es complejo, se podría especificar como segundo argumento +una función anónima : + +```php +$result = ArrayHelper::getColumn($array, function ($element) { + return $element['id']; +}); +``` + + +## Re-indexar Arrays <a name="reindexing-arrays"></a> + +Con el fin de indexar un array según una clave especificada, se puede usar el método `index`. La entrada del array debe ser +multidimensional o un array de objetos. La clave puede ser un nombre clave del sub-array, un nombre de una propiedad del objeto, o +una función anónima que retorne el valor de la clave dado el elemento del array. + +Si el valor de la clave es null, el correspondiente elemento del array será desechado y no se pondrá en el resultado. Por ejemplo, + +```php +$array = [ + ['id' => '123', 'data' => 'abc'], + ['id' => '345', 'data' => 'def'], +]; +$result = ArrayHelper::index($array, 'id'); +// el resultado es: +// [ +// '123' => ['id' => '123', 'data' => 'abc'], +// '345' => ['id' => '345', 'data' => 'def'], +// ] + +// usando función anónima +$result = ArrayHelper::index($array, function ($element) { + return $element['id']; +}); +``` + + +## Construyendo Mapas (Maps) <a name="building-maps"></a> + +Con el fin de construir un mapa (pareja clave-valor) de un array multidimensional o un array de objetos puedes usar el método `map`. +Los parámetros `$from` y `$to` especifican los nombres de las claves o los nombres de las propiedades que serán configuradas en el mapa. Opcionalmente, se puede +agrupar en el mapa de acuerdo al campo de agrupamiento `$group`. Por ejemplo, + +```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'); +// el resultado es: +// [ +// '123' => 'aaa', +// '124' => 'bbb', +// '345' => 'ccc', +// ] + +$result = ArrayHelper::map($array, 'id', 'name', 'class'); +// el resultado es: +// [ +// 'x' => [ +// '123' => 'aaa', +// '124' => 'bbb', +// ], +// 'y' => [ +// '345' => 'ccc', +// ], +// ] +``` + + +## Ordenamiento Multidimensional <a name="multidimensional-sorting"></a> + +El método `multisort` ayuda a ordenar un array de objetos o arrays anidados por una o varias claves. Por ejemplo, + +```php +$data = [ + ['age' => 30, 'name' => 'Alexander'], + ['age' => 30, 'name' => 'Brian'], + ['age' => 19, 'name' => 'Barney'], +]; +ArrayHelper::multisort($data, ['age', 'name'], [SORT_ASC, SORT_DESC]); +``` + +Después del ordenado obtendremos lo siguiente en `$data`: + +```php +[ + ['age' => 19, 'name' => 'Barney'], + ['age' => 30, 'name' => 'Brian'], + ['age' => 30, 'name' => 'Alexander'], +]; +``` + +El segundo argumento que especifica las claves para ordenar puede ser una cadena si se trata de una clave, un array en caso de que tenga múltiples claves +o una función anónima como la siguiente + +```php +ArrayHelper::multisort($data, function($item) { + return isset($item['age']) ? ['age', 'name'] : 'name'; +}); +``` + +El tercer argumento es la dirección. En caso de ordenar por una clave podría ser `SORT_ASC` o +`SORT_DESC`. Si ordenas por múltiples valores puedes ordenar cada valor diferentemente proporcionando un array de +direcciones de ordenación. + +El último argumento es un PHP sort flag que toma los mismos valores que los pasados a +PHP [sort()](http://php.net/manual/es/function.sort.php). + + +## Detectando Tipos de Array <a name="detecting-array-types"></a> + +Es muy útil saber si un array es indexado o asociativo. He aquí un ejemplo: + +```php +// sin claves especificadas +$indexed = ['Qiang', 'Paul']; +echo ArrayHelper::isIndexed($indexed); + +// todas las claves son strings +$associative = ['framework' => 'Yii', 'version' => '2.0']; +echo ArrayHelper::isAssociative($associative); +``` + + +## Codificación y Decodificación de Valores HTML <a name="html-encoding-values"></a> + +Con el fin de codificar o decodificar caracteres especiales en un array de strings con entidades HTML puedes usar lo siguiente: + +```php +$encoded = ArrayHelper::htmlEncode($data); +$decoded = ArrayHelper::htmlDecode($data); +``` + +Solo los valores se codifican por defecto. Pasando como segundo argumento `false` puedes codificar un array de claves también. +La codificación utilizará el charset de la aplicación y podría ser cambiado pasandole un tercer argumento. + + +## Fusionando Arrays <a name="merging-arrays"></a> + +```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) +``` + + +## Convirtiendo Objetos a Arrays <a name="converting-objects-to-arrays"></a> + +A menudo necesitas convertir un objeto o un array de objetos a un array. El caso más común es convertir los modelos de +active record con el fin de servir los arrays de datos vía API REST o utilizarlos de otra manera. El siguiente código +se podría utilizar para hacerlo: + +```php +$posts = Post::find()->limit(10)->all(); +$data = ArrayHelper::toArray($post, [ + 'app\models\Post' => [ + 'id', + 'title', + // el nombre de la clave del resultado del array => nombre de la propiedad + 'createTime' => 'created_at', + // el nombre de la clave del resultado del array => función anónima + 'length' => function ($post) { + return strlen($post->content); + }, + ], +]); +``` + +El primer argumento contiene el dato que queremos convertir. En nuestro caso queremos convertir un modelo AR `Post`. + +El segundo argumento es el mapeo de conversión por clase. Estamos configurando un mapeo para el modelo `Post`. +Cada array de mapeo contiene un conjunto de mapeos. Cada mapeo podría ser: + +- Un campo nombre para incluir como está. +- Un par clave-valor del array deseado con un nombre clave y el nombre de la columna del modelo que tomará el valor. +- Un par clave-valor del array deseado con un nombre clave y una función anónima que retorne el valor. + +El resultado de la conversión anterior será: + + +```php +[ + 'id' => 123, + 'title' => 'test', + 'createTime' => '2013-01-01 12:00AM', + 'length' => 301, +] +``` + +Es posible proporcionar una manera predeterminada de convertir un objeto a un array para una clase especifica +mediante la implementación de la interfaz [[yii\base\Arrayable|Arrayable]] en esa clase.