Browse Source

Merge branch 'master' into 2.1

# Conflicts:
#	framework/di/Instance.php
#	tests/framework/filters/AccessRuleTest.php
tags/3.0.0-alpha1
Alexander Makarov 8 years ago
parent
commit
f8cf1e2b6a
  1. 2
      .travis.yml
  2. 2
      build/controllers/ReleaseController.php
  3. 2
      composer.json
  4. 40
      docs/guide-es/db-migrations.md
  5. 5
      docs/guide-es/helper-array.md
  6. 2
      docs/guide-es/start-installation.md
  7. 8
      docs/guide-es/test-fixtures.md
  8. 2
      docs/guide-es/tutorial-start-from-scratch.md
  9. 2
      docs/guide-es/tutorial-yii-integration.md
  10. 30
      docs/guide-fr/concept-aliases.md
  11. 147
      docs/guide-fr/intro-upgrade-from-v1.md
  12. 40
      docs/guide-fr/start-databases.md
  13. 97
      docs/guide-fr/structure-application-components.md
  14. 517
      docs/guide-fr/structure-applications.md
  15. 364
      docs/guide-fr/structure-controllers.md
  16. 34
      docs/guide-fr/structure-entry-scripts.md
  17. 430
      docs/guide-fr/structure-models.md
  18. 225
      docs/guide-fr/structure-modules.md
  19. 8
      docs/guide-fr/structure-overview.md
  20. 588
      docs/guide-fr/structure-views.md
  21. 655
      docs/guide-fr/tutorial-i18n.md
  22. 4
      docs/guide-id/start-installation.md
  23. 2
      docs/guide-it/start-installation.md
  24. 32
      docs/guide-ja/concept-di-container.md
  25. 42
      docs/guide-ja/db-migrations.md
  26. 13
      docs/guide-ja/helper-array.md
  27. 8
      docs/guide-ja/input-multiple-models.md
  28. 27
      docs/guide-ja/rest-response-formatting.md
  29. 32
      docs/guide-ja/start-installation.md
  30. 1
      docs/guide-ja/structure-entry-scripts.md
  31. 2
      docs/guide-ja/structure-modules.md
  32. 2
      docs/guide-ja/structure-views.md
  33. 4
      docs/guide-ja/structure-widgets.md
  34. 8
      docs/guide-ja/test-fixtures.md
  35. 2
      docs/guide-ja/tutorial-start-from-scratch.md
  36. 2
      docs/guide-ja/tutorial-yii-integration.md
  37. 4
      docs/guide-pl/start-installation.md
  38. 2
      docs/guide-pl/tutorial-start-from-scratch.md
  39. 2
      docs/guide-pt-BR/start-installation.md
  40. 2
      docs/guide-pt-BR/tutorial-yii-integration.md
  41. 34
      docs/guide-ru/db-migrations.md
  42. 7
      docs/guide-ru/helper-array.md
  43. 2
      docs/guide-ru/input-multiple-models.md
  44. 2
      docs/guide-ru/output-sorting.md
  45. 2
      docs/guide-ru/output-theming.md
  46. 2
      docs/guide-ru/rest-resources.md
  47. 2
      docs/guide-ru/start-installation.md
  48. 2
      docs/guide-ru/structure-applications.md
  49. 8
      docs/guide-ru/test-fixtures.md
  50. 2
      docs/guide-ru/tutorial-start-from-scratch.md
  51. 2
      docs/guide-ru/tutorial-yii-integration.md
  52. 2
      docs/guide-uk/start-installation.md
  53. 4
      docs/guide-uk/tutorial-start-from-scratch.md
  54. 2
      docs/guide-uk/tutorial-yii-integration.md
  55. 2
      docs/guide-vi/start-installation.md
  56. 2
      docs/guide-zh-CN/start-installation.md
  57. 4
      docs/guide/caching-data.md
  58. 4
      docs/guide/caching-page.md
  59. 2
      docs/guide/concept-configurations.md
  60. 31
      docs/guide/concept-di-container.md
  61. 46
      docs/guide/db-migrations.md
  62. 87
      docs/guide/helper-array.md
  63. 4
      docs/guide/helper-html.md
  64. 10
      docs/guide/input-multiple-models.md
  65. 2
      docs/guide/intro-upgrade-from-v1.md
  66. 2
      docs/guide/rest-controllers.md
  67. 8
      docs/guide/rest-quick-start.md
  68. 32
      docs/guide/rest-response-formatting.md
  69. 2
      docs/guide/runtime-handling-errors.md
  70. 39
      docs/guide/start-installation.md
  71. 2
      docs/guide/structure-assets.md
  72. 4
      docs/guide/structure-controllers.md
  73. 1
      docs/guide/structure-entry-scripts.md
  74. 281
      docs/guide/structure-modules.md
  75. 2
      docs/guide/structure-views.md
  76. 5
      docs/guide/structure-widgets.md
  77. 8
      docs/guide/test-fixtures.md
  78. 7
      docs/guide/tutorial-i18n.md
  79. 2
      docs/guide/tutorial-performance-tuning.md
  80. 2
      docs/guide/tutorial-start-from-scratch.md
  81. 2
      docs/guide/tutorial-yii-integration.md
  82. 43
      docs/internals-ja/README.md
  83. 5
      docs/internals-ja/automation.md
  84. 8
      docs/internals-ja/core-code-style.md
  85. BIN
      docs/internals-ja/exception_hierarchy.png
  86. BIN
      docs/internals-ja/exception_hierarchy.vsd
  87. 4
      docs/internals-ja/git-workflow.md
  88. 33
      docs/internals-ja/project-organization.md
  89. 6
      docs/internals-ja/pull-request-qa.md
  90. 79
      docs/internals-ja/release.md
  91. BIN
      docs/internals-ja/schema-builder-patterns.xlsx
  92. 4
      docs/internals-ja/translation-status.md
  93. 65
      docs/internals-ja/translation-teams.md
  94. BIN
      docs/internals-ja/versions-branches.png
  95. 82
      docs/internals-ja/versions.md
  96. 4
      docs/internals-ja/view-code-style.md
  97. 2
      docs/internals-ru/git-workflow.md
  98. 5
      docs/internals-sr-Latn/automation.md
  99. 50
      docs/internals-sr-Latn/git-workflow.md
  100. 2
      docs/internals-sr-Latn/report-an-issue.md
  101. Some files were not shown because too many files have changed in this diff Show More

2
.travis.yml

@ -33,7 +33,7 @@ addons:
install:
- travis_retry composer self-update && composer --version
- travis_retry composer global require "fxp/composer-asset-plugin:~1.1.1"
- travis_retry composer global require "fxp/composer-asset-plugin:^1.2.0"
- export PATH="$HOME/.composer/vendor/bin:$PATH"
# core framework:
- travis_retry composer install --prefer-dist --no-interaction

2
build/controllers/ReleaseController.php

@ -437,7 +437,7 @@ class ReleaseController extends Controller
$this->runGit("git push --tags", $frameworkPath);
$this->stdout("\n\n");
$this->stdout("CONGRATULATIONS! You have just released extension ", Console::FG_YELLOW, Console::BOLD);
$this->stdout("CONGRATULATIONS! You have just released ", Console::FG_YELLOW, Console::BOLD);
$this->stdout('framework', Console::FG_RED, Console::BOLD);
$this->stdout(" version ", Console::FG_YELLOW, Console::BOLD);
$this->stdout($version, Console::BOLD);

2
composer.json

@ -68,7 +68,7 @@
"yiisoft/yii2-composer": "~2.0.4",
"ezyang/htmlpurifier": "~4.6",
"cebe/markdown": "~1.0.0 | ~1.1.0",
"bower-asset/jquery": "2.2.*@stable | 2.1.*@stable | 1.11.*@stable",
"bower-asset/jquery": "2.2.*@stable | 2.1.*@stable | 1.11.*@stable | 1.12.*@stable",
"bower-asset/jquery.inputmask": "~3.2.2",
"bower-asset/punycode": "1.3.*",
"bower-asset/yii2-pjax": "~2.0.1"

40
docs/guide-es/db-migrations.md

@ -185,14 +185,14 @@ Existe una lista de todos los métodos disponibles para la definición de tipos
Desde la versión 2.0.7 la consola provee una manera muy conveniente de generar migraciones.
Si el nombre de la migración tiene una forma especial, por ejemplo `create_xxx` o `drop_xxx` entonces el archivo de la migración generada
Si el nombre de la migración tiene una forma especial, por ejemplo `create_xxx_table` o `drop_xxx_table` entonces el archivo de la migración generada
contendrá código extra, en este caso para crear/eliminar tablas.
A continuación se describen todas estas variantes.
### Crear Tabla
```php
yii migrate/create create_post
yii migrate/create create_post_table
```
esto genera
@ -201,7 +201,7 @@ esto genera
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -226,7 +226,7 @@ class m150811_220037_create_post extends Migration
Para crear las columnas en ese momento, las puedes especificar vía la opción `--fields`.
```php
yii migrate/create create_post --fields="title:string,body:text"
yii migrate/create create_post_table --fields="title:string,body:text"
```
genera
@ -235,7 +235,7 @@ genera
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -263,7 +263,7 @@ class m150811_220037_create_post extends Migration
Puedes especificar más parámetros para las columnas.
```php
yii migrate/create create_post --fields="title:string(12):notNull:unique,body:text"
yii migrate/create create_post_table --fields="title:string(12):notNull:unique,body:text"
```
genera
@ -272,7 +272,7 @@ genera
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -304,7 +304,7 @@ class m150811_220037_create_post extends Migration
Desde 2.0.8 el generador soporta claves foráneas utilizando la palabra clave `foreignKey`.
```php
yii migrate/create create_post --fields="author_id:integer:notNull:foreignKey(user),category_id:integer:defaultValue(1):foreignKey,title:string,body:text"
yii migrate/create create_post_table --fields="author_id:integer:notNull:foreignKey(user),category_id:integer:defaultValue(1):foreignKey,title:string,body:text"
```
genera
@ -317,7 +317,7 @@ genera
* - `user`
* - `category`
*/
class m160328_040430_create_post extends Migration
class m160328_040430_create_post_table extends Migration
{
/**
* @inheritdoc
@ -422,13 +422,13 @@ una columna llamada `author_id` con una clave foránea a la tabla `user` mientra
### Eliminar Tabla
```php
yii migrate/create drop_post --fields="title:string(12):notNull:unique,body:text"
yii migrate/create drop_post_table --fields="title:string(12):notNull:unique,body:text"
```
genera
```php
class m150811_220037_drop_post extends Migration
class m150811_220037_drop_post_table extends Migration
{
public function up()
{
@ -448,19 +448,19 @@ class m150811_220037_drop_post extends Migration
### Agregar Columna
Si el nombre de la migración está en la forma `add_xxx_to_yyy` entonces el archivo generado contendrá
Si el nombre de la migración está en la forma `add_xxx_column_to_yyy_table` entonces el archivo generado contendrá
las declaraciones `addColumn` y `dropColumn` necesarias.
Para agregar una columna:
```php
yii migrate/create add_position_to_post --fields="position:integer"
yii migrate/create add_position_column_to_post_table --fields="position:integer"
```
genera
```php
class m150811_220037_add_position_to_post extends Migration
class m150811_220037_add_position_column_to_post_table extends Migration
{
public function up()
{
@ -476,17 +476,17 @@ class m150811_220037_add_position_to_post extends Migration
### Eliminar Columna
Si el nombre de la migración está en la forma `drop_xxx_from_yyy` entonces el archivo generado contendrá
Si el nombre de la migración está en la forma `drop_xxx_column_from_yyy_table` entonces el archivo generado contendrá
las declaraciones `addColumn` y `dropColumn` necesarias.
```php
yii migrate/create drop_position_from_post --fields="position:integer"
yii migrate/create drop_position_column_from_post_table --fields="position:integer"
```
genera
```php
class m150811_220037_drop_position_from_post extends Migration
class m150811_220037_drop_position_column_from_post_table extends Migration
{
public function up()
{
@ -502,11 +502,11 @@ class m150811_220037_drop_position_from_post extends Migration
### Agregar Tabla de Unión
Si el nombre de la migración está en la forma `create_junction_xxx_and_yyy` entonces se generará el código necesario
Si el nombre de la migración está en la forma `create_junction_table_for_xxx_and_yyy_tables` entonces se generará el código necesario
para una tabla de unión.
```php
yii migrate/create create_junction_post_and_tag --fields="created_at:dateTime"
yii migrate/create create_junction_table_for_post_and_tag_tables --fields="created_at:dateTime"
```
genera
@ -519,7 +519,7 @@ genera
* - `post`
* - `tag`
*/
class m160328_041642_create_junction_post_and_tag extends Migration
class m160328_041642_create_junction_table_for_post_and_tag_tables extends Migration
{
/**
* @inheritdoc

5
docs/guide-es/helper-array.md

@ -371,8 +371,9 @@ mediante la implementación de la interfaz [[yii\base\Arrayable|Arrayable]] en e
A menudo necesitarás comprobar está en un array o un grupo de elementos es un sub-grupo de otro.
A pesar de que PHP ofrece `in_array()`, este no soporta sub-grupos u objetos de tipo `\Traversable`.
Para ayudar en este tipo de pruebas, [[yii\base\ArrayHelper]] provee [[yii\base\ArrayHelper::isIn()|isIn()]]
y [[yii\base\ArrayHelper::isSubset()|isSubset()]] con la misma firma del método [[in_array()]].
Para ayudar en este tipo de pruebas, [[yii\helpers\ArrayHelper]] provee [[yii\helpers\ArrayHelper::isIn()|isIn()]]
y [[yii\helpers\ArrayHelper::isSubset()|isSubset()]] con la misma firma del método
[in_array()](http://php.net/manual/en/function.in-array.php).
```php
// true

2
docs/guide-es/start-installation.md

@ -40,7 +40,7 @@ ejecutando el comando `composer self-update`
Teniendo Composer instalado, puedes instalar Yii ejecutando los siguientes comandos en un directorio accesible vía Web:
```bash
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
```

8
docs/guide-es/test-fixtures.md

@ -310,7 +310,7 @@ yii fixture/load User
yii fixture User
// carga varios fixtures
yii fixture User UserProfile
yii fixture "User, UserProfile"
// carga todos los fixtures
yii fixture/load "*"
@ -319,7 +319,7 @@ yii fixture/load "*"
yii fixture "*"
// carga todos los fixtures excepto uno
yii fixture "*" -DoNotLoadThisOne
yii fixture "*, -DoNotLoadThisOne"
// carga fixtures, pero los busca en diferente espacio de nombre. El espacio de nombre por defecto es: tests\unit\fixtures.
yii fixture User --namespace='alias\my\custom\namespace'
@ -340,13 +340,13 @@ Para descargar un fixture, ejecuta el siguiente comando:
yii fixture/unload User
// descarga varios fixtures
yii fixture/unload User,UserProfile
yii fixture/unload "User, UserProfile"
// descarga todos los fixtures
yii fixture/unload "*"
// descarga todos los fixtures excepto uno
yii fixture/unload "*" -DoNotUnloadThisOne
yii fixture/unload "*, -DoNotUnloadThisOne"
```

2
docs/guide-es/tutorial-start-from-scratch.md

@ -50,6 +50,6 @@ Utilizar el Template
Eso es todo lo que se necesita para crear un nuevo template de proyecto Yii. Ahora puedes crear tus propios proyectos a partir de este template:
```
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist --stability=dev mysoft/yii2-app-coolone new-project
```

2
docs/guide-es/tutorial-yii-integration.md

@ -82,7 +82,7 @@ instalar Yii , e iniciar Yii.
Si el sistema de terceros usa Composer para manejar sus dependencias, simplemente ejecuta estos comandos
para instalar Yii:
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer require yiisoft/yii2
composer install

30
docs/guide-fr/concept-aliases.md

@ -1,6 +1,7 @@
Les Alias
=========
Les alias sont utilisés pour représenter des chemins de fichier ou des URLs de sorte que vous n'ayez pas à spécifier des chemins ou des URLs explicitement dans votre projet. Un alias doit commencer par le caractère `@` de façon à le différencier des chemins de fichiers habituels et des URLs. Yii dispose déjà d'un nombre important d'alias prédéfinis. Par exemple, l'alias `@yii` représéente le chemin d'installation du framework Yii; `@web` représente l'URL de base pour l'application web courante.
Les alias sont utilisés pour représenter des chemins de fichier ou des URLs de sorte que vous n'ayez pas à spécifier des chemins ou des URLs explicitement dans votre projet. Un alias doit commencer par le caractère `@` de façon à le différencier des chemins de fichiers habituels et des URLs. Les alias définis sans le caractère de tête `@` seront préfixés avec ce caractère `@`.
Yii dispose déjà d'un nombre important d'alias prédéfinis. Par exemple, l'alias `@yii` représente le chemin d'installation du *framework* Yii; `@web` représente l'URL de base pour l'application web courante.
@ -18,15 +19,15 @@ Yii::setAlias('@bar', 'http://www.example.com');
```
> Note: le chemin de fichier ou l'URL cible de l'alias *ne* doit *pas* nécessairement référencer un fichier ou une ressource existante.
Etant donné un alias défini, il est possible de faire dériver un nouvel alias (sans appeler la commande [[Yii::setAlias()]]) en ajoutant une barre oblique `/` suivi d'un ou de plusieurs segments de chemin de fichier. Les alias définis via la commande [[Yii::setAlias()]] sont des *alias racines*, les alias qui en dérivent sont des *alias dérivés*. Par example, `@foo` est un alias racine, tandis que `@foo/bar/file.php` est un alias dérivé.
Étant donné un alias défini, il est possible de faire dériver un nouvel alias (sans appeler la commande [[Yii::setAlias()]]) en ajoutant une barre oblique `/` suivi d'un ou de plusieurs segments de chemin de fichier. Les alias définis via la commande [[Yii::setAlias()]] sont des *alias racines*, les alias qui en dérivent sont des *alias dérivés*. Par exemple, `@foo` est un alias racine, tandis que `@foo/bar/file.php` est un alias dérivé.
Il est possible de définir une alias en utilisant un autre alias (qu'il soit racine ou dérivé):
Il est possible de définir un alias en utilisant un autre alias (qu'il soit racine ou dérivé):
```php
Yii::setAlias('@foobar', '@foo/bar');
```
Les alias racines sont habituellement définit pendant l'étape d'[amorçage](runtime-bootstrapping.md). Vous pouvez par exemple appeler la commande [[Yii::setAlias()]] dans le [script d'entrée](structure-entry-scripts.md). Pour plus de commodité, [Application](structure-applications.md) propose une propriété modifiable appelée `aliases` que vous pouvez définir dans la [configuration](concept-configurations.md) de l'application:
Les alias racines sont habituellement définis pendant l'étape d'[amorçage](runtime-bootstrapping.md). Vous pouvez par exemple appeler la commande [[Yii::setAlias()]] dans le [script d'entrée](structure-entry-scripts.md). Pour plus de commodité, l'objet [Application](structure-applications.md) propose une propriété modifiable appelée `aliases` que vous pouvez définir dans la [configuration](concept-configurations.md) de l'application:
```php
return [
@ -49,10 +50,10 @@ echo Yii::getAlias('@bar'); // displays: http://www.example.com
echo Yii::getAlias('@foo/bar/file.php'); // displays: /path/to/foo/bar/file.php
```
Le chemin/URL représenté par un alias dérivé est déterminé en renplaçant la partie alias racine avec son chemain/URL correspondant dans l'alias dérivé.
> Note: La méthode [[Yii::getAlias()]] ne vérifie pas si le chemin/URL obtenu représente un fichier ou une ressource existante.
Le chemin/URL représenté par un alias dérivé est déterminé en remplaçant la partie alias racine avec son chemin/URL correspondant dans l'alias dérivé.
> Note: la méthode [[Yii::getAlias()]] ne vérifie pas si le chemin/URL obtenu représente un fichier ou une ressource existante.
Un alias racine peut également conctenir des barres obliques `/`. La méthode [[Yii::getAlias()]] est suffisement intelligeante pour déterminer quelle part de l'alias est un alias racine et donc détermine correctement le chemin de fichier ou l'url correspondant:
Un alias racine peut également contenir des barres obliques `/`. La méthode [[Yii::getAlias()]] est suffisamment intelligente pour déterminer quelle partie de l'alias est un alias racine et donc déterminer correctement le chemin de fichier ou l'url correspondant:
```php
Yii::setAlias('@foo', '/chemin/vers/foo');
@ -61,7 +62,7 @@ Yii::getAlias('@foo/test/file.php'); // affiche /chemin/vers/foo/test/file.php
Yii::getAlias('@foo/bar/file.php'); // affiche /chemin2/bar/file.php
```
Si `@foo/bar` n'est pas défini comme un alias racine, le dernier exemple affichierait `/chemin/vers/foo/bar/file.php`.
Si `@foo/bar` n'était pas défini comme un alias racine, le dernier exemple afficherait `/chemin/vers/foo/bar/file.php`.
Utilisation des alias <span id="using-aliases"></span>
@ -76,7 +77,7 @@ $cache = new FileCache([
'cachePath' => '@runtime/cache',
]);
```
Merci de porter attention à la documentation de l'API pour vérifier si une propriété ou un paramètre d'une méthode supporte les alias.
Reportez-vous à la documentation de l'API pour vérifier si une propriété ou un paramètre d'une méthode accepte les alias.
Alias prédéfinis <span id="predefined-aliases"></span>
@ -86,21 +87,20 @@ Yii définit une série d'alias pour faciliter le référencement des chemins de
- `@yii`, le répertoire où se situe le fichier `BaseYii.php` (aussi appelé le répertoire framework).
- `@app`, le [[yii\base\Application::basePath|chemin de base]] de l'application courante.
- `@runtime`, le [[yii\base\Application::runtimePath|le chemin d'exécution]] de l'application courante. Valeur par défaut: `@app/runtime`.
- `@webroot`, La répertoire web racine de l'application web courante. It is determined based on the directory
containing the [entry script](structure-entry-scripts.md).
- `@webroot`, La répertoire web racine de l'application web courante. Il est déterminé en se basant sur le répertoire contenant le [script d'entrée](structure-entry-scripts.md).
- `@web`, l'url de base de l'application courante. Cet alias a la même valeur que la propriété [[yii\web\Request::baseUrl]].
- `@vendor`, le [[yii\base\Application::vendorPath|Le répertoire vendor de Composer]]. Valeur par défaut: `@app/vendor`.
- `@bower`, le répertoire racine qui contient [les paquets bower](http://bower.io/). Valeur par défaut: `@vendor/bower`.
- `@npm`, le répertoire racine qui contient [les paquets npm](https://www.npmjs.org/). Valeur par défaut: `@vendor/npm`.
L'alias `@yii` est défini quand le fichier `Yii.php`est inclu dans votre [script d'entrée](structure-entry-scripts.md). Le reste des alias sont définit dans le constructeur de l'application au moment ou la [configuration](concept-configurations.md) de cette dernière est appliquée
L'alias `@yii` est défini quand le fichier `Yii.php`est inclus dans votre [script d'entrée](structure-entry-scripts.md). Le reste des alias est défini dans le constructeur de l'application au moment ou la [configuration](concept-configurations.md) de cette dernière est appliquée.
Alias d'extension <span id="extension-aliases"></span>
-----------------
Un alias est automatiquement définit pour chaque [extension](structure-extensions.md) installée via Composer.
Chacun de ces alias est nommé par l'espace de nom (namespace) racine de l'extension tel que déclaré dans son fichier `composer.json`, et chacun pointe sur le répertoire racine du paquet. Par exemple, si vous installez l'extension `yiisoft/yii2-jui`, vous obtiendrez automatiquement un alias `@yii/jui` défini pendant la [phase d'amorçage](runtime-bootstrapping.md), équivalent à
Un alias est automatiquement défini pour chaque [extension](structure-extensions.md) installée via Composer.
Chacun de ces alias est nommé par l'espace de noms (namespace) racine de l'extension tel que déclaré dans son fichier `composer.json`, et chacun pointe sur le répertoire racine du paquet. Par exemple, si vous installez l'extension `yiisoft/yii2-jui`, vous obtenez automatiquement un alias `@yii/jui` défini pendant la [phase d'amorçage](runtime-bootstrapping.md), équivalent à
```php
Yii::setAlias('@yii/jui', 'VendorPath/yiisoft/yii2-jui');
```
```

147
docs/guide-fr/intro-upgrade-from-v1.md

@ -5,7 +5,7 @@ Il y a beaucoup de différences entre les versions 1.1 et 2.0 de Yii, le framewo
la 2.0. En conséquence, la mise à jour depuis la version 1.1 n'est pas aussi triviale que la mise à jour entre deux
versions mineures. Dans ce guide, vous trouverez les principales différences entre les deux versions.
Si vous n'avez pas utilisé Yii 1.1 avant, vous pouvez ignorer cette section et passer directement à la partie
Si vous n'avez pas utilisé Yii 1.1 avant, vous pouvez ignorer cette section et passer directement à la section
"[Mise en route] (start-installation.md)".
Merci de noter que Yii 2.0 introduit plus de nouvelles fonctionnalités que celles abordées ici. Il est fortement
@ -17,10 +17,10 @@ Installation
------------
Yii 2.0 exploite pleinement [Composer] (https://getcomposer.org/), le gestionnaire de paquet PHP. L'installation
du framework, ainsi que des extensions, sont gérées par Composer. Merci de lire la partie
du framework, ainsi que des extensions, sont gérées par Composer. Reportez-vous à la section
[Installer Yii](start-installation.md) pour apprendre comment installer Yii 2.0. Si vous voulez
créer de nouvelles extensions, ou rendre vos extensions existantes 1.1 compatibles 2.0, merci de lire
la partie [Créer des extensions](extend-creating-extensions.md) de ce guide.
créer de nouvelles extensions, ou rendre vos extensions existantes 1.1 compatibles 2.0, reportez-vous à
la section [Créer des extensions](extend-creating-extensions.md) de ce guide.
Pré-requis PHP
@ -28,7 +28,7 @@ Pré-requis PHP
Yii 2.0 requiert PHP 5.4 ou plus, ce qui est une grosse amélioration par rapport à PHP 5.2 qui était requis pour Yii 1.1.
Par conséquent, il y a beaucoup de différences au niveau du langage pour lesquelles vous devriez prêter attention.
Par conséquent, il y a beaucoup de différences au niveau du langage auxquelles vous devriez prêter attention.
Voici un résumé des principaux changements concernant PHP:
- [Espaces de noms](http://php.net/manual/fr/language.namespaces.php).
@ -43,7 +43,7 @@ Voici un résumé des principaux changements concernant PHP:
d'internationalisation.
Espaces de Noms
Espaces de noms
---------------
Le changement le plus évident dans Yii 2.0 est l'utilisation des espaces de noms. La majorité des classes du noyau
@ -61,27 +61,27 @@ Composants et objets
Yii 2.0 décompose la classe `CComponent` 1.1 en deux classes: [[yii\base\Object]] et [[yii\base\Component]].
Le classe [[yii\base\Object|Object]] est une classe de base légère qui permet de définir les
[Propriétés de l'objet](concept-properties.md) via des accesseurs. La classe [[yii\base\Component|Component]] est une
sous classe de [[yii\base\Object|Object]] et supporte les [Evénements] (concept events.md) et les
sous classe de [[yii\base\Object|Object]] et prend en charge les [Evénements] (concept events.md) et les
[Comportements](concept-behaviors.md).
Si votre classe n'a pas besoin des événements et des comportements, vous devriez envisager d'utiliser
[[yii\base\Object|Object]] comme classe de base. C'est généralement le cas pour les classes qui représentent
une structures de données basique.
une structure de données basique.
Configuration d'Objet
Configuration d'objets
---------------------
La classe [[yii\base\Object|Object]] introduit une manière uniforme pour configurer les objets. Toute sous classe
La classe [[yii\base\Object|Object]] introduit une manière uniforme de configurer les objets. Toute sous-classe
de [[yii\base\Object|Object]] doit déclarer son constructeur (si besoin) de la manière suivante afin qu'elle
puisse être configurée correctement:
puisse être configurée correctement :
```php
class MyClass extends \yii\base\Object
{
public function __construct($param1, $param2, $config = [])
{
// ... initialisation avant que la configuration soit appliquée
// ... initialisation avant que la configuration ne soit appliquée
parent::__construct($config);
}
@ -90,7 +90,7 @@ class MyClass extends \yii\base\Object
{
parent::init();
// ... initialisation après que la configuration soit appliquée
// ... initialisation après que la configuration est appliquée
}
}
```
@ -98,7 +98,7 @@ class MyClass extends \yii\base\Object
Dans ce qui précède, le dernier paramètre du constructeur doit être un tableau de configuration
qui contient des entrées nom-valeur pour initialiser les propriétés à la fin du constructeur.
Vous pouvez remplacer la méthode [[yii\base\Object::init()|init()]] pour le travail d'initialisation qui doit être fait
après que la configuration ait été appliquée.
après que la configuration a été appliquée.
En suivant cette convention, vous serez en mesure de créer et de configurer de nouveaux objets en utilisant un tableau
de configuration :
@ -111,11 +111,11 @@ $object = Yii::createObject([
], [$param1, $param2]);
```
Plus de détails sur les configurations peuvent être trouvés dans la partie
[Configurations d'objet](concept-configurations.md).
Plus de détails sur les configurations peuvent être trouvés dans la section
[Configurations](concept-configurations.md).
Evénements
Événements
----------
Avec Yii 1, les événements étaient créés par la définition d'une méthode `on` (par exemple `onBeforeSave`). Avec Yii 2,
@ -134,7 +134,7 @@ $component->on($eventName, $handler);
// Pour détacher le gestionnaire, utilisez :
// $component->off($eventName, $handler);
```
Il y a de nombreuses améliorations dans la gestion des événements. Pour plus de détails, merci de lire la partie [Evénements](concept-events.md).
Il y a de nombreuses améliorations dans la gestion des événements. Pour plus de détails, reportez-vous à la section [Evénements](concept-events.md).
Alias
@ -146,14 +146,14 @@ Par exemple, l'alias `@yii` fait référence au répertoire d'installation de Yi
supportés dans la plupart du code de Yii. Par exemple, [[yii\caching\FileCache::cachePath]] peut prendre
à la fois un alias et un chemin de répertoire normal.
Un alias est aussi étroitement liée aux espaces de noms des classes. Il est recommandé de définir
un alias pour chaque espace de nom racine, ce qui vous permet d'utiliser le chargeur automatique de classe de Yii sans
Un alias est aussi étroitement lié aux espaces de noms des classes. Il est recommandé de définir
un alias pour chaque espace de noms racine, ce qui vous permet d'utiliser le chargeur automatique de classe de Yii sans
sans devoir en faire d'avantage. Par exemple, vu que `@yii` fait référence au dossier d'installation de Yii,
une classe comme `yii\web\Request` peut être chargée automatiquement. Si vous utilisez une librairie tierce,
telle que Zend Framework, vous pouvez définir un alias de chemin `@Zend` qui fera référence au dossier
d'installation de Zend Framework. Une fois que vous avez fait cela, Yii sera aussi en mesure de charger automatiquement une classe de ce framework.
Pour en savoir plus, consultez la partie [Alias](concept-aliases.md).
Pour en savoir plus, consultez la section [Alias](concept-aliases.md).
Vues
@ -164,16 +164,16 @@ contrôleur ou widget. Au lieu de cela, `$this` correspond maintenant à un obje
introduit dans la version 2.0. L'objet *vue* est de type [[yii\web\View]], et représente la partie vue
du modèle MVC. Si vous souhaitez accéder au contrôleur ou widget dans une vue, vous pouvez utiliser `$this->context`.
Pour afficher une vue depuis une autre vue, utilisez `$this->render()`, et non `$this->renderPartial()`. Le résultat retourné par la méthode `render()` doit être explictement envoyé à la sortie, en effet `render()` retournera la vue au lieu de l'afficher. Par exemple :
Pour afficher une vue depuis une autre vue, utilisez `$this->render()`, et non `$this->renderPartial()`. Le résultat retourné par la méthode `render()` doit être explicitement envoyé à la sortie, en effet `render()` retournera la vue au lieu de l'afficher. Par exemple :
```php
echo $this->render('_item', ['item' => $item]);
```
Outre l'utilisation de PHP comme langage principal de gabarit, Yii 2.0 supporte également
deux moteurs de gabarit populaires : Smarty et Twig. Le moteur de gabarit Prado n'est plus supporté.
Outre l'utilisation de PHP comme langage principal de gabarit, Yii 2.0 prend également en charge
deux moteurs de gabarit populaires : Smarty et Twig. Le moteur de gabarit Prado n'est plus pris en charge.
Pour utiliser ces moteurs de gabarit, vous devez configurer le composant `view` de l'application en définissant la propriété
[[yii\base\View::$renderers|View::$renderers]]. Merci de lire la partie [Moteur de gabarit](tutorial-template-engines.md) pour en savoir plus.
[[yii\base\View::$renderers|View::$renderers]]. Reportez-vous à la section [Moteur de gabarit](tutorial-template-engines.md) pour en savoir plus.
Modèles
@ -183,7 +183,7 @@ Yii 2.0 utilise la classe [[yii\base\Model]] comme modèle de base, similaire à
La classe `CFormModel` a été supprimée. Vous pouvez, à la place, étendre la classe [[yii\base\Model]] afin de créer une classe modèle pour un formulaire.
Yii 2.0 introduit une nouvelle méthode appelée [[yii\base\Model::scenarios()|scenarios()]] pour déclarer
les scénarios pris en charge, et indiquer dans quel scénario un attribut doit être validé, peut être considéré comme sûr ou non, etc. Par exemple:
les scénarios pris en charge, indiquer dans quel scénario un attribut doit être validé et si cet attribut peut être considéré comme sûr ou non, etc. Par exemple:
```php
public function scenarios()
@ -196,21 +196,21 @@ public function scenarios()
```
Dans ce qui précède, deux scénarios sont déclarés: `backend` et `frontend`. Pour le scénario `backend` les
propriétés `email` et `role` sont sûres et peuvent être affectées massivement. Pour le scénario `frontend`,
`email` peut être affectée massivement tandis que `role` ne peut pas. `email` et `rôle` doivent être validées en utilisant des règles.
attribut `email` et `role` sont sûrs et peuvent être affectés massivement. Pour le scénario `frontend`,
`email` peut être affecté massivement tandis que `role` ne le peut pas. `email` et `rôle` doivent être validées en utilisant des règles.
La méthode [[yii\base\Model::rules()|rules()]] est toujours utilisée pour déclarer les règles de validation. Remarque : suite à l'introduction de la méthode [[yii\base\Model::scenarios()|scenarios()]], le validateur `unsafe` n'as plus de raison d'être.
Dans la plupart des cas, vous n'avez pas besoin de surcharger la méthode [[yii\base\Model::scenarios()|scenarios()]]
lorsque les scénarios existants sont déclarés via la méthode [[yii\base\Model::rules()|rules()]], et il n'y a pas besoin de déclarer de propriétés `unsafe`.
Pour en savoir plus sur les modèles, merci de lire la partie [Modèles](structure-models.md).
Pour en savoir plus sur les modèles, reportez-vous à la section [Modèles](structure-models.md).
Contrôleurs
-----------
Yii 2.0 utilise la classe [[yii\web\Controller]] comme classe de base des contrôleurs, similaire à la classe `CWebController` dans la version Yii 1.1.
Yii 2.0 utilise la classe [[yii\web\Controller]] comme classe de base des contrôleurs, similaire à la classe `CController` dans la version Yii 1.1.
[[yii\base\Action]] est la classe de base pour les actions.
L'impact le plus évident de ces changements sur votre code est qu'une action de contrôleur doit retourner le contenu
@ -228,7 +228,7 @@ public function actionView($id)
}
```
Merci de lire la partie [Contrôleurs](structure-controllers.md) pour plus de détails.
Reportez-vous à la section [Contrôleurs](structure-controllers.md) pour plus de détails.
Widgets
@ -236,7 +236,7 @@ Widgets
Yii 2.0 utilise la classe [[yii\base\Widget]] comme classe de base pour les widgets, similaire à la classe `CWidget` de Yii 1.1.
Pour avoir un meilleur support du framework dans les EDI, Yii2 introduit une nouvelle syntaxe pour utiliser les widgets. Les methodes statiques
Pour avoir une meilleure prise en charge du framework dans les EDI, Yii2 introduit une nouvelle syntaxe pour utiliser les widgets. Les méthodes statiques
[[yii\base\Widget::begin()|begin()]], [[yii\base\Widget::end()|end()]], et [[yii\base\Widget::widget()|widget()]]
ont été créées et sont utilisables comme suit :
@ -256,7 +256,7 @@ $form = ActiveForm::begin([
ActiveForm::end();
```
Merci de lire la partie [Widgets](structure-widgets.md) pour en savoir plus.
Reportez-vous à la section [Widgets](structure-widgets.md) pour en savoir plus.
Thèmes
@ -271,7 +271,7 @@ de fichier de vue à un chemin de fichier de vue thématisée. Par exemple, si l
En outre, il n'y a plus de composant `CThemeManager`. A la place, `theme` est une propriété configurable du composant `view`
de l'application.
Merci de lire la partie [Thématisation](tutorial-theming.md) pour plus de détails.
Reportez-vous à la section [Thématisation](tutorial-theming.md) pour plus de détails.
Applications en ligne de commande
@ -287,26 +287,26 @@ les options déclarées dans la méthode [[yii\console\Controller::options()]].
Yii 2.0 prend en charge la génération automatique d'aide à partir des blocs de commentaire.
Merci de lire la partie [Commandes console](tutorial-console.md) pour plus de détails.
Reportez-vous à la section [Commandes console](tutorial-console.md) pour plus de détails.
I18N
----
Yii 2.0 supprime les fonctionnalités internes de formattage de dates et nombres, en faveur du [module PHP PECL intl] (http://pecl.php.net/package/intl).
Yii 2.0 supprime les fonctionnalités internes de formatage des dates et des nombres, en faveur du [module PHP PECL intl] (http://pecl.php.net/package/intl).
La traduction de message est désormais effectuée via le composant d'application `i18n`.
La traduction des messages est désormais effectuée via le composant d'application `i18n`.
Ce composant gère un ensemble de sources de messages, ce qui vous permet d'utiliser différentes
sources de messages en fonction de catégories.
Merci de lire la partie [Internationalisation](tutorial-i18n.md) pour plus de détails.
Reportez-vous à la section [Internationalisation](tutorial-i18n.md) pour plus de détails.
Filtres d'action
----------------
Les filtres d'action sont maintenant implémentés comme des comportements. Pour définir un nouveau filtre personnalisé, étendez la classe [[yii\base\ActionFilter]]. Pour utiliser un filtre, déclarez le
comme un comportement du contrôleur. Par exemple, pour utilser le filtre [[yii\filters\AccessControl]], vous aurez le code suivant dans le contrôleur :
comme un comportement du contrôleur. Par exemple, pour utiliser le filtre [[yii\filters\AccessControl]], vous aurez le code suivant dans le contrôleur :
```php
public function behaviors()
@ -322,26 +322,26 @@ public function behaviors()
}
```
Merci de lire la partie [Filtres](structure-filters.md) pour plus de détails.
Reportez-vous à la section [Filtres](structure-filters.md) pour plus de détails.
Ressources
----------
Yii 2.0 introduit un nouveau concept de packet de ressources (*asset bundle*) qui remplace le concept de gestionnaire de ressources (*asset manager*) de la version 1.1.
Yii 2.0 introduit un nouveau concept de paquet de ressources (*asset bundle*) qui remplace le concept de gestionnaire de ressources (*asset manager*) de la version 1.1.
Un packet de ressources est une collection de fichiers (par exemple : fichier JavaScript, CSS, image, etc.)
Un paquet de ressources est une collection de fichiers (par exemple : fichier JavaScript, CSS, image, etc.)
dans un dossier. Chaque paquet est représenté par une classe étendant [[yii\web\AssetBundle]].
En *enregistrant* un packet via [[yii\web\AssetBundle::register()]], vous rendez les ressources du packet accessibles via le Web. Contrairement à Yii 1.1, la page *enregistrant* le paquet
En *enregistrant* un paquet de ressources via [[yii\web\AssetBundle::register()]], vous rendez les ressources du paquet accessibles via le Web. Contrairement à Yii 1.1, la page *enregistrant* le paquet
contiendra automatiquement les références vers les fichiers déclarés dans le paquet.
Merci de lire la partie [Assets](structure-assets.md) pour plus de détails.
Reportez-vous à la section [Assets](structure-assets.md) pour plus de détails.
Assistants
----------
Yii 2.0 introduit de nombreuses assistants couramment utilisés, sous la forme de classes statiques, y compris :
Yii 2.0 introduit de nombreux assistants couramment utilisés, sous la forme de classes statiques, y compris :
* [[yii\helpers\Html]]
* [[yii\helpers\ArrayHelper]]
@ -349,7 +349,7 @@ Yii 2.0 introduit de nombreuses assistants couramment utilisés, sous la forme d
* [[yii\helpers\FileHelper]]
* [[yii\helpers\Json]]
Merci de lire la partie [Assistants](helper-overview.md) pour plus de détails.
Reportez-vous à la section [Assistants](helper-overview.md) pour plus de détails.
Formulaires
@ -370,7 +370,7 @@ En utilisant des champs, vous pouvez construire un formulaire plus proprement qu
<?php yii\widgets\ActiveForm::end(); ?>
```
Merci de lire la partie [Créer des formulaires](input-forms.md) pour plus de détails.
Reportez-vous à la section [Créer des formulaires](input-forms.md) pour plus de détails.
Constructeur de requête
@ -394,7 +394,7 @@ $rows = $command->queryAll();
De plus, ces méthodes de construction de requête peuvent également être utilisées lorsque vous travaillez avec [Active Record](db-active-record.md).
Merci de lire la partie [Constructeur de requête](db-query-builder.md) pour plus de détails.
Reportez-vous à la section [Constructeur de requête](db-query-builder.md) pour plus de détails.
Active Record
@ -443,14 +443,14 @@ primaires des enregistrements principaux.
Au lieu de retourner des objets [[yii\db\ActiveRecord|ActiveRecord]], vous pouvez utiliser la méthode
[[yii\db\ActiveQuery::asArray()|asArray()]] lors de la construction d'une requête pour renvoyer un grand nombre
d'enregistrements. Ainsi le résultat retourné sera sous forme de tableaux, ce qui peut réduire considérablement le temps de calcul nécessaire et la mémoire dans le cas d'un grand nombre d'enregistrements. Par exemple:
d'enregistrements. Ainsi le résultat sera retourné sous forme de tableaux, ce qui peut réduire considérablement le temps de calcul et la mémoire nécessaires dans le cas d'un grand nombre d'enregistrements. Par exemple:
```php
$customers = Customer::find()->asArray()->all();
```
Un autre changement est que vous ne pouvez plus définir les valeurs par défaut des attributs en utilisant des propriétés
publiques. Si vous avez besoin, vous devez utiliser la méthode `init` de la classe de votre modèle.
Un autre changement fait que vous ne pouvez plus définir les valeurs par défaut des attributs en utilisant des propriétés
publiques. Si vous en avez besoin, vous devez utiliser la méthode `init` de la classe de votre modèle.
```php
public function init()
@ -465,25 +465,52 @@ la version 2.0. Notez que lorsque vous ajoutez des paramètres au constructeur,
la méthode [[yii\db\ActiveRecord::instantiate()]].
Il y a beaucoup d'autres modifications et améliorations à Active Record.
Merci de lire la partie [Active Record](db-active-record.md) pour en savoir plus.
Reportez-vous à la section [Active Record](db-active-record.md) pour en savoir plus.
Comportement des Enregistrements actifs)
---------------------------------------------------------
Dans la version 2.0, nous avons la classe de base des *behaviors* (comportements) `CActiveRecordBehavior`. Si vous voulez créer une classe de comportement d'enregistrement actif (Active Record), vous devez étendre directement la classe `yii\base\Behavior`. Si la classe de comportement doit réagir à certains événements du propriétaire, vous devez redéfinir les méthodes `events()` comme suit :
```php
namespace app\components;
use yii\db\ActiveRecord;
use yii\base\Behavior;
class MyBehavior extends Behavior
{
// ...
public function events()
{
return [
ActiveRecord::EVENT_BEFORE_VALIDATE => 'beforeValidate',
];
}
public function beforeValidate($event)
{
// ...
}
}
```
User et IdentityInterface
-------------------------
La classe `CWebUser` 1.1 est maintenant remplacé par [[yii\web\User]], et il n'y a plus de classe `CUserIdentity`.
La classe `CWebUser` 1.1 est maintenant remplacée par [[yii\web\User]], et il n'y a plus de classe `CUserIdentity`.
Au lieu de cela, vous devez implémenter [[yii\web\IdentityInterface]] qui est beaucoup plus simple à utiliser.
Le modèle d'application avancé fournit un exemple.
Le modèle de projet avancé fournit un exemple.
Merci de lire les parties [Authentification](security-authentication.md), [Authorisation](security-authorization.md), et
[Modèle application avancée](tutorial-advanced-app.md) pour en savoir plus.
Reportez-vous aux sections [Authentification](security-authentication.md), [Authorisation](security-authorization.md), et
[Modèle de projet avancé](tutorial-advanced-app.md) pour en savoir plus.
Gestion des URL
---------------
La gestion des URL dans Yii 2 est similaire à celle disponible dans la version 1.1. Une amélioration majeure est que la
gestion des URL supporte désormais les paramètres optionnels. Par exemple, si vous avez une règle déclarée comme suit,
gestion des URL prend désormais en charge les paramètres optionnels. Par exemple, si vous avez une règle déclarée comme suit,
cela fera correspondre `post/popular` et `post/1/popular`. Dans la version 1.1, il fallait utiliser deux règles pour
atteindre le même objectif.
@ -495,11 +522,13 @@ atteindre le même objectif.
]
```
Merci de lire la partie [Gestion des URL](url.md) pour en savoir plus.
Reportez-vous à la section [Documentation de la gestion des URL](runtime-routing.md) pour en savoir plus.
Un changement important dans la convention de nommage pour les routes est que les noms utilisant la *casse en dos de chameau* des contrôleurs et des actions utilisent désormais uniquement des mots en bas de casse séparés par des tirets, p. ex. l'identifiant du contrôleur Reportez-vous à la section traitant des [Identifiants de contrôleur](structure-controllers.md#controller-ids) et [Identifiants d'action](structure-controllers.md#action-ids) pour plus de détails.
Utiliser Yii 1.1 et 2.x ensemble
--------------------------------
Si vous avez du code Yii 1.1 que vous souhaitez réutiliser avec Yii 2, merci de lire la partie [Utiliser Yii 1.1 et 2.0 ensemble](extend-using-v1-v2.md).
Si vous avez du code Yii 1.1 que vous souhaitez réutiliser avec Yii 2, reportez-vous à la section [Utiliser Yii 1.1 et 2.0 ensemble](tutorial-yii-integration.md).

40
docs/guide-fr/start-databases.md

@ -1,9 +1,9 @@
Travailler avec les bases de données
======================
Cette section décrira comment créer une nouvelle page qui affiche des données pays récupérées dans une table de base
Cette section décrit comment créer une nouvelle page qui affiche des données pays récupérées dans une table de base
de données nommée `country`. Pour ce faire, vous allez configurer une connexion à une base de données, créer une
classe [Active Record](db-active-record.md), et définir une [action](structure-controllers.md), et créer une
classe [Active Record](db-active-record.md), définir une [action](structure-controllers.md), et créer une
[vue](structure-views.md).
Au long de ce tutoriel, vous apprendrez comment :
@ -27,7 +27,7 @@ Vous pouvez créer une base de données SQLite, MySQL, PostgreSQL, MSSQL ou Orac
applications de base de données. Par simplicité, nous supposerons que vous utilisez MySQL dans les descriptions qui
suivent.
Next, create a table named `country` in the base de données, and insert some sample data. You may run the following SQL statements to do so:
Créez maintenant une table nommée `country` dans la base de données et insérez-y quelques données exemples. Vous pouvez exécuter l'instruction SQL suivante pour le faire :
```sql
CREATE TABLE `country` (
@ -48,12 +48,12 @@ INSERT INTO `country` VALUES ('RU','Russia',146519759);
INSERT INTO `country` VALUES ('US','United States',322976000);
```
A ce niveau, vous avez une base de données appelée `yii2basic`, et dedans, une table `country` comportant trois colonnes, contenant dix lignes de données.
Vous avez désormais une base de données appelée `yii2basic` conmprenant une table `country` comportant trois colonnes et contenant dix lignes de données.
Configurer une Connexion à la BDD <span id="configuring-db-connection"></span>
---------------------------
Avant de continuer, assurons nous que vous avez installé à la fois l'extension PHP
Avant de continuer, vérifiez que vous avez installé à la fois l'extension PHP
[PDO](http://www.php.net/manual/fr/book.pdo.php) et le pilote PDO pour la base de données que vous utilisez (c'est
à dire `pdo_mysql` pour MySQL). C'est une exigence de base si votre application utilise une base de données
relationnelle.
@ -80,15 +80,15 @@ dans la base de données sous-jacente.
On peut accéder à connexion à la BDD configurée ci-dessus depuis le code de l'application vial'expression
`Yii::$app->db`.
> Info: Le fichier `config/db.php` sera inclus par la configuration principale de l'application `config/web.php`,
> Info: le fichier `config/db.php` sera inclus par la configuration principale de l'application `config/web.php`,
qui spécifie comment l'instante d'[application](structure-applications.md) doit être initialisée.
Pour plus d'informations, merci de vous référer à la section [Configurations](concept-configurations.md).
Pour plus d'informations, reportez-vous à la section [Configurations](concept-configurations.md).
Créer un Active Record <span id="creating-active-record"></span>
-------------------------
Pour représenter et aller chercher des données dans la table `country`, créez une classe dérivée d'[Active Record](db-active-record.md) appelée `Country`, et enregistrez la dans le fichier `models/Country.php`.
Pour représenter et aller chercher des données dans la table `country`, créez une classe dérivée d'[Active Record](db-active-record.md) appelée `Country`, et enregistrez-la dans le fichier `models/Country.php`.
```php
<?php
@ -102,10 +102,10 @@ class Country extends ActiveRecord
}
```
La classe `Country` étend [[yii\db\ActiveRecord]]. Vous n'avez pas besoin d'y écrire le moindre code ! Simplement avec
le code ci-dessus, Yii devinera le nom de la table associée au nom de la class.
La classe `Country` étend [[yii\db\ActiveRecord]]. Vous n'avez pas besoin d'y écrire le moindre code ! Simplement, avec
le code ci-dessus, Yii devine le nom de la table associée au nom de la classe.
> Info: Si aucune correspondance directe ne peut être faite à partir du nom de la classe, vous pouvez outrepasser la méthode [[yii\db\ActiveRecord::tableName()]] pour spécifier explicitement un nom de table.
> Info: si aucune correspondance directe ne peut être faite à partir du nom de la classe, vous pouvez outrepasser la méthode [[yii\db\ActiveRecord::tableName()]] pour spécifier explicitement un nom de table.
A l'aide de la classe `Country`, vous pouvez facilement manipuler les données de la table `country`, comme dans les bribes suivantes :
@ -137,7 +137,7 @@ Créer une Action <span id="creating-action"></span>
Pour exposer les données pays aux utilisateurs, vous devez créer une action. Plutôt que de placer la nouvelle action
dans le contrôleur `site`, comme vous l'avez fait dans les sections précédentes, il est plus cohérent de créer un
nouveau contrôleur spécifiquement pour toutes les actions liées aux données pays. Nommez ce contrôleur
nouveau contrôleur spécifique à toutes les actions liées aux données pays. Nommez ce contrôleur
`CountryController`, et créez-y une action `index`, comme suit.
```php
@ -182,7 +182,7 @@ Pour limiter le nombre de pays retournés par chaque requête, la requête est p
* Il ajuste les clauses `offset` et `limit` de la déclaration SQL représentée par la requête afin qu'elle en retourne
qu'une page de données à la fois (au plus 5 colonnes par page).
* Il est utilisé dans la vue pour afficher un pagineur qui consiste en une liste de boutons de page, comme nous
* Il est utilisé dans la vue pour afficher un sélecteur de pages qui consiste en une liste de boutons de page, comme nous
l'expliquerons dans la prochaine sous-section.
A la fin du code, l'action `index` effectue le rendu d'une vue nommée `index`, et lui transmet les données pays ainsi que les informations de pagination.
@ -213,16 +213,16 @@ use yii\widgets\LinkPager;
<?= LinkPager::widget(['pagination' => $pagination]) ?>
```
La vue a deux sections relatives à l'affichage des données pays. Dans la première partie, les données pays fournies
est parcourue et rendue sous forme de liste non ordonnée HTML.
La vue comprend deux sections relatives à l'affichage des données pays. Dans la première partie, les données pays fournies
sont parcourues et rendues sous forme de liste non ordonnée HTML.
Dans la deuxième partie, un widget [[yii\widgets\LinkPager]] est rendu en utilisant les informations de pagination transmises par l'action.
Le widget `LinkPager` affiche une liste de boutons de pages. Le fait de cliquer sur l'un deux rafraichit les données pays dans la page correspondante.
Le widget `LinkPager` affiche une liste de boutons de page. Le fait de cliquer sur l'un deux rafraichit les données pays dans la page correspondante.
Essayer <span id="trying-it-out"></span>
-------------
Pour voir comment tout le code ci-dessus fonctionne, utilisez votre navigateur pour accéder à l'URL suivant :
Pour voir comment tout le code ci-dessus fonctionne, pointez votre navigateur sur l'URL suivante :
```
http://hostname/index.php?r=country/index
@ -230,7 +230,7 @@ http://hostname/index.php?r=country/index
![Liste de Pays](images/start-country-list.png)
Au début, vous verrez une page affichant cinq pays. En dessous des pays, vous verrez un pagineur avec quatre boutons.
Au début, vous verrez une page affichant cinq pays. En dessous des pays, vous verrez un sélecteur de pages avec quatre boutons.
Si vous cliquez sur le bouton "2", vous verrez la page afficher cinq autres pays de la base de données : la deuxième
page d'enregistrements.
Observez plus attentivement et vous noterez que l'URL dans le navigateur devient
@ -243,7 +243,7 @@ En coulisse, [[yii\data\Pagination|Pagination]] fournit toutes les fonctionnalit
* Au départ, [[yii\data\Pagination|Pagination]] représente la première page, qui reflète la requête SELECT de country
avec la clause `LIMIT 5 OFFSET 0`. Il en résulte que les cinq premiers pays seront trouvés et affichés.
* Le widget [[yii\widgets\LinkPager|LinkPager]] effectue le rendu des boutons de pages en utilisant les URLs créés par
* Le widget [[yii\widgets\LinkPager|LinkPager]] effectue le rendu des boutons de pages en utilisant les URLs créées par
[[yii\data\Pagination::createUrl()|Pagination]]. Les URLs contiendront le paramètre de requête `page`, qui représente
les différents numéros de pages.
* Si vous cliquez sur le bouton de page "2", une nouvelle requête pour la route `country/index` sera déclenchée et
@ -257,7 +257,7 @@ Résumé <span id="summary"></span>
-------
Dans cette section, vous avez appris comment travailler avec une base de données. Vous avez également appris comment
chercher et afficher des données dans des pages avec l'aide de [[yii\data\Pagination]] et [[yii\widgets\LinkPager]].
chercher et afficher des données dans des pages avec l'aide de [[yii\data\Pagination]] et de [[yii\widgets\LinkPager]].
Dans la prochaine section, vous apprendrez comment utiliser le puissant outil de génération de code, appelé
[Gii](tool-gii.md), pour vous aider à implémenter rapidement des fonctionnalités communément requises, telles que les

97
docs/guide-fr/structure-application-components.md

@ -0,0 +1,97 @@
Composants d'application
======================
Les applications sont des [(localisateurs de services (service locators)](concept-service-locator.md). Elles hébergent un jeu composants appelés « composants d'application » qui procurent différents services pour la prise en charge des requêtes. Par exemple, le composant `urlManager` (gestionnaire d'url) est chargé de router les requêtes Web vers les contrôleurs appropriés; le composant `db` (base de données) fournit les services relatifs à la base de données; et ainsi de suite.
Chaque composant d'application possède un identifiant unique qui le distingue des autres composants d'application de la même application. Vous pouvez accéder à un composant d'application via l'expression :
```php
\Yii::$app->componentID
```
Par exemple, vous pouvez utiliser `\Yii::$app->db` pour obtenir la [[yii\db\Connection|connexion à la base de données]], et `\Yii::$app->cache` pour accéder au [[yii\caching\Cache|cache primaire]] enregistré dans l'application.
Un composant d'application est créé la première fois qu'on veut y accéder en utilisant l'expression ci-dessus. Les accès ultérieurs retournent la même instance du composant.
Les composants d'application peuvent être n'importe quel objet. Vous pouvez les enregistrer en configurant la propriété [[yii\base\Application::components]] dans la [configuration de l'application](structure-applications.md#application-configurations).
Par exemple,
```php
[
'components' => [
// enregistre le composant "cache" à partir du nom de classe
'cache' => 'yii\caching\ApcCache',
// enregistre le composant "db" à l'aide d'un tableau de configuration
'db' => [
'class' => 'yii\db\Connection',
'dsn' => 'mysql:host=localhost;dbname=demo',
'username' => 'root',
'password' => '',
],
// enregistre le composant "search" en utilisant une fonction anonyme
'search' => function () {
return new app\components\SolrService;
},
],
]
```
> Info: bien que vous puissiez enregistrer autant de composants d'application que vous le désirez, vous devriez le faire avec discernement. Les composants d'application sont comme les variables globales, une utilisation trop importante de composants d'application est susceptible de rendre votre code plus difficile à tester et à maintenir. Dans beaucoup de cas, vous pouvez simplement créer un composant localement et l'utiliser lorsque vous en avez besoin.
## Composants du processus d'amorçage <span id="bootstrapping-components"></span>
Comme il a été dit plus haut, un composant d'application n'est instancié que lorsqu'on y accède pour la première fois. S'il n'est pas du tout accédé dans le traitement de la requête, il n'est pas instancié. Parfois, vous désirez peut être instancier un composant d'application pour chacune des requêtes, même s'il n'est pas explicitement accédé.
Pour cela, vous pouvez lister son identifiant (ID) dans la propriété [[yii\base\Application::bootstrap|bootstrap]] de l'application.
Par exemple, la configuration d'application suivante garantit que le composant `log` est toujours chargé.
```php
[
'bootstrap' => [
'log',
],
'components' => [
'log' => [
// configuration pour le composant "log"
],
],
]
```
## Composants d'application du noyau <span id="core-application-components"></span>
Yii définit un jeu de composants d'application dit *core application components* (composants d'application du noyau ou du cœur) avec des identifiants fixés et des configurations par défaut. Par exemple, le composant [[yii\web\Application::request|request (requête)]] est utilisé pour collecter les informations sur une requête utilisateur et la résoudre en une [route](runtime-routing.md); le composant [[yii\base\Application::db|db (base de données)]] représente une connexion à une base de données à l'aide de laquelle vous pouvez effectuer des requêtes de base de données. C'est à l'aide des ces composants d'application du noyau que les applications Yii sont en mesure de prendre en charge les requêtes des utilisateurs.
Vous trouverez ci-après la liste des composants d'application prédéfinis du noyau. Vous pouvez les configurer et les personnaliser comme tout composant d'application. Lorsque vous configurez une composant d'application du noyau, vous n'avez pas besoin de spécifier sa classe, celle par défaut est utilisée.
* [[yii\web\AssetManager|assetManager (gestionnaire de ressources]]: gère les paquets de ressources et la publication des ressources.
Reportez-vous à la section [Gestion des ressources](structure-assets.md) pour plus de détails.
* [[yii\db\Connection|db (base de données)]]: représente une connexion à une base de données à l'aide de laquelle vous pouvez effectuer des requêtes de base de données.
Notez que lorsque vous configurez ce composant, vous devez spécifier la classe de composant tout comme les autres propriétés de composant, telle que [[yii\db\Connection::dsn]].
Reportez-vous à la section [Objets d'accès aux données](db-dao.md) pour plus de détails.
* [[yii\base\Application::errorHandler|errorHandler (gestionnaire d'erreurs) ]]: gère les erreurs PHP et les exceptions.
Reportez-vous à la section [Gestion des erreurs](runtime-handling-errors.md) pour plus de détails.
* [[yii\i18n\Formatter|formatter ]]: formate les données lorsqu'elles sont présentées à l'utilisateur final. Par exemple, un nombre peut être affiché avec un séparateur de milliers, une date affichée dans un format long, etc.
Reportez-vous à la section [Formatage des données](output-formatting.md) pour plus de détails.
* [[yii\i18n\I18N|i18n]]: prend en charge la traduction et le formatage des messages.
Reportez-vous à la section [Internationalisation](tutorial-i18n.md) pour plus de détails.
* [[yii\log\Dispatcher|log]]: gère les journaux cibles.
Reportez-vous à la section [Journaux](runtime-logging.md) pour plus de détails.
* [[yii\swiftmailer\Mailer|mail]]: prend en charge la composition et l'envoi des courriels.
Reportez-vous à la section [Mailing](tutorial-mailing.md) pour plus de détails.
* [[yii\base\Application::response|response]]: représente la réponse qui est adressée à l'utilisateur final.
Reportez-vous à la section [Réponses](runtime-responses.md) pour plus de détails.
* [[yii\base\Application::request|request]]: représente la requête reçue de l'utilisateur final.
Reportez-vous à la section [Requests](runtime-requests.md) pour plus de détails.
* [[yii\web\Session|session]]: représente les informations de session. Ce composant n'est disponible que dans les [[yii\web\Application|applications Web]].
Reportez-vous à la section [Sessions et Cookies](runtime-sessions-cookies.md) pour plus de détails.
* [[yii\web\UrlManager|urlManager (gestionnaire d'url)]]: prend en charge l'analyse des URL et leur création.
Reportez-vous à la section [Analyse et création d'URL](runtime-routing.md) pour plus de détails.
* [[yii\web\User|user]]: représente les informations d'authentification de l'utilisateur. Ce composant n'est disponible que dans les [[yii\web\Application|applications Web]].
Reportez-vous à la section [Authentification](security-authentication.md) pour plus de détails.
* [[yii\web\View|view]]: prend en charge le rendu des vues.
Reportez-vous à la section [Vues](structure-views.md) pour plus de détails.

517
docs/guide-fr/structure-applications.md

@ -0,0 +1,517 @@
Applications
============
Les Applications sont des objets qui gouvernent la structure d'ensemble et le cycle de vie des systèmes mettant en œuvre Yii.
Chacun des systèmes mettant en œuvre Yii contient un objet *Application* unique qui est créé par le [Script d'entrée](structure-entry-scripts.md) et est globalement accessible à l'aide de l'expression `\Yii::$app`.
> Info: selon le contexte, lorsque nous utilisons le terme « application », cela peut signifier soit un objet *Application*, soit un système mettant en œuvre Yii.
Il existe deux types d'application : [[yii\web\Application|les applications Web]] et
[[yii\console\Application|les applications de console]]. Comme leur nom l'indique, les premières prennent en charge des requêtes Web tandis que les deuxièmes prennent en charge des requêtes de la console.
## Configurations d'application <span id="application-configurations"></span>
Losqu'un [script d'entrée](structure-entry-scripts.md) crée une application, il charge une [configuration](concept-configurations.md) et l'applique à cette application de la manière suivante :
```php
require(__DIR__ . '/../vendor/autoload.php');
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
// charger la configuration de l'application
$config = require(__DIR__ . '/../config/web.php');
// instancier et configurer l'application
(new yii\web\Application($config))->run();
```
Tout comme les [configurations](concept-configurations.md) habituelles, les configurations d'application spécifient comment initialiser les propriétés des objets *Application*. Comme les configurations d'application sont souvent très complexes, elles sont ordinairement conservées dans des [fichiers de configuration](concept-configurations.md#configuration-files),
tels que le fichier `web.php` de l'exemple précédent.
## Propriétés des applications <span id="application-properties"></span>
Il y a de nombreuses propriétés importantes des applications que vous devez spécifier dans les configurations d'application.
Ces propriétés décrivent l'environnement dans lequel ces applications sont exécutées. Par exemple, les applications doivent savoir comment charger les [contrôleurs](structure-controllers.md), où ranger les fichiers temporaires, etc. Nous allons passer en revue ces propriétés.
### Propriétés requises <span id="required-properties"></span>
Dans toute application, vous devez au moins spécifier deux propriétés :: [[yii\base\Application::id|id]] et [[yii\base\Application::basePath|basePath]].
#### [[yii\base\Application::id|id]] <span id="id"></span>
La propriété [[yii\base\Application::id|id]] spécifie un identifiant unique qui distingue une application des autres. On l'utilise principalement dans des instructions. Bien que cela ne soit pas une exigence, l'utilisation des seuls caractères alphanumériques, pour spécifier cet identifiant, est recommandée pour assurer une meilleure interopérabilité.
#### [[yii\base\Application::basePath|basePath]] <span id="basePath (chemin du dossier racine)"></span>
La propriété [[yii\base\Application::basePath|basePath]] spécifie le dossier racine d'une application. Il s'agit du dossier qui contient tout le code source protégé d'une application mettant en œuvre Yii. Dans ce dossier, on trouve généralement des sous-dossiers tels que `models`, `views` et`controllers`, qui contiennent le code source correspondant au modèle de conception MVC.
Vous pouvez configurer la propriété [[yii\base\Application::basePath|basePath]] en utilisant un chemin de dossier
ou un [alias de chemin](concept-aliases.md). Dans les deux cas, le dossier correspondant doit exister,
sinon une exception est levée. Le chemin doit être normalisé à l'aide de la fonction `realpath()`.
La propriété [[yii\base\Application::basePath|basePath]] est souvent utilisée pour dériver d'autres chemins importants
(p. ex. le chemin runtime ). À cette fin, un alias nommé `@app` est prédéfini pour représenter ce chemin.
Les chemins dérivés peuvent être formés à l'aide de cet alias (p. ex. `@app/runtime` pour faire référence au dossier `runtime`).
### Propriétés importantes <span id="important-properties"></span>
Les propriétés décrites dans cette sous-section doivent souvent être spécifiées car elles différent à travers les différentes applications.
#### [[yii\base\Application::aliases|alias]] <span id="aliases"></span>
Cette propriété vous permet de définir un jeu d' [alias](concept-aliases.md) sous forme de tableau associatif.
Les clés du tableau représentent les noms des alias, tandis que les valeurs représentent la définition des chemins.
Par exemple :
```php
[
'aliases' => [
'@name1' => 'chemin/vers/dossier1',
'@name2' => 'chemin/vers/dossier2',
],
]
```
Cette propriété est mise à votre disposition pour vous éviter d'avoir à définir les alias par programme en appelant la méthode [[Yii::setAlias()]].
#### [[yii\base\Application::bootstrap|bootstrap (amorçage)]] <span id="bootstrap"></span>
Cette propriété est très utile. Elle vous permet de spécifier un tableau de composants qui devraient être exécutés lors du [[yii\base\Application::bootstrap()|processus d'amorçage]].
Par exemple, si vous désirez utiliser un [module](structure-modules.md) pour personnaliser les [règles d'URL](runtime-routing.md),
vous pouvez indiquer son identifiant (ID) en tant qu'élément de cette propriété.
Chacun des composants listés dans cette propriété peut être spécifié sous une des formes suivantes :
- un identifiant (ID) de composant d'application comme vous le spécifieriez via [components](#components),
- un identifiant (ID) de module comme vous le spécifieriez via [modules](#modules),
- un nom de classe,
- un tableau de configuration,
- une fonction anonyme qui crée et retourne un composant.
Par exemple:
```php
[
'bootstrap' => [
// un identifiant de composant d'application ou de module
'demo',
// un nom de classe
'app\components\Profiler',
// un tableau de configuration
[
'class' => 'app\components\Profiler',
'level' => 3,
],
// une fonction anonyme
function () {
return new app\components\Profiler();
}
],
]
```
> Info: si un identifiant (ID) de module est identique à celui d'un composant d'application, le composant d'application est utilisé lors du processus de démarrage. Si vous désirez utiliser le module, vous pouvez le spécifier via une fonction anonyme comme le montre l'exemple suivant :
>
> ```php
> [
> function () {
> return Yii::$app->getModule('user');
> },
> ]
> ```
Los du processus d'amorçage, chaque composant est instancié. Si la classe du composant implémente [[yii\base\BootstrapInterface]], sa méthode [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] est également appelée.
Un autre exemple pratique se trouve dans la configuration de l'application du [Modèle du projet Basic](start-installation.md),
où les modules `debug` et `gii` sont configurés en tant que composants d'amorçage lorsque l'application est dans l'environnement de développement.
```php
if (YII_ENV_DEV) {
// réglages de configuration pour l'environnement 'dev'
$config['bootstrap'][] = 'debug';
$config['modules']['debug'] = 'yii\debug\Module';
$config['bootstrap'][] = 'gii';
$config['modules']['gii'] = 'yii\gii\Module';
}
```
> Note: placer trop de composants dans `bootstrap` dégrade la performance de votre application car, à chaque requête, le même jeu de composants doit être exécuté. C'est pourquoi vous devez utiliser les composants de démarrage avec discernement.
#### [[yii\web\Application::catchAll|catchAll (ramasse tout)]] <span id="catchAll"></span>
Cette propriété est prise en charge par les [[yii\web\Application|applications Web]] uniquement. Elle spécifie une
[action de contrôleur](structure-controllers.md) qui prend en charge toutes les requêtes de l'utilisateur. Cela est essentiellement utilisé lorsque l'application est dans le mode maintenance et doit prendre en charge toutes les requêtes avec une action unique.
La configuration est un tableau dont le premier élément spécifie la route de l'action. Le reste des éléments du tableau (paires clé-valeur) spécifie les paramètres à associer à l'action. Par exemple :
```php
[
'catchAll' => [
'offline/notice',
'param1' => 'valeur1',
'param2' => 'valeur2',
],
]
```
> Info: le panneau de débogage dans l'environnement de développement ne fonctionne pas lorsque cette propriété est activée.
#### [[yii\base\Application::components|components (composants)]] <span id="components"></span>
Il s'agit de la seule plus importante propriété. Elle vous permet d'enregistrer par leur nom une liste de composants appelés [composants d'application](structure-application-components.md) que vous pouvez utiliser partout ailleurs. Par exemple :
```php
[
'components' => [
'cache' => [
'class' => 'yii\caching\FileCache',
],
'user' => [
'identityClass' => 'app\models\User',
'enableAutoLogin' => true,
],
],
]
```
Chaque composant d'application est spécifié sous la forme d'un couple clé-valeur dans le tableau. La clé représente l'identifiant (ID) du composant, tandis que la valeur représente le nom de la classe du composant ou un tableau de [configuration](concept-configurations.md).
Vous pouvez enregistrer n'importe quel composant dans une application, et vous pouvez ensuite y accéder globalement via l'expression `\Yii::$app->componentID`.
Reportez-vous à la section [Composants d'application](structure-application-components.md) pour plus de détails.
#### [[yii\base\Application::controllerMap|controllerMap (cartographie des contrôleurs)]] <span id="controllerMap"></span>
Cette propriété vous permet de faire correspondre un identifiant (ID) de contrôleur avec une classe de contrôleur arbitraire. Par défaut, Yii fait correspondre un identifiant de contrôleur avec une classe de contrôleur selon une [convention](#controllerNamespace) (p. ex. l'identifiant `post` correspond à `app\controllers\PostController`). En configurant cette propriété, vous passez outre la convention pour les contrôleurs spécifiés. Dans l'exemple qui suit, `account` correspond à
`app\controllers\UserController`, tandis que `article` correspond à `app\controllers\PostController`.
```php
[
'controllerMap' => [
'account' => 'app\controllers\UserController',
'article' => [
'class' => 'app\controllers\PostController',
'enableCsrfValidation' => false,
],
],
]
```
Les clés du tableau de cette propriété représentent les identifiants des contrôleurs, tandis que les valeurs représentent les noms des classes mises en correspondance ou les tableaux de [configurations](concept-configurations.md).
#### [[yii\base\Application::controllerNamespace|controllerNamespace (espaces de noms des contrôleurs]] <span id="controllerNamespace"></span>
Cette propriété spécifie l'espace de noms par défaut sous lequel les classes des contrôleurs sont situées. Par défaut, il s'agit de
`app\controllers`. Si l'identifiant d'un contrôleur est `post`, par convention le contrôleur correspondant (sans l'espace de noms) est `PostController`, et le nom de classe totalement qualifié est `app\controllers\PostController`.
Les classes de contrôleur peuvent aussi résider dans des sous-dossiers du dossier correspondant à cet espace de noms.
Par exemple, étant donné un identifiant de contrôleur`admin/post`, le nom de classe de contrôleur totalement qualifié est `app\controllers\admin\PostController`.
Il est important que la classe de contrôleur totalement qualifiée puisse être [auto-chargée](concept-autoloading.md) et que l'espace de noms réel de votre classe de contrôleur corresponde à la valeur de cette propriété. Autrement, vous obtenez une erreur « Page non trouvée » quand vous accédez à votre application.
Si vous désirez passer outre la convention décrite précédemment, vous devez configurer la propriété [controllerMap](#controllerMap).
#### [[yii\base\Application::language|language (langue)]] <span id="language"></span>
Cette propriété spécifie la langue dans laquelle l'application présente les contenus aux utilisateurs finaux.
La valeur par défaut de cette propriété est `en`, pour anglais. Vous devez configurer cette propriété si votre application doit prendre en charge plusieurs langues.
La valeur de cette propriété détermine des aspects variés de l'[internationalisation](tutorial-i18n.md) tels que la traduction des messages, le formatage des dates et des nombres, etc. Par exemple, le widget [[yii\jui\DatePicker]] utilise la valeur de cette propriété pour déterminer dans quelle langue le calendrier doit être affiché et comment les dates doivent être formatées.
La spécification de la langue par une [étiquette IETF d'identification de langue ](http://en.wikipedia.org/wiki/IETF_language_tag) est recommandée. Par exemple, `en` signifie anglais, tandis que `en-US` signifie anglais (États-Unis)..
Pour plus d'informations sur cette propriété, reportez-vous à la section [Internationalisation](tutorial-i18n.md).
#### [[yii\base\Application::modules|modules]] <span id="modules"></span>
Cette propriété spécifie les [modules](structure-modules.md) que comprend l'application.
Cette propriété accepte un tableau de classes de module ou de tableaux de [configurations](concept-configurations.md) dans lequel les clés sont les identifiants (ID) des modules. Par exemple :
```php
[
'modules' => [
// un module "booking" (réservations) spécifié par sa classe
'booking' => 'app\modules\booking\BookingModule',
// un module "comment" (commentaires) spécifié par un tableau de configuration
'comment' => [
'class' => 'app\modules\comment\CommentModule',
'db' => 'db',
],
],
]
```
Reportez-vous à la section [Modules](structure-modules.md) pour des informations complémentaires.
#### [[yii\base\Application::name|name (nom]] <span id="name"></span>
Cette propriété spécifie le nom de l'application qui est présenté à l'utilisateur final. Contrairement à la propriété
[[yii\base\Application::id|id]] qui ne peut prendre qu'une valeur unique, la valeur de cette propriété, qui n'intervient que pour l'affichage, n'a pas besoin d'être unique.
Vous n'avez pas besoin de configurer cette propriété si vous ne l'utilisez pas dans votre code.
#### [[yii\base\Application::params|params (paramètres)]] <span id="params"></span>
Cette propriété spécifie un tableau de paramètres de l'application accessibles globalement. Plutôt que de parsemer votre code des mêmes nombres et chaînes de caractères formulées `en dur`, une bonne pratique consiste à les définir une fois pour toute sous forme de paramètres et à utiliser ces paramètres ici et là, ce qui évite, si vous devez en modifier la valeur, d'intervenir en de multiples endroits de votre code. À titre d'exemple, vous pouvez définir la taille des vignettes d'images en tant que paramètre de la façon suivante :
```php
[
'params' => [
'thumbnail.size' => [128, 128],
],
]
```
puis dans votre code, là où vous devez utiliser cette taille, procéder de la façon suivante :
```php
$size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0];
```
Plus tard, si vous changez d'avis à propos de la taille de ces vignettes, il vous suffit de modifier la valeur du paramètre dans la configuration de l'application sans avoir à toucher à votre code.
#### [[yii\base\Application::sourceLanguage|sourceLanguage (langue source)]] <span id="sourceLanguage"></span>
Cette propriété spécifie la langue dans laquelle l'application est écrite. La valeur par défaut est `'en-US'`,
pour (anglais — États-Unis). Vous devriez configurer cette propriété si les textes dans votre code ne sont pas en anglais US.
Comme pour la propriété [language (langue)](#language), vous devez configurer cette propriété à l'aide d'une [étiquette IETF d'identification de langue](http://en.wikipedia.org/wiki/IETF_language_tag). Par exemple, `en` signifie `anglais`,
tandis que `en-US` signifie for `anglais-États-Unis`).
Pour plus d'informations sur cette propriété, reportez-vous à la section [Internationalisation](tutorial-i18n.md).
#### [[yii\base\Application::timeZone|timeZone (fuseau horaire)]] <span id="timeZone"></span>
Cette propriété est fournie comme une manière alternative de définir le fuseau horaire par défaut au moment de l'exécution du script PHP.
En configurant cette propriété, vous ne faites essentiellement qu'appeler la fonction PHP
[date_default_timezone_set()](http://php.net/manual/en/function.date-default-timezone-set.php). Par exemple :
```php
[
'timeZone' => 'America/Los_Angeles',
]
```
#### [[yii\base\Application::version|version]] <span id="version"></span>
Cette propriété spécifie la version de l'application. Sa valeur par défaut est `'1.0'`. Il n'est pas nécessaire que vous définissiez cette propriété si vous ne l'utilisez pas dans votre code.
### Propriétés utiles <span id="useful-properties"></span>
Les propriétés décrites dans cette sous-section ne sont en général pas spécifiées car leur valeur par défaut dérive de conventions ordinaires. Néanmoins, vous pouvez les spécifier pour outrepasser les conventions.
#### [[yii\base\Application::charset|charset (jeu de caractères)]] <span id="charset"></span>
Cette propriété spécifie le jeu de caractères que l'application utilise. La valeur par défaut est `'UTF-8'`, qui devrait être gardée telle quelle dans la plupart des applications sauf si vous travaillez avec un système ancien qui utilise de nombreuses données non Unicode.
#### [[yii\base\Application::defaultRoute|defaultRoute (route par défaut) ]] <span id="defaultRoute"></span>
Cette propriété spécifie la [route](runtime-routing.md) qu'une application devrait utiliser lorsqu'une requête n'en spécifie aucune. La route peut être constituée à partir d'un identifiant de module, d'un identifiant de contrôleur et/ou d'un identifiant d'action. Par exemple, `help`, `post/create` ou `admin/post/create`. Si un identifiant d'action n'est pas fourni, cette propriété prend la valeur par défaut spécifiée dans [[yii\base\Controller::defaultAction]]
Pour les [[yii\web\Application|applications Web]], la valeur par défaut de cette propriété est `'site'`, ce qui donne le contrôleur
`SiteController` et son action par défaut est utilisée. En conséquence, si vous accédez à l'application sans spécifier de route, vous aboutissez à ce que retourne l'action `app\controllers\SiteController::actionIndex()`.
Pour les [[yii\console\Application|applications de console]], la valeur par défaut est `'help'` (aide), ce qui conduit à
[[yii\console\controllers\HelpController::actionIndex()]]. Par conséquent, si vous exécutez la commande `yii` sans lui fournir d'argument, l'application affiche l'information d'aide.
#### [[yii\base\Application::extensions|extensions]] <span id="extensions"></span>
Cette propriété spécifie la liste des [extensions](structure-extensions.md) installées et utilisées par l'application.
Par défaut, elle reçoit le tableau retourné par le fichier `@vendor/yiisoft/extensions.php`. Le fichier `extensions.php` est généré et maintenu automatiquement lorsque vous faites appel à [Composer](https://getcomposer.org) pour installer des extensions. Ainsi, dans la plupart des cas, vous n'avez pas besoin de spécifier cette propriété.
Dans le cas particulier où vous souhaitez maintenir les extensions à la main, vous pouvez configurer cette propriété de la manière suivante :
```php
[
'extensions' => [
[
'name' => 'extension name', //nom de l'extension
'version' => 'version number',//numéro de version
'bootstrap' => 'BootstrapClassName', // facultatif, peut aussi être un tableau de configuration
'alias' => [ // facultatif
'@alias1' => 'vers/chemin1',
'@alias2' => 'vers/chemin2',
],
],
// ... configuration d'autres extensions similaires à ce qui précède ...
],
]
```
Comme vous pouvez le constater, la propriété reçoit un tableau de spécifications d'extension. Chacune des extensions est spécifiée par un tableau constitué du
nom (`name`) et de la `version` de l'extension. Si une extension doit être exécutée durant le processus d'[amorçage](runtime-bootstrapping.md), un élément `bootstrap` doit être spécifié par un nom de classe d'amorçage (`bootstrap`) ou un tableau de [configuration](concept-configurations.md). Une extension peut aussi définir quelques [alias](concept-aliases.md).
#### [[yii\base\Application::layout|layout (disposition de page)]] <span id="layout"></span>
Cette propriété spécifie le nom de la disposition de page par défaut (`layout`) qui doit être utilisée lors du rendu d'une [vue](structure-views.md). La valeur par défaut est `'main'`, ce qui signifie que le fichier de disposition de page `main.php` sous le chemin [layout path](#layoutPath) est utilisé.
Si, à la fois, le chemin de la disposition de page [layout path](#layoutPath) et le chemin de la vue [view path](#viewPath) prennent leur valeur par défaut, le fichier de disposition de page par défaut peut être représenté par l'alias `@app/views/layouts/main.php`.
Vous pouvez définir cette propriété à la valeur `false` pour désactiver la disposition de page par défaut, bien que cela se fasse rarement.
#### [[yii\base\Application::layoutPath|layoutPath (chemin de la disposition de page)]] <span id="layoutPath"></span>
Cette propriété spécifie le chemin du dossier où rechercher les fichiers de disposition de page. La valeur par défaut `layouts` correspond à un sous-dossier de [view path](#viewPath). Si [view path](#viewPath) prend sa valeur par défaut, le chemin de la disposition de page par défaut peut être représenté par l'alias `@app/views/layouts`.
Vous pouvez le définir comme un dossier ou un [alias](concept-aliases.md) de chemin.
#### [[yii\base\Application::runtimePath|runtimePath (chemin du dossier d'exécution)]] <span id="runtimePath"></span>
Cette propriété spécifie le chemin du dossier où les fichiers temporaires, tels que les journaux et les fichiers de cache, sont placés. La valeur par défaut est `@app/runtime`.
Vous pouvez configurer cette propriété comme un dossier ou un [alias](concept-aliases.md) de chemin. Notez que le dossier d'exécution `runtimePath` doit être accessible en écriture par le processus qui exécute l'application et rendu inaccessible aux utilisateurs finaux, parce que les fichiers temporaires qu'il contient peuvent contenir des informations sensibles.
Pour simplifier l'accès à ce chemin, Yii a prédéfini un alias de chemin nommé `@runtime`.
#### [[yii\base\Application::viewPath|viewPath (chemin des vues)]] <span id="viewPath"></span>
Cette propriété spécifie le dossier racine des fichiers de vues. La valeur par défaut est le dossier représenté par l'alias `@app/views`. Vous pouvez le définir sous forme de dossier ou comme un [alias](concept-aliases.md) de chemin.
#### [[yii\base\Application::vendorPath|vendorPath (chemin des vendeurs)]] <span id="vendorPath"></span>
Cette propriété spécifie le dossier des vendeurs gérés par [Composer](https://getcomposer.org). Il contient toutes les bibliothèques de tierces parties utilisées par l'application, y compris le *framework* Yii. La valeur par défaut est le dossier représenté par `@app/vendor`.
Vous pouvez configurer cette propriété comme un dossier ou un [alias](concept-aliases.md) de chemin. Lorsque vous modifiez cette propriété, assurez-vous d'ajuster la configuration de Composer en conséquence.
Pour simplifier l'accès à ce chemin, Yii a prédéfini un alias de chemin nommé `@vendor`.
#### [[yii\console\Application::enableCoreCommands|enableCoreCommands (activer les commandes du noyau)]] <span id="enableCoreCommands"></span>
Cette propriété est prise en charge par les [[yii\console\Application|applications de console]] uniquement. Elle spécifie si les commandes du noyau de la version de Yii sont activées ou pas. La valeur par défaut est `true` (vrai).
## Événements d'application <span id="application-events"></span>
Une application déclenche plusieurs événements tout au long de son cycle de vie pour prendre en compte une requête. Vous pouvez attacher des gestionnaires d'événement à ces événements dans la configuration de l'application de la manière suivante :
```php
[
'on beforeRequest' => function ($event) {
// ...
},
]
```
L'utilisation de la syntaxe `on eventName` (on Non d'événement) est décrite dans la section [Configurations](concept-configurations.md#configuration-format).
En alternative, vous pouvez attacher les gestionnaires d'événement lors du [processus d'amorçage](runtime-bootstrapping.md) après que l'objet Application a été instancié. Par exemple :
```php
\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
// ...
});
```
### [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] <span id="beforeRequest"></span>
Cette événement est déclenché *avant* que l'application ne prenne la requête en charge. Le nom réel de l'événement est `beforeRequest`.
Lorsque cet événement est déclenché, l'objet Application a été configuré et initialisé. C'est donc un bon endroit pour insérer votre code personnalisé via le mécanisme événementiel pour intercepter le processus de prise en charge de la requête. Par exemple, dans le gestionnaire d'événement, vous pouvez définir dynamiquement la propriété [[yii\base\Application::language (langue)]] en fonction de certains paramètres.
### [[yii\base\Application::EVENT_AFTER_REQUEST|EVENT_AFTER_REQUEST]] <span id="afterRequest"></span>
Cet événement est déclenché *après* que l'application a fini de prendre la requête en charge mais *avant* que la réponse ne soit envoyée. Le nom réel de l'événement est `afterRequest`.
Lorsque cet événement est déclenché, la prise en charge de la requête est terminée et vous pouvez profiter de cette opportunité pour effectuer quelques post-traitements de la requête et personnaliser la réponse.
Notez que le composant [[yii\web\Response|response (réponse)]] déclenche également quelques événements tandis qu'il envoie la réponse au navigateur. Ces événements sont déclenchés *après* cet événement.
### [[yii\base\Application::EVENT_BEFORE_ACTION|EVENT_BEFORE_ACTION]] <span id="beforeAction"></span>
Cet événement est déclenché *avant* d'exécuter toute [action de contrôleur](structure-controllers.md).
Le nom réel de l'événement est `beforeAction`.
Le paramètre de l'événement est une instance de [[yii\base\ActionEvent]]. Un gestionnaire d'événement peut définir la propriété [[yii\base\ActionEvent::isValid (est valide)]] à `false` pour arrêter l'exécution de l'action.
Par exemple:
```php
[
'on beforeAction' => function ($event) {
if (some condition) {
$event->isValid = false;
} else {
}
},
]
```
Notez que le même événement `beforeAction` est également déclenché par les [modules](structure-modules.md)
et les [contrôleurs](structure-controllers.md).L'objet *Application* est le premier à déclencher cet événement, suivis des modules (s'il en existe) et, pour finir, des contrôleurs. Si un gestionnaire d'événement défini la propriété [[yii\base\ActionEvent::isValid]] à `false`, tous les événements qui devraient suivre ne sont PAS déclenchés.
### [[yii\base\Application::EVENT_AFTER_ACTION|EVENT_AFTER_ACTION]] <span id="afterAction"></span>
Cet événement est déclenché *après* que chacune des [actions de contrôleur](structure-controllers.md) a été exécutée.
Le paramètre de l'événement est [[yii\base\ActionEvent]]. Un gestionnaire d'événement peut accéder au résultat de l'action et le modifier via la propriété [[yii\base\ActionEvent::result]].
Par exemple:
```php
[
'on afterAction' => function ($event) {
if (some condition) {
// modify $event->result
} else {
}
},
]
```
Notez que le même événement `afterAction` est également déclenché par les [modules](structure-modules.md)
et les [contrôleurs](structure-controllers.md). Ces objets déclenchent ces événements dans l'ordre inverse de celui des événements déclenchés par `beforeAction`. En clair, les contrôleurs sont les premiers objets à déclencher cet événement, suivis des modules (s'il en existe) et, finalement, de l'application.
## Cycle de vie d'une application<span id="application-lifecycle"></span>
![Application Lifecycle](images/application-lifecycle.png)
Lorsqu'un [script d'entrée](structure-entry-scripts.md) est exécuté pour prendre en compte une requête, une application entame le cycle de vie suivant :
1. Le script d'entrée charge la configuration de l'application sous forme de tableau.
2. Le script d'entrée crée un nouvel objet *Application* :
* Sa méthode [[yii\base\Application::preInit()|preInit()]] est appelée pour configurer quelques propriétés de haute priorité de cette application, comme [[yii\base\Application::basePath|basePath]].
* Il enregistre [[yii\base\Application::errorHandler|le gestionnaire d'erreurs]].
* Il configure les propriétés de l'application.
* Sa méthode [[yii\base\Application::init()|init()]] est appelée qui appelle ensuite la méthode
[[yii\base\Application::bootstrap()|bootstrap()]] pour exécuter les composants du processus d'amorçage.
3. Le script d'entrée appelle la méthode [[yii\base\Application::run()]] pour exécuter l'application qui :
* déclenche l'événement [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]];
* prend en charge la requête: résout la requête en une [route](runtime-routing.md) et ses paramètres associés;
* crée le module, le contrôleur et l'action spécifiés par la route et exécute l'action ;
* déclenche l'événement [[yii\base\Application::EVENT_AFTER_REQUEST|EVENT_AFTER_REQUEST]];
* renvoie la réponse au navigateur.
4. Le script d'entrée reçoit l'état de sortie de l'exécution de l'application et complète le processus de prise en charge de la requête.

364
docs/guide-fr/structure-controllers.md

@ -0,0 +1,364 @@
Contrôleurs
===========
Les contrôleurs font partie du modèle d'architecture [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) (Modèle Vue Contrôleur). Ce sont des objets dont la classe étend [[yii\base\Controller]]. Ils sont chargés de traiter les requêtes et de générer les réponses. En particulier, après que l'objet [application](structure-applications.md) leur a passé le contrôle, ils analysent les données de la requête entrante, les transmettent aux [modèles](structure-models.md), injectent le résultat des modèles dans les [vues](structure-views.md) et, pour finir, génèrent les réponses sortantes.
## Actions <span id="actions"></span>
Les contrôleurs sont constitués d'*actions* qui sont les unités les plus élémentaires dont l'utilisateur final peut demander l'exécution. Un contrôleur comprend une ou plusieurs actions.
L'exemple qui suit présente un contrôleur `post` avec deux actions : `view` et `create`:
```php
namespace app\controllers;
use Yii;
use app\models\Post;
use yii\web\Controller;
use yii\web\NotFoundHttpException;
class PostController extends Controller
{
public function actionView($id)
{
$model = Post::findOne($id);
if ($model === null) {
throw new NotFoundHttpException;
}
return $this->render('view', [
'model' => $model,
]);
}
public function actionCreate()
{
$model = new Post;
if ($model->load(Yii::$app->request->post()) && $model->save()) {
return $this->redirect(['view', 'id' => $model->id]);
} else {
return $this->render('create', [
'model' => $model,
]);
}
}
}
```
Dans l'action `view` (définie par la méthode `actionView()`), le code commence par charger le [modèle](structure-models.md) en fonction de l'identifiant (ID) du modèle requis. Si le chargement du modèle réussit, l'action l'affiche en utilisant une [vue](structure-views.md) nommée `view`. Autrement, elle lève une exception.
Dans l'action `create` (définie par le méthode `actionCreate()`), le code est similaire. Elle commence par essayer de peupler une nouvelle instance du [modèle](structure-models.md) avec les données de la requête et sauvegarde le modèle. Si les deux opérations réussissent, elle redirige le navigateur vers l'action `view` en lui passant l'identifiant (ID) du nouveau modèle. Autrement, elle affiche la vue `create` dans laquelle l'utilisateur peut saisir les entrées requises.
## Routes <span id="routes"></span>
L'utilisateur final demande l'exécution des actions via ce qu'on appelle des *routes*. Une route est une chaîne de caractères constituée des parties suivantes :
* un identifiant (ID) de module : cette partie n'est présente que si le contrôleur appartient à un [module](structure-modules.md) qui n'est pas en soi une application ;
* un [identifiant de contrôleur](#controller-ids) : une chaîne de caractères qui distingue le contrôleur des autres contrôleurs de la même application — ou du même module si le contrôleur appartient à un module ;
* un [identifiant d'action](#action-ids) : une chaîne de caractères qui distingue cette action des autres actions du même contrôleur.
Les routes se présentent dans le format suivant :
```
identifiant_de_contrôleur/identifiant_d_action
```
ou dans le format suivant si le contrôleur appartient à un module :
```php
identifiant_de_module/identifiant_de_contrôleur/identifiant_d_action
```
Ainsi si un utilisateur requiert l'URL `http://hostname/index.php?r=site/index`, l'action `index` dans le contrôleur `site` sera exécutée. Pour plus de détails sur la façon dont les routes sont résolues, reportez-vous à la section [Routage et génération d'URL](runtime-routing.md).
## Création des contrôleurs <span id="creating-controllers"></span>
Dans les [[yii\web\Application|applications Web]], les contrôleur doivent étendre la classe [[yii\web\Controller]] ou ses classes filles. De façon similaire, dans les [[yii\console\Application|applications de console]], les contrôleurs doivent étendre la classe [[yii\console\Controller]] ou ses classes filles. Le code qui suit définit un contrôleur nommé `site` :
```php
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
}
```
### Identifiant des contrôleurs <span id="controller-ids"></span>
Généralement, un contrôleur est conçu pour gérer les requêtes concernant un type particulier de ressource. Pour cette raison, l'identifiant d'un contrôleur est souvent un nom faisant référence au type de ressources que ce contrôleur gère.
Par exemple, vous pouvez utiliser `article` comme identifiant d'un contrôleur qui gère des données d'articles.
Par défaut, l'identifiant d'un contrôleur ne peut contenir que les caractères suivants : lettres de l'alphabet anglais en bas de casse, chiffres, tiret bas, trait d'union et barre oblique de division. Par exemple, `article` et `post-comment` sont tous deux des identifiants de contrôleur valides, tandis que `article?`, `PostComment` et `admin\post` ne le sont pas.
Un identifiant de contrôleur peut aussi contenir un préfixe de sous-dossier. Par exemple `admin/article` représente un contrôleur `article` dans le dossier `admin` dans l'[[yii\base\Application::controllerNamespace|espace de noms du contrôleur]].
Les caractères valides pour le préfixe des sous-dossiers incluent : les lettres de l'alphabet anglais dans les deux casses, les chiffres, le tiret bas et la barre oblique de division, parmi lesquels les barres obliques de division sont utilisées comme séparateurs pour les sous-dossiers à plusieurs niveaux (p. ex. `panels/admin`).
### Nommage des classes de contrôleur <span id="controller-class-naming"></span>
Les noms de classe de contrôleur peut être dérivés de l'identifiant du contrôleur selon la procédure suivante :
1. Mettre la première lettre de chacun des mots séparés par des trait d'union en capitale. Notez que si l'identifiant du contrôleur contient certaines barres obliques, cette règle ne s'applique qu'à la partie après la dernière barre oblique dans l'identifiant.
2. Retirer les traits d'union et remplacer toute barre oblique de division par une barre oblique inversée.
3. Ajouter le suffixe `Controller`.
4. Préfixer avec l'[[yii\base\Application::controllerNamespace|espace de noms du contrôleur]].
Ci-après sont présentés quelques exemples en supposant que l'[[yii\base\Application::controllerNamespace|espace de noms du contrôleur]] prend la valeur par défaut, soit `app\controllers`:
* `article` donne `app\controllers\ArticleController`;
* `post-comment` donne `app\controllers\PostCommentController`;
* `admin/post-comment` donne `app\controllers\admin\PostCommentController`;
* `adminPanels/post-comment` donne `app\controllers\adminPanels\PostCommentController`.
Les classes de contrôleur doivent être [auto-chargeables](concept-autoloading.md). Pour cette raison, dans les exemples qui précèdent, la classe de contrôleur `article` doit être sauvegardée dans le fichier dont l'[alias](concept-aliases.md) est `@app/controllers/ArticleController.php`; tandis que la classe de contrôleur `admin/post-comment` doit se trouver dans `@app/controllers/admin/PostCommentController.php`.
> Info: dans le dernier exemple, `admin/post-comment` montre comment placer un contrôleur dans un sous-dossier de l'[[yii\base\Application::controllerNamespace|espace de noms du contrôleur]]. Cela est utile lorsque vous voulez organiser vos contrôleurs en plusieurs catégories et que vous ne voulez pas utiliser de [modules](structure-modules.md).
### Cartographie des contrôleurs <span id="controller-map"></span>
Vous pouvez configurer [[yii\base\Application::controllerMap|controller map (cartographie des contrôleurs)]] pour outrepasser les contraintes concernant les identifiants de contrôleur et les noms de classe décrites plus haut. Cela est principalement utile lorsque vous utilisez des contrôleurs de tierces parties et que vous n'avez aucun contrôle sur le nommage de leur classe.
Vous pouvez configurer [[yii\base\Application::controllerMap|controller map]] dans la [configuration de l'application](structure-applications.md#application-configurations). Par exemple :
```php
[
'controllerMap' => [
// declares "account" controller using a class name
'account' => 'app\controllers\UserController',
// declares "article" controller using a configuration array
'article' => [
'class' => 'app\controllers\PostController',
'enableCsrfValidation' => false,
],
],
]
```
### Contrôleur par défaut <span id="default-controller"></span>
Chaque application possède un contrôleur par défaut spécifié via la propriété [[yii\base\Application::defaultRoute]]. Lorsqu'une requête ne précise aucune [route](#routes), c'est la route spécifiée par cette propriété qui est utilisée. Pour les [[yii\web\Application|applications Web]], sa valeur est `'site'`, tandis que pour les [[yii\console\Application|applications de console]], c'est `help`. Par conséquent, si une URL est de la forme `http://hostname/index.php`, c'est le contrôleur `site` qui prend la requête en charge.
Vous pouvez changer de contrôleur par défaut en utilisant la [configuration d'application](structure-applications.md#application-configurations) suivante :
```php
[
'defaultRoute' => 'main',
]
```
## Création d'actions <span id="creating-actions"></span>
Créer des actions est aussi simple que de définir ce qu'on appelle des *méthodes d'action* dans une classe de contrôleur. Une méthode d'action est une méthode *publique* dont le nom commence par le mot `action`. La valeur retournée par une méthode d'action représente les données de la réponse à envoyer à l'utilisateur final. Le code qui suit définit deux actions, `index` et `hello-world`:
```php
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
public function actionIndex()
{
return $this->render('index');
}
public function actionHelloWorld()
{
return 'Hello World';
}
}
```
### Identifiants d'action <span id="action-ids"></span>
Une action est souvent conçue pour effectuer une manipulation particulière d'une ressource. Pour cette raison, les identifiants d'action sont habituellement des verbes comme `view` (voir), `update` (mettre à jour), etc.
Par défaut, les identifiants d'action ne doivent contenir rien d'autre que les caractères suivants : les lettres de l'alphabet anglais en bas de casse, les chiffres, le tiret bas et le trait d'union. Vous pouvez utiliser le trait d'union pour séparer les mots. Par exemple :
`view`, `update2`, et `comment-post` sont des identifiants d'action valides, tandis que `view?` et `Update` ne le sont pas.
Vous pouvez créer des actions sous deux formes : les actions en ligne (*inline*) et les actions autonomes (*standalone*). Une action en ligne est définie en tant que méthode dans un contrôleur, alors qu'une action autonome est une classe qui étend la classe [[yii\base\Action]] ou une des ses classes filles. La définition d'une action en ligne requiert moins d'efforts et est souvent préférée lorsqu'il n'y a pas d'intention de réutiliser cette action. Par contre, les actions autonomes sont essentiellement créées pour être utilisées dans différents contrôleurs ou pour être redistribuées dans des [extensions](structure-extensions.md).
### Actions en ligne <span id="inline-actions"></span>
Les actions en ligne sont les actions qui sont définies en terme de méthodes d'action comme nous l'avons décrit plus haut.
Les noms des méthodes d'action sont dérivés des identifiants d'action selon la procédure suivante :
1. Mettre la première lettre de chaque mot de l'identifiant en capitale.
2. Supprimer les traits d'union.
3. Préfixer le tout par le mot `action`.
Par exemple, `index` donne `actionIndex`, et `hello-world` donne `actionHelloWorld`.
> Note: les noms des méthodes d'action sont *sensibles à la casse*. Si vous avez une méthode nommée `ActionIndex`, elle ne sera pas considérée comme étant une méthode d'action et, par conséquent, la requête de l'action `index` aboutira à une exception. Notez également que les méthodes d'action doivent être publiques. Une méthode privée ou protégée ne définit PAS une action en ligne.
Les actions en ligne sont les actions les plus communément définies parce qu'elle ne requièrent que peu d'efforts pour leur création. Néanmoins, si vous envisagez de réutiliser la même action en différents endroits, ou si vous voulez redistribuer cette action, vous devriez envisager de la définir en tant qu'*action autonome*.
### Actions autonomes <span id="standalone-actions"></span>
Les actions autonomes sont définies comme des classes d'action qui étendent la classe [[yii\base\Action]] ou une de ses classes filles.
Par exemple, dans les versions de Yii, il y a [[yii\web\ViewAction]] et [[yii\web\ErrorAction]], qui sont toutes les deux des actions autonomes.
Pour utiliser une action autonome, vous devez la déclarer dans la *cartographie des actions* en redéfinissant les méthodes de la classe [[yii\base\Controller::actions()]] dans la classe de votre contrôleur de la manière suivante :
```php
public function actions()
{
return [
// déclare une action "error" en utilisant un nom de classe
'error' => 'yii\web\ErrorAction',
// déclare une action "view" action en utilisant un tableau de configuration
'view' => [
'class' => 'yii\web\ViewAction',
'viewPrefix' => '',
],
];
}
```
Comme vous pouvez l'observer, les méthodes `actions()` doivent retourner un tableau dont les clés sont les identifiants d'action et les valeurs le nom de la classe d'action correspondant ou des tableaux de [configuration](concept-configurations.md). Contrairement aux actions en ligne, les identifiants d'action autonomes peuvent comprendre n'importe quels caractères du moment qu'ils sont déclarés dans la méthode `actions()`.
Pour créer une classe d'action autonome, vous devez étendre la classe [[yii\base\Action]] ou une de ses classes filles, et implémenter une méthode publique nommée `run()`. Le rôle de la méthode `run()` est similaire à celui d'une méthode d'action. Par exemple :
```php
<?php
namespace app\components;
use yii\base\Action;
class HelloWorldAction extends Action
{
public function run()
{
return "Hello World";
}
}
```
### Valeur de retour d'une action <span id="action-results"></span>
Le valeur de retour d'une méthode d'action, ou celle de la méthode `run()` d'une action autonome, représente le résultat de l'action correspondante.
La valeur de retour peut être un objet [response](runtime-responses.md) qui sera transmis à l'utilisateur final en tant que réponse.
* Pour les [[yii\web\Application|applications Web]], la valeur de retour peut également être des données arbitraires qui seront assignées à l'objet [[yii\web\Response::data]] et converties ensuite en une chaîne de caractères représentant le corps de la réponse.
* Pour les [[yii\console\Application|applications de console]], la valeur de retour peut aussi être un entier représentant l'[[yii\console\Response::exitStatus|état de sortie]] de l'exécution de la commande.
Dans les exemples ci-dessus, les valeurs de retour des actions sont toutes des chaînes de caractères qui seront traitées comme le corps de la réponse envoyée à l'utilisateur final. Les exemples qui suivent montrent comment une action peut rediriger le navigateur vers une nouvelle URL en retournant un objet *response* (parce que la méthode [[yii\web\Controller::redirect()|redirect()]] retourne un objet *response*) :
```php
public function actionForward()
{
// redirect the user browser to http://example.com
return $this->redirect('http://example.com');
}
```
### Paramètres d'action <span id="action-parameters"></span>
Les méthodes d'action pour les actions en ligne et la méthode `run()` d'une action autonome acceptent des paramètres appelés *paramètres d'action*. Leurs valeurs sont tirées des requêtes. Pour les [[yii\web\Application|applications Web]], la valeur de chacun des paramètres d'action est obtenue de la méthode `$_GET` en utilisant le nom du paramètre en tant que clé. Pour les [[yii\console\Application|applications de console]], les valeurs des paramètres correspondent aux argument de la commande.
Dans d'exemple qui suit, l'action `view` (une action en ligne) déclare deux paramètres : `$id` et `$version`.
```php
namespace app\controllers;
use yii\web\Controller;
class PostController extends Controller
{
public function actionView($id, $version = null)
{
// ...
}
}
```
En fonction de la requête, les paramètres de l'action seront établis comme suit :
* `http://hostname/index.php?r=post/view&id=123`: le paramètre `$id` reçoit la valeur `'123'`, tandis que le paramètre `$version` reste *null* (sa valeur par défaut) car la requête ne contient aucun paramètre `version`.
* `http://hostname/index.php?r=post/view&id=123&version=2`: les paramètres `$id` et `$version` reçoivent les valeurs `'123'` et `'2'`, respectivement.
* `http://hostname/index.php?r=post/view`: une exception [[yii\web\BadRequestHttpException]] est levée car le paramètre obligatoire `$id` n'est pas fourni par la requête.
* `http://hostname/index.php?r=post/view&id[]=123`: une exception [[yii\web\BadRequestHttpException]] est levée car le paramètre `$id` reçoit, de manière inattendue, un tableau (`['123']`).
Si vous voulez que votre paramètre d'action accepte un tableau, il faut, dans la définition de la méthode, faire allusion à son type, avec `array`, comme ceci :
```php
public function actionView(array $id, $version = null)
{
// ...
}
```
Désormais, si la requête est `http://hostname/index.php?r=post/view&id[]=123`, le paramètre `$id` accepte la valeur `['123']`. Si la requête est `http://hostname/index.php?r=post/view&id=123`, le paramètre `$id` accepte également la valeur transmise par la requête parce que les valeurs scalaires sont automatiquement convertie en tableau (*array*).
Les exemples qui précèdent montrent essentiellement comment les paramètres d'action fonctionnent dans les applications Web. Pour les applications de console, reportez-vous à la section [Commandes de console](tutorial-console.md) pour plus de détails.
### Action par défaut <span id="default-action"></span>
Chaque contrôleur dispose d'une action par défaut spécifiée par la propriété [[yii\base\Controller::defaultAction]].
Lorsqu'une [route](#routes) ne contient que l'identifiant du contrôleur, cela implique que l'action par défaut de ce contrôleur est requise.
Par défaut, l'action par défaut est définie comme étant `index`. Si vous désirez changer cette valeur par défaut, contentez-vous de redéfinir cette propriété dans la classe du contrôleur, comme indiqué ci-après :
```php
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
public $defaultAction = 'home';
public function actionHome()
{
return $this->render('home');
}
}
```
## Cycle de vie d'un contrôleur <span id="controller-lifecycle"></span>
Lors du traitement d'une requête, une [application](structure-applications.md) crée un contrôleur en se basant sur la [route](#routes) requise. Le contrôleur entame alors le cycle de vie suivant pour satisfaire la requête :
1. La méthode [[yii\base\Controller::init()]] est appelée après que le contrôleur est créé et configuré.
2. Le contrôleur crée un objet *action* en se basant sur l'identifiant d'action de la requête :
* Si l'identifiant de l'action n'est pas spécifié, l'[[yii\base\Controller::defaultAction|identifiant de l'action par défaut]] est utilisé.
* Si l'identifiant de l'action est trouvé dans la [yii\base\Controller::actions()|cartographie des actions]], une action autonome est créée.
* Si l'identifiant de l'action est trouvé et qu'il correspond à une méthode d'action, une action en ligne est créée.
* Dans les autres cas, une exception [[yii\base\InvalidRouteException]] est levée.
3. Le contrôleur appelle consécutivement la méthode `beforeAction()` de l'application, celle du module (si module si le contrôleur appartient à un module) et celle du contrôleur.
* Si l'un des appels retourne *false*, les appels aux méthodes `beforeAction()` qui devraient suivre ne sont pas effectués et l'exécution de l'action est annulée.
* Par défaut, chacun des appels à la méthode `beforeAction()` déclenche un événement `beforeAction` auquel vous pouvez attacher un gestionnaire d'événement.
4. Le contrôleur exécute l'action.
* Les paramètres de l'action sont analysés et définis à partir des données transmises par la requête.
5. Le contrôleur appelle successivement la méthode `afterAction()` du contrôleur, du module (si le contrôleur appartient à un module) et de l'application.
* Par défaut, chacun des appels à la méthode `afterAction()` déclenche un événement `afterAction` auquel vous pouvez attacher un gestionnaire d'événement.
6. L'application assigne le résultat de l'action à l'objet [response](runtime-responses.md).
## Meilleures pratiques <span id="best-practices"></span>
Dans une application bien conçue, les contrôleurs sont souvent très légers avec des actions qui ne contiennent que peu de code. Si votre contrôleur est plutôt compliqué, cela traduit la nécessité de remanier le code pour en déplacer certaines parties dans d'autres classes.
Voici quelques meilleures pratiques spécifiques. Les contrôleurs :
* peuvent accéder aux données de la [requête](runtime-requests.md);
* peuvent appeler les méthodes des [modèles](structure-models.md) et des autres composants de service avec les données de la requête;
* peuvent utiliser des [vues](structure-views.md) pour composer leurs réponses;
* ne devraient PAS traiter les données de la requête — cela devrait être fait dans la [couche modèle](structure-models.md);
* devraient éviter d'encapsuler du code HTML ou tout autre code relatif à la présentation — cela est plus avantageusement fait dans les [vues](structure-views.md).

34
docs/guide-fr/structure-entry-scripts.md

@ -1,22 +1,22 @@
Scripts d'entrée
=============
Les scripts d'entrée sont la première chaîne dans le processus de d'amorçage de l'application. Une application (qu'elle
soit une application Web ou une application console) a un unique script de démarrage. Les utilisateurs font des
requêtes au scripts de démarrage qui instancient des instances d'application et leur transmettent les requêtes.
Le script d'entrée est le premier rencontré dans le processus d'amorçage de l'application. Une application (qu'elle
soit une application Web ou une application console) a un unique script d'entrée. Les utilisateurs font des
requêtes au script d'entrée qui instancie un objet *Application* et lui transmet les requêtes.
Les scripts d'entrée pour application Web doivent être placés dans des dossiers accessibles par le Web pour que les
Les scripts d'entrée des applications Web doivent être placés dans des dossiers accessibles par le Web pour que les
utilisateurs puissent y accéder. Ils sont souvent nommés `index.php`, mais peuvent également avoir tout autre nom,
du moment que les serveurs Web peuvent les trouver.
Les scripts d'entrée pour les applications console sont généralement placés dans le [répertoire de base](structure-applications.md)
Les scripts d'entrée des applications console sont généralement placés dans le [répertoire de base](structure-applications.md)
des applications et sont nommés `yii` (avec le suffixe `.php`). Ils doivent être rendus exécutables afin que les
utilisateurs puissent lancer des applications console grâce à la commande `./yii <route> [arguments] [options]`.
Les scipts de démarrage effectuent principalement les tâches suivantes :
Les scipts d'entrée effectuent principalement les tâches suivantes :
* Définir des constantes globales;
* Enregistrer l'[autoloader Composer](https://getcomposer.org/doc/01-basic-usage.md#autoloading);
* Enregistrer l'[chargeur automatique Composer](https://getcomposer.org/doc/01-basic-usage.md#autoloading);
* Inclure le fichier de classe de [[Yii]];
* Charger la configuration de l'application;
* Créer et configurer une instance d'[application](structure-applications.md);
@ -25,7 +25,7 @@ Les scipts de démarrage effectuent principalement les tâches suivantes :
## Applications Web <span id="web-applications"></span>
Ce qui suit est le code du script de démarrage du [Modèle Basique d'Application Web](start-installation.md).
Ce qui suit est le code du script d'entrée du [Modèle Basique d'Application Web](start-installation.md).
```php
<?php
@ -81,19 +81,19 @@ exit($exitCode);
## Définir des Constantes <span id="defining-constants"></span>
Les scripts de démarrage sont l'endroit idéal pour définir des constantes globales. Yii supporte les trois constantes suivantes :
Les scripts d'entrée sont l'endroit idéal pour définir des constantes globales. Yii prend en charge les trois constantes suivantes :
* `YII_DEBUG` : spécifie si une application tourne en mode de débogage. Si elle est en mode de débogage, une
application loguera plus d'informations, et révélera des piles d'appels d'erreurs détaillées si des exceptions
sont lancées. C'est pour cette raison que le mode de débogage doit être utilisé principalement pendant la phase
de développement. La valeur par défaut de `YII_DEBUG` est faux.
* `YII_ENV` : spécifie sur quel environnement l'application est en train de tourner. Cela a été décrit plus en détails
application enregistrera des journaux plus détaillés, et révélera des piles d'appels d'erreurs détaillées si des exceptions
sont levées. C'est pour cette raison que le mode de débogage doit être utilisé principalement pendant la phase
de développement. La valeur par défaut de `YII_DEBUG` est `false` (faux).
* `YII_ENV` : spécifie dans quel environnement l'application est en train de tourner. Cela est décrit plus en détails
dans la section [Configurations](concept-configurations.md#environment-constants). La valeur par défaut de `YII_ENV`
est `'prod'`, ce qui signifie que l'application tourne en environnement de production.
est `'prod'`, ce qui signifie que l'application tourne dans l'environnement de production.
* `YII_ENABLE_ERROR_HANDLER` : spécifie si le gestionnaire d'erreurs fourni par Yii doit être activé. La valeur par
défaut de cette constantes est vrai.
défaut de cette constante est `true` (vrai).
Quand on définit une constant, on utilise souvent le code suivant :
Quand on définit une constante, on utilise souvent le code suivant :
```php
defined('YII_DEBUG') or define('YII_DEBUG', true);
@ -109,5 +109,5 @@ if (!defined('YII_DEBUG')) {
Clairement, le premier est plus succinct et plus aisé à comprendre.
Les définitions de constantes doit être faite au tout début d'un script de démarrage pour qu'elles puissent prendre
Les définitions de constantes doit être faites au tout début d'un script d'entrée pour qu'elles puissent prendre
effet quand d'autres fichiers PHP sont inclus.

430
docs/guide-fr/structure-models.md

@ -0,0 +1,430 @@
Modèles
=======
Les modèles font partie du modèle d'architecture [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) (Modèle Vue Contrôleur).
Ces objets représentent les données à traiter, les règles et la logique de traitement.
Vous pouvez créer des classes de modèle en étendant la classe [[yii\base\Model]] ou ses classe filles. La classe de base [[yii\base\Model]] prend en charge des fonctionnalités nombreuses et utiles :
* Les [attributs](#attributes) : ils représentent les données à traiter et peuvent être accédés comme des propriétés habituelles d'objets ou des éléments de tableaux.
* Les étiquettes d'[attribut](#attribute-labels) : elles spécifient les étiquettes pour l'affichage des attributs.
* L'[assignation massive](#massive-assignment) : elle permet l'assignation de multiples attributs en une seule étape.
* Les [règles de validation](#validation-rules) : elles garantissent la validité des données saisies en s'appuyant sur des règles de validation déclarées.
* L'[exportation des données](#data-exporting) : elle permet au modèle de données d'être exporté sous forme de tableaux dans des formats personnalisables.
La classe `Model` est également la classe de base pour des modèles plus évolués, comme la classe class [Active Record (enregistrement actif)](db-active-record.md). Reportez-vous à la documentation ad hoc pour plus de détails sur ces modèles évolués.
> Info: vous n'êtes pas forcé de baser vos classes de modèle sur la classe [[yii\base\Model]]. Néanmoins, comme il y a de nombreux composants de Yii conçus pour prendre en charge la classe [[yii\base\Model]], il est généralement préférable de baser vos modèles sur cette classe.
## Attributs <span id="attributes"></span>
Les modèles représentent les données de l'application en termes d'attributs. Chaque attribut est comme un propriété publiquement accessible d'un modèle. La méthode [[yii\base\Model::attributes()]] spécifie quels attributs une classe de modèle possède.
Vous pouvez accéder à un attribut comme vous accédez à une propriété d'un objet ordinaire :
```php
$model = new \app\models\ContactForm;
// "name" is an attribute of ContactForm
$model->name = 'example';
echo $model->name;
```
Vous pouvez également accéder aux attributs comme aux éléments d'un tableau, grâce à la prise en charge de [ArrayAccess](http://php.net/manual/en/class.arrayaccess.php) et [ArrayIterator](http://php.net/manual/en/class.arrayiterator.php)
par la classe [[yii\base\Model]]:
```php
$model = new \app\models\ContactForm;
// accès aux attributs comme à des éléments de tableau
$model['name'] = 'example';
echo $model['name'];
// itération sur les attributs
foreach ($model as $name => $value) {
echo "$name: $value\n";
}
```
### Definition d'attributs <span id="defining-attributes"></span>
Par défaut, si votre classe de modèle étend directement la classe [[yii\base\Model]], toutes ses variables membres *non statiques et publiques* sont des attributs. Par exemple, la classe de modèle `ContactForm` ci-dessous possède quatre attributs : `name`, `email`,
`subject` et `body`. Le modèle `ContactForm` est utilisé pour représenter les données saisies dans un formulaire HTML.
```php
namespace app\models;
use yii\base\Model;
class ContactForm extends Model
{
public $name;
public $email;
public $subject;
public $body;
}
```
Vous pouvez redéfinir la méthode [[yii\base\Model::attributes()]] pour spécifier les attributs d'une autre manière. La méthode devrait retourner le nom des attributs d'un modèle. Par exemple, [[yii\db\ActiveRecord]] fait cela en retournant le nom des colonnes de la base de données associée en tant que noms d'attribut. Notez que vous pouvez aussi avoir besoin de redéfinir les méthodes magiques telles que `__get()` et `__set()` afin que les attributs puissent être accédés comme les propriétés d'un objet ordinaire.
### Étiquettes d'attribut <span id="attribute-labels"></span>
Lors de l'affichage de la valeur d'un attribut ou lors de la saisie d'une entrée pour une telle valeur, il est souvent nécessaire d'afficher une étiquette associée à l'attribut. Par exemple, étant donné l'attribut nommé `firstName` (prénom), vous pouvez utiliser une étiquette de la forme `First Name` qui est plus conviviale lorsqu'elle est présentée à l'utilisateur final dans un formulaire ou dans un message d'erreur.
Vous pouvez obtenir l'étiquette d'un attribut en appelant la méthode [[yii\base\Model::getAttributeLabel()]]. Par exemple :
```php
$model = new \app\models\ContactForm;
// displays "Name"
echo $model->getAttributeLabel('name');
```
Par défaut, les étiquettes d'attribut sont automatiquement générées à partir des noms d'attribut. La génération est faite en appelant la méthode [[yii\base\Model::generateAttributeLabel()]]. Cette méthode transforme un nom de variable avec une casse en dos de chameau en de multiples mots, chacun commençant par une capitale. Par exemple, `username` donne `Username` et `firstName` donne `First Name`.
Si vous ne voulez pas utiliser les étiquettes à génération automatique, vous pouvez redéfinir la méthode [[yii\base\Model::attributeLabels()]] pour déclarer explicitement les étiquettes d'attribut. Par exemple :
```php
namespace app\models;
use yii\base\Model;
class ContactForm extends Model
{
public $name;
public $email;
public $subject;
public $body;
public function attributeLabels()
{
return [
'name' => 'Nom',
'email' => 'Adresse de courriel',
'subject' => 'Subjet',
'body' => 'Contenu',
];
}
}
```
Pour les application prenant en charge de multiples langues, vous désirez certainement traduire les étiquettes d'attribut. Cela peut être fait dans la méthode [[yii\base\Model::attributeLabels()|attributeLabels()]] également, en procédant comme ceci :
```php
public function attributeLabels()
{
return [
'name' => \Yii::t('app', 'Your name'),
'email' => \Yii::t('app', 'Your email address'),
'subject' => \Yii::t('app', 'Subject'),
'body' => \Yii::t('app', 'Content'),
];
}
```
Vous pouvez même définir les étiquettes en fonction de conditions. Par exemple, en fonction du [scénario](#scenarios) dans lequel le modèle est utilisé, vous pouvez retourner des étiquettes différentes pour le même attribut.
> Info: strictement parlant, les étiquettes d'attribut font partie des [vues](structure-views.md). Mais la déclaration d'étiquettes dans les modèles est souvent très pratique et conduit à un code propre et réutilisable.
## Scénarios <span id="scenarios"></span>
Un modèle peut être utilisé dans différents *scénarios*. Par exemple, un modèle `User` (utilisateur) peut être utilisé pour collecter les données d'un utilisateur, mais il peut aussi être utilisé à des fins d'enregistrement d'enregistrement de l'utilisateur. Dans différents scénarios, un modèle peut utiliser des règles de traitement et une logique différente. Par exemple, `email` peut être nécessaire lors de l'enregistrement de l'utilisateur mais pas utilisé lors de sa connexion.
Un modèle utilise la propriété [[yii\base\Model::scenario]] pour conserver un trace du scénario dans lequel il est utilisé.
Par défaut, un modèle prend en charge un unique scénario nommé `default`. Le code qui suit montre deux manières de définir le scénario d'un modèle :
```php
// le scénario est défini comme une propriété
$model = new User;
$model->scenario = User::SCENARIO_LOGIN;
// le scénario est défini via une configuration
$model = new User(['scenario' => User::SCENARIO_LOGIN]);
```
Par défaut, les scénarios pris en charge par un modèle sont détérminés par les [règles de validation](#validation-rules) déclarées dans le modèle. Néanmoins, vous pouvez personnaliser ce comportement en redéfinissant la méthode [[yii\base\Model::scenarios()]], de la manière suivante :
```php
namespace app\models;
use yii\db\ActiveRecord;
class User extends ActiveRecord
{
const SCENARIO_LOGIN = 'login';
const SCENARIO_REGISTER = 'register';
public function scenarios()
{
return [
self::SCENARIO_LOGIN => ['username', 'password'],
self::SCENARIO_REGISTER => ['username', 'email', 'password'],
];
}
}
```
> Info: dans ce qui précède et dans l'exemple qui suit, les classes de modèle étendent la classe [[yii\db\ActiveRecord]] parce que l'utilisation de multiples scénarios intervient ordinairement dans les classes [Active Record](db-active-record.md).
La méthode `scenarios()` retourne un tableau dont les clés sont les noms de scénario et les valeurs les *attributs actifs* correspondants. Les attributs actifs peuvent être [assignés massivement](#massive-assignment) et doivent respecter des règles de [validation](#validation-rules). Dans l'exemple ci-dessus, les attributs `username` et `password` sont actifs dans le scénario `login`, tandis que dans le scénario `register` , `email` est, en plus de `username` et`password`, également actif.
La mise en œuvre par défaut des `scenarios()` retourne tous les scénarios trouvés dans la méthode de déclaration des règles de validation [[yii\base\Model::rules()]]. Lors de la redéfinition des `scenarios()`, si vous désirez introduire de nouveaux scénarios en plus des scénarios par défaut, vous pouvez utiliser un code similaire à celui qui suit :
```php
namespace app\models;
use yii\db\ActiveRecord;
class User extends ActiveRecord
{
const SCENARIO_LOGIN = 'login';
const SCENARIO_REGISTER = 'register';
public function scenarios()
{
$scenarios = parent::scenarios();
$scenarios[self::SCENARIO_LOGIN] = ['username', 'password'];
$scenarios[self::SCENARIO_REGISTER] = ['username', 'email', 'password'];
return $scenarios;
}
}
```
La fonctionnalité *scénarios* est d'abord utilisée pour la [validation](#validation-rules) et dans l'[assignation massive des attributs](#massive-assignment). Vous pouvez, cependant l'utiliser à d'autres fins. Par exemple, vous pouvez déclarer des [étiquettes d'attribut](#attribute-labels) différemment en vous basant sur le scénario courant.
## Règles de validation<span id="validation-rules"></span>
Losque les données pour un modèle sont reçues de l'utilisateur final, elles doivent être validées pour être sûr qu'elles respectent certaines règles (appelées *règles de validation*). Par exemple, étant donné un modèle pour un formulaire de contact (`ContactForm`), vous voulez vous assurer qu'aucun des attributs n'est vide et que l'attribut `email` contient une adresse de courriel valide. Si les valeurs pour certains attributs ne respectent pas les règles de validation, les messages d'erreur appropriés doivent être affichés pour aider l'utilisateur à corriger les erreurs.
Vous pouvez faire appel à la méthode [[yii\base\Model::validate()]] pour valider les données reçues. La méthode utilise les règles de validation déclarées dans [[yii\base\Model::rules()]] pour valider chacun des attributs concernés. Si aucune erreur n'est trouvée, elle retourne `true` (vrai). Autrement, les erreurs sont stockées dans la propriété [[yii\base\Model::errors]] et la méthode retourne `false` (faux). Par exemple :
```php
$model = new \app\models\ContactForm;
// définit les attributs du modèle avec les entrées de l'utilisateur final
$model->attributes = \Yii::$app->request->post('ContactForm');
if ($model->validate()) {
// toutes les entrées sont valides
} else {
// la validation a échoué : le tableau $errors contient les messages d'erreur
$errors = $model->errors;
}
```
Pour déclarer des règles de validation associées à un modèle, redéfinissez la méthode [[yii\base\Model::rules()]] en retournant les règles que le modèle doit respecter. L'exemple suivant montre les règles de validation déclarées pour le modèle *formulaire de contact `ContactForm` :
```php
public function rules()
{
return [
// the name, email, subject and body attributes are required
[['name', 'email', 'subject', 'body'], 'required'],
// the email attribute should be a valid email address
['email', 'email'],
];
}
```
Une règle peut être utilisée pour valider un ou plusieurs attributs, et un attribut peut être validé par une ou plusieurs règles. Reportez-vous à la section [validation des entrées](input-validation.md) pour plus de détails sur la manière de déclarer les règles de validation.
Parfois, vous désirez qu'une règle ne soit applicable que dans certains [scénarios](#scenarios). Pour cela, vous pouvez spécifier la propriété `on` d'une règle, comme ci-dessous :
```php
public function rules()
{
return [
// username, email et password sont tous requis dans le scénario "register"
[['username', 'email', 'password'], 'required', 'on' => self::SCENARIO_REGISTER],
// username et password sont requis dans le scénario "login"
[['username', 'password'], 'required', 'on' => self::SCENARIO_LOGIN],
];
}
```
Si vous ne spécifiez pas la propriété `on`, la règle sera appliquée dans tous les scénarios. Une règle est dite *règle active* si elle s'applique au scénario courant [[yii\base\Model::scenario|scenario]].
Un attribut n'est validé que si, et seulement si, c'est un attribut actif déclaré dans `scenarios()` et s'il est associé à une ou plusieurs règles actives déclarées dans `rules()`.
## Assignation massive <span id="massive-assignment"></span>
L'assignation massive est une façon pratique de peupler un modèle avec les entrées de l'utilisateur final en utilisant une seule ligne de code . Elle peuple les attributs d'un modèle en assignant directement les données d'entrée à la propriété [[yii\base\Model::$attributes]]. Les deux extraits de code suivants sont équivalent. Ils tentent tous deux d'assigner les données du formulaire soumis par l'utilisateur final aux attributs du modèle `ContactForm`. En clair, le premier qui utilise l'assignation massive, est plus propre et moins sujet aux erreurs que le second :
```php
$model = new \app\models\ContactForm;
$model->attributes = \Yii::$app->request->post('ContactForm');
```
```php
$model = new \app\models\ContactForm;
$data = \Yii::$app->request->post('ContactForm', []);
$model->name = isset($data['name']) ? $data['name'] : null;
$model->email = isset($data['email']) ? $data['email'] : null;
$model->subject = isset($data['subject']) ? $data['subject'] : null;
$model->body = isset($data['body']) ? $data['body'] : null;
```
### Attributs sûr <span id="safe-attributes"></span>
L'assignation massive ne s'applique qu'aux attributs dits *attributs sûrs* qui sont les attributs listés dans la méthode [[yii\base\Model::scenarios()]] pour le [yii\base\Model::scenario|scénario]] courant d'un modèle.
Par exemple, si le modèle `User` contient la déclaration de scénarios suivante, alors, lorsque le scénario courant est `login`, seuls les attributs `username` et `password` peuvent être massivement assignés. Tout autre attribut n'est pas touché par l'assignation massive.
```php
public function scenarios()
{
return [
self::SCENARIO_LOGIN => ['username', 'password'],
self::SCENARIO_REGISTER => ['username', 'email', 'password'],
];
}
```
> Info: la raison pour laquelle l'assignation massive ne s'applique qu'aux attributs sûrs est de vous permettre de contrôler quels attributs peuvent être modifiés par les données envoyées par l'utilisateur final. Par exemple, si le modèle `User` possède un attribut `permission` qui détermine les permissions accordées à l'utilisateur, vous préférez certainement que cet attribut ne puisse être modifié que par un administrateur via l'interface d'administration seulement.
Comme la mise en œuvre par défaut de la méthode [[yii\base\Model::scenarios()]] retourne tous les scénarios et tous les attributs trouvés dans la méthode [[yii\base\Model::rules()]], si vous ne redéfinissez pas cette méthode, cela signifie qu'un attribut est *sûr* tant qu'il apparaît dans une des règles de validation actives.
Pour cette raison, un validateur spécial dont l'alias est `safe` est fourni pour vous permettre de déclarer un attribut *safe* sans réellement le valider. Par exemple, les règles suivantes déclarent que `title`
et `description` sont tous deux des attributs sûrs.
```php
public function rules()
{
return [
[['title', 'description'], 'safe'],
];
}
```
### Attributs non sûr <span id="unsafe-attributes"></span>
Comme c'est expliqué plus haut, la méthode [[yii\base\Model::scenarios()]] remplit deux objectifs : déterminer quels attributs doivent être validés, et déterminer quels attributs sont *sûrs*. Dans certains cas, vous désirez valider un attribut sans le marquer comme *sûr*. Vous pouvez le faire en préfixant son nom par un point d'exclamation `!` lorsque vous le déclarez dans la méthode `scenarios()`, comme c'est fait pour l'attribut `secret` dans le code suivant :
```php
public function scenarios()
{
return [
self::SCENARIO_LOGIN => ['username', 'password', '!secret'],
];
}
```
Losque le modèle est dans le scénario `login`, les trois attributs sont validés. Néanmoins, seuls les attributs `username`
et `password` peuvent être massivement assignés. Pour assigner une valeur d'entrée à l'attribut `secret`, vous devez le faire explicitement, comme montré ci-dessous :
```php
$model->secret = $secret;
```
La même chose peut être faite dans la méthode `rules()` :
```php
public function rules()
{
return [
[['username', 'password', '!secret'], 'required', 'on' => 'login']
];
}
```
Dans ce cas, les attributs `username`, `password` et `secret` sont requis, mais `secret` doit être assigné explicitement.
## Exportation de données <span id="data-exporting"></span>
On a souvent besoin d'exporter les modèles dans différents formats. Par exemple, vous désirez peut-être convertir une collection de modèles dans le format JSON ou dans le format Excel. Le processus d'exportation peut être décomposé en deux étapes indépendantes. Dans la première étape, les modèles sont convertis en tableaux. Dans la deuxième étape, les tableaux sont convertis dans les formats cibles. Vous pouvez vous concentrer uniquement sur la première étape, parce que la seconde peut être accomplie par des formateurs génériques de données, tels que [[yii\web\JsonResponseFormatter]].
La manière la plus simple de convertir un modèle en tableau est d'utiliser la propriété [[yii\base\Model::$attributes]]. Par exemple :
```php
$post = \app\models\Post::findOne(100);
$array = $post->attributes;
```
Par défaut, la propriété [[yii\base\Model::$attributes]] retourne les valeurs de *tous* les attributs déclarés dans la méthode [[yii\base\Model::attributes()]].
Une manière plus souple et plus puissante de convertir un modèle en tableau est d'utiliser la méthode [[yii\base\Model::toArray()]]. Son comportement par défaut est de retourner la même chose que la propriété [[yii\base\Model::$attributes]]. Néanmoins, elle vous permet de choisir quelles données, appelées *champs*, doivent être placées dans le tableau résultant et comment elles doivent être formatées. En fait, c'est la manière par défaut pour exporter les modèles dans le développement d'un service Web respectant totalement l'achitecture REST, telle que décrite à la section [Formatage de la réponse](rest-response-formatting.md).
### Champs <span id="fields"></span>
Un champ n'est rien d'autre qu'un élément nommé du tableau qui est obtenu en appelant la méthode [[yii\base\Model::toArray()]] d'un modèle.
Par défaut, les noms de champ sont équivalents aux noms d'attribut. Cependant, vous pouvez changer ce comportement en redéfinissant la méthode [[yii\base\Model::fields()|fields()]] et/ou la méthode [[yii\base\Model::extraFields()|extraFields()]]. Ces deux méthodes doivent retourner une liste de définitions de champ. Les champs définis par `fields()` sont des champs par défaut, ce qui signifie que `toArray()` retourne ces champs par défaut. La méthode `extraFields()` définit des champs additionnels disponibles qui peuvent également être retournés par `toArray()` du moment que vous les spécifiez via le paramètre `$expand`. Par exemple, le code suivant retourne tous les champs définis dans la méthode `fields()` ainsi que les champs `prettyName` et `fullAddress`, s'ils sont définis dans `extraFields()`.
```php
$array = $model->toArray([], ['prettyName', 'fullAddress']);
```
Vous pouvez redéfinir la méthode `fields()` pour ajouter, retirer, renommer ou redéfinir des champs. La valeur de retour de la méthode `fields()` doit être un tableau associatif. Les clés du tableau sont les noms des champs et les valeurs sont les définitions de champ correspondantes qui peuvent être, soit des noms d'attribut/propriété, soit des fonctions anonymes retournant les valeurs de champ correspondantes. Dans le cas particulier où un nom de champ est identique à celui du nom d'attribut qui le définit, vous pouvez omettre la clé du tableau. Par exemple :
```php
// liste explicitiement chaque champ; à utiliser de préférence quand vous voulez être sûr
// que les changements dans votre table de base de données ou dans les attributs de votre modèle
// ne créent pas de changement dans vos champs (pour conserver la rétro-compatibilité de l'API).
public function fields()
{
return [
// le nom du champ est identique à celui de l'attribut
'id',
// le nom du champ est "email", le nom d'attribut correspondant est "email_address"
'email' => 'email_address',
// le nom du champ est "name", sa valeur est définie par une fonction PHP de rappel
'name' => function () {
return $this->first_name . ' ' . $this->last_name;
},
];
}
// filtre quelques champs; à utiliser de préférence quand vous voulez hériter de l'implémentation du parent
// et mettre quelques champs sensibles en liste noire.
public function fields()
{
$fields = parent::fields();
// retire les champs contenant des informations sensibles
unset($fields['auth_key'], $fields['password_hash'], $fields['password_reset_token']);
return $fields;
}
```
> Warning: étant donné que, par défaut, tous les attributs d'un modèle sont inclus dans le tableau exporté,
> vous devez vous assurer que vos données ne contiennent pas d'information sensible.
> Si de telles informations existent, vous devriez redéfinir la méthode `fields()` pour les filtrer.
> Dans l'exemple ci-dessus, nous avons choisi d'exclure `auth_key`, `auth_key`, `password_hash` et `password_reset_token`.
## Meilleures pratiques <span id="best-practices"></span>
Les modèles sont les endroits centraux pour représenter les données de l'application, les règles et la logique. Ils doivent souvent être réutilisés à différents endroits. Dans une application bien conçue, les modèles sont généralement plus volumineux que les [contrôleurs](structure-controllers.md).
En résumé, voici les caractéristiques essentielles des modèles :
* Ils peuvent contenir des attributs pour représenter les données de l'application.
* Ils peuvent contenir des règles de validation pour garantir la validité et l'intégrité des données.
* Ils peuvent contenir des méthodes assurant le traitement logique des données de l'application.
* Ils ne devraient PAS accéder directement à la requête, à la session ou à n'importe quelle autre donnée environnementale. Ces données doivent être injectées dans les modèles par les [contrôleurs](structure-controllers.md).
* Ils devraient éviter d'inclure du code HTML ou tout autre code relatif à la présentation — cela est fait de manière plus avantageuse dans les [vues](structure-views.md).
* Il faut éviter d'avoir trop de [scénarios](#scenarios) dans un même modèle.
Vous pouvez ordinairement considérer cette dernière recommandation lorsque vous développez des systèmes importants et complexes. Dans ces systèmes, les modèles pourraient être très volumineux parce que, étant utilisés dans de nombreux endroits, ils doivent contenir de nombreux jeux de règles et de traitement logiques. Cela se termine le plus souvent en cauchemar pour la maintenance du code du modèle parce que le moindre changement de code est susceptible d'avoir de l'effet en de nombreux endroits. Pour rendre le modèle plus maintenable, vous pouvez adopter la stratégie suivante :
* Définir un jeu de classes de base du modèle qui sont partagées par différentes [applications](structure-applications.md) ou
[modules](structure-modules.md). Ces classes de modèles devraient contenir un jeu minimal de règles et de logique qui sont communes à tous les usages.
* Dans chacune des [applications](structure-applications.md) ou [modules](structure-modules.md) qui utilise un modèle, définir une classe de modèle concrète en étendant la classe de base de modèle correspondante. Les classes de modèles concrètes devraient contenir certaines règles et logiques spécifiques à cette application ou à ce module.
Par exemple, dans le [Modèle avancé de projet](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md), vous pouvez définir une classe de modèle de base `common\models\Post`. Puis, pour l'application « interface utilisateur » (*frontend*) vous pouvez définir une classe de base concrète `frontend\models\Post` qui étend la classe `common\models\Post`. De manière similaire, pour l'application « interface d'administration » (*backend*) vous pouvez définir une classe `backend\models\Post`. Avec cette stratégie, vous êtes sûr que le code de `frontend\models\Post` est seulement spécifique à l'application « interface utilisateur », et si vous y faite un changement, vous n'avez à vous soucier de savoir si cela à une influence sur l'application « interface d'administration ».

225
docs/guide-fr/structure-modules.md

@ -0,0 +1,225 @@
Modules
=======
Les modules sont des unités logicielles auto-suffisantes constituées de [modèles](structure-models.md), [vues](structure-views.md),
[contrôleurs](structure-controllers.md) et autres composants de prise en charge. L'utilisateur final peut accéder aux contrôleurs dans un module lorsqu'il est installé dans une [application](structure-applications.md). Pour ces raisons, les modules sont souvent regardés comme de mini-applications. Les modules diffèrent des [applications](structure-applications.md) par le fait que les modules ne peuvent être déployés seuls et doivent résider dans une application.
## Création de modules <span id="creating-modules"></span>
Un module est organisé comme un dossier qui est appelé le [[yii\base\Module::basePath|dossier de base (*basePath*)]] du module. Dans ce dossier, se trouvent des sous-dossiers, tels que `controllers`, `models` et `views`, qui contiennent les contrôleurs, les modèles , les vues et d'autres parties de code, juste comme une application. L'exemple suivant présente le contenu d'un module :
```
forum/
Module.php le fichier de classe du module
controllers/ contient les fichiers de classe des contrôleurs
DefaultController.php le fichier de classe de contrôleur par défaut
models/ contient les fichiers de classe des modèles
views/ contient les fichiers de contrôleur, de vue et de disposition
layouts/ contient les fichiers de diposition
default/ contient les fichiers de vues pour le contrôleur par défaut
index.php le fichier de vue index
```
### Classes de module <span id="module-classes"></span>
Chacun des modules doit avoir une classe unique de module qui étend [[yii\base\Module]]. La classe doit être située directement dans le [[yii\base\Module::basePath|dossier de base]] du module et doit être [auto-chargeable](concept-autoloading.md). Quand un module est accédé, une instance unique de la classe de module correspondante est créée. Comme les [instances d'application](structure-applications.md), les instances de module sont utilisées pour partager des données et des composants.
L'exemple suivant montre à quoi une classe de module peut ressembler :
```php
namespace app\modules\forum;
class Module extends \yii\base\Module
{
public function init()
{
parent::init();
$this->params['foo'] = 'bar';
// ... other initialization code ...
}
}
```
La méthode `init()` contient un code volumineux pour initialiser les propriétés du module. Vous pouvez également les sauvegarder sous forme de [configuration](concept-configurations.md) et charger cette configuration avec le code suivant dans la méthode `init()`:
```php
public function init()
{
parent::init();
// initialise le module à partir de la configuration chargée depuis config.php
\Yii::configure($this, require(__DIR__ . '/config.php'));
}
```
où le fichier de configuration `config.php` peut avoir le contenu suivant, similaire à celui d'une [configuration d'application](structure-applications.md#application-configurations).
```php
<?php
return [
'components' => [
// liste des configurations de composant
],
'params' => [
// liste des paramètres
],
];
```
### Contrôleurs dans les modules <span id="controllers-in-modules"></span>
Lorsque vous créez des contrôleurs dans un module, une convention est de placer les classes de contrôleur dans le sous-espace de noms `controllers` dans l'espace de noms de la classe du module. Cela signifie également que les fichiers de classe des contrôleur doivent être placés dans le dossier `controllers` dans le [[yii\base\Module::basePath|dossier de base]] du module. Par exemple, pour créer un contrôleur `post` dans le module `forum` présenté dans la section précédente, vous devez déclarer la classe de contrôleur comme ceci :
```php
namespace app\modules\forum\controllers;
use yii\web\Controller;
class PostController extends Controller
{
// ...
}
```
Vous pouvez personnaliser l'espace de noms des classes de contrôleur en configurant la propriété [[yii\base\Module::controllerNamespace]]. Dans le cas où certains contrôleurs sont en dehors de cet espace de noms, vous pouvez les rendre accessibles en configurant la propriété [[yii\base\Module::controllerMap]] comme vous le feriez dans une [application](structure-applications.md#controllerMap).
### Vues dans les modules <span id="views-in-modules"></span>
Les vues dans les modules doivent être placées dans le dossier `views` du [[yii\base\Module::basePath|dossier de base (*base path*)]] du module. Quant aux vues rendues par un contrôleur du module, elles doivent être placées dans le dossier `views/ControllerID`, où `ControllerID` fait référence à l'[identifiant du contrôleur](structure-controllers.md#routes). Par exemple, si la classe du contrôleur est `PostController`, le dossier doit être `views/post` dans le [[yii\base\Module::basePath|dossier de base]] du module.
Un module peut spécifier une [disposition](structure-views.md#layouts) qui s'applique aux vues rendues par les contrôleurs du module. La disposition doit être mise dans le dossier `views/layouts` par défaut, et vous devez configurer la propriété [[yii\base\Module::layout]] pour qu'elle pointe sur le nom de la disposition. Si vous ne configurez pas la propriété `layout` c'est la disposition de l'application qui est utilisée à sa place.
### Commande de console dans les modules <span id="console-commands-in-modules"></span>
Votre module peut aussi déclarer des commandes, qui sont accessibles via le mode [Console](tutorial-console.md).
Afin que l'utilitaire de ligne de commande reconnaisse vos commandes, vous devez changer la propriété [[yii\base\Module::controllerNamespace (espace de noms du contrôleur)]] lorsque Yii est exécuté en mode console, et le diriger sur votre espace de noms de commandes.
Une manière de réaliser cela est de tester le type d'instance de l'application Yii dans la méthode `init` du module :
```php
public function init()
{
parent::init();
if (Yii::$app instanceof \yii\console\Application) {
$this->controllerNamespace = 'app\modules\forum\commands';
}
}
```
Vos commandes seront disponibles en ligne de commande en utilisant la route suivante :
```
yii <module_id>/<command>/<sub_command>
```
## Utilisation des modules <span id="using-modules"></span>
Pour utiliser un module dans une application, il vous suffit de configurer l'application en listant le module dans la propriété [[yii\base\Application::modules|modules]] de l'application. Le code qui suit dans la [configuration de l'application](structure-applications.md#application-configurations) permet l'utilisation du module `forum` :
```php
[
'modules' => [
'forum' => [
'class' => 'app\modules\forum\Module',
// ... autres éléments de configuration pour le module ...
],
],
]
```
La propriété [[yii\base\Application::modules|modules]] accepte un tableau de configurations de module. Chaque clé du tableau représente un *identifiant de module* qui distingue ce module parmi les autres modules de l'application, et la valeur correspondante est une [configuration](concept-configurations.md) pour la création du module.
### Routes <span id="routes"></span>
Les [routes](structure-controllers.md#routes) sont utilisées pour accéder aux contrôleurs d'un module comme elles le sont pour accéder aux contrôleurs d'une application. Une route pour un contrôleur d'un module doit commencer par l'identifiant du module, suivi de l'[identifiant du contrôleur](structure-controllers.md#controller-ids) et de [identifiant de l'action](structure-controllers.md#action-ids). Par exemple, si une application utilise un module nommé `forum`, alors la route `forum/post/index` représente l'action `index` du contrôleur `post` du module. Si la route ne contient que l'identifiant du module, alors la propriété [[yii\base\Module::defaultRoute]], dont la valeur par défaut est `default`, détermine quel contrôleur/action utiliser. Cela signifie que la route `forum` représente le contrôleur `default` dans le module `forum`.
### Accès aux modules <span id="accessing-modules"></span>
Dans un module, souvent, il arrive que vous ayez besoin d'une instance de la [classe du module](#module-classes) de façon à pouvoir accéder à l'identifiant du module, à ses paramètres, à ses composants, etc. Vous pouvez le faire en utilisant l'instruction suivante :
```php
$module = MyModuleClass::getInstance();
```
dans laquelle `MyModuleClass` fait référence au nom de la classe du module qui vous intéresse. La méthode `getInstance()` retourne l'instance de la classe du module actuellement requis. Si le module n'est pas requis, la méthode retourne `null`. Notez que vous n'avez pas besoin de créer manuellement une nouvelle instance de la classe du module parce que celle-ci serait différente de celle créée par Yii en réponse à la requête.
> Info: lors du développement d'un module, vous ne devez pas supposer que le module va utiliser un identifiant fixe. Cela tient au fait qu'un module peut être associé à un identifiant arbitraire lorsqu'il est utilisé dans une application ou dans un autre module. Pour obtenir l'identifiant du module, vous devez utiliser l'approche ci-dessus pour obtenir d'abord une instance du module, puis obtenir l'identifiant via `$module->id`.
Vous pouvez aussi accéder à l'instance d'un module en utilisant les approches suivantes :
```php
// obtenir le module fils dont l'identifiant est "forum"
$module = \Yii::$app->getModule('forum');
// obtenir le module auquel le contrôleur actuellement requis appartient
$module = \Yii::$app->controller->module;
```
La première approche n'est utile que lorsque vous connaissez l'identifiant du module, tandis que la seconde est meilleure lorsque vous connaissez le contrôleur actuellement requis.
Une fois que vous disposez de l'instance du module, vous pouvez accéder aux paramètres et aux composants enregistrés avec le module. Par exemple :
```php
$maxPostCount = $module->params['maxPostCount'];
```
### Modules faisant partie du processus d'amorçage <span id="bootstrapping-modules"></span>
Il se peut que certains modules doivent être exécutés pour chacune des requêtes. Le module [[yii\debug\Module|debug]] en est un exemple. Pour que des modules soit exécutés pour chaque requête, vous devez les lister dans la propriété [[yii\base\Application::bootstrap|bootstrap]] de l'application.
Par exemple, la configuration d'application suivante garantit que le module `debug` est chargé à chaque requête :
```php
[
'bootstrap' => [
'debug',
],
'modules' => [
'debug' => 'yii\debug\Module',
],
]
```
## Modules imbriqués <span id="nested-modules"></span>
Les modules peuvent être imbriqués sur un nombre illimité de niveaux. C'est à dire qu'un module pour contenir un autre module qui contient lui-même un autre module. Nous parlons alors de *module parent* pour le module englobant, et de *module enfant* pour le module contenu. Les modules enfants doivent être déclarés dans la propriété [[yii\base\Module::modules|modules]] de leur module parent. Par exemple :
```php
namespace app\modules\forum;
class Module extends \yii\base\Module
{
public function init()
{
parent::init();
$this->modules = [
'admin' => [
// Vous devriez envisager l'utilisation d'un espace de noms plus court ici !
'class' => 'app\modules\forum\modules\admin\Module',
],
];
}
}
```
La route vers un contrôleur inclus dans un module doit inclure les identifiants de tous ses modules ancêtres. Par exemple, la route `forum/admin/dashboard/index` représente l'action `index` du contrôleur `dashboard` dans le module `admin` qui est un module enfant du module `forum`.
> Info: la méthode [[yii\base\Module::getModule()|getModule()]] ne retourne que le module enfant appartenant directement à son parent. La propriété [[yii\base\Application::loadedModules]] tient à jour une liste des modules chargés, y compris les enfant directs et les enfants des générations suivantes, indexée par le nom de classe.
## Meilleures pratiques <span id="best-practices"></span>
L'utilisation des modules est préférable dans les grosses applications dont les fonctionnalités peuvent être réparties en plusieurs groupes, consistant chacun en un jeu de fonctionnalités liées d'assez près. Chacune de ces fonctionnalités peut être conçue comme un module développé et maintenu par un développeur ou une équipe spécifique.
Les modules sont aussi un bon moyen de réutiliser du code au niveau des groupes de fonctionnalités. Quelques fonctionnalité d'usage courant, telles que la gestion des utilisateurs, la gestion des commentaires, etc. peuvent être développées en tant que modules ce qui facilite leur réutilisation dans les projets suivants.

8
docs/guide-fr/structure-overview.md

@ -1,7 +1,7 @@
Vue d'ensemble
========
Les applications Yii sont organisées suivant le patron de conception
Les applications Yii sont organisées suivant le modèle de conception
[model-view-controller (MVC)](http://wikipedia.org/wiki/Model-view-controller). Les [Modèles](structure-models.md)
représentent les données, la logique métier et les règles; les [vues](structure-views.md) sont les représentations
visuelles des modèles, et les [contrôleurs](structure-controllers.md) prennent une entrée et la convertissent en
@ -9,14 +9,14 @@ commandes pour les [modèles](structure-models.md) et les [vues](structure-views
En plus du MVC, les applications Yii ont les entités suivantes :
* [scripts de démarrage](structure-entry-scripts.md): ce sont des scripts PHP qui sont directement accessibles aux
utilisateurs. Ils sont responsables du démarrage d'un cycle de gestion de requête.
* [scripts d'entrée](structure-entry-scripts.md): ce sont des scripts PHP qui sont directement accessibles aux
utilisateurs. Ils sont responsables de l'amorçage d'un cycle de gestion de requête.
* [applications](structure-applications.md): ce sont des objets globalement accessibles qui gèrent les composants
d'application et les coordonnent pour satisfaire des requêtes.
* [composants d'application](structure-application-components.md): ce sont des objets enregistrés avec des applications et
qui fournissent différents services pour satisfaire des requêtes.
* [modules](structure-modules.md): ce sont des paquets auto-contenus qui contiennent du MVC complet. Une application peut
être organisée en termes de multiples modules.
être organisée en de multiples modules.
* [filtres](structure-filters.md): ils représentent du code qui doit être invoqué avant et après la gestion effective
de chaque requête par des contrôleurs.
* [widgets](structure-widgets.md): ce sont des objets qui peuvent être intégrés dans des [vues](structure-views.md). Ils

588
docs/guide-fr/structure-views.md

@ -0,0 +1,588 @@
Vues
=====
Les vues font partie du modèle d'architecture [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) (Modèle Vue Contrôleur).
Elles sont chargées de présenter les données à l'utilisateur final. Dans une application Web, les vues sont ordinairement créées en termes de *modèles de vue* qui sont des script PHP contenant principalement du code HTML et du code PHP relatif à la présentation.
Elles sont gérées par le [[yii\web\View|view]] [composant application](structure-application-components.md) qui fournit des méthodes d'usage courant pour faciliter la composition des vues et leur rendu. Par souci de simplicité, nous appellerons *vues* les modèles de vue et les fichiers de modèle de vue.
## Création des vues <span id="creating-views"></span>
Comme nous l'avons dit ci-dessus, une vue n'est rien d'autre qu'un script PHP incluant du code HTML et du code PHP. Le script ci-dessous correspond à la vue d'un formulaire de connexion. Comme vous pouvez le voir le code PHP est utilisé pour générer le contenu dynamique, dont par exemple le titre de la page et le formulaire, tandis que le code HTML les organise en une page présentable.
```php
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;
/* @var $this yii\web\View */
/* @var $form yii\widgets\ActiveForm */
/* @var $model app\models\LoginForm */
$this->title = 'Login';
?>
<h1><?= Html::encode($this->title) ?></h1>
<p>Veuillez remplir les champs suivants pour vous connecter:</p>
<?php $form = ActiveForm::begin(); ?>
<?= $form->field($model, 'username') ?>
<?= $form->field($model, 'password')->passwordInput() ?>
<?= Html::submitButton('Login') ?>
<?php ActiveForm::end(); ?>
```
À l'intérieur d'une vue, vous avez accès à `$this` qui fait référence au [[yii\web\View|composant view (vue)]] responsable de le gestion et du rendu de ce modèle de vue.
En plus de `$this`, il peut aussi y avoir d'autres variables prédéfinies dans une vue, telles que `$model` dans l'exemple précédent. Ces variables représentent les données qui sont *poussées* dans la vue par les [contrôleurs](structure-controllers.md) ou par d'autres objets qui déclenche le [rendu d'une vue](#rendering-views).
> Tip: les variables prédéfinies sont listées dans un bloc de commentaires au début d'une vue de manière à être reconnues par les EDI. C'est également une bonne manière de documenter vos vues.
### Sécurité <span id="security"></span>
Lors de la création de vues qui génèrent des pages HTML, il est important que vous encodiez et/ou filtriez les données en provenance de l'utilisateur final avant des les présenter. Autrement, votre application serait sujette aux [attaques par injection de scripts (*cross-site scripting*)](http://en.wikipedia.org/wiki/Cross-site_scripting).
Pour afficher du texte simple, commencez par l'encoder en appelant la méthode [[yii\helpers\Html::encode()]]. Par exemple, le code suivant encode le nom d'utilisateur (*username*) avant de l'afficher :
```php
<?php
use yii\helpers\Html;
?>
<div class="username">
<?= Html::encode($user->name) ?>
</div>
```
Pour afficher un contenu HTML, utilisez l'objet [[yii\helpers\HtmlPurifier]] pour d'abord en filtrer le contenu. Par exemple, le code suivant filtre le contenu de la variable *post* avant de l'afficher :
```php
<?php
use yii\helpers\HtmlPurifier;
?>
<div class="post">
<?= HtmlPurifier::process($post->text) ?>
</div>
```
> Tip: bien que l'objet HTMLPurifier effectue un excellent travail en rendant vos sorties sûres, il n'est pas rapide. Vous devriez envisager de mettre le résultat en [cache](caching-overview.md) lorsque votre application requiert une performance élevée.
### Organisation des vues <span id="organizing-views"></span>
Comme les [contrôleurs](structure-controllers.md) et les [modèles](structure-models.md), il existe certaines conventions pour organiser les vues.
* Pour les vues rendues par un contrôleur, elles devraient être placées par défaut dans le dossier `@app/views/ControllerID``ControllerID` doit être remplacé par l'[identifiant du contrôleur](structure-controllers.md#routes). Par exemple, si la classe du contrôleur est `PostController`, le dossier est `@app/views/post`; si c'est `PostCommentController` le dossier est `@app/views/post-comment`. Dans le cas où le contrôleur appartient à un module, le dossier s'appelle `views/ControllerID` et se trouve dans le [[yii\base\Module::basePath|dossier racine du module]].
* Pour les vues rendues dans un [widget (objet graphique)](structure-widgets.md), elles devraient être placées par défaut dans le dossier `WidgetPath/views``WidgetPath` est le dossier contenant le fichier de la classe du widget.
* Pour les vues rendues par d'autres objets, il est recommandé d'adopter une convention similaire à celle utilisée pour les *widgets*.
Vous pouvez personnaliser ces dossiers par défaut en redéfinissant la méthode [[yii\base\ViewContextInterface::getViewPath()]] des contrôleurs ou des *widgets*.
## Rendu des vues <span id="rendering-views"></span>
Vous pouvez rendre les vues dans des [contrôleurs](structure-controllers.md), des [widgets](structure-widgets.md), ou dans d'autres endroits en appelant les méthodes de rendu des vues. Ces méthodes partagent un signature similaire comme montré ci-dessous :
```
/**
* @param string $view nom de la vue ou chemin du fichier, selon la méthode réelle de rendu
* @param array $params les données injectées dans la vue
* @return string le résultat du rendu
*/
methodName($view, $params = [])
```
### Rendu des vues dans des contrôleurs <span id="rendering-in-controllers"></span>
Dans les [contrôleurs](structure-controllers.md), vous pouvez appeler la méthode de contrôleur suivante pour rendre une vue :
* [[yii\base\Controller::render()|render()]]: rend une [vue nommée](#named-views) et applique une [disposition](#layouts)
au résultat du rendu.
* [[yii\base\Controller::renderPartial()|renderPartial()]]: rend une [vue nommée](#named-views) sans disposition.
* [[yii\web\Controller::renderAjax()|renderAjax()]]: rend une [vue nommée ](#named-views) sans disposition et injecte tous les scripts et fichiers JS/CSS enregistrés. Cette méthode est ordinairement utilisée en réponse à une requête Web AJAX.
* [[yii\base\Controller::renderFile()|renderFile()]]: rend une vue spécifiée en terme de chemin ou d'[alias](concept-aliases.md) de fichier de vue.
* [[yii\base\Controller::renderContent()|renderContent()]]: rend un chaîne statique en l'injectant dans la [disposition](#layouts) courante. Cette méthode est disponible depuis la version 2.0.1.
Par exemple :
```php
namespace app\controllers;
use Yii;
use app\models\Post;
use yii\web\Controller;
use yii\web\NotFoundHttpException;
class PostController extends Controller
{
public function actionView($id)
{
$model = Post::findOne($id);
if ($model === null) {
throw new NotFoundHttpException;
}
// rend une vue nommée "view" et lui applique une disposition de page
return $this->render('view', [
'model' => $model,
]);
}
}
```
### Rendu des vues dans les *widgets* <span id="rendering-in-widgets"></span>
Dans les [*widgets*](structure-widgets.md), vous pouvez appeler les méthodes suivantes de la classe widget pour rendre une vue :
* [[yii\base\Widget::render()|render()]]: rend une [vue nommée](#named-views).
* [[yii\base\Widget::renderFile()|renderFile()]]: rend une vue spécifiée en terme de chemin ou d'[alias](concept-aliases.md) de fichier de vue.
Par exemple :
```php
namespace app\components;
use yii\base\Widget;
use yii\helpers\Html;
class ListWidget extends Widget
{
public $items = [];
public function run()
{
// rend une vue nommée "list"
return $this->render('list', [
'items' => $this->items,
]);
}
}
```
### Rendu des vues dans des vues <span id="rendering-in-views"></span>
Vous pouvez rendre une vue dans une autre vue en appelant les méthodes suivantes du [[yii\base\View|composant view]]:
* [[yii\base\View::render()|render()]]: rend une [vue nommée](#named-views).
* [[yii\web\View::renderAjax()|renderAjax()]]: rend une [vue nommée](#named-views) et injecte tous les fichiers et scripts JS/CSS enregistrés. On l'utilise ordinairement en réponse à une réquête Web AJAX.
* [[yii\base\View::renderFile()|renderFile()]]: rend une vue spécifiée en terme de chemin ou d'[alias](concept-aliases.md) de fichier de vue.
Par exemple, le code suivant dans une vue, rend le fichier de vue `_overview.php` qui se trouve dans le même dossier que la vue courante. Rappelez-vous que `$this` dans une vue fait référence au composant [[yii\base\View|view]] :
```php
<?= $this->render('_overview') ?>
```
### Rendu de vues en d'autres endroits <span id="rendering-in-other-places"></span>
Dans n'importe quel endroit, vous pouvez accéder au composant d'application [[yii\base\View|view]] à l'aide de l'expression `Yii::$app->view` et ensuite appeler une de ses méthodes mentionnées plus haut pour rendre une vue. Par exemple :
```php
// displays the view file "@app/views/site/license.php"
echo \Yii::$app->view->renderFile('@app/views/site/license.php');
```
### Vues nommées <span id="named-views"></span>
Lorsque vous rendez une vue, vous pouvez spécifier la vue en utilisant soit un nom de vue, soit un chemin/alias de fichier de vue. Dans la plupart des cas, vous utilisez le nom car il est plus concis et plus souple. Nous appelons les vues spécifiées par leur nom, des *vues nommées*.
Un nom de vue est résolu en le chemin de fichier correspondant en appliquant les règles suivantes :
* Un nom de vue peut omettre l'extension du nom de fichier. Dans ce cas, `.php` est utilisé par défaut en tant qu'extension. Par exemple, le nom de vue `about` correspond au nom de fichier `about.php`.
* Si le nom de vue commence par une double barre de division `//`, le chemin de fichier correspondant est `@app/views/ViewName``ViewName` est le nom de la vue. Dans ce cas la vue est recherchée dans le dossier [[yii\base\Application::viewPath|chemin des vues de l'application]]. Par exemple, `//site/about` est résolu en `@app/views/site/about.php`.
* Si le nom de la vue commence par une unique barre de division `/`, le chemin de fichier de la vue est formé en préfixant le nom de vue avec [[yii\base\Module::viewPath|chemin des vues]] du [module](structure-modules.md) actif courant . Si aucun module n'est actif, `@app/views/ViewName` — où `ViewName` est le nom de la vue — est utilisé. Par exemple, `/user/create` est résolu en `@app/modules/user/views/user/create.php`, si le module actif courant est `user` et en `@app/views/user/create.php`si aucun module n'est actif.
* Si la vue est rendue avec un [[yii\base\View::context|contexte]] et que le contexte implémente [[yii\base\ViewContextInterface]],le chemin de fichier de vue est formé en préfixant le nom de vue avec le [[yii\base\ViewContextInterface::getViewPath()|chemin des vues]] du contexte. Cela s'applique principalement aux vues rendues dans des contrôleurs et dans des *widgets*. Par exemple, `about` est résolu en `@app/views/site/about.php` si le contexte est le contrôleur `SiteController`.
* Si une vue est rendue dans une autre vue, le dossier contenant le nom de la nouvelle vue est préfixé avec le chemin du dossier contenant l'autre vue. Par exemple, la vue `item` est résolue en `@app/views/post/item.php` lorsqu'elle est rendue dans `@app/views/post/index.php`.
Selon les règles précédentes, l'appel de `$this->render('view')` dans le contrôleur `app\controllers\PostController` rend réellement le fichier de vue `@app/views/post/view.php`, tandis que l'appel de `$this->render('_overview')` dans cette vue rend le fichier de vue `@app/views/post/_overview.php`.
### Accès aux données dans les vues <span id="accessing-data-in-views"></span>
Il existe deux approches pour accéder aux données à l'intérieur d'une vue : *pousser* et *tirer*.
En passant les données en tant que second paramètre des méthodes de rendu de vues, vous utilisez la méthode *pousser*. Les données doivent être présentées sous forme de tableau clé-valeur. Lorsque la vue est rendue, la fonction PHP `extract()` est appelée sur ce tableau pour que le tableau soit restitué sous forme de variables dans la vue. Par exemple, le code suivant de rendu d'une vue dans un contrôleur *pousse* deux variables dans la vue `report` :
`$foo = 1` et `$bar = 2`.
```php
echo $this->render('report', [
'foo' => 1,
'bar' => 2,
]);
```
L'approche *tirer* retrouve les données de manière plus active à partir du [[yii\base\View|composant view]] ou à partir d'autres objets accessibles dans les vues (p. ex. `Yii::$app`). En utilisant le code exemple qui suit, vous pouvez, dans une vue, obtenir l'objet contrôleur `$this->context`. Et, en conséquence, il vous est possible d'accéder à n'importe quelle propriété ou méthode du contrôleur, comme la propriété `id` du contrôleur :
```php
The controller ID is: <?= $this->context->id ?>
```
L'approche *pousser* est en général le moyen préféré d'accéder aux données dans les vues, parce qu'elle rend les vues moins dépendantes des objets de contexte. Son revers, et que vous devez construire le tableau de données à chaque fois, ce qui peut devenir ennuyeux et sujet aux erreurs si la vue est rendue en divers endroits.
### Partage de données entre vues <span id="sharing-data-among-views"></span>
Le [[yii\base\View|composant view ]] dispose de la propriété [[yii\base\View::params|params]] que vous pouvez utiliser pour partager des données entre vues.
Par exempe, dans une vue `about` (à propos), vous pouvez avoir le code suivant qui spécifie le segment courant du *fil d'Ariane*.
```php
$this->params['breadcrumbs'][] = 'About Us';
```
Ainsi, dans le fichier de la [disposition](#layouts), qui est également une vue, vous pouvez afficher le *fil d'Ariane* en utilisant les données passées par [[yii\base\View::params|params]] :
```php
<?= yii\widgets\Breadcrumbs::widget([
'links' => isset($this->params['breadcrumbs']) ? $this->params['breadcrumbs'] : [],
]) ?>
```
## Dispositions <span id="layouts"></span>
Les dispositions (*layouts*) sont des types spéciaux de vues qui représentent les parties communes de multiples vues. Par exemple, les pages de la plupart des applications Web partagent le même entête et le même pied de page. Bien que vous puissiez répéter le même entête et le même pied de page dans chacune des vues, il est préférable de le faire une fois dans une disposition et d'inclure le résultat du rendu d'une vue de contenu à l'endroit approprié de la disposition.
### Création de dispositions <span id="creating-layouts"></span>
Parce que les dispositions sont aussi des vues, elles peuvent être créées de manière similaire aux vues ordinaires. Par défaut, les dispositions sont stockées dans le dossier `@app/views/layouts`. Les dispositions utilisées dans un [module](structure-modules.md) doivent être stockées dans le dossier `views/layouts` du [[yii\base\Module::basePath|dossier racine du module]]. Vous pouvez personnaliser le dossier par défaut des dispositions en configurant la propriété [[yii\base\Module::layoutPath]] de l'application ou du module.
L'exemple qui suit montre à quoi ressemble une disposition. Notez que dans un but illustratif, nous avons grandement simplifié le code à l'intérieur de cette disposition. En pratique, vous désirerez ajouter à ce code plus de contenu, comme des balises head, un menu principal, etc.
```php
<?php
use yii\helpers\Html;
/* @var $this yii\web\View */
/* @var $content string */
?>
<?php $this->beginPage() ?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<?= Html::csrfMetaTags() ?>
<title><?= Html::encode($this->title) ?></title>
<?php $this->head() ?>
</head>
<body>
<?php $this->beginBody() ?>
<header>My Company</header>
<?= $content ?>
<footer>&copy; 2014 by My Company</footer>
<?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>
```
Comme vous pouvez le voir, la disposition génère les balises HTML qui sont communes à toutes les pages. Dans la section `<body>` la disposition rend la variable `$content` qui représente le résultat de rendu d'une vue de contenu qui est poussée dans la disposition par l'appel à la fonction [[yii\base\Controller::render()]].
La plupart des dispositions devraient appeler les méthodes suivantes, comme illustré dans l'exemple précédent. Ces méthodes déclenchent essentiellement des événements concernant le processus de rendu de manière à ce que des balises et des scripts enregistrés dans d'autres endroits puissent être injectés à l'endroit où ces méthodes sont appelées.
- [[yii\base\View::beginPage()|beginPage()]]: cette méthode doit être appelée au tout début de la disposition. Elle déclenche l'événement [[yii\base\View::EVENT_BEGIN_PAGE|EVENT_BEGIN_PAGE]] qui signale le début d'une page.
- [[yii\base\View::endPage()|endPage()]]: cette méthode doit être appelée à la fin de la disposition. Elle déclenche l'événement [[yii\base\View::EVENT_END_PAGE|EVENT_END_PAGE]] qui signale la fin d'une page.
- [[yii\web\View::head()|head()]]: cette méthode doit être appelée dans la section `<head>` d'une page HTML. Elle génère une valeur à remplacer qui sera remplacée par le code d'entête HTML (p. ex. des balises liens, des balises meta, etc.) lorsqu'une page termine son processus de rendu.
- [[yii\web\View::beginBody()|beginBody()]]: cette méthode doit être appelée au début de la section `<body>`. Elle déclenche l'événement [[yii\web\View::EVENT_BEGIN_BODY|EVENT_BEGIN_BODY]] et génère une valeur à remplacer qui sera remplacée par le code HTML enregistré (p. ex. Javascript) dont la cible est le début du corps de la page.
- [[yii\web\View::endBody()|endBody()]]: cette méthode doit être appelée à la fin de la section `<body>`. Elle déclenche l'événement [[yii\web\View::EVENT_END_BODY|EVENT_END_BODY]] et génère une valeur à remplacer qui sera remplacée par le code HTML enregistré (p. ex. Javascript) dont la cible est la fin du corps de la page.
### Accès aux données dans les dispositions <span id="accessing-data-in-layouts"></span>
Dans une disposition, vous avez accès à deux variables prédéfinies : `$this` et `$content`. La première fait référence au composant [[yii\base\View|view]], comme dans les vues ordinaires, tandis que la seconde contient le résultat de rendu d'une vue de contenu qui est rendue par l'appel de la méthode [[yii\base\Controller::render()|render()]] dans un contrôleur.
Si vous voulez accéder à d'autres données dans les dispositions, vous devez utiliser l'approche *tirer* comme c'est expliqué à la sous-section [Accès aux données dans les vues](#accessing-data-in-views). Si vous voulez passer des données d'une vue de contenu à une disposition, vous pouvez utiliser la méthode décrite à la sous-section [Partage de données entre vues](#sharing-data-among-views).
### Utilisation des dispositions <span id="using-layouts"></span>
Comme c'est décrit à la sous-section [Rendu des vues dans les contrôleurs](#rendering-in-controllers), lorsque vous rendez une vue en appelant la méthode [[yii\base\Controller::render()|render()]] dans un contrôleur, une disposition est appliquée au résultat du rendu. Par défaut, la disposition `@app/views/layouts/main.php` est utilisée.
Vous pouvez utiliser une disposition différente en configurant soit [[yii\base\Application::layout]], soit [[yii\base\Controller::layout]]. La première gouverne la disposition utilisée par tous les contrôleurs, tandis que la deuxième redéfinit la première pour les contrôleurs individuels. Par exemple, le code suivant fait que le contrôleur `post` utilise `@app/views/layouts/post.php` en tant qu disposition lorsqu'il rend ses vues. Les autres contrôleurs, en supposant que leur propriété `layout` n'est pas modifiée, continuent d'utiliser la disposition par défaut `@app/views/layouts/main.php`.
```php
namespace app\controllers;
use yii\web\Controller;
class PostController extends Controller
{
public $layout = 'post';
// ...
}
```
Pour les contrôleurs appartenant à un module ,vous pouvez également configurer la propriété [[yii\base\Module::layout|layout]] pour utiliser une disposition particulière pour ces contrôleurs.
Comme la propriété `layout` peut être configurée à différents niveaux (contrôleurs, modules, application), en arrière plan, Yii opère en deux étapes pour déterminer quel est le fichier de disposition réel qui doit être utilisé pour un contrôleur donné.
Dans la première étape, il détermine la valeurs de la disposition et le module du contexte :
- Si la propriété [[yii\base\Controller::layout]] du contrôleur n'est pas nulle, il l'utilise en tant que valeur de disposition et le [[yii\base\Controller::module|module]] du contrôleur en tant que module du contexte.
- Si la propriété [[yii\base\Controller::layout|layout]] est nulle, il cherche, à travers tous les modules ancêtres (y compris l'application elle-même) du contrôleur, le premier module dont la propriété [[yii\base\Module::layout|layout]] n'est pas nulle. Il utilise alors ce module et la valeur de sa [[yii\base\Module::layout|disposition]] comme module du contexte et valeur de disposition, respectivement. Si un tel module n'est pas trouvé, cela signifie qu'aucune disposition n'est appliquée.
Dans la seconde étape, il détermine le fichier de disposition réel en fonction de la valeur de disposition et du module du contexte déterminés dans la première étape. La valeur de disposition peut être :
- Un alias de chemin (p. ex. `@app/views/layouts/main`).
- Un chemin absolu (p. ex. `/main`): la valeur de disposition commence par une barre oblique de division. Le fichier réel de disposition est recherché dans le [[yii\base\Application::layoutPath|chemin des disposition (*layoutPath*)]] (par défaut `@app/views/layouts`).
- Un chemin relatif (p. ex. `main`): le fichier réel de disposition est recherché dans le [[yii\base\Module::layoutPath|chemin des dispositions (*layoutPath*)]] du module du contexte (par défaut`views/layouts`) dans le [[yii\base\Module::basePath|dossier racine du module]].
- La valeur booléenne `false`: aucune disposition n'est appliquée.
Si la valeur de disposition ne contient pas d'extension de fichier, l'extension par défaut `.php` est utilisée.
### Dispositions imbriquées <span id="nested-layouts"></span>
Parfois, vous désirez imbriquer une disposition dans une autre. Par exemple, dans les différentes sections d'un site Web, vous voulez utiliser des dispositions différentes, bien que ces dispositions partagent la même disposition de base qui génère la structure d'ensemble des pages HTML5. Vous pouvez réaliser cela en appelant la méthode [[yii\base\View::beginContent()|beginContent()]] et la méthode
[[yii\base\View::endContent()|endContent()]] dans les dispositions filles comme illustré ci-après :
```php
<?php $this->beginContent('@app/views/layouts/base.php'); ?>
...contenu de la disposition fille ici...
<?php $this->endContent(); ?>
```
Comme on le voit ci-dessus, le contenu de la disposition fille doit être situé entre les appels des méthodes [[yii\base\View::beginContent()|beginContent()]] et [[yii\base\View::endContent()|endContent()]]. Le paramètre passé à la méthode [[yii\base\View::beginContent()|beginContent()]] spécifie quelle est la disposition parente. Ce peut être un fichier de disposition ou un alias. En utilisant l'approche ci-dessus, vous pouvez imbriquer des dispositions sur plusieurs niveaux.
### Utilisation des blocs <span id="using-blocks"></span>
Les blocs vous permettent de spécifier le contenu de la vue à un endroit et l'afficher ailleurs. Ils sont souvent utilisés conjointement avec les dispositions. Par exemple, vous pouvez définir un bloc dans une vue de contenu et l'afficher dans la disposition.
Pour définir un bloc, il faut appeler les méthodes [[yii\base\View::beginBlock()|beginBlock()]] et [[yii\base\View::endBlock()|endBlock()]]. Vous pouvez accéder au bloc via son identifiant avec `$view->blocks[$blockID]`, où `$blockID` représente l'identifiant unique que vous assignez au bloc lorsque vous le définissez.
L'exemple suivant montre comment utiliser les blocs pour personnaliser des parties spécifiques dans la disposition d'une vue de contenu.
Tout d'abord, dans une vue de contenu, définissez un ou de multiples blocs :
```php
...
<?php $this->beginBlock('block1'); ?>
...contenu de block1...
<?php $this->endBlock(); ?>
...
<?php $this->beginBlock('block3'); ?>
...contenu de block3...
<?php $this->endBlock(); ?>
```
Ensuite, dans la vue de la disposition, rendez les blocs s'ils sont disponibles, ou affichez un contenu par défaut si le bloc n'est pas défini.
```php
...
<?php if (isset($this->blocks['block1'])): ?>
<?= $this->blocks['block1'] ?>
<?php else: ?>
... contenu par défaut de block1 ...
<?php endif; ?>
...
<?php if (isset($this->blocks['block2'])): ?>
<?= $this->blocks['block2'] ?>
<?php else: ?>
... contenu par défaut de block2 ...
<?php endif; ?>
...
<?php if (isset($this->blocks['block3'])): ?>
<?= $this->blocks['block3'] ?>
<?php else: ?>
... contenu par défaut de block3 ...
<?php endif; ?>
...
```
## Utilisation des composants view <span id="using-view-components"></span>
Les composants [[yii\base\View|view]] fournissent de nombreuses fonctionnalités relatives aux vues. Bien que vous puissiez créer des composants *view* en créant des instances de la classe [[yii\base\View]] ou de ses classes filles, dans la plupart des cas, vous utilisez principalement le composant d'application `view` . Vous pouvez configurer ce composant dans les [configuration d'application](structure-applications.md#application-configurations), comme l'illustre l'exemple qui suit :
```php
[
// ...
'components' => [
'view' => [
'class' => 'app\components\View',
],
// ...
],
]
```
Les composants View fournissent les fonctionnalités utiles suivantes relatives aux vues, chacune décrite en détails dans une section séparée:
* [gestion des thèmes](output-theming.md): vous permet des développer et de changer les thèmes pour votre site Web.
* [mise en cache de fragments](caching-fragment.md): vous permet de mettre en cache un fragment de votre page Web.
* [gestion des scripts client](output-client-scripts.md): prend en charge l'enregistrement et le rendu de code CSS et JavaScript.
* [gestion de paquets de ressources](structure-assets.md): prend en charge l'enregistrement et le rendu de [paquets de ressources](structure-assets.md).
* [moteurs de modèle alternatif](tutorial-template-engines.md): vous permet d'utiliser d'autres moteur de modèles tels que [Twig](http://twig.sensiolabs.org/) et [Smarty](http://www.smarty.net/).
Vous pouvez aussi utiliser les fonctionnalités suivantes qui, bien que mineures, sont néanmoins utiles, pour développer vos pages Web.
### Définition du titre des pages <span id="setting-page-titles"></span>
Chaque page Web doit avoir un titre. Normalement la balise titre est affichée dans une [disposition](#layouts). Cependant, en pratique, le titre est souvent détérminé dans les vues de contenu plutôt que dans les dispositions. Pour résoudre ce problème,[[yii\web\View]] met à votre disposition la propriété [[yii\web\View::title|title]] qui vous permet de passer l'information de titre de la vue de contenu à la disposition.
Pour utiliser cette fonctionnalité, dans chacune des vues de contenu, vous pouvez définir le titre de la page de la manière suivante :
```php
<?php
$this->title = 'Le titre de ma page';
?>
```
Ensuite dans la disposition, assurez-vous qui vous avez placé le code suivant dans la section `<head>` :
```php
<title><?= Html::encode($this->title) ?></title>
```
### Enregistrement des balises meta <span id="registering-meta-tags"></span>
Généralement, les pages Web, ont besoin de générer des balises meta variées dont ont besoin diverses parties. Comme le titre des pages, les balises meta apparaissent dans la section `<head>` et sont généralement générées dans les dispositions.
Si vous désirez spécifier quelles balises meta générer dans les vues de contenu, vous pouvez appeler [[yii\web\View::registerMetaTag()]] dans une vue de contenu comme illustrer ci-après :
```php
<?php
$this->registerMetaTag(['name' => 'keywords', 'content' => 'yii, framework, php']);
?>
```
Le code ci-dessus enregistre une balise meta "mot clé" dans le composant view. La balise meta enregistrée est rendue après que le rendu de la disposition est terminé. Le code HTML suivant est généré et inséré à l'endroit où vous appelez [[yii\web\View::head()]] dans la disposition :
```php
<meta name="keywords" content="yii, framework, php">
```
Notez que si vous appelez [[yii\web\View::registerMetaTag()]] à de multiples reprises, elle enregistrera de multiples balises meta, que les balises soient les mêmes ou pas.
Pour garantir qu'il n'y a qu'une instance d'un type de balise meta, vous pouvez spécifier une clé en tant que deuxième paramètre lors de l'appel de la méthode.
Par exemple, le code suivant, enregistre deux balises meta « description ». Cependant, seule la seconde sera rendue.
F
```php
$this->registerMetaTag(['name' => 'description', 'content' => 'This is my cool website made with Yii!'], 'description');
$this->registerMetaTag(['name' => 'description', 'content' => 'This website is about funny raccoons.'], 'description');
```
### Enregistrement de balises liens <span id="registering-link-tags"></span>
Comme les [balises meta](#registering-meta-tags), les balises liens sont utiles dans de nombreux cas, comme la personnalisation de favicon, le pointage sur les flux RSS ou la délégation d'OpenID à un autre serveur. Vous pouvez travailler avec les balises liens comme avec les balises meta en utilisant [[yii\web\View::registerLinkTag()]]. Par exemple, dans une vue de contenu, vous pouvez enregistrer une balise lien de la manière suivante :
```php
$this->registerLinkTag([
'title' => 'Live News for Yii',
'rel' => 'alternate',
'type' => 'application/rss+xml',
'href' => 'http://www.yiiframework.com/rss.xml/',
]);
```
Le code suivant produit le résultat suivant :
```html
<link title="Live News for Yii" rel="alternate" type="application/rss+xml" href="http://www.yiiframework.com/rss.xml/">
```
Comme avec [[yii\web\View::registerMetaTag()|registerMetaTag()]], vous pouvez spécifier un clé lors de l'appel de [[yii\web\View::registerLinkTag()|registerLinkTag()]] pour éviter de générer des liens identiques.
## Événements de vues <span id="view-events"></span>
Les [[yii\base\View|composants View ]] déclenchent plusieurs événements durant le processus de rendu des vues. Vous pouvez répondre à ces événements pour injecter du contenu dans des vues ou traiter les résultats du rendu avant leur transmission à l'utilisateur final.
- [[yii\base\View::EVENT_BEFORE_RENDER|EVENT_BEFORE_RENDER]]: déclenché au début du rendu d'un fichier dans un contrôleur. Les gestionnaires de cet événement peuvent définir [[yii\base\ViewEvent::isValid]] à `false` (faux) pour arrêter le processus de rendu.
- [[yii\base\View::EVENT_AFTER_RENDER|EVENT_AFTER_RENDER]]: déclenché après le rendu d'un fichier par appel de [[yii\base\View::afterRender()]]. Les gestionnaires de cet événement peuvent obtenir le résultat du rendu via [[yii\base\ViewEvent::output]] et peuvent modifier cette propriété pour modifier le résultat du rendu.
- [[yii\base\View::EVENT_BEGIN_PAGE|EVENT_BEGIN_PAGE]]: déclenché par l'appel de [[yii\base\View::beginPage()]] dans une disposition.
- [[yii\base\View::EVENT_END_PAGE|EVENT_END_PAGE]]: déclenché par l'appel de [[yii\base\View::endPage()]] dans une disposition.
- [[yii\web\View::EVENT_BEGIN_BODY|EVENT_BEGIN_BODY]]: déclenché par l'appel de [[yii\web\View::beginBody()]] dans une disposition.
- [[yii\web\View::EVENT_END_BODY|EVENT_END_BODY]]: déclenché par l'appel de [[yii\web\View::endBody()]] dans une disposition.
Par exemple, le code suivant injecte la date courante à la fin du corps de la page.
```php
\Yii::$app->view->on(View::EVENT_END_BODY, function () {
echo date('Y-m-d');
});
```
## Rendu des pages statiques <span id="rendering-static-pages"></span>
Les pages statiques font références aux pages dont le contenu principal est essentiellement statique sans recours à des données dynamiques poussées par les contrôleurs.
Vous pouvez renvoyer des pages statiques en plaçant leur code dans des vues, et en utilisant un code similaire à ce qui suit dans un contrôleur :
```php
public function actionAbout()
{
return $this->render('about');
}
```
Si un site Web contient beaucoup de pages statiques, ce serait très ennuyeux de répéter un code similaire de nombreuses fois. Pour résoudre ce problème, vous pouvez introduire une [action autonome](structure-controllers.md#standalone-actions) appelée [[yii\web\ViewAction]] dans un contrôleur. Par exemple :
```php
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
public function actions()
{
return [
'page' => [
'class' => 'yii\web\ViewAction',
],
];
}
}
```
Maintenant, si vous créez une vue nommée `about` dans le dossier `@app/views/site/pages`, vous pourrez afficher cette vue via l'URL suivante :
```
http://localhost/index.php?r=site%2Fpage&view=about
```
Le paramètre `view` de la méthode `GET` dit à [[yii\web\ViewAction]] quelle est la vue requise. L'action recherche alors cette vue dans le dossier `@app/views/site/pages`. Vous pouvez configurer la propriété [[yii\web\ViewAction::viewPrefix]] pour changer le dossier dans lequel la vue est recherchée.
## Meilleures pratiques <span id="best-practices"></span>
Les vues sont chargées de présenter les modèles dans le format désiré par l'utilisateur final. En général :
* Elles devraient essentiellement contenir du code relatif à la présentation, tel que le code HTML, du code PHP simple pour parcourir, formater et rendre les données.
* Elles ne devraient pas contenir de code qui effectue des requêtes de base de données. Un tel code devrait être placé dans les modèles.
* Elles devraient éviter d'accéder directement aux données de la requête, telles que `$_GET`, `$_POST`. C'est le rôle des contrôleurs. Si les données de la requête sont nécessaires, elles devraient être poussées dans les vues par les contrôleurs.
* Elles peuvent lire les propriétés des modèles, mais ne devraient pas les modifier.
Pour rendre les vues plus gérables, évitez de créer des vues qui sont trop complexes ou qui contiennent trop de code redondant. Vous pouvez utiliser les techniques suivantes pour atteindre cet but :
* Utiliser des [dispositions](#layouts) pour représenter les sections communes de présentation (p. ex. l'entête de page, le pied de page).
* Diviser une vue complexe en plusieurs vues plus réduites. Les vues plus réduites peuvent être rendue et assemblées dans une plus grande en utilisant les méthodes de rendu que nous avons décrites.
* Créer et utiliser des [widgets](structure-widgets.md) en tant que blocs de construction des vues.
* Créer et utiliser des classes d'aide pour transformer et formater les données dans les vues.

655
docs/guide-fr/tutorial-i18n.md

@ -0,0 +1,655 @@
Internationalisation
====================
Le terme *Internationalisation* (I18N) fait référence au processus de conception d'une application logicielle qui permet son adaptation à diverses langues et régions sans intervenir dans le code. Pour des applications Web, la chose est particulièrement importante puisque celle-ci peut concerner des utilisateurs potentiels répartis sur toute la surface de la terre. Yii met à votre disposition tout un arsenal de fonctionnalités qui prennent en charge la traduction des messages et des vues, ainsi que le formatage des nombres et des dates.
## Locale et Langue <span id="locale-language"></span>
Une *locale* est un jeu de paramètres qui définissent la langue de l'utilisateur, son pays et des préférences spéciales que celui-ci désire voir dans l'interface utilisateur.
Elle est généralement identifiée par un identifiant (ID), lui-même constitué par un identifiant de langue et un identifiant de région. Par exemple, l'identifiant `en-US` représente la locale *anglais* pour la langue et *États-Unis* pour la région.
Pour assurer la cohérence, tous les identifiants utilisés par les application Yii doivent être présentés sous leur forme canonique `ll-CC`, où `ll` est un code à 2 ou 3 lettres pour la langue conforme à la norme [ISO-639](http://www.loc.gov/standards/iso639-2/) et `CC` est un code à deux lettres pour le pays conforme à la norme [ISO-3166](http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html).
Pour plus de détails sur les locales, reportez-vous à la [documentation du projet ICU](http://userguide.icu-project.org/locale#TOC-The-Locale-Concept).
Dans Yii, nous utilisons souvent le mot « langue » pour faire référence à la locale.
Une application Yii utilise deux langues : la [[yii\base\Application::$sourceLanguage|langue source ]] et la [[yii\base\Application::$language|langue cible]]. La première fait référence à la langue dans laquelle les messages sont rédigés dans le code source, tandis que la deuxième est celle qui est utilisée pour présenter les textes à l'utilisateur final.
Pour l'essentiel, le service appelé *message translation service*(service de traduction des messages) assure la traduction d'un message textuel de la langue source vers la langue cible.
Vous pouvez configurer les langues de l'application dans la configuration de la manière suivante :
```php
return [
// définit la langue cible comme étant le français-France
'language' => 'fr-FR',
// définit la langue source comme étant l'anglais États-Unis
'sourceLanguage' => 'en-US',
......
];
```
La valeur par défaut pour la [[yii\base\Application::$sourceLanguage|langue source]] est `en-US`, qui signifie « anglais États-Unis ». Il est recommandé de conserver cette valeur sans la changer car il est généralement plus facile de trouver des gens capables de traduire de l'anglais vers d'autres langues que d'une langue non anglaise vers une autre langue.
Il est souvent nécessaire de définir la [[yii\base\Application::$language|langue cible]] de façon dynamique en se basant sur différents facteurs tels que, par exemple, les préférences linguistiques de l'utilisateur final. Au lieu de la définir dans la configuration de l'application vous pouvez utiliser l'instruction suivante pour changer la langue cible :
```php
// modifier la langue cible pour qu'elle soit français-FRANCE
\Yii::$app->language = 'fr-FR';
```
> Tip: si votre langue source change selon les différentes parties de votre code, vous pouvez modifier la valeur de la langue source localement comme c'est expliqué dans la section suivante.
## Traduction des messages <span id="message-translation"></span>
Le service de traduction des messages traduit un message textuel d'une langue (généralement la [[yii\base\Application::$sourceLanguage|langue source]]) vers une autre langue (généralement la [[yii\base\Application::$language|langue cible]]). Il effectue la traduction en recherchant le message à traduire dans une source de messages qui stocke les messages originaux et les messages traduits.
Si le message est trouvé, le message traduit correspondant est renvoyé; dans le cas contraire, le message original est renvoyé sans traduction.
Pour utiliser le service de traduction des messages, vous devez principalement effectuer les opérations suivantes :
* Envelopper le message textuel à traduire dans un appel à la méthode [[Yii::t()]];
* Configurer une ou plusieurs sources de messages dans lesquelles le service de traduction des messages peut rechercher des traductions;
* Confier aux traducteurs le soin de traduire les messages et de les stocker dans les sources de messages.
La méthode [[Yii::t()]] peut être utilisée comme le montre l'exemple suivant :
```php
echo \Yii::t('app', 'This is a string to translate!');
```
où le deuxième paramètre fait référence au message textuel à traduire, tandis que le premier paramètre fait référence au nom de la catégorie à laquelle le message appartient.
La méthode [[Yii::t()]] appelle la méthode `translate` du [composant d'application](structure-application-components.md) `i18n` pour assurer le travail réel de traduction. Le composant peut être configuré dans la configuration de l'application de la manière suivante :
```php
'components' => [
// ...
'i18n' => [
'translations' => [
'app*' => [
'class' => 'yii\i18n\PhpMessageSource',
//'basePath' => '@app/messages',
//'sourceLanguage' => 'en-US',
'fileMap' => [
'app' => 'app.php',
'app/error' => 'error.php',
],
],
],
],
],
```
Dans le code qui précède, une source de messages prise en charge par [[yii\i18n\PhpMessageSource]] est configurée. Le motif `app*` indique que toutes les catégories de messages dont les noms commencent par `app` doivent être traduites en utilisant cette source de messages. La classe [[yii\i18n\PhpMessageSource]] utilise des fichiers PHP pour stocker les traductions de messages. Chacun des fichiers PHP correspond aux messages d'une même catégorie. Par défaut, le nom du fichier doit être celui de la catégorie. Néanmoins, vous pouvez configurer [[yii\i18n\PhpMessageSource::fileMap|fileMap (cartographie de fichiers)]] pour faire correspondre une catégorie à un fichier PHP dont le nom obéit à une autre approche de nommage. Dans l'exemple qui précède, la catégorie `app/error` correspond au fichier PHP `@app/messages/fr-FR/error.php` (en supposant que `fr-FR` est la langue cible). Sans cette configuration, la catégorie correspondrait à `@app/messages/fr-FR/app/error.php`.
En plus de la possibilité de stocker les messages dans des fichiers PHP, vous pouvez aussi utiliser les sources de messages suivantes pour stocker vos traductions sous une autre forme :
- [[yii\i18n\GettextMessageSource]] utilise des fichiers GNU Gettext, MO ou PO pour maintenir les messages traduits.
- [[yii\i18n\DbMessageSource]] utilise une base de donnée pour stocker les messages traduits.
## Format des messages <span id="message-formatting"></span>
Lorsque vous traduisez un message, vous pouvez inclure dans le messages des « valeurs à remplacer » qui seront remplacées dynamiquement en fonction de la valeur d'un paramètre. Vous pouvez même utiliser une syntaxe spéciale des « valeurs à remplacer » pour que les valeurs de remplacement soient formatées en fonction de la langue cible.
Dans cette sous-section, nous allons décrire différentes manières de formater un message.
### Valeurs à remplacer des message <span id="message-parameters"></span>
Dans un message à traduire, vous pouvez inclure une ou plusieurs « valeurs à remplacer » pour qu'elles puissent être remplacées par les valeurs données. En spécifiant différents jeux de valeurs, vous pouvez faire varier le message dynamiquement. Dans l'exemple qui suit, la valeur à remplacer `{username}` du message `'Hello, {username}!'` sera remplacée par `'Alexander'` et `'Qiang'`, respectivement.
```php
$username = 'Alexander';
// affiche un message traduit en remplaçant {username} par "Alexander"
echo \Yii::t('app', 'Hello, {username}!', [
'username' => $username,
]);
$username = 'Qiang';
// affiche un message traduit en remplaçant {username} par "Qiang"
echo \Yii::t('app', 'Hello, {username}!', [
'username' => $username,
]);
```
Lorsque le traducteur traduit un message contenant une valeur à remplacer, il doit laisser la valeur à remplacer telle quelle. Cela tient au fait que les valeurs à remplacer seront remplacées par les valeurs réelles au moment de l'appel de `Yii::t()` pour traduire le message.
Dans un même message, vous pouvez utiliser, soit des « valeurs à remplacer nommées », soit des « valeurs à remplacer positionnelles », mais pas les deux types.
L'exemple précédent montre comment utiliser des valeurs à remplacer nommées, c'est à dire, des valeurs à remplacer écrites sous la forme `{nom}`, et pour lesquelles vous fournissez un tableau associatif dont les clés sont les noms des valeurs à remplacer (sans les accolades) et les valeurs, les valeurs de remplacement.
Les valeurs à remplacer positionnelles utilisent une suite d'entiers démarrant de zéro en tant que noms de valeurs à remplacer qui seront remplacées par les valeurs de remplacement, fournies sous forme d'un tableau, en fonction de leur position dans le tableau lors de l'appel de la méthode `Yii::t()`. Dans l'exemple suivant, les valeurs à remplacer positionnelles `{0}`, `{1}` et `{2}` seront remplacées respectivement par les valeurs de `$price`, `$count` et `$subtotal`.
```php
$price = 100;
$count = 2;
$subtotal = 200;
echo \Yii::t('app', 'Price: {0}, Count: {1}, Subtotal: {2}', [$price, $count, $subtotal]);
```
Dans le cas d'une seule valeur à remplacer, la valeur de remplacement peut être donnée sans la placer dans un tableau :
```php
echo \Yii::t('app', 'Price: {0}', $price);
```
> Tip: dans la plupart des cas, vous devriez utiliser des valeurs à remplacer nommées, parce que les noms permettent aux traducteurs de
> mieux comprendre le sens des messages qu'ils doivent traduire.
### Formatage des valeurs de remplacement <span id="parameter-formatting"></span>
Vous pouvez spécifier des règles de formatage additionnelles dans les valeurs à remplacer qui seront appliquées aux valeurs de remplacement. Dans l'exemple suivant, la valeur de remplacement *price* est traitée comme un nombre et formatée comme une valeur monétaire :
```php
$price = 100;
echo \Yii::t('app', 'Price: {0,number,currency}', $price);
```
> Note: le formatage des valeurs de remplacement nécessite l'installation de [extension intl de PHP](http://www.php.net/manual/en/intro.intl.php).
Vous pouvez utiliser, soit la forme raccourcie, soit la forme complète pour spécifier une valeur à remplacer avec un format :
```
forme raccourcie : {name,type}
forme complète : {name,type,style}
```
> Note: si vous avez besoin des caractères spéciaux tels que `{`, `}`, `'`, `#`, entourez-les de `'`:
>
```php
echo Yii::t('app', "Example of string with ''-escaped characters'': '{' '}' '{test}' {count,plural,other{''count'' value is # '#{}'}}", ['count' => 3]);
```
Le format complet est décrit dans la [documentation ICU](http://icu-project.org/apiref/icu4c/classMessageFormat.html).
Dans ce qui suit, nous allons présenter quelques usages courants.
#### Nombres <span id="number"></span>
La valeur de remplacement est traitée comme un nombre. Par exemple,
```php
$sum = 42;
echo \Yii::t('app', 'Balance: {0,number}', $sum);
```
Vous pouvez spécifier un style facultatif pour la valeur de remplacement `integer` (entier), `currency` (valeur monétaire), ou `percent` (pourcentage) :
```php
$sum = 42;
echo \Yii::t('app', 'Balance: {0,number,currency}', $sum);
```
Vous pouvez aussi spécifier un motif personnalisé pour formater le nombre. Par exemple,
```php
$sum = 42;
echo \Yii::t('app', 'Balance: {0,number,,000,000000}', $sum);
```
Les caractères à utiliser dans les formats personnalisés sont présentés dans le document [ICU API reference](http://icu-project.org/apiref/icu4c/classicu_1_1DecimalFormat.html) à la section "Special Pattern Characters" (Caractères pour motifs spéciaux).
La valeur de remplacement est toujours formatée en fonction de la locale cible c'est à dire que vous ne pouvez pas modifier les séparateurs de milliers et de décimales, les symboles monétaires, etc. sans modifier la locale de traduction. Si vous devez personnaliser ces éléments vous pouvez utiliser [[yii\i18n\Formatter::asDecimal()]] et [[yii\i18n\Formatter::asCurrency()]].
#### Date <span id="date"></span>
La valeur de remplacement doit être formatée comme une date. Par exemple,
```php
echo \Yii::t('app', 'Today is {0,date}', time());
```
Vous pouvez spécifier des styles facultatifs pour la valeur de remplacement comme `short` (court), `medium` (moyen), `long` (long) ou `full` (complet) :
```php
echo \Yii::t('app', 'Today is {0,date,short}', time());
```
Vous pouvez aussi spécifier un motif personnalisé pour formater la date :
```php
echo \Yii::t('app', 'Today is {0,date,yyyy-MM-dd}', time());
```
Voir [Formatting reference](http://icu-project.org/apiref/icu4c/classicu_1_1SimpleDateFormat.html).
#### Heure <span id="time"></span>
La valeur de remplacement doit être formatée comme une heure (au sens large heure minute seconde). Par exemple,
```php
echo \Yii::t('app', 'It is {0,time}', time());
```
Vous pouvez spécifier des styles facultatifs pour la valeur de remplacement comme `short` (court), `medium` (moyen), `long` (long) ou `full` (complet) :
```php
echo \Yii::t('app', 'It is {0,time,short}', time());
```
Vous pouvez aussi spécifier un motif personnalisé pour formater l'heure :
```php
echo \Yii::t('app', 'It is {0,date,HH:mm}', time());
```
Voir [Formatting reference](http://icu-project.org/apiref/icu4c/classicu_1_1SimpleDateFormat.html).
#### Prononciation <span id="spellout"></span>
La valeur de remplacement doit être traitée comme un nombre et formatée comme une prononciation. Par exemple,
```php
// produit "42 is spelled as forty-two"
echo \Yii::t('app', '{n,number} is spelled as {n,spellout}', ['n' => 42]);
```
Par défaut le nombre est épelé en tant que cardinal. Cela peut être modifié :
```php
// produit "I am forty-seventh agent"
echo \Yii::t('app', 'I am {n,spellout,%spellout-ordinal} agent', ['n' => 47]);
```
Notez qu'il ne doit pas y avoir d'espace après `spellout,` et avant `%`.
Pour trouver une liste des options disponibles pour votre locale, reportez-vous à
"Numbering schemas, Spellout" à [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/).
#### Nombre ordinal <span id="ordinal"></span>
La valeur de remplacement doit être traitée comme un nombre et formatée comme un nombre ordinal. Par exemple,
```php
// produit "You are the 42nd visitor here!" (vous êtes le 42e visiteur ici!)
echo \Yii::t('app', 'You are the {n,ordinal} visitor here!', ['n' => 42]);
```
Les nombres ordinaux acceptent plus de formats pour des langues telles que l'espagnol :
```php
// produit 471ª
echo \Yii::t('app', '{n,ordinal,%digits-ordinal-feminine}', ['n' => 471]);
```
Notez qu'il ne doit pas y avoir d'espace après `ordinal,` et avant `%`.
Pour trouver une liste des options disponibles pour votre locale, reportez-vous à
"Numbering schemas, Ordinal" à [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/).
#### Durée <span id="duration"></span>
La valeur de remplacement doit être traitée comme un nombre de secondes et formatée comme une durée. Par exemple,
```php
// produit "You are here for 47 sec. already!" (Vous êtes ici depuis 47sec. déjà!)
echo \Yii::t('app', 'You are here for {n,duration} already!', ['n' => 47]);
```
La durée accepte d'autres formats :
```php
// produit 130:53:47
echo \Yii::t('app', '{n,duration,%in-numerals}', ['n' => 471227]);
```
Notez qu'il ne doit pas y avoir d'espace après `duration,` et avant `%`.
Pour trouver une liste des options disponibles pour votre locale, reportez-vous à
"Numbering schemas, Duration" à [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/).
#### Pluriel <span id="plural"></span>
Les langues diffèrent dans leur manière de marquer le pluriel. Yii fournit un moyen pratique pour traduire les messages dans différentes formes de pluriel qui fonctionne même pour des règles très complexes. Au lieu de s'occuper des règles d'inflexion directement, il est suffisant de fournir la traductions des mots infléchis dans certaines situations seulement. Par exemple,
```php
// Lorsque $n = 0, produit "There are no cats!"
// Losque $n = 1, produit "There is one cat!"
// Lorsque $n = 42, produit "There are 42 cats!"
echo \Yii::t('app', 'There {n,plural,=0{are no cats} =1{is one cat} other{are # cats}}!', ['n' => $n]);
```
Dans les arguments des règles de pluralisation ci-dessus, `=` signifie valeur exacte. Ainsi `=0` signifie exactement zéro, `=1` signifie exactement un. `other` signifie n'importe quelle autre valeur. `#` est remplacé par la valeur de `n` formatée selon la langue cible.
Les formes du pluriel peuvent être très compliquées dans certaines langues. Dans l'exemple ci-après en russe, `=1` correspond exactement à `n = 1`
tandis que `one` correspond à `21` ou `101`:
```
Здесь {n,plural,=0{котов нет} =1{есть один кот} one{# кот} few{# кота} many{# котов} other{# кота}}!
```
Ces noms d'arguments spéciaux tels que `other`, `few`, `many` et autres varient en fonction de la langue. Pour savoir lesquels utiliser pour une locale particulière, reportez-vous aux "Plural Rules, Cardinal" à [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/).
En alternative, vous pouvez vous reporter aux [rules reference at unicode.org](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html).
> Note: le message en russe ci-dessus est principalement utilisé comme message traduit, pas comme message source, sauf si vous définissez la [[yii\base\Application::$sourceLanguage|langue source]] de votre application comme étant `ru-RU` et traduisez à partir du russe.
>
> Lorsqu'une traduction n'est pas trouvée pour un message source spécifié dans un appel de `Yii::t()`, les règles du pluriel pour la
> [[yii\base\Application::$sourceLanguage|langue source]] seront appliquées au message source.
Il existe un paramètre `offset` dans le cas où la chaîne est de la forme suivante :
```php
$likeCount = 2;
echo Yii::t('app', 'You {likeCount,plural,
offset: 1
=0{did not like this}
=1{liked this}
one{and one other person liked this}
other{and # others liked this}
}', [
'likeCount' => $likeCount
]);
// You and one other person liked this
```
#### Sélection ordinale <span id="ordinal-selection">
L'argument `selectordinal` pour une valeur à remplacer numérique a pour but de choisir une chaîne de caractères basée sur les règles linguistiques de la locale cible pour les ordinaux. Ainsi, 
```php
$n = 3;
echo Yii::t('app', 'You are the {n,selectordinal,one{#st} two{#nd} few{#rd} other{#th}} visitor', ['n' => $n]);
```
//Produit pour l'anglais :
//You are the 3rd visitor
//Traduction en russe,
'You are the {n,selectordinal,one{#st} two{#nd} few{#rd} other{#th}} visitor' => 'Вы {n,selectordinal,other{#-й}} посетитель',
//Traduit en russe produit :
//Вы 3-й посетитель
//Traduction en français
'You are the {n,selectordinal,one{#st} two{#nd} few{#rd} other{#th}} visitor' => 'Vous êtes le {n,selectordinal,one{#er} other{#e}} visiteur'
//Traduit en français produit :
//Vous êtes le 3e visiteur
```
Le format est assez proche de celui utilisé pour le pluriel. Pour connaître quels arguments utiliser pour une locale particulière, reportez-vous aux "Plural Rules, Ordinal" à [http://intl.rmcreative.ru/](http://intl.rmcreative.ru/).
En alternative, vous pouvez vous reporter aux [rules reference at unicode.org](http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html).
#### Sélection <span id="selection"></span>
Vous pouvez utiliser l'argument `select` dans une valeur à remplacer pour choisir une phrase en fonction de la valeur de remplacement. Par exemple,
```php
// Peut produire "Snoopy is a dog and it loves Yii!"
echo \Yii::t('app', '{name} is a {gender} and {gender,select,female{she} male{he} other{it}} loves Yii!', [
'name' => 'Snoopy',
'gender' => 'dog',
]);
```
Dans l'expression qui précède, `female` et `male` sont des valeurs possibles de l'argument, tandis que `other` prend en compte les valeurs qui ne sont ni l'une ni l'autre des ces valeurs. Derrière chacune des valeurs possibles de l'argument, vous devez spécifier un segment de phrase en l'entourant d'accolades.
### Spécification des sources de messages par défaut<span id="default-translation"></span>
Vous pouvez spécifier les sources de messages par défaut qui seront utilisées comme solution de repli pour les catégories qui ne correspondent à aucune des catégories configurées.
Cette source de message doit être marquée par un caractère générique `*`. Pour cela ajoutez les lignes suivantes dans la configuration de l'application :
```php
//configure i18n component
'i18n' => [
'translations' => [
'*' => [
'class' => 'yii\i18n\PhpMessageSource'
],
],
],
```
Désormais, vous pouvez utiliser une catégorie sans la configurer, ce qui est un comportement identique à celui de Yii 1.1. Les messages pour cette catégorie proviendront d'une source de messages par défaut située dans le dossier `basePath` c.-à-d. `@app/messages`:
```php
echo Yii::t('not_specified_category', 'message from unspecified category');
```
Le message sera chargé depuis `@app/messages/<LanguageCode>/not_specified_category.php`.
### Traduction des messages d'un module <span id="module-translation"></span>
Si vous voulez traduire les messages d'un module et éviter d'avoir un unique fichier de traduction pour tous les messages, vous pouvez procéder comme suit :
```php
<?php
namespace app\modules\users;
use Yii;
class Module extends \yii\base\Module
{
public $controllerNamespace = 'app\modules\users\controllers';
public function init()
{
parent::init();
$this->registerTranslations();
}
public function registerTranslations()
{
Yii::$app->i18n->translations['modules/users/*'] = [
'class' => 'yii\i18n\PhpMessageSource',
'sourceLanguage' => 'en-US',
'basePath' => '@app/modules/users/messages',
'fileMap' => [
'modules/users/validation' => 'validation.php',
'modules/users/form' => 'form.php',
...
],
];
}
public static function t($category, $message, $params = [], $language = null)
{
return Yii::t('modules/users/' . $category, $message, $params, $language);
}
}
```
Dans l'exemple précédent, nous utilisons le caractère générique pour la correspondance puis nous filtrons chacune des catégories par fichier requis. Au lieu d'utiliser `fileMap`, vous pouvez utiliser la convention de mise en correspondance du fichier de même nom.
Désormais, vous pouvez utiliser `Module::t('validation', 'your custom validation message')` ou `Module::t('form', 'some form label')` directement.
### Traduction des messages de widgets <span id="widget-translation"></span>
La règle applicable aux modules présentée ci-dessus s'applique également aux widgets, par exemple :
```php
<?php
namespace app\widgets\menu;
use yii\base\Widget;
use Yii;
class Menu extends Widget
{
public function init()
{
parent::init();
$this->registerTranslations();
}
public function registerTranslations()
{
$i18n = Yii::$app->i18n;
$i18n->translations['widgets/menu/*'] = [
'class' => 'yii\i18n\PhpMessageSource',
'sourceLanguage' => 'en-US',
'basePath' => '@app/widgets/menu/messages',
'fileMap' => [
'widgets/menu/messages' => 'messages.php',
],
];
}
public function run()
{
echo $this->render('index');
}
public static function t($category, $message, $params = [], $language = null)
{
return Yii::t('widgets/menu/' . $category, $message, $params, $language);
}
}
```
Au lieu d'utiliser `fileMap`, vous pouvez utiliser la convention de mise en correspondance du fichier de même nom.
Désormais, vous pouvez utiliser `Menu::t('messages', 'new messages {messages}', ['{messages}' => 10])` directement.
> Note: pour les widgets, vous pouvez aussi utiliser les vues i18n, en y appliquant les mêmes règles que celles applicables aux contrôleurs.
### Traduction des messages du framework <span id="framework-translation"></span>
Yii est fourni avec les traductions par défaut des messages d'erreurs de validation et quelques autres chaînes. Ces messages sont tous dans la catégorie `yii`. Parfois, vous souhaitez corriger la traduction par défaut des messages du framework pour votre application. Pour le faire, configurez le [composant d'application](structure-application-components.md) `i18n` comme indiqué ci-après :
```php
'i18n' => [
'translations' => [
'yii' => [
'class' => 'yii\i18n\PhpMessageSource',
'sourceLanguage' => 'en-US',
'basePath' => '@app/messages'
],
],
],
```
Vous pouvez désormais placer vos traductions corrigées dans `@app/messages/<language>/yii.php`.
### Gestion des traductions manquantes <span id="missing-translations"></span>
Même si la traduction n'est pas trouvée dans la source de traductions, Yii affiche le contenu du message demandé. Un tel comportement est très pratique tant que le message est une phrase valide. Néanmoins, quelques fois, cela ne suffit pas. Vous pouvez désirer faire quelque traitement de la situation, au moment où le message apparaît manquant. Vous pouvez utiliser pour cela l'événement [[yii\i18n\MessageSource::EVENT_MISSING_TRANSLATION|missingTranslation (traduction manquante)]] de [[yii\i18n\MessageSource]].
Par exemple, vous désirez peut-être marquer toutes les traductions manquantes par quelque chose de voyant, de manière à les repérer facilement dans la page. Vous devez d'abord configurer un gestionnaire d'événement. Cela peut se faire dans la configuration de l'application :
```php
'components' => [
// ...
'i18n' => [
'translations' => [
'app*' => [
'class' => 'yii\i18n\PhpMessageSource',
'fileMap' => [
'app' => 'app.php',
'app/error' => 'error.php',
],
'on missingTranslation' => ['app\components\TranslationEventHandler', 'handleMissingTranslation']
],
],
],
],
```
Vous devez ensuite implémenter votre gestionnaire d'événement :
```php
<?php
namespace app\components;
use yii\i18n\MissingTranslationEvent;
class TranslationEventHandler
{
public static function handleMissingTranslation(MissingTranslationEvent $event)
{
$event->translatedMessage = "@MISSING: {$event->category}.{$event->message} FOR LANGUAGE {$event->language} @";
}
}
```
Si [[yii\i18n\MissingTranslationEvent::translatedMessage]] est défini par le gestionnaire d'événement, il sera affiché en tant que résultat de la traduction.
> Note: chacune des sources de messages gère ses traductions manquantes séparément. Si vous avez recours à plusieurs sources de messages et que vous voulez qu'elles gèrent les messages manquants de la même manière, vous devez assigner le gestionnaire d'événement correspondant à chacune d'entre-elles.
### Utilisation de la commande `message`<a name="message-command"></a>
Les traductions peuvent être stockées dans des [[yii\i18n\PhpMessageSource|fichiers php]], des [[yii\i18n\GettextMessageSource|fichiers .po ]] ou dans une [[yii\i18n\DbMessageSource|bases de données]]. Reportez-vous aux classes spécifiques pour connaître les options supplémentaires.
En premier lieu, vous devez créer un fichier de configuration. Décidez de son emplacement et exécutez la commande suivante :
```bash
./yii message/config-template path/to/config.php
```
Ouvrez le fichier ainsi créé et ajustez-en les paramètres pour qu'ils répondent à vos besoins. Portez-une attention particulière à :
* `languages`: un tableau des langues dans lesquelles votre application doit être traduite ;
* `messagePath`: le chemin du dossier où doivent être placés les fichiers de messages, qui doit correspondre le paramètre `basePath` de `i18n` dans la configuration de l'application.
Vous pouvez également utiliser la commande './yii message/config' pour générer dynamiquement le fichier de configuration avec les options spécifiées via le ligne de commande. Par exemple, vous pouvez définir `languages` et `messagePath` comme indiqué ci-dessous :
```bash
./yii message/config --languages=de,ja --messagePath=messages path/to/config.php
```
Pour connaître toutes les options utilisables, exécutez la commande :
```bash
./yii help message/config
```
Une fois que vous en avez terminé avec la configuration, vous pouvez finalement extraire vos messages par la commande :
```bash
./yii message path/to/config.php
```
Vous pouvez aussi utiliser des options pour changer dynamiquement les paramètres d'extraction.
Vous trouverez alors vos fichiers de traduction (si vous avez choisi les traductions basées sur des fichiers) dans votre dossier `messagePath`.
## Traduction des vues<span id="view-translation"></span>
Plutôt que de traduire des textes de messages individuels, vous pouvez parfois désirer traduire le script d'une vue tout entier. Pour cela, contentez-vous de traduire la vue et de la sauvegarder dans un sous-dossier dont le nom est le code de la langue cible. Par exemple, si vous avez traduit le script de la vue `views/site/index.php` et que la langue cible est `fr-FR`, vous devez sauvegarder la traduction dans `views/site/fr-FR/index.php`. Désormais, à chaque fois que vous appellerez [[yii\base\View::renderFile()]] ou toute méthode qui invoque cette méthode (p. ex. [[yii\base\Controller::render()]]) pour rendre la vue, `views/site/index.php`, ce sera la vue `views/site/fr-FR/index.php` qui sera rendue à sa place.
> Note: si la [[yii\base\Application::$language|langue cible]] est identique à la [[yii\base\Application::$sourceLanguage|langue source]]
> la vue originale sera rendue sans tenir compte de l'existence de la vue traduite.
## Formatage des dates et des nombres<span id="date-number"></span>
Reportez-vous à la section [Formatage des données](output-formatting.md) pour les détails.
## Configuration de l'environnement PHP <span id="setup-environment"></span>
Yii utilise l'[extension intl de PHP](http://php.net/manual/en/book.intl.php) pour fournir la plupart de ses fonctionnalités d'internationalisation, telles que le formatage des dates et des nombres de la classe [[yii\i18n\Formatter]] et le formatage des messages de la classe [[yii\i18n\MessageFormatter]].
Les deux classes fournissent un mécanisme de remplacement lorsque l'extension `intl` n'est pas installée. Néanmoins, l'implémentation du mécanisme de remplacement ne fonctionne bien que quand la langue cible est l'anglais. C'est pourquoi, il est fortement recommandé d'installer `intl` quand c'est nécessaire.
L'[extension intl de PHP](http://php.net/manual/en/book.intl.php) est basée sur la [bibliothèque ICU](http://site.icu-project.org/) qui fournit la base de connaissances et les règles de formatage pour les différentes locales. Des versions différentes d'ICU peuvent conduire à des formatages différents des dates et des nombres. Pour être sûr que votre site Web donne les même résultats dans tous les environnements, il est recommandé d'installer la même version de l'extension `intl` (et par conséquent la même version d'ICU) dans tous les environnements.
Pour savoir quelle version d'ICU est utilisée par PHP, vous pouvez exécuter le script suivant, qui vous restitue la version de PHP et d'ICU en cours d'utilisation.
```php
<?php
echo "PHP: " . PHP_VERSION . "\n";
echo "ICU: " . INTL_ICU_VERSION . "\n";
echo "ICU Data: " . INTL_ICU_DATA_VERSION . "\n";
```
Il est également recommandé d'utiliser une version d'ICU supérieure ou égale à 48. Cela garantit que toutes les fonctionnalités décrites dans ce document sont utilisables. Par exemple, une version d'ICU inférieure à 49 ne prend pas en charge la valeur à remplacer `#` dans les règles de pluralisation. Reportez-vous à <http://site.icu-project.org/download> pour obtenir une liste complète des versions d'ICU disponibles. Notez que le numérotage des versions a changé après la version 4.8 (p. ex., ICU 4.8, ICU 49, ICU 50, etc.)
En outre, les informations dans la base de donnée des fuseaux horaires fournie par la bibliothèque ICU peuvent être surannées. Reportez-vous au [manuel d'ICU](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data) pour les détails sur la manière de mettre la base de données des fuseaux horaires à jour. Bien que la base de données des fuseaux horaires d'ICU soit utilisée pour le formatage, celle de PHP peut aussi être d'actualité. Vous pouvez la mettre à jour en installant la dernière version du [paquet `timezonedb` de pecl](http://pecl.php.net/package/timezonedb).

4
docs/guide-id/start-installation.md

@ -40,7 +40,7 @@ dengan menjalankan `composer self-update`.
Dengan Komposer diinstal, Anda dapat menginstal Yii dengan menjalankan perintah berikut di bawah folder yang terakses web:
```bash
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
```
@ -235,4 +235,4 @@ Bila menggunakan konfigurasi ini, Anda juga harus menetapkan `cgi.fix_pathinfo=0
untuk menghindari banyak panggilan `stat()` sistem yang tidak perlu.
Sekalian catat bahwa ketika menjalankan server HTTPS, Anda perlu menambahkan `fastcgi_param HTTPS on;` sehingga Yii
benar dapat mendeteksi jika sambungan aman.
benar dapat mendeteksi jika sambungan aman.

2
docs/guide-it/start-installation.md

@ -27,7 +27,7 @@ Se hai già Composer installato assicurati di avere una versione aggiornata. Puo
Una volta installato Composer, puoi installare Yii eseguendo questo comando in una directory accessbile via web:
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
Il primo comando installa il [plugin composer asset](https://github.com/francoispluchino/composer-asset-plugin/)

32
docs/guide-ja/concept-di-container.md

@ -12,6 +12,7 @@
Yii は [[yii\di\Container]] クラスを通して DI コンテナの機能を提供します。これは、次の種類の依存注入をサポートしています:
* コンストラクタ·インジェクション
* メソッド・インジェクション
* セッター/プロパティ·インジェクション
* PHP コーラブル·インジェクション
@ -38,6 +39,37 @@ $foo = new Foo($bar);
```
### メソッド・インジェクション <span id="method-injection"></span>
通常、クラスの依存はコンストラクタに渡されて、そのクラスの内部でライフサイクル全体にわたって利用可能になります。
メソッド・インジェクションを使うと、クラスのメソッドの一つだけに必要となる依存、例えば、コンストラクタに渡すことが不可能であったり、大半のユースケースにおいてはオーバーヘッドが大きすぎるような依存を提供することが可能になります。
クラスのメソッドを次の例の `doSomething` メソッドのように定義することが出来ます。
```php
class MyClass extends \yii\base\Component
{
public function __construct(/* 軽量の依存はここに */, $config = [])
{
// ...
}
public function doSomething($param1, \my\heavy\Dependency $something)
{
// $something を使って何かをする
}
}
```
あなた自身で `\my\heavy\Dependency` のインスタンスを渡すか、次のように
[[yii\di\Container::invoke()]] を使えば、このメソッドを呼ぶことが出来ます。
```php
$obj = new MyClass(/*...*/);
Yii::$container->invoke([$obj, 'doSomethingWithHeavyDependency'], ['param1' => 42]); // $something は DI コンテナによって提供される
```
### セッター/プロパティ·インジェクション <span id="setter-and-property-injection"></span>
セッター/プロパティ·インジェクションは、[構成情報](concept-configurations.md) を通してサポートされます。

42
docs/guide-ja/db-migrations.md

@ -176,15 +176,15 @@ class m150101_185401_create_news_table extends Migration
バージョン 2.0.7 以降では、マイグレーション・コンソールがマイグレーションを生成する便利な方法を提供しています。
マイグレーションの名前が特定の形式である場合は、生成されるマイグレーション・ファイルに追加のコードが書き込まれます。
例えば、`create_xxx` や `drop_xxx` であれば、テーブルの作成や削除をするコードが追加されます。
マイグレーションの名前が特別な形式である場合は、生成されるマイグレーション・ファイルに追加のコードが書き込まれます。
例えば、`create_xxx_table` や `drop_xxx_table` であれば、テーブルの作成や削除をするコードが追加されます。
以下で、この機能の全ての変種を説明します。
### テーブルの作成
```php
yii migrate/create create_post
yii migrate/create create_post_table
```
上記のコマンドは、次のコードを生成します。
@ -193,7 +193,7 @@ yii migrate/create create_post
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -218,7 +218,7 @@ class m150811_220037_create_post extends Migration
テーブルのフィールドも直接に生成したい場合は、`--fields` オプションでフィールドを指定します。
```php
yii migrate/create create_post --fields="title:string,body:text"
yii migrate/create create_post_table --fields="title:string,body:text"
```
これは、次のコードを生成します。
@ -227,7 +227,7 @@ yii migrate/create create_post --fields="title:string,body:text"
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -255,7 +255,7 @@ class m150811_220037_create_post extends Migration
さらに多くのフィールド・パラメータを指定することも出来ます。
```php
yii migrate/create create_post --fields="title:string(12):notNull:unique,body:text"
yii migrate/create create_post_table --fields="title:string(12):notNull:unique,body:text"
```
これは、次のコードを生成します。
@ -264,7 +264,7 @@ yii migrate/create create_post --fields="title:string(12):notNull:unique,body:te
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -297,7 +297,7 @@ class m150811_220037_create_post extends Migration
バージョン 2.0.8 からは、`foreignKey` キーワードを使って外部キーを生成することができます。
```php
yii migrate/create create_post --fields="author_id:integer:notNull:foreignKey(user),category_id:integer:defaultValue(1):foreignKey,title:string,body:text"
yii migrate/create create_post_table --fields="author_id:integer:notNull:foreignKey(user),category_id:integer:defaultValue(1):foreignKey,title:string,body:text"
```
これは、次のコードを生成します。
@ -310,7 +310,7 @@ yii migrate/create create_post --fields="author_id:integer:notNull:foreignKey(us
* - `user`
* - `category`
*/
class m160328_040430_create_post extends Migration
class m160328_040430_create_post_table extends Migration
{
/**
* @inheritdoc
@ -413,13 +413,13 @@ class m160328_040430_create_post extends Migration
### テーブルを削除する
```php
yii migrate/create drop_post --fields="title:string(12):notNull:unique,body:text"
yii migrate/create drop_post_table --fields="title:string(12):notNull:unique,body:text"
```
これは、次のコードを生成します。
```php
class m150811_220037_drop_post extends Migration
class m150811_220037_drop_post_table extends Migration
{
public function up()
{
@ -439,18 +439,18 @@ class m150811_220037_drop_post extends Migration
### カラムを追加する
マイグレーションの名前が `add_xxx_to_yyy` の形式である場合、ファイルの内容は、必要となる `addColumn``dropColumn` を含むことになります。
マイグレーションの名前が `add_xxx_column_to_yyy_table` の形式である場合、ファイルの内容は、必要となる `addColumn``dropColumn` を含むことになります。
カラムを追加するためには、次のようにします。
```php
yii migrate/create add_position_to_post --fields="position:integer"
yii migrate/create add_position_column_to_post_table --fields="position:integer"
```
これが次のコードを生成します。
```php
class m150811_220037_add_position_to_post extends Migration
class m150811_220037_add_position_column_to_post_table extends Migration
{
public function up()
{
@ -466,16 +466,16 @@ class m150811_220037_add_position_to_post extends Migration
### カラムを削除する
マイグレーションの名前が `drop_xxx_from_yyy` の形式である場合、ファイルの内容は、必要となる `addColumn``dropColumn` を含むことになります。
マイグレーションの名前が `drop_xxx_column_from_yyy_table` の形式である場合、ファイルの内容は、必要となる `addColumn``dropColumn` を含むことになります。
```php
yii migrate/create drop_position_from_post --fields="position:integer"
yii migrate/create drop_position_column_from_post_table --fields="position:integer"
```
これは、次のコードを生成します。
```php
class m150811_220037_drop_position_from_post extends Migration
class m150811_220037_drop_position_column_from_post_table extends Migration
{
public function up()
{
@ -491,10 +491,10 @@ class m150811_220037_drop_position_from_post extends Migration
### 中間テーブルを追加する
マイグレーションの名前が `create_junction_xxx_and_yyy` の形式である場合は、中間テーブルを作成するのに必要となるコードが生成されます。
マイグレーションの名前が `create_junction_table_for_xxx_and_yyy_tables` の形式である場合は、中間テーブルを作成するのに必要となるコードが生成されます。
```php
yii migrate/create create_junction_post_and_tag --fields="created_at:dateTime"
yii migrate/create create_junction_table_for_post_and_tag_tables --fields="created_at:dateTime"
```
これは、次のコードを生成します。
@ -507,7 +507,7 @@ yii migrate/create create_junction_post_and_tag --fields="created_at:dateTime"
* - `post`
* - `tag`
*/
class m160328_041642_create_junction_post_and_tag extends Migration
class m160328_041642_create_junction_table_for_post_and_tag_tables extends Migration
{
/**
* @inheritdoc

13
docs/guide-ja/helper-array.md

@ -207,7 +207,7 @@ $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');
// 結果は次のようになります
@ -368,16 +368,17 @@ $data = ArrayHelper::toArray($posts, [
ある要素が配列の中に存在するかどうか、また、一連の要素が配列のサブセットであるかどうか、ということを調べる必要がある場合がよくあります。
PHP は `in_array()` を提供していますが、これはサブセットや `\Traversable` なオブジェクトをサポートしていません。
この種のチェックを助けるために、[[yii\base\ArrayHelper]] は [[yii\base\ArrayHelper::isIn()|isIn()]]
および [[yii\base\ArrayHelper::isSubset()|isSubset()]] を [[in_array()]] と同じシグニチャで提供しています。
この種のチェックを助けるために、[[yii\helpers\ArrayHelper]] は [[yii\helpers\ArrayHelper::isIn()|isIn()]]
および [[yii\helpers\ArrayHelper::isSubset()|isSubset()]] を
[in_array()](http://php.net/manual/en/function.in-array.php) と同じシグニチャで提供しています。
```php
// true
ArrayHelper::isIn('a', ['a']);
// true
ArrayHelper::isIn('a', new(ArrayObject['a']));
ArrayHelper::isIn('a', new ArrayObject(['a']));
// true
ArrayHelper::isSubset(new(ArrayObject['a', 'c']), new(ArrayObject['a', 'b', 'c'])
// true
ArrayHelper::isSubset(new ArrayObject(['a', 'c']), new ArrayObject(['a', 'b', 'c']));
```

8
docs/guide-ja/input-multiple-models.md

@ -24,10 +24,14 @@ class UserController extends Controller
public function actionUpdate($id)
{
$user = User::findOne($id);
if (!$user) {
throw new NotFoundHttpException("ユーザが見つかりませんでした。");
}
$profile = Profile::findOne($id);
if (!isset($user, $profile)) {
throw new NotFoundHttpException("ユーザが見つかりませんでした。");
if (!$profile) {
throw new NotFoundHttpException("ユーザのプロファイルがありません。");
}
$user->scenario = 'update';

27
docs/guide-ja/rest-response-formatting.md

@ -146,3 +146,30 @@ Content-Type: application/json; charset=UTF-8
}
}
```
### JSON 出力を制御する
JSON 形式のレスポンスを生成する [[yii\web\JsonResponseFormatter|JsonResponseFormatter]] クラスは [[yii\helpers\Json|JSON ヘルパ]] を内部的に使用します。
このフォーマッタはさまざまなオプションによって構成することが可能です。
例えば、[[yii\web\JsonResponseFormatter::$prettyPrint|$prettyPrint]] オプションは、より読みやすいレスポンスのためのもので、開発時に有用なオプションです。
また、[[yii\web\JsonResponseFormatter::$encodeOptions|$encodeOptions]] によって JSON エンコーディングの出力を制御することが出来ます。
フォーマッタは、以下のように、アプリケーションの [構成情報](concept-configuration.md) の中で、`response` アプリケーション・コンポーネントの [[yii\web\Response::formatters|formatters]] プロパティの中で構成することが出来ます。
```php
'response' => [
// ...
'formatters' => [
\yii\web\Response::FORMAT_JSON => [
'class' => 'yii\web\JsonResponseFormatter',
'prettyPrint' => YII_DEBUG, // デバッグモードでは "きれい" な出力を使用
'encodeOptions' => JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
// ...
],
],
],
```
[DAO](db-dao.md) データベース・レイヤを使ってデータベースからデータを返す場合は、全てのデータが文字列として表されます。
しかし、特に数値は JSON では数として表現されなければなりませんので、これは必ずしも期待通りの結果であるとは言えません。
一方、ActiveRecord レイヤを使ってデータベースからデータを取得する場合は、数値カラムの値は、[[yii\db\ActiveRecord::populateRecord()]] においてデータベースからデータが取得される際に、整数に変換されます。

32
docs/guide-ja/start-installation.md

@ -21,7 +21,9 @@ Yii はもう一つ、[アドバンストプロジェクトテンプレート](h
Composer によるインストール <span id="installing-via-composer"></span>
---------------------------
まだ Composer をインストールしていない場合は、[getcomposer.org](https://getcomposer.org/download/) の指示に従ってインストールすることが出来ます。
### Composer をインストールする
まだ Composer をインストールしていない場合は、[getcomposer.org]() の指示に従ってインストールすることが出来ます。
Linux や Mac OS X では、次のコマンドを実行します。
```bash
@ -31,27 +33,43 @@ mv composer.phar /usr/local/bin/composer
Windows では、[Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe) をダウンロードして実行します。
何か問題が生じたときや、Composer の使い方に関してもっと学習したいときは、[Composer ドキュメント](https://getcomposer.org/doc/) を参照してください。
何か問題が生じたときは、[Composer ドキュメントのトラブル・シューティングの節](https://getcomposer.org/doc/articles/troubleshooting.md) を参照してください。
Composer は初めてだという場合は、少なくとも、Composer ドキュメントの [基本的な使い方の節](https://getcomposer.org/doc/01-basic-usage.md) も参照することを推奨します。
このガイドでは、composer のコマンドの全ては、あなたが composer を [グローバル](https://getcomposer.org/doc/00-intro.md#globally) にインストールし、`composer` コマンドとして使用できるようにしているものと想定しています。
そうではなく、ローカル・ディレクトリにある `composer.phar` を使おうとする場合は、例に出てくるコマンドをそれに合せて修正しなければなりません。
以前に Composer をインストールしたことがある場合は、確実に最新のバージョンを使うようにしてください。
Composer は `composer self-update` コマンドを実行してアップデートすることが出来ます。
> Note: Yii のインストールを実行する際に、Composer は大量の情報を Github API から要求する必要が生じます。
> リクエストの量は、あなたのアプリケーションが持つ依存の数に依存しますが、**Github API レート制限** より大きくなることがあり得ます。
> この制限にかかった場合、Composer は Github API トークンを取得するために、あなたの Github ログイン認証情報を要求するでしょう。
> 高速な接続においては、Composer が対処できるよりも早い段階でこの制限にかかることもありますので、
> Yii のインストールの前に、このアクセス・トークンを構成することを推奨します。
> アクセス・トークンの構成の仕方については、[Github API トークンに関する Composer ドキュメント](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
> の指示を参照して下さい。
### Yii をインストールする
Composer がインストールされたら、ウェブからアクセスできるフォルダで下記のコマンドを実行することによって Yii をインストールすることが出来ます。
```bash
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:~1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
```
最初のコマンドは [composer アセットプラグイン](https://github.com/francoispluchino/composer-asset-plugin/) をインストールします。
これにより、Composer を通じて bower と npm の依存パッケージを管理することが出来るようになります。
このコマンドは一度だけ実行すれば十分です。
第二のコマンドは `basic` という名前のディレクトリに Yii をインストールします。
第二のコマンドは `basic` という名前のディレクトリに Yii の最新の安定版をインストールします。
必要なら別のディレクトリ名を選ぶことも出来ます。
> Note: インストール実行中に Composer が あなたの Github のログイン認証情報を求めることがあるかも知れません。
> これは、Comoser が依存パッケージの情報を Github から読み出すために十分な API レートを必要とするためで、普通にあることです。
> 詳細については、[Composer ドキュメント](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens) を参照してください。
> Info: `composer create-project` コマンドが失敗するときは、composer asset plugin が正しくインストール出来ているかどうかを確認して下さい。
> `composer global show` を実行することで確認することが出来ます。このコマンドの出力に `fxp/composer-asset-plugin` のエントリが含まれていなければなりません。.
> よくあるエラーについては、[Composer ドキュメントのトラブル・シューティングの節](https://getcomposer.org/doc/articles/troubleshooting.md)
> も参照して下さい。
> エラーを修正した後は、`basic` ディレクトリの中で `composer update` を実行して、中断されたインストールを再開することが出来ます。
> Tip: Yii の最新の開発バージョンをインストールしたい場合は、[stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability) を追加した次のコマンドを代りに使うことが出来ます。
>

1
docs/guide-ja/structure-entry-scripts.md

@ -61,6 +61,7 @@ $config = require(__DIR__ . '/../config/web.php');
*/
defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'dev');
// Composer のオートローダを登録
require(__DIR__ . '/vendor/autoload.php');

2
docs/guide-ja/structure-modules.md

@ -95,7 +95,7 @@ class PostController extends Controller
コントローラクラスの名前空間は、[[yii\base\Module::controllerNamespace]] プロパティを構成してカスタマイズすることが出来ます。
いくつかのコントローラがこの名前空間の外にある場合でも、[[yii\base\Module::controllerMap]] プロパティを構成することによって、それらをアクセス可能にすることが出来ます。
これは、[アプリケーションでのコントローラマップ](structure-applications.md#controller-map) の場合と同様です。
これは、[アプリケーションでのコントローラマップ](structure-applications.md#controllerMap) の場合と同様です。
### モジュール内のビュー <span id="views-in-modules"></span>

2
docs/guide-ja/structure-views.md

@ -587,7 +587,7 @@ $this->registerLinkTag([
<link title="Yii ライブニューズ" rel="alternate" type="application/rss+xml" href="http://www.yiiframework.com/rss.xml/">
```
[[yii\web\View::registerMetaTag()|registerMetaTags()]] と同じように、[[yii\web\View::registerLinkTag()|registerLinkTag()]] を呼ぶときにキーを指定すると、同じリンクタグを繰り返して生成するのを避けることが出来ます。
[[yii\web\View::registerMetaTag()|registerMetaTag()]] と同じように、[[yii\web\View::registerLinkTag()|registerLinkTag()]] を呼ぶときにキーを指定すると、同じリンクタグを繰り返して生成するのを避けることが出来ます。
## ビューのイベント <span id="view-events"></span>

4
docs/guide-ja/structure-widgets.md

@ -67,6 +67,10 @@ use yii\helpers\Html;
[[yii\base\Widget::widget()]] がウィジェットのレンダリング結果を返すのとは違って、[[yii\base\Widget::begin()]] メソッドがウィジェットのインスタンスを返すことに注意してください。
返されたウィジェットのインスタンスを使って、ウィジェットのコンテントを構築することが出来ます。
> Note: いくつかのウィジェットは、[[yii\base\Widget::end()]] が呼ばれるときに内包されるコンテンツを調整するため、[出力バッファリング](http://php.net/manual/ja/book.outcontrol.php) を使用します。
> この理由から、[[yii\base\Widget::begin()]] と [[yii\base\Widget::end()]] の呼び出しは、同じビューファイルの中で発生するものと想定されています。
> この規則に従わない場合は、予期しない出力結果が生じ得ます。
### グローバルなデフォルトを構成する

8
docs/guide-ja/test-fixtures.md

@ -307,7 +307,7 @@ yii fixture/load User
yii fixture User
// load several fixtures
yii fixture User UserProfile
yii fixture "User, UserProfile"
// load all fixtures
yii fixture/load "*"
@ -316,7 +316,7 @@ yii fixture/load "*"
yii fixture "*"
// load all fixtures except ones
yii fixture "*" -DoNotLoadThisOne
yii fixture "*, -DoNotLoadThisOne"
// load fixtures, but search them in different namespace. By default namespace is: tests\unit\fixtures.
yii fixture User --namespace='alias\my\custom\namespace'
@ -337,13 +337,13 @@ To unload fixture, run the following command:
yii fixture/unload User
// Unload several fixtures
yii fixture/unload User,UserProfile
yii fixture/unload "User, UserProfile"
// unload all fixtures
yii fixture/unload "*"
// unload all fixtures except ones
yii fixture/unload "*" -DoNotUnloadThisOne
yii fixture/unload "*, -DoNotUnloadThisOne"
```

2
docs/guide-ja/tutorial-start-from-scratch.md

@ -54,6 +54,6 @@ Yii の新しいプロジェクトテンプレートを作成するのに必要
これで、あなたのテンプレートを使ってプロジェクトを作成することが出来ます。
```
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist --stability=dev mysoft/yii2-app-coolone new-project
```

2
docs/guide-ja/tutorial-yii-integration.md

@ -77,7 +77,7 @@ Yii は数多くの優れた機能を提供していますので、サードパ
サードパーティのシステムが Composer を使って依存を管理している場合は、単に下記のコマンドを実行すれば Yii をインストールすることが出来ます。
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:~1.2.0"
composer require yiisoft/yii2
composer install

4
docs/guide-pl/start-installation.md

@ -36,7 +36,7 @@ Jeśli posiadałeś już wcześniej zainstalowanego Composera, upewnij się, że
Z zainstalowanym Composerem możesz przejść do instalacji Yii wywołując poniższe komendy w katalogu dostępnym z poziomu sieci web:
```bash
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
```
@ -221,4 +221,4 @@ server {
W przypadku użycia tej konfiguracji, powinienieś ustawić również `cgi.fix_pathinfo=0` w pliku `php.ini`, aby zapobiec wielu zbędnym wywołaniom 'stat()'.
Należy również pamiętać, że podczas pracy na serwerze HTTPS musisz dodać `fastcgi_param HTTPS on;`, aby Yii prawidłowo wykrywało, że połączenie jest bezpieczne.
Należy również pamiętać, że podczas pracy na serwerze HTTPS musisz dodać `fastcgi_param HTTPS on;`, aby Yii prawidłowo wykrywało, że połączenie jest bezpieczne.

2
docs/guide-pl/tutorial-start-from-scratch.md

@ -52,6 +52,6 @@ Użycie szablonu
Tylko tyle jest wymagane, aby stworzyć nowy szablon projektu Yii. Teraz już możesz rozpocząć pracę nad świeżym projektem, używając swojego szablonu, za pomocą komend:
```
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist --stability=dev mojafirma/yii2-app-fajna nowy-projekt
```

2
docs/guide-pt-BR/start-installation.md

@ -46,7 +46,7 @@ Você pode atualizar o Composer executando o comando `composer self-update`.
Com o Composer instalado, você pode instalar o Yii executando o seguinte comando
em um diretório acessível pela Web:
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
O primeiro comando instala o [composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin/)

2
docs/guide-pt-BR/tutorial-yii-integration.md

@ -66,7 +66,7 @@ Como o Yii fornece muitas características excelentes, algumas vezes você pode
Se o sistema em questão utilizar o Composer para gerenciar suas dependências, você pode simplesmente executar o seguinte comando para instalar o Yii:
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer require yiisoft/yii2
composer install

34
docs/guide-ru/db-migrations.md

@ -160,19 +160,19 @@ class m150101_185401_create_news_table extends Migration
Начиная с версии 2.0.7 появился удобный способ создания миграций из консоли.
В том случае, если миграция названа особым образом, таким как, например, `create_xxx` или `drop_xxx` сгенерированный
В том случае, если миграция названа особым образом, таким как, например, `create_xxx_table` или `drop_xxx_table` сгенерированный
файл миграции будет содержать дополнительный код.
### Создание таблицы
```php
yii migrate/create create_post
yii migrate/create create_post_table
```
сгенерирует
```php
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
public function up()
{
@ -191,13 +191,13 @@ class m150811_220037_create_post extends Migration
Чтобы сразу создать поля таблицы, укажите их через опцию `--fields`.
```php
yii migrate/create create_post --fields=title:string,body:text
yii migrate/create create_post_table --fields=title:string,body:text
```
сгенерирует
```php
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
public function up()
{
@ -218,13 +218,13 @@ class m150811_220037_create_post extends Migration
Можно указать дополнительные параметры.
```php
yii migrate/create create_post --fields=title:string(12):notNull:unique,body:text
yii migrate/create create_post_table --fields=title:string(12):notNull:unique,body:text
```
сгенерирует
```php
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
public function up()
{
@ -249,13 +249,13 @@ class m150811_220037_create_post extends Migration
### Удаление таблицы
```php
yii migrate/create drop_post --fields=title:string(12):notNull:unique,body:text
yii migrate/create drop_post_table --fields=title:string(12):notNull:unique,body:text
```
сгенерирует
```php
class m150811_220037_drop_post extends Migration
class m150811_220037_drop_post_table extends Migration
{
public function up()
{
@ -275,18 +275,18 @@ class m150811_220037_drop_post extends Migration
### Добавление столбца
Если имя миграции задано как `add_xxx_to_yyy`, файл будет содержать необходимые методы `addColumn` и `dropColumn`.
Если имя миграции задано как `add_xxx_column_to_yyy_table`, файл будет содержать необходимые методы `addColumn` и `dropColumn`.
Для добавления столбца:
```php
yii migrate/create add_position_to_post --fields=position:integer
yii migrate/create add_position_column_to_post_table --fields=position:integer
```
сгенерирует
```php
class m150811_220037_add_position_to_post extends Migration
class m150811_220037_add_position_column_to_post_table extends Migration
{
public function up()
{
@ -302,16 +302,16 @@ class m150811_220037_add_position_to_post extends Migration
### Удаление столбца
Если имя миграции задано как `drop_xxx_from_yyy`, файл будет содержать необходимые методы `addColumn` и `dropColumn`.
Если имя миграции задано как `drop_xxx_column_from_yyy_table`, файл будет содержать необходимые методы `addColumn` и `dropColumn`.
```php
yii migrate/create drop_position_from_post --fields=position:integer
yii migrate/create drop_position_column_from_post_table --fields=position:integer
```
сгенерирует
```php
class m150811_220037_drop_position_from_post extends Migration
class m150811_220037_drop_position_column_from_post_table extends Migration
{
public function up()
{
@ -327,10 +327,10 @@ class m150811_220037_drop_position_from_post extends Migration
### Добавление промежуточной таблицы
Если имя миграции задано как `create_junction_xxx_and_yyy`, файл будет содержать код для создания промежуточной таблцы.
Если имя миграции задано как `create_junction_table_for_xxx_and_yyy_tables`, файл будет содержать код для создания промежуточной таблцы.
```php
yii migrate/create create_junction_post_and_tag
yii migrate/create create_junction_table_for_post_and_tag_tables
```
сгенерирует

7
docs/guide-ru/helper-array.md

@ -280,10 +280,11 @@ $data = ArrayHelper::toArray($posts, [
## Проверка на присутствие в массиве <span id="testing-arrays"></span>
Часто необходимо проверить, содержится ли элемент в массиве, или является ли массив подмножеством другого массива.
К сожалению, PHP функция [[in_array()]] не поддерживает подмножества объектов, реализующих интерфейс `\Traversable`.
К сожалению, PHP функция `in_array()` не поддерживает подмножества объектов, реализующих интерфейс `\Traversable`.
Для таких случаев [[yii\base\ArrayHelper]] предоставляет [[yii\base\ArrayHelper::isIn()|isIn()]] и
[[yii\base\ArrayHelper::isSubset()|isSubset()]]. Методы принимают такие же параметры, что и [[in_array()]].
Для таких случаев [[yii\helpers\ArrayHelper]] предоставляет [[yii\helpers\ArrayHelper::isIn()|isIn()]] и
[[yii\helpers\ArrayHelper::isSubset()|isSubset()]]. Методы принимают такие же параметры, что и
[in_array()](http://php.net/manual/en/function.in-array.php).
```php
// true

2
docs/guide-ru/input-multiple-models.md

@ -52,7 +52,7 @@ class UserController extends Controller
}
```
В действии `update`, мы сначала загружаем из базы модели `$user` and `$profile`. Затем мы вызываем метод [[yii\base\Model::load()]]
В действии `update`, мы сначала загружаем из базы модели `$user` и `$profile`. Затем мы вызываем метод [[yii\base\Model::load()]]
для заполнения этих двух моделей данными, введенными пользователем. В случае успеха мы проверяем модели и сохраняем их. В противном случае
мы рендерим представление `update`, которое содержит следующий контент:

2
docs/guide-ru/output-sorting.md

@ -47,7 +47,7 @@ foreach ($models as $model) {
}
```
В примере выше, мы объявляем два атрибута, которые поддерживают сортировку: `name` and `age`.
В примере выше, мы объявляем два атрибута, которые поддерживают сортировку: `name` и `age`.
Мы передаем информацию о сортировке в запрос статьи, поэтому результаты запроса будут отсортированы
согласно сортировке, установленной в объекте Sort. В представлении, мы отображаем две ссылки,
которые ведут на страницы с данными, отсортированными по соответствующим атрибутам.

2
docs/guide-ru/output-theming.md

@ -5,7 +5,7 @@
замечательно подходит для изменения внешнего вида приложения.
Для того, чтобы начать использовать темизацию, настройте свойство [[yii\base\View::theme|theme]] компонента
приложения `view`. Конфигурация настраивает объект [[yii\base\Theme]], который отвечает за то, как как именно
приложения `view`. Конфигурация настраивает объект [[yii\base\Theme]], который отвечает за то, как именно
заменяются файлы отображений. Главным образом, стоит настроить следующие свойства [[yii\base\Theme]]:
- [[yii\base\Theme::basePath]]: базовая директория, в которой размещены темизированные ресурсы (CSS, JS, изображения,

2
docs/guide-ru/rest-resources.md

@ -19,7 +19,7 @@ RESTful API строятся вокруг доступа к *ресурсам*
## Поля <span id="fields"></span>
Когда ресурс включается в ответ RESTful API, необходимо серилеазовать его в строку. Yii разбивает этот процесс на два этапа.
Когда ресурс включается в ответ RESTful API, необходимо сериализовать его в строку. Yii разбивает этот процесс на два этапа.
Сначала ресурс конвертируется в массив при помощи [[yii\rest\Serializer]]. На втором этапе массив сериализуется в строку
заданного формата (например, JSON или XML) при помощи [[yii\web\ResponseFormatterInterface|форматтера ответа]].
Именно на этом стоит сосредоточится при разработке класса ресурса.

2
docs/guide-ru/start-installation.md

@ -30,7 +30,7 @@ mv composer.phar /usr/local/bin/composer
После установки Composer устанавливать Yii можно запустив следующую команду в папке доступной через веб:
```bash
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
```

2
docs/guide-ru/structure-applications.md

@ -589,7 +589,7 @@ $width = \Yii::$app->params['thumbnail.size'][0];
Когда [входной скрипт](structure-entry-scripts.md) выполняется для обработки запроса, приложение
будет развиваться согласно следующему жизненному циклу:
1. Входной скрипт загружает конфигурацию приложения в качества массива;
1. Входной скрипт загружает конфигурацию приложения в качестве массива;
2. Входной скрипт создаёт новый объект приложения:
* Вызывается метод [[yii\base\Application::preInit()|preInit()]], который настраивает некоторые
жизненно важные свойства приложения, такие как [[yii\base\Application::basePath|basePath]];

8
docs/guide-ru/test-fixtures.md

@ -312,7 +312,7 @@ yii fixture/load User
yii fixture User
// загрузить нескольких фикстур
yii fixture User UserProfile
yii fixture "User, UserProfile"
// загрузить все фикстуры
yii fixture/load "*"
@ -321,7 +321,7 @@ yii fixture/load "*"
yii fixture "*"
// загрузить все фикстуры кроме указанной
yii fixture "*" -DoNotLoadThisOne
yii fixture "*, -DoNotLoadThisOne"
// загрузка фикстур, но искать их следует в другом пространстве имен. Пространство имен по умолчанию: tests\unit\fixtures.
yii fixture User --namespace='alias\my\custom\namespace'
@ -342,13 +342,13 @@ yii fixture User --globalFixtures='some\name\space\Custom'
yii fixture/unload User
// выгрузить несколько фикстур
yii fixture/unload User,UserProfile
yii fixture/unload "User, UserProfile"
// выгрузить все фикстуры
yii fixture/unload "*"
// выгрузить все фикстуры за исключением указанной
yii fixture/unload "*" -DoNotUnloadThisOne
yii fixture/unload "*, -DoNotUnloadThisOne"
```

2
docs/guide-ru/tutorial-start-from-scratch.md

@ -46,6 +46,6 @@ git clone git@github.com:yiisoft/yii2-app-basic.git
Это все, что требуется для создания нового шаблона проекта в Yii. Сейчас вы можете создавать проекты, использующие ваш шаблон:
```
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist --stability=dev mysoft/yii2-app-coolone new-project
```

2
docs/guide-ru/tutorial-yii-integration.md

@ -63,7 +63,7 @@ Yii::$classMap['Class2'] = 'path/to/Class2.php';
Если сторонняя система использует для управления зависимостями Composer, Yii можно просто установить с помощью следующих команд:
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer require "yiisoft/yii2:*"
composer install

2
docs/guide-uk/start-installation.md

@ -40,7 +40,7 @@
Після встановлення Composer, встановити Yii можна виконавши наступну команду з директорії, яка доступна через Web:
```bash
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
```

4
docs/guide-uk/tutorial-start-from-scratch.md

@ -57,6 +57,6 @@ git clone git@github.com:yiisoft/yii2-app-basic.git
Тепер ви можете створювати проекти, використовуючи свій шаблон:
```
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist --stability=dev mysoft/yii2-app-coolone new-project
```
```

2
docs/guide-uk/tutorial-yii-integration.md

@ -84,7 +84,7 @@ Yii::$classMap['Class2'] = 'path/to/Class2.php';
Якщо стороння система використовує управління залежностями Composer, ви можете встановити Yii за допомогою наступних команд:
```bash
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer require yiisoft/yii2
composer install
```

2
docs/guide-vi/start-installation.md

@ -36,7 +36,7 @@ Nếu bạn đã cài Composer rồi, hãy chắc chắn rằng bạn đang sử
Sau khi cài đặt Composer, bạn có thể cài đặt Yii bằng cách chạy lệnh sau ở thư mục Web mà ứng dụng cần chạy:
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
Câu lệnh đầu tiên sẽ cài đặt [composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin/)

2
docs/guide-zh-CN/start-installation.md

@ -22,7 +22,7 @@
Composer 安装后,切换到一个可通过 Web 访问的目录,执行如下命令即可安装 Yii :
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
第一条命令安装 [Composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin/),它是通过 Composer 管理 bower 和 npm 包所必须的,此命令全局生效,一劳永逸。

4
docs/guide/caching-data.md

@ -89,7 +89,7 @@ Yii supports a wide range of cache storage. The following is a summary:
the corresponding cache component. In both cases, you may use the same code
`Yii::$app->cache->get($key)` to attempt retrieving data from the cache without worrying that
`Yii::$app->cache` might be `null`.
* [[yii\caching\FileCache]]: uses standard files to store cached data. This is particular suitable
* [[yii\caching\FileCache]]: uses standard files to store cached data. This is particularly suitable
to cache large chunk of data, such as page content.
* [[yii\caching\MemCache]]: uses PHP [memcache](http://php.net/manual/en/book.memcache.php)
and [memcached](http://php.net/manual/en/book.memcached.php) extensions. This option can be considered as
@ -227,7 +227,7 @@ $cache->set($key, $data, 30, $dependency);
// The cache will check if the data has expired.
// It will also check if the associated dependency was changed.
// It will return false if any of these conditions is met.
// It will return false if any of these conditions are met.
$data = $cache->get($key);
```

4
docs/guide/caching-page.md

@ -27,8 +27,8 @@ public function behaviors()
}
```
The above code states that page caching should be used only for the `index` action; the page content should
be cached for at most 60 seconds and should be variated by the current application language;
The above code states that page caching should be used only for the `index` action. The page content should
be cached for at most 60 seconds and should be variated by the current application language
and the cached page should be invalidated if the total number of posts is changed.
As you can see, page caching is very similar to [fragment caching](caching-fragment.md). They both support options such

2
docs/guide/concept-configurations.md

@ -224,7 +224,7 @@ the specified classes when they are being created using [[Yii::createObject()]].
can be specified by calling `Yii::$container->set()` in the [bootstrapping](runtime-bootstrapping.md) code.
For example, if you want to customize [[yii\widgets\LinkPager]] so that ALL link pagers will show at most 5 page buttons
(the default value is 10), you may use the following code to achieve this goal,
(the default value is 10), you may use the following code to achieve this goal:
```php
\Yii::$container->set(\yii\widgets\LinkPager::class, [

31
docs/guide/concept-di-container.md

@ -13,6 +13,7 @@ Yii provides the DI container feature through the class [[yii\di\Container]]. It
dependency injection:
* Constructor injection;
* Method injection;
* Setter and property injection;
* PHP callable injection;
@ -39,6 +40,36 @@ $foo = new Foo($bar);
```
### Method Injection <span id="method-injection"></span>
Usually the dependencies of a class are passed to the constructor and are available inside of the class during the whole lifecycle.
With Method Injection it is possible to provide a dependency that is only needed by a single method of the class
and passing it to the constructor may not be possible or may cause too much overhead in the majority of use cases.
A class method can be defined like the `doSomething()` method in the following example:
```php
class MyClass extends \yii\base\Component
{
public function __construct(/*Some lightweight dependencies here*/, $config = [])
{
// ...
}
public function doSomething($param1, \my\heavy\Dependency $something)
{
// do something with $something
}
}
```
You may call that method either by passing an instance of `\my\heavy\Dependency` yourself or using [[yii\di\Container::invoke()]] like the following:
```php
$obj = new MyClass(/*...*/);
Yii::$container->invoke([$obj, 'doSomething'], ['param1' => 42]); // $something will be provided by the DI container
```
### Setter and Property Injection <span id="setter-and-property-injection"></span>
Setter and property injection is supported through [configurations](concept-configurations.md).

46
docs/guide/db-migrations.md

@ -185,14 +185,14 @@ A list of all available methods for defining the column types is available in th
Since version 2.0.7 migration console provides a convenient way to create migrations.
If the migration name is of a special form, for example `create_xxx` or `drop_xxx` then the generated migration
If the migration name is of a special form, for example `create_xxx_table` or `drop_xxx_table` then the generated migration
file will contain extra code, in this case for creating/dropping tables.
In the following all variants of this feature are described.
### Create Table
```php
yii migrate/create create_post
yii migrate/create create_post_table
```
generates
@ -201,7 +201,7 @@ generates
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -226,7 +226,7 @@ class m150811_220037_create_post extends Migration
To create table fields right away, specify them via `--fields` option.
```php
yii migrate/create create_post --fields="title:string,body:text"
yii migrate/create create_post_table --fields="title:string,body:text"
```
generates
@ -235,7 +235,7 @@ generates
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -263,7 +263,7 @@ class m150811_220037_create_post extends Migration
You can specify more field parameters.
```php
yii migrate/create create_post --fields="title:string(12):notNull:unique,body:text"
yii migrate/create create_post_table --fields="title:string(12):notNull:unique,body:text"
```
generates
@ -272,7 +272,7 @@ generates
/**
* Handles the creation for table `post`.
*/
class m150811_220037_create_post extends Migration
class m150811_220037_create_post_table extends Migration
{
/**
* @inheritdoc
@ -304,7 +304,7 @@ class m150811_220037_create_post extends Migration
Since 2.0.8 the generator supports foreign keys using the `foreignKey` keyword.
```php
yii migrate/create create_post --fields="author_id:integer:notNull:foreignKey(user),category_id:integer:defaultValue(1):foreignKey,title:string,body:text"
yii migrate/create create_post_table --fields="author_id:integer:notNull:foreignKey(user),category_id:integer:defaultValue(1):foreignKey,title:string,body:text"
```
generates
@ -317,7 +317,7 @@ generates
* - `user`
* - `category`
*/
class m160328_040430_create_post extends Migration
class m160328_040430_create_post_table extends Migration
{
/**
* @inheritdoc
@ -422,13 +422,13 @@ column named `author_id` with a foreign key to the `user` table while
### Drop Table
```php
yii migrate/create drop_post --fields="title:string(12):notNull:unique,body:text"
yii migrate/create drop_post_table --fields="title:string(12):notNull:unique,body:text"
```
generates
```php
class m150811_220037_drop_post extends Migration
class m150811_220037_drop_post_table extends Migration
{
public function up()
{
@ -448,19 +448,19 @@ class m150811_220037_drop_post extends Migration
### Add Column
If the migration name is of the form `add_xxx_to_yyy` then the file content would contain `addColumn` and `dropColumn`
statements necessary.
If the migration name is of the form `add_xxx_column_to_yyy_table` then the file
content would contain `addColumn` and `dropColumn` statements necessary.
To add column:
```php
yii migrate/create add_position_to_post --fields="position:integer"
yii migrate/create add_position_column_to_post_table --fields="position:integer"
```
generates
```php
class m150811_220037_add_position_to_post extends Migration
class m150811_220037_add_position_column_to_post_table extends Migration
{
public function up()
{
@ -476,17 +476,17 @@ class m150811_220037_add_position_to_post extends Migration
### Drop Column
If the migration name is of the form `drop_xxx_from_yyy` then the file content would contain `addColumn` and `dropColumn`
statements necessary.
If the migration name is of the form `drop_xxx_column_from_yyy_table` then
the file content would contain `addColumn` and `dropColumn` statements necessary.
```php
yii migrate/create drop_position_from_post --fields="position:integer"
yii migrate/create drop_position_column_from_post_table --fields="position:integer"
```
generates
```php
class m150811_220037_drop_position_from_post extends Migration
class m150811_220037_drop_position_column_from_post_table extends Migration
{
public function up()
{
@ -502,11 +502,11 @@ class m150811_220037_drop_position_from_post extends Migration
### Add Junction Table
If the migration name is in if the form of `create_junction_xxx_and_yyy` then code necessary to create junction table
will be generated.
If the migration name is of the form `create_junction_table_for_xxx_and_yyy_tables` or `create_junction_xxx_and_yyy_tables`
then code necessary to create junction table will be generated.
```php
yii migrate/create create_junction_post_and_tag --fields="created_at:dateTime"
yii migrate/create create_junction_table_for_post_and_tag_tables --fields="created_at:dateTime"
```
generates
@ -519,7 +519,7 @@ generates
* - `post`
* - `tag`
*/
class m160328_041642_create_junction_post_and_tag extends Migration
class m160328_041642_create_junction_table_for_post_and_tag_tables extends Migration
{
/**
* @inheritdoc

87
docs/guide/helper-array.md

@ -209,7 +209,7 @@ $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:
@ -303,21 +303,68 @@ Encoding will use application charset and could be changed via third argument.
## Merging Arrays <span id="merging-arrays"></span>
You can use [[yii\helpers\ArrayHelper::merge()|ArrayHelper::merge()]] to merge 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()](http://php.net/manual/en/function.array-merge-recursive.php)).
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.
You can use [[yii\helpers\UnsetArrayValue]] object to unset value from previous array or
[[yii\helpers\ReplaceArrayValue]] to force replace former value instead of recursive merging.
For example:
```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)
$array1 = [
'name' => 'Yii',
'version' => '1.1',
'ids' => [
1,
],
'validDomains' => [
'example.com',
'www.example.com',
],
'emails' => [
'admin' => 'admin@example.com',
'dev' => 'dev@example.com',
],
];
$array2 = [
'version' => '2.0',
'ids' => [
2,
],
'validDomains' => new \yii\helpers\ReplaceArrayValue([
'yiiframework.com',
'www.yiiframework.com',
]),
'emails' => [
'dev' => new \yii\helpers\UnsetArrayValue(),
],
];
$result = ArrayHelper::merge($array1, $array2);
```
The result will be:
```php
[
'name' => 'Yii',
'version' => '2.0',
'ids' => [
1,
2,
],
'validDomains' => [
'yiiframework.com',
'www.yiiframework.com',
],
'emails' => [
'admin' => 'admin@example.com',
],
]
```
@ -371,16 +418,16 @@ It is possible to provide default way of converting object to array for a specif
Often you need to check if an element is in an array or a set of elements is a subset of another.
While PHP offers `in_array()`, this does not support subsets or `\Traversable` objects.
To aid these kinds of tests, [[yii\base\ArrayHelper]] provides [[yii\base\ArrayHelper::isIn()|isIn()]]
and [[yii\base\ArrayHelper::isSubset()|isSubset()]] with the same signature as [[in_array()]].
To aid these kinds of tests, [[yii\helpers\ArrayHelper]] provides [[yii\helpers\ArrayHelper::isIn()|isIn()]]
and [[yii\helpers\ArrayHelper::isSubset()|isSubset()]] with the same signature as
[in_array()](http://php.net/manual/en/function.in-array.php).
```php
// true
ArrayHelper::isIn('a', ['a']);
// true
ArrayHelper::isIn('a', new(ArrayObject['a']));
ArrayHelper::isIn('a', new ArrayObject(['a']));
// true
ArrayHelper::isSubset(new(ArrayObject['a', 'c']), new(ArrayObject['a', 'b', 'c'])
ArrayHelper::isSubset(new ArrayObject(['a', 'c']), new ArrayObject(['a', 'b', 'c']));
```

4
docs/guide/helper-html.md

@ -328,7 +328,7 @@ echo Html::getAttributeName('dates[0]');
## Styles and Scripts <span id="styles-and-scripts"></span>
There two methods to generate tags wrapping embedded styles and scripts:
There are two methods to generate tags wrapping embedded styles and scripts:
```php
<?= Html::style('.danger { color: #f00; }') ?>
@ -386,7 +386,7 @@ The first argument is the title. It's not encoded so if you're using data got fr
`Html::encode()`. Second argument is what will be in `href` of `<a` tag. See [Url::to()](helper-url.md) for details on
what values it accepts. Third argument is array of tag properties.
In you need to generate `mailto` link you can use the following code:
If you need to generate `mailto` link you can use the following code:
```php
<?= Html::mailto('Contact us', 'admin@example.com') ?>

10
docs/guide/input-multiple-models.md

@ -27,12 +27,16 @@ class UserController extends Controller
public function actionUpdate($id)
{
$user = User::findOne($id);
$profile = Profile::findOne($id);
if (!isset($user, $profile)) {
if (!$user) {
throw new NotFoundHttpException("The user was not found.");
}
$profile = Profile::findOne($user->profile_id);
if (!$profile) {
throw new NotFoundHttpException("The user has no profile.");
}
$user->scenario = 'update';
$profile->scenario = 'update';

2
docs/guide/intro-upgrade-from-v1.md

@ -471,7 +471,7 @@ Active Record Behaviors
In 2.0, we have dropped the base behavior class `CActiveRecordBehavior`. If you want to create an Active Record Behavior,
you will have to extend directly from `yii\base\Behavior`. If the behavior class needs to respond to some events
of the owner, you have to override the `events()` method like the following,
of the owner, you have to override the `events()` method like the following:
```php
namespace app\components;

2
docs/guide/rest-controllers.md

@ -82,7 +82,7 @@ than adding other filters described above, because the CORS filter has to be app
and thus needs a slightly different approach compared to other filters. Also authentication has to be disabled for the
[CORS Preflight requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Preflighted_requests)
so that a browser can safely determine whether a request can be made beforehand without the need for sending
authentication credentials. The follow code shows the code that is needed to add the [[yii\filters\Cors]] filter
authentication credentials. The following shows the code that is needed to add the [[yii\filters\Cors]] filter
to an existing controller that extends from [[yii\rest\ActiveController]]:
```php

8
docs/guide/rest-quick-start.md

@ -24,7 +24,7 @@ and you have already created the [active record](db-active-record.md) class `app
## Creating a Controller <span id="creating-controller"></span>
First, create a [controller](structure-controllers.md) class `app\controllers\UserController` as follows,
First, create a [controller](structure-controllers.md) class `app\controllers\UserController` as follows:
```php
namespace app\controllers;
@ -44,7 +44,7 @@ as `app\models\User`, the controller knows which model can be used for fetching
## Configuring URL Rules <span id="configuring-url-rules"></span>
Then, modify the configuration about the `urlManager` component in your application configuration:
Then, modify the configuration of the `urlManager` component in your application configuration:
```php
'urlManager' => [
@ -94,7 +94,7 @@ for accessing the user data. The APIs you have created include:
* `OPTIONS /users/123`: show the supported verbs regarding endpoint `/users/123`.
> Info: Yii will automatically pluralize controller names for use in endpoints.
> You can configure this using the [[yii\rest\UrlRule::$pluralize]]-property.
> You can configure this using the [[yii\rest\UrlRule::$pluralize]] property.
You may access your APIs with the `curl` command like the following,
@ -175,7 +175,7 @@ Content-Type: application/json; charset=UTF-8
> Tip: You may also access your APIs via Web browser by entering the URL `http://localhost/users`.
However, you may need some browser plugins to send specific request headers.
As you can see, in the response headers, there are information about the total count, page count, etc.
As you can see, in the response headers, there is information about the total count, page count, etc.
There are also links that allow you to navigate to other pages of data. For example, `http://localhost/users?page=2`
would give you the next page of the user data.

32
docs/guide/rest-response-formatting.md

@ -85,7 +85,7 @@ response format names which must be supported in [[yii\web\Response::formatters]
## Data Serializing <span id="data-serializing"></span>
As we have described above, [[yii\rest\Serializer]] is the central piece responsible for converting resource
objects or collections into arrays. It recognizes objects implementing [[yii\base\ArrayableInterface]] as
objects or collections into arrays. It recognizes objects implementing [[yii\base\Arrayable]] as
well as [[yii\data\DataProviderInterface]]. The former is mainly implemented by resource objects, while
the latter resource collections.
@ -155,3 +155,33 @@ Content-Type: application/json; charset=UTF-8
}
}
```
### Controlling JSON output
The JSON response is generated by the [[yii\web\JsonResponseFormatter|JsonResponseFormatter]] class which will
use the [[yii\helpers\Json|JSON helper]] internally. This formatter can be configured with different options like
for example the [[yii\web\JsonResponseFormatter::$prettyPrint|$prettyPrint]] option, which is useful on development for
better readable responses, or [[yii\web\JsonResponseFormatter::$encodeOptions|$encodeOptions]] to control the output
of the JSON encoding.
The formatter can be configured in the [[yii\web\Response::formatters|formatters]] property of the `response` application
component in the application [configuration](concept-configuration.md) like the following:
```php
'response' => [
// ...
'formatters' => [
\yii\web\Response::FORMAT_JSON => [
'class' => 'yii\web\JsonResponseFormatter',
'prettyPrint' => YII_DEBUG, // use "pretty" output in debug mode
'encodeOptions' => JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
// ...
],
],
],
```
When returning data from a database using the [DAO](db-dao.md) database layer all data will be represented
as strings, which is not always the expected result especially numeric values should be represented as
numbers in JSON. When using the ActiveRecord layer for retrieving data from the database, the values for numeric
columns will be converted to integers when data is fetched from the database in [[yii\db\ActiveRecord::populateRecord()]].

2
docs/guide/runtime-handling-errors.md

@ -157,7 +157,7 @@ the error action and the error view are already defined for you.
### Customizing Error Response Format <span id="error-format"></span>
The error handler displays errors according to the format setting of the [response](runtime-responses.md).
If the the [[yii\web\Response::format|response format]] is `html`, it will use the error or exception view
If the [[yii\web\Response::format|response format]] is `html`, it will use the error or exception view
to display errors, as described in the last subsection. For other response formats, the error handler will
assign the array representation of the exception to the [[yii\web\Response::data]] property which will then
be converted to different formats accordingly. For example, if the response format is `json`, you may see

39
docs/guide/start-installation.md

@ -5,7 +5,7 @@ You can install Yii in two ways, using the [Composer](https://getcomposer.org/)
The former is the preferred way, as it allows you to install new [extensions](structure-extensions.md) or update Yii by simply running a single command.
Standard installations of Yii result in both the framework and a project template being downloaded and installed.
A project template is a working Yii project implementing some basic features, such as login, contact form, etc.
A project template is a working Yii project implementing some basic features, such as login, contact form, etc.
Its code is organized in a recommended way. Therefore, it can serve as a good starting point for your projects.
In this and the next few sections, we will describe how to install Yii with the so-called *Basic Project Template* and
@ -21,6 +21,8 @@ to develop applications with multiple tiers.
Installing via Composer <span id="installing-via-composer"></span>
-----------------------
### Installing Composer
If you do not already have Composer installed, you may do so by following the instructions at
[getcomposer.org](https://getcomposer.org/download/). On Linux and Mac OS X, you'll run the following commands:
@ -31,26 +33,45 @@ mv composer.phar /usr/local/bin/composer
On Windows, you'll download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe).
Please refer to the [Composer Documentation](https://getcomposer.org/doc/) if you encounter any
problems or want to learn more about Composer usage.
Please refer to the [Troubleshooting section of the Composer Documentation](https://getcomposer.org/doc/articles/troubleshooting.md)
if you encounter any problems.
If you are new to Composer, we also recommend to read at least the [Basic usage section](https://getcomposer.org/doc/01-basic-usage.md)
of the Composer documentation.
In this guide all composer commands assume you have installed composer [globally](https://getcomposer.org/doc/00-intro.md#globally)
so that it is available as the `composer` command. If you are using the `composer.phar` in the local directory instead,
you have to adjust the example commands accordingly.
If you had Composer already installed before, make sure you use an up to date version. You can update Composer
by running `composer self-update`.
> Note: During the installation of Yii, Composer will need to request a lot of information from the Github API.
> The amount of requests depends on the number of dependencies your application has and may be bigger than the
> **Github API rate limit**. If you hit this limit, Composer may ask for your Github login credentials to obtain
> a Github API access token. On fast connections you may hit this limit earlier than Composer can handle so we
> recommend to configure the access token before installing Yii.
> Please refer to the [Composer documentation about Github API tokens](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
> for instructions on how to do this.
### Installing Yii
With Composer installed, you can install Yii by running the following commands under a Web-accessible folder:
```bash
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
```
The first command installs the [composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin/)
which allows managing bower and npm package dependencies through Composer. You only need to run this command
once for all. The second command installs Yii in a directory named `basic`. You can choose a different directory name if you want.
> Note: During the installation Composer may ask for your Github login credentials. This is normal because Composer
> needs to get enough API rate-limit to retrieve the dependent package information from Github. For more details,
> please refer to the [Composer documentation](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens).
once for all. The second command installs the latest stable version of Yii in a directory named `basic`.
You can choose a different directory name if you want.
> Info: If the `composer create-project` command fails make sure you have the composer asset plugin installed correctly.
> You can do that by running `composer global show`, which should contain an entry `fxp/composer-asset-plugin`.
> You may also refer to the [Troubleshooting section of the Composer Documentation](https://getcomposer.org/doc/articles/troubleshooting.md)
> for common errors. When you have fixed the error, you can resume the aborted installation
> by running `composer update` inside of the `basic` directory.
> Tip: If you want to install the latest development version of Yii, you may use the following command instead,
> which adds a [stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability):

2
docs/guide/structure-assets.md

@ -488,7 +488,7 @@ A Web page can include many CSS and/or JavaScript files. To reduce the number of
download size of these files, a common practice is to combine and compress multiple CSS/JavaScript files into
one or very few files, and then include these compressed files instead of the original ones in the Web pages.
> Info: Combining and compressing assets is usually needed when an application is in production mode.
> Info: Combining and compressing assets are usually needed when an application is in production mode.
In development mode, using the original CSS/JavaScript files is often more convenient for debugging purposes.
In the following, we introduce an approach to combine and compress asset files without the need to modify

4
docs/guide/structure-controllers.md

@ -57,8 +57,8 @@ according to the requested model ID; If the model is loaded successfully, it wil
a [view](structure-views.md) named `view`. Otherwise, it will throw an exception.
In the `create` action (defined by the `actionCreate()` method), the code is similar. It first tries to populate
the [model](structure-models.md) using the request data and save the model. If both succeed it will redirect
the browser to the `view` action with the ID of the newly created model. Otherwise it will display
a new instance of the [model](structure-models.md) using the request data and save the model. If both succeed it
will redirect the browser to the `view` action with the ID of the newly created model. Otherwise it will display
the `create` view through which users can provide the needed input.

1
docs/guide/structure-entry-scripts.md

@ -63,6 +63,7 @@ Similarly, the following is the code for the entry script of a console applicati
*/
defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'dev');
// register Composer autoloader
require(__DIR__ . '/vendor/autoload.php');

281
docs/guide/structure-modules.md

@ -1,281 +0,0 @@
Modules
=======
Modules are self-contained software units that consist of [models](structure-models.md), [views](structure-views.md),
[controllers](structure-controllers.md), and other supporting components. End users can access the controllers
of a module when it is installed in [application](structure-applications.md). For these reasons, modules are
often viewed as mini-applications. Modules differ from [applications](structure-applications.md) in that
modules cannot be deployed alone and must reside within applications.
## Creating Modules <span id="creating-modules"></span>
A module is organized as a directory which is called the [[yii\base\Module::basePath|base path]] of the module.
Within the directory, there are sub-directories, such as `controllers`, `models`, `views`, which hold controllers,
models, views, and other code, just like in an application. The following example shows the content within a module:
```
forum/
Module.php the module class file
controllers/ containing controller class files
DefaultController.php the default controller class file
models/ containing model class files
views/ containing controller view and layout files
layouts/ containing layout view files
default/ containing view files for DefaultController
index.php the index view file
```
### Module Classes <span id="module-classes"></span>
Each module should have a unique module class which extends from [[yii\base\Module]]. The class should be located
directly under the module's [[yii\base\Module::basePath|base path]] and should be [autoloadable](concept-autoloading.md).
When a module is being accessed, a single instance of the corresponding module class will be created.
Like [application instances](structure-applications.md), module instances are used to share data and components
for code within modules.
The following is an example how a module class may look like:
```php
namespace app\modules\forum;
class Module extends \yii\base\Module
{
public function init()
{
parent::init();
$this->params['foo'] = 'bar';
// ... other initialization code ...
}
}
```
If the `init()` method contains a lot of code initializing the module's properties, you may also save them in terms
of a [configuration](concept-configurations.md) and load it with the following code in `init()`:
```php
public function init()
{
parent::init();
// initialize the module with the configuration loaded from config.php
\Yii::configure($this, require(__DIR__ . '/config.php'));
}
```
where the configuration file `config.php` may contain the following content, similar to that in an
[application configuration](structure-applications.md#application-configurations).
```php
<?php
return [
'components' => [
// list of component configurations
],
'params' => [
// list of parameters
],
];
```
### Controllers in Modules <span id="controllers-in-modules"></span>
When creating controllers in a module, a convention is to put the controller classes under the `controllers`
sub-namespace of the namespace of the module class. This also means the controller class files should be
put in the `controllers` directory within the module's [[yii\base\Module::basePath|base path]].
For example, to create a `post` controller in the `forum` module shown in the last subsection, you should
declare the controller class like the following:
```php
namespace app\modules\forum\controllers;
use yii\web\Controller;
class PostController extends Controller
{
// ...
}
```
You may customize the namespace of controller classes by configuring the [[yii\base\Module::controllerNamespace]]
property. In case some of the controllers are outside of this namespace, you may make them accessible
by configuring the [[yii\base\Module::controllerMap]] property, similar to [what you do in an application](structure-applications.md#controller-map).
### Views in Modules <span id="views-in-modules"></span>
Views in a module should be put in the `views` directory within the module's [[yii\base\Module::basePath|base path]].
For views rendered by a controller in the module, they should be put under the directory `views/ControllerID`,
where `ControllerID` refers to the [controller ID](structure-controllers.md#routes). For example, if
the controller class is `PostController`, the directory would be `views/post` within the module's
[[yii\base\Module::basePath|base path]].
A module can specify a [layout](structure-views.md#layouts) that is applied to the views rendered by the module's
controllers. The layout should be put in the `views/layouts` directory by default, and you should configure
the [[yii\base\Module::layout]] property to point to the layout name. If you do not configure the `layout` property,
the application's layout will be used instead.
### Console commands in Modules <span id="console-commands-in-modules"></span>
Your module may also declare commands, that will be available through the [Console](tutorial-console.md) mode.
In order for the command line utility to see your commands, you will need to change the [[yii\base\Module::controllerNamespace]]
property, when Yii is executed in the console mode, and point it to your commands namespace.
One way to achieve that is to test the instance type of the Yii application in the module's `init` method:
```php
public function init()
{
parent::init();
if (Yii::$app instanceof \yii\console\Application) {
$this->controllerNamespace = 'app\modules\forum\commands';
}
}
```
Your commands will then be available from the command line using the following route:
```
yii <module_id>/<command>/<sub_command>
```
## Using Modules <span id="using-modules"></span>
To use a module in an application, simply configure the application by listing the module in
the [[yii\base\Application::modules|modules]] property of the application. The following code in the
[application configuration](structure-applications.md#application-configurations) uses the `forum` module:
```php
[
'modules' => [
'forum' => [
'class' => 'app\modules\forum\Module',
// ... other configurations for the module ...
],
],
]
```
The [[yii\base\Application::modules|modules]] property takes an array of module configurations. Each array key
represents a *module ID* which uniquely identifies the module among all modules in the application, and the corresponding
array value is a [configuration](concept-configurations.md) for creating the module.
### Routes <span id="routes"></span>
Like accessing controllers in an application, [routes](structure-controllers.md#routes) are used to address
controllers in a module. A route for a controller within a module must begin with the module ID followed by
the [controller ID](structure-controllers.md#controller-ids) and [action ID](structure-controllers.md#action-ids).
For example, if an application uses a module named `forum`, then the route
`forum/post/index` would represent the `index` action of the `post` controller in the module. If the route
only contains the module ID, then the [[yii\base\Module::defaultRoute]] property, which defaults to `default`,
will determine which controller/action should be used. This means a route `forum` would represent the `default`
controller in the `forum` module.
### Accessing Modules <span id="accessing-modules"></span>
Within a module, you may often need to get the instance of the [module class](#module-classes) so that you can
access the module ID, module parameters, module components, etc. You can do so by using the following statement:
```php
$module = MyModuleClass::getInstance();
```
where `MyModuleClass` refers to the name of the module class that you are interested in. The `getInstance()` method
will return the currently requested instance of the module class. If the module is not requested, the method will
return null. Note that you do not want to manually create a new instance of the module class because it will be
different from the one created by Yii in response to a request.
> Info: When developing a module, you should not assume the module will use a fixed ID. This is because a module
can be associated with an arbitrary ID when used in an application or within another module. In order to get
the module ID, you should use the above approach to get the module instance first, and then get the ID via
`$module->id`.
You may also access the instance of a module using the following approaches:
```php
// get the child module whose ID is "forum"
$module = \Yii::$app->getModule('forum');
// get the module to which the currently requested controller belongs
$module = \Yii::$app->controller->module;
```
The first approach is only useful when you know the module ID, while the second approach is best used when you
know about the controllers being requested.
Once you have the module instance, you can access parameters and components registered with the module. For example,
```php
$maxPostCount = $module->params['maxPostCount'];
```
### Bootstrapping Modules <span id="bootstrapping-modules"></span>
Some modules may need to be run for every request. The [[yii\debug\Module|debug]] module is such an example.
To do so, list the IDs of such modules in the [[yii\base\Application::bootstrap|bootstrap]] property of the application.
For example, the following application configuration makes sure the `debug` module is always loaded:
```php
[
'bootstrap' => [
'debug',
],
'modules' => [
'debug' => 'yii\debug\Module',
],
]
```
## Nested Modules <span id="nested-modules"></span>
Modules can be nested in unlimited levels. That is, a module can contain another module which can contain yet
another module. We call the former *parent module* while the latter *child module*. Child modules must be declared
in the [[yii\base\Module::modules|modules]] property of their parent modules. For example,
```php
namespace app\modules\forum;
class Module extends \yii\base\Module
{
public function init()
{
parent::init();
$this->modules = [
'admin' => [
// you should consider using a shorter namespace here!
'class' => 'app\modules\forum\modules\admin\Module',
],
];
}
}
```
For a controller within a nested module, its route should include the IDs of all its ancestor modules.
For example, the route `forum/admin/dashboard/index` represents the `index` action of the `dashboard` controller
in the `admin` module which is a child module of the `forum` module.
> Info: The [[yii\base\Module::getModule()|getModule()]] method only returns the child module directly belonging
to its parent. The [[yii\base\Application::loadedModules]] property keeps a list of loaded modules, including both
direct children and nested ones, indexed by their class names.
## Best Practices <span id="best-practices"></span>
Modules are best used in large applications whose features can be divided into several groups, each consisting of
a set of closely related features. Each such feature group can be developed as a module which is developed and
maintained by a specific developer or team.
Modules are also a good way of reusing code at the feature group level. Some commonly used features, such as
user management, comment management, can all be developed in terms of modules so that they can be reused easily
in future projects.

2
docs/guide/structure-views.md

@ -626,7 +626,7 @@ The code above will result in
<link title="Live News for Yii" rel="alternate" type="application/rss+xml" href="http://www.yiiframework.com/rss.xml/">
```
Similar as [[yii\web\View::registerMetaTag()|registerMetaTags()]], you can specify a key when calling
Similar as [[yii\web\View::registerMetaTag()|registerMetaTag()]], you can specify a key when calling
[[yii\web\View::registerLinkTag()|registerLinkTag()]] to avoid generating repeated link tags.

5
docs/guide/structure-widgets.md

@ -68,6 +68,11 @@ use yii\helpers\Html;
Note that unlike [[yii\base\Widget::widget()]] which returns the rendering result of a widget, the method
[[yii\base\Widget::begin()]] returns an instance of the widget which you can use to build the widget content.
> Note: Some widgets will use [output buffering](http://php.net/manual/en/book.outcontrol.php) to adjust the enclosed
> content when [[yii\base\Widget::end()]] is called. For this reason calling [[yii\base\Widget::begin()]] and
> [[yii\base\Widget::end()]] is expected to happen in the same view file.
> Not following this rule may result in unexpected output.
### Configuring global defaults

8
docs/guide/test-fixtures.md

@ -310,7 +310,7 @@ yii fixture/load User
yii fixture User
// load several fixtures
yii fixture User UserProfile
yii fixture "User, UserProfile"
// load all fixtures
yii fixture/load "*"
@ -319,7 +319,7 @@ yii fixture/load "*"
yii fixture "*"
// load all fixtures except ones
yii fixture "*" -DoNotLoadThisOne
yii fixture "*, -DoNotLoadThisOne"
// load fixtures, but search them in different namespace. By default namespace is: tests\unit\fixtures.
yii fixture User --namespace='alias\my\custom\namespace'
@ -340,13 +340,13 @@ To unload fixture, run the following command:
yii fixture/unload User
// Unload several fixtures
yii fixture/unload User,UserProfile
yii fixture/unload "User, UserProfile"
// unload all fixtures
yii fixture/unload "*"
// unload all fixtures except ones
yii fixture/unload "*" -DoNotUnloadThisOne
yii fixture/unload "*, -DoNotUnloadThisOne"
```

7
docs/guide/tutorial-i18n.md

@ -434,10 +434,11 @@ do not match either one of them. Following each possible parameter value, you sh
it in a pair of curly brackets.
### Specifying default translation <span id="default-translation"></span>
### Specifying default message source <span id="default-message-source"></span>
You can specify default translations that will be used as a fallback for categories that don't match any other translation.
This translation should be marked with `*`. In order to do it add the following to the application config:
You can specify default message source that will be used as a fallback for category that don't match any
configured category. You can do that by configuring a wildcard category `*`. In order to do that, add the following
to the application config:
```php
//configure i18n component

2
docs/guide/tutorial-performance-tuning.md

@ -138,7 +138,7 @@ If you have [Redis](http://redis.io/) on your server, it is highly recommended y
## Optimizing Databases <span id="optimizing-databases"></span>
Execute DB queries and fetching data from databases is often the main performance bottleneck in
Executing DB queries and fetching data from databases are often the main performance bottleneck in
a Web application. Although using [data caching](caching-data.md) techniques may alleviate the performance hit,
it does not fully solve the problem. When the database contains enormous amounts of data and the cached data is invalid,
fetching the latest data could be prohibitively expensive without proper database and query design.

2
docs/guide/tutorial-start-from-scratch.md

@ -50,6 +50,6 @@ Use the Template
That's all that's required to create a new Yii project template. Now you can create projects using your template:
```
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer create-project --prefer-dist --stability=dev mysoft/yii2-app-coolone new-project
```

2
docs/guide/tutorial-yii-integration.md

@ -82,7 +82,7 @@ take two steps: install Yii, and bootstrap Yii.
If the third-party system uses Composer to manage its dependencies, you can simply run the following commands
to install Yii:
composer global require "fxp/composer-asset-plugin:~1.1.1"
composer global require "fxp/composer-asset-plugin:^1.2.0"
composer require yiisoft/yii2
composer install

43
docs/internals-ja/README.md

@ -0,0 +1,43 @@
Yii 開発者ドキュメント
======================
このディレクトリは、Yii フレームワークの開発とリリースプロセスに関するドキュメントを含んでいます。
寄稿者のためのガイドライン
--------------------------
- [課題を報告する仕方](report-an-issue.md)
- [始めよう](getting-started.md)
- [Yii 2 寄稿者のための Git ワークフロー](git-workflow.md) - 開発環境をセットアップして Yii に対する寄稿を始めるためのステップバイステップのガイド。
- [Yii2 コアフレームワークコードスタイル](core-code-style.md)
- [Yii2 ビューコードスタイル](view-code-style.md)
ドキュメント
------------
- [翻訳ステータス](translation-status.md) - どのドキュメントが翻訳できる状態か。
- [翻訳チーム](translation-teams.md)
- [翻訳ワークフロー](translation-workflow.md)
フレームワーク開発
------------------
- [プルリクエストの品質保証](pull-request-qa.md)
- [自動化されるタスク](automation.md) コードスタイルの修正、ドキュメントやファイルの自動生成など。
- [設計上の決定](design-decisions.md) - よく議論される事柄についての FAQ 形式の声明リスト。
バージョニングとリリース
------------------------
- [プロジェクトの編成](project-organization.md)
- [Yii のバージョニング](versions.md)
- [新しいバージョンのリリース](release.md)
その他
------
### 例外の階層
![Yii フレームワークの例外階層](exception_hierarchy.png)

5
docs/internals-ja/automation.md

@ -13,3 +13,8 @@ Yii の開発に取り組む際に、自動化できるタスクがいくつか
`./build/build php-doc/fix` を実行して修正してください。
このコマンドは完璧なものではないため、望ましくない変更があるかもしれませんので、コミットする前に変更点をチェックしてください。
`git add -p` を使って変更をレビューすることが出来ます。
- Mime 型マジックファイル (`framework/helpers/mimeTypes.php`) の Apache HTTPd レポジトリによる更新。
`./build/build mime-type` を実行してファイルを更新して下さい。
上記のコマンドの全てが [release process]() に含まれています。これらをリリースの間に実行しても構いませんが、必要ではありません。

8
docs/internals-ja/core-code-style.md

@ -1,5 +1,5 @@
Yii2 コアフレームワークコードスタイル
=======================================
Yii2 コアフレームワークコードスタイル
=====================================
下記のコードスタイルが Yii 2.x コアと公式エクステンションの開発に用いられています。
コアに対してコードをプルリクエストをしたいときは、これを使用することを考慮してください。
@ -239,7 +239,7 @@ $arr = [
```php
$config = [
'name' => 'Yii',
'name' => 'Yii',
'options' => ['usePHP' => true],
];
```
@ -474,7 +474,7 @@ public function getEventHandlers($name)
- 定数へのアクセスには `self` を使わなければなりません: `self::MY_CONSTANT`
- private な静的プロパティへのアクセスには `self` を使わなければなりません: `self::$_events`
- 再帰呼出しにおいて、拡張クラスの実装ではなく、現在のクラスの実装を再び呼び出したいときには、`self` を使うことが許可されます。
- 再帰呼出しにおいて、拡張クラスの実装ではなく、現在のクラスの実装を再び呼び出したいときなど、合理的な理由がある場合には、`self` を使うことが許可されます。
### 「何かをするな」を示す値

BIN
docs/internals-ja/exception_hierarchy.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 63 KiB

BIN
docs/internals-ja/exception_hierarchy.vsd

Binary file not shown.

4
docs/internals-ja/git-workflow.md

@ -27,13 +27,13 @@ Yii をクローンしたディレクトリ、通常は "yii2" に入って、
git remote add upstream git://github.com/yiisoft/yii2.git
```
### 3. テスト環境を準備する
### 3. テスト環境を準備する <span id="prepare-the-test-environment"></span
以下のステップは、翻訳またはドキュメントだけに取り組みたい場合は、必要ではありません。
- `composer update` を実行して、依存パッケージをインストールします ([composer をグローバルにインストール](https://getcomposer.org/doc/00-intro.md#globally) したものと仮定しています)。
> Note: `Problem 1 The requested package bower-asset/jquery could not be found in any version, there may be a typo in the package name.` というようなエラーが生ずる場合は、`composer global require "fxp/composer-asset-plugin:~1.1.1"` を実行する必要があります。
> Note: `Problem 1 The requested package bower-asset/jquery could not be found in any version, there may be a typo in the package name.` というようなエラーが生ずる場合は、`composer global require "fxp/composer-asset-plugin:^1.2.0"` を実行する必要があります。
- `php build/build dev/app basic` を実行して、ベーシックアプリケーションをクローンし、その依存パッケージをインストールします。
このコマンドは外部 composer パッケージは通常どおりインストールしますが、yii2 レポジトリは現在チェックアウトされているものをリンクします。

33
docs/internals-ja/project-organization.md

@ -0,0 +1,33 @@
プロジェクトの編成
==================
このドキュメントは Yii2 開発レポジトリの編成を説明するものです。
1. 個々のコアエクステンションとアプリケーションテンプレートは、[yiisoft](https://github.com/yiisoft) Github オーガニゼーションの下の *独立した* 別の Github プロジェクトとして保守されます。
エクステンションのプロジェクト名は、先頭に `yii2-` を付けます。例えば、`gii` エクステンションは `yii2-gii` です。
Composer のパッケージ名は Github レポジトリ名と同じで、例えば `yiisoft/yii2-gii` です。
アプリケーションテンプレートのプロジェクト名は、先頭に `yii2-app-` を付けます。例えば、`basic` アプリケーションテンプレートは `yii2-app-basici` です。
Composer のパッケージ名は Github レポジトリ名と同じで、例えば `yiisoft/yii2-app-basic` です。
各々のエクステンション/アプリケーションのプロジェクトは、
* "docs" フォルダにおいてそのチュートリアルドキュメントを保守します。API ドキュメントは、エクステンション/アプリケーションがリリースされるときにその場で生成されます。
* "tests" フォルダにおいてそれ自身のテストコードを保守します。
* それ自身のメッセージ翻訳やその他全ての関係するメタコードを保守します。
* 対応する Github プロジェクトによって、課題 (issue) を追跡します。
エクステンションのレポジトリは、必要に応じて、個別にリリースされます。アプリケーションテンプレートはフレームワークとともにリリースされます。
詳細は [バージョンポリシー](versions.md) を参照して下さい。
2. `yiisoft/yii2` プロジェクトが、Yii2 フレームワーク開発のためのメインレポジトリです。
このレポジトリは Composer パッケージ [yiisoft/yii2-dev](https://packagist.org/packages/yiisoft/yii2-dev) を提供します。
これは、コアフレームワークコード、フレームワークの単体テスト、決定版ガイド、そして、フレームワーク開発とリリースのための一組のビルドツールを含んでいます。
コアフレームワークのバグと機能要望は、この Github プロジェクトのイッシュートラッカーによって追跡されます。
3. `yiisoft/yii2-framework` レポジトリは、開発プロジェクトレポジトリの `framework` ディレクトリのリードオンリーな git subsplit です。
このレポジトリが、フレームワークのインストールに使用される Composer 公式パッケージである [yiisoft/yii2](https://packagist.org/packages/yiisoft/yii2) を提供します。
4. 開発するときには、[build dev/app](git-workflow.md#prepare-the-test-environment) コマンドを使って、アプリケーションとエクステンションを開発プロジェクトの構成に含めることが出来ます。

6
docs/internals-ja/pull-request-qa.md

@ -1,10 +1,10 @@
プルリクエストの品質保証
========================
PR をマージるか否かをチェックするときには、特に以下の基準が考慮されるべきです。
PR をマージできるか否かをチェックするときには、特に以下の基準が考慮されるべきです。
- PR にリンクされている課題(イッシュー)が存在するか、または、PR がどのようなことを修正ないし追加しようとしているのかに関する十分な説明があること。
- 単体テスト。必須ではありませんが、非常に高く評価されます。PR によって修正されたコードが無ければ失敗する、というテストであること。
- CHANGELOG のエントリがあること。エントリは次のリリースのセクションに、イッシューのタイプと番号の順に書き入れます。
- 単体テスト。必須ではありませんが、大いに歓迎されます。PR によって修正されるコードが無ければ失敗する、というテストであること。
- CHANGELOG のエントリがあること。エントリは次のリリースのセクションに、課題のタイプと番号の順に書き入れます。
担当した者のニックネームがあること。
- [コードスタイル](core-code-style.md) および [ビューコードスタイル](view-code-style.md) が OK であること。これらは、マージされる際に、マージする者の判断に従って修正される場合があります。

79
docs/internals-ja/release.md

@ -0,0 +1,79 @@
新しいバージョンのリリース
==========================
フレームワークのリリースを作成するのに必要とされる手順のリストは、時とともに長くなり、手作業で管理するのが困難になっています。
そのため、どの手順も忘れられることが無いように、コマンドラインツールを作成しました。
リリースの手順の概要
--------------------
- ...
リリースコマンド
----------------
リリースの手順は、フレームワークの開発レポジトリに含まれている [release コンソールコマンド](../../build/controllers/ReleaseController.php) によって自動化されています。
リリースコマンドは、フレームワークの `build` ディレクトリに含まれている Yii アプリケーションを使って呼び出すことが出来ます。
./build/build help release # このコマンドをフレームワークのレポジトリのルートで実行します
> Info: コマンドを `--dryRun` オプションを付けて実行すると、どのようになるかを見ることが出来ます。
> このオプションを使うと、変更は何もなされず、どんなコミットやタグも生成されたり、プッシュされたりしません。
### 必要条件
リリースコマンドは、[Git ワークフローのドキュメント](git-workflow.md#extensions) で紹介されている開発環境に依存しています。
すなわち、アプリケーションテンプレートは `/apps/` の下に配置されていなければならず、
エクステンションは `/extensions/` の下に配置されていなければなりません。
この構成は `dev/app` および `dev/ext` のコマンドを使って作成することが推奨されます。
例えば、エクステンションのインストールは:
./build/build dev/ext authclient
アプリケーションは:
./build/build dev/app basic
このインストール方法によって、エクステンションが現在のレポジトリの状態と同じフレームワークコードを使用する事を保証することが出来ます。
### バージョンの概要
フレームワークとエクステンションのバージョンについて概要を把握したいときは、以下を実行することが出来ます。
./build/build release/info
全てのレポジトリのタグを取得するために `--update` を指定して実行し、最新の情報を取得することも出来ます。
### リリースを作成する
フレームワークのリリースの作成では、下記のコマンドの実行します (アプリケーションは常にフレームワークと一緒にリリースされます)。
./build release framework
./build release app-basic
./build release app-advanced
エクステンションのリリースの作成では、実行するコマンドは一つだけです (例えば、redis なら)
./build release redis
リリースコマンドは、デフォルトでは、現在チェックアウトされているブランチを元に新しいマイナーバージョンをリリースします。
デフォルトと異なるバージョンをリリースするためには、`--version` オプションを使ってバージョンを指定する必要があります。例えば、
`--version=2.1.0`, or `--version=2.1.0-beta`.
#### 新しいメジャーバージョン、例えば 2.1.0 をリリースする
新しいメジャーバージョンのリリースは、[バージョン規約](versions.md) で説明されているように、ブランチの変更を伴います。
以下は、`master` から派生した `2.1` ブランチ上で開発されている `2.1.0` バージョンをリリースする例を示すものです。
リリース前においては `master``2.0.x` の諸バージョンを含んでいます。
- `master` から新しいブランチ `2.0` を作成する
- composer.json がこのブランチに対するブランチエイリアスを含まないようにする
- 必要な変更を `master` から `2.1` にマージする
- `master``2.1` の最新のコミットを指すようにする
- composer.json のマスターに対するブランチエイリアスを `2.1.x-dev` とする
- `2.1` ブランチを削除する
`master` をチェックアウトし、`--version=2.1.0` オプションを付けて、リリースコマンドを実行する。

BIN
docs/internals-ja/schema-builder-patterns.xlsx

Binary file not shown.

4
docs/internals-ja/translation-status.md

@ -0,0 +1,4 @@
翻訳ステータス
==============
すべてのドキュメントが翻訳可能な状態です。

65
docs/internals-ja/translation-teams.md

@ -0,0 +1,65 @@
翻訳チーム
==========
ブラジルのポルトガル語
----------------------
- **Davidson Alencar, [@davidsonalencar](https://github.com/davidsonalencar), davidson.t.i@gmail.com**
- [@wbraganca](https://github.com/wbraganca)
- Alan Michel Willms Quinot, [@alanwillms](https://github.com/alanwillms), dyulax@gmail.com
中国語
------
- **Paris Qian Sen 东方孤思子,[@qiansen1386](https://github.com/qiansen1386),qiansen1386@gmail.com**
- [@AbrahamGreyson 刘阳](https://github.com/AbrahamGreyson)
- [@fmalee](https://github.com/fmalee)
- [@funson86 花生](https://github.com/funson86)
- [@ivantree 长兴苗木](https://github.com/ivantree)
- [@netyum 未来](https://github.com/netyum)
- [@riverlet 小河](https://github.com/riverlet)
- [@yiichina 巡洋舰](https://github.com/yiichina)
フィンランド語
--------------
- Jani Mikkonen, [@janisto](https://github.com/janisto), janisto@php.net
ドイツ語
--------
- Carsten Brandt, [@cebe](https://github.com/cebe), mail@cebe.cc
イタリア語
----------
- Lorenzo Milesi, [@maxxer](https://github.com/maxxer), maxxer@yetopen.it
日本語
------
- Nobuo Kihara 木原伸夫, [@softark](https://github.com/softark), softark@gmail.com
- Tomoki Morita, [@jamband](https://github.com/jamband), tmsongbooks215@gmail.com
- Hisateru Tanaka, [@tanakahisateru](https://github.com/tanakahisateru), tanakahisateru@gmail.com
ロシア語
--------
- **Alexander Makarov, [@samdark](https://github.com/samdark), sam@rmcreative.ru**
- [@MUTOgen](https://github.com/MUTOgen)
- [@prozacUa](https://github.com/prozacUa)
スペイン語
----------
- Luciano Baraglia, [@lucianobaraglia](https://github.com/lucianobaraglia)
- Marco Da Silva, [@markmarco16](https://github.com/markmarco16), markmarco16@gmail.com
- Daniel Gómez Pan [@pana1990](https://github.com/pana1990), pana_1990@hotmail.com
ウクライナ語
------------
- **Alexandr Bordun [@borales](https://github.com/Borales), admin@yiiframework.com.ua**
- Roman Bahatyi [@RichWeber](https://github.com/RichWeber), rbagatyi@gmail.com
- Igor Zozulinskyi [@3y3ik](https://github.com/3y3ik)
- Vadym Chenin [@vchenin](https://github.com/vchenin), vchenin@meta.ua

BIN
docs/internals-ja/versions-branches.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 813 KiB

82
docs/internals-ja/versions.md

@ -10,41 +10,77 @@ Yii バージョン規約
しかし、これは理想としての計画です。
ferver の記事は、Semantic Versioning を使おうが使うまいが、これが現実には達成が困難な計画であることを示す現実世界の実例を示しています。
要約すれば、私たちのバージョン付与ポリシーは次のようになります。
要約すれば、Yii 2 に対する私たちのバージョン付与ポリシーは次のようになります。
## バージョン番号
## パッチリリース `2.x.Y`
パッチリリースは、100% 後方互換であるべきです。
理想的には、互換性が損なわれる可能性を減らすために、バグ修正のみを含ませたいと私たちは望んでいます。
実際には、2.0.x はより頻繁にリリースされており、また、小さな機能改良をも追加して、ユーザが新機能をより早く享受できるようにしています。
* `2.x` という名前のブランチ上で保守される。
* 主としてバグ修正と小さな機能強化を含む。
* 大きな機能拡張はしない。
* 不安無しのアップグレードを保証するために、100% 後方互換でなければならない。唯一の例外はセキュリティ問題で、その場合は後方互換性が破られることもある。
* リリースのサイクルは1~2ヶ月程度。
* プレリリース (alpha, beta, RC) は不要。
* 定期的に (少なくとも週に一回は手作業で) マスターブランチにマージバックされるべき。
バージョン番号は `2.x.y.z` のフォーマットとします。ここで `z``0` であるリリースについては、`z` は省略可能です。
将来出るであろう Yii バージョン 3 については、1.0 に対する 2.0 のようなものになると予想されるので、ここでは言及しません。
このようなことは、外的な技術進歩 (たとえば PHP の 5.0 から 5.4 へのアップグレード) によって、3年から5年に一度しか生じないものと予期しています。
## マイナーリリース `2.X.0`
## `2.X.0`: メジャーリリース
後方互換性を損ないうる大きな機能と変更を含む非後方互換なリリース。
以前のバージョンからのアップグレードは簡単ではないかもしれないが、完全なアップグレードのガイド、または可能であればスクリプトが提供される
後方互換性を損ないうる大きな機能追加と変更を含む、非後方互換なリリースです。
以前のバージョンからのアップグレードは簡単ではないかも知れませんが、完全なアップグレードのガイドが提供されます。
* マスターブランチ上で開発。
* 主として新機能とバグ修正を含む。
* パッチリリースからマージされた小さな機能強化とバグ修正を含む。
* `UPGRADE-2.X.md` ファイルに記録される非後方互換な変更を含みうる。
* リリースのサイクルは6~8ヶ月程度
* リリースのサイクルはだいたい12ヶ月またはそれ以上
* プレリリースが必要: `2.X.0-alpha`, `2.X.0-beta`, `2.X.0-rc`
* 大きなニュースリリースとマーケティング努力を必要とする。
## `2.x.Y`: マイナーリリース
100% 後方互換であるべき、パッチリリースです。
理想的には、後方互換性を損なわない変更だけを含ませたいと私たちは望んでいます。
しかし、100% の後方互換性を常に保つことは不可能ですので、アップグレードに関するノートが `UPGRADE.md` に記録されます。
実際には、2.0.x はより頻繁にリリースされており、また、小さな機能改良をも追加して、ユーザが新機能をより早く享受できるようにしています。
* 主としてバグ修正と小さな機能強化を含む。
* 大きな機能拡張や修正はしない。
* 不安無しのアップグレードを保証するために、100% 後方互換でなければならない。ごく少数の例外は許容されるが、その場合は `UPGRADE.md` に記録される。
* リリースのサイクルは1~2ヶ月程度。
* プレリリース (alpha, beta, RC) は不要。
* 継続的に (少なくとも週に一回は手作業で) マスターブランチにマージバックされるべき。
* ニュースによる広報を伴う。プロジェクトサイトがアップデートされる。
### `2.x.y.Z`: パッチリリース
バグ修正のみを含む、100% 後方互換であるべき、パッチリリースです。
ニュースによる広報やプロジェクトサイトのアップデートはしません (ただし、重大な/セキュリティの問題についての修正を含む場合は、別です)。
このリリースのプロセスはほぼ自動的に実行されます。
* バグ修正のみを含む。機能追加はしない。
* 不安無しのアップグレードを保証するために、100% 後方互換でなければならない。唯一の例外はセキュリティ問題で、その場合は後方互換性が破られることもある。
* リリースのサイクルは1~2週間程度。
* プレリリース (alpha, beta, RC) は不要。
* リリース時にマスターブランチにマージバックされなければならない。
## ブランチ規約
* `master` ブランチは、現在の安定版メジャーリリースの開発ブランチで、現在は `2.0.x` バージョンです。
* 各メジャーリリースは、そのバージョン番号の名前を持つブランチ上で開発されます。例えば、`2.1`。
* メジャーリリース `2.n` の準備が出来たら、`master` から `2.(n-1).x` と名付けられた保守ブランチを作成します。
例えば、バージョン `2.1.0` が安定版としてリリースされ、`master` 上で開発されるようになると、`2.0` ブランチが作成されます。
([composer branch naming schema](https://getcomposer.org/doc/02-libraries.md#branches) を参照).
* パッチリリースをマークするために `2.x.y.z` というタグと `2.x.y` ブランチを作成します。`0` は省略されます。
* `2.n.x` 保守ブランチ上の変更は、継続的に `master` ブランチにマージバックされます。
次の図は、各ブランチ上でのコミット履歴の経時的な変化を説明したものです。
![ブランチ規約](versions-branches.png)
## メジャーリリース `X.0.0`
## リリース
1.0 に対する 2.0 など。
これは外部的な技術の進歩 (例えば、PHP が 5.0 から 5.4 へアップグレードされた、など) に依存して、3年から5年の間に一度だけ生じるものであると私たちは予想しています。
Yii 2 フレームワークと公式エクステンションのプロジェクトは、ともに、上述のバージョン規約およびブランチ規約に従います。
ただし、フレームワークと公式エクステンションのプロジェクトは、お互いに独立にリリースされます。
すなわち、すなわち、フレームワークとエクステンションの間で、バージョン番号が異なることが予想されます。
アプリケーションテンプレートは、常に、フレームワークと同時にリリースされます。
> Note: 公式エクステンションも同じバージョン付与ポリシーに従っていますが、フレームワークとは独立にリリースされることがあります。
すなわち、フレームワークとエクステンションの間で、バージョン番号が異なることが予想されます。
上記で説明されたリリースサイクルは、コアフレームワークにのみ適用されます。
エクステンションは必要に応じてリリースされます。
エクステンションは、何らバグ修正や機能拡張を受けずに、長期間にわたって新しいリリースを持たないことがあり得ます。

4
docs/internals-ja/view-code-style.md

@ -1,5 +1,5 @@
Yii2 ビューコードスタイル
===========================
Yii2 ビューコードスタイル
=========================
下記のコードスタイルが Yii 2.x コアと公式エクステンションのビューファイルに用いられています。
私たちは、あなたが自分のアプリケーションにこのコードスタイルを使うことを強制するものではありません。

2
docs/internals-ru/git-workflow.md

@ -36,7 +36,7 @@ git remote add upstream git://github.com/yiisoft/yii2.git
- выполните `composer update` для установки зависимостей (если [composer у вас установлен глобально](https://getcomposer.org/doc/00-intro.md#globally)).
> Note: Если вы видите такие ошибки, как `Problem 1 The requested package bower-asset/jquery could not be found in
> any version, there may be a typo in the package name.`, необходимо запустить `composer global require "fxp/composer-asset-plugin:~1.1.1"`
> any version, there may be a typo in the package name.`, необходимо запустить `composer global require "fxp/composer-asset-plugin:^1.2.0"`
- выполните `php build/build dev/app basic` для клонирования базового приложения и установки его зависимостей.
Эта команда установит сторонние пакеты composer обычным образом, но создаст ссылку с репозитория yii2 на только

5
docs/internals-sr-Latn/automation.md

@ -12,4 +12,7 @@ Postoje taskovi koji se rade automatski kada radite sa Yii frejmvorkom:
- Ispravljanje stila pisanja koda i ostalih sitnijih problema u phpdoc komentarima.
Pokrenite `./build/build php-doc/fix` kako bi ih ispravili.
Proverite izmene pre njihovog komitovanja zato što se mogu desiti neželjene promene zato što komanda nije idealna.
Možete koristiti `git add -p` kako bi pregledali izmene.
Možete koristiti `git add -p` kako bi pregledali izmene.
- Ažuriranje Mime Type Magic fajla (`framework/helpers/mimeTypes.php`) iz Apache HTTPd repozitorijuma.
Pokrenite `./build/build mime-type` kako bi ažurirali falj.

50
docs/internals-sr-Latn/git-workflow.md

@ -12,7 +12,7 @@ Pripremite vaše razvojno okruženje
Sledeći koraci će napraviti razvojno okruženje za Yii, koje možete koristiti kako bi radili
na baznom kodu Yii frejmvorka. Ovi se koraci trebaju uraditi samo jednom.
### 1. [Forkujte](http://help.github.com/fork-a-repo/) Yii repozitorijum na GitHub-u i klonirajte vaš fork na vešem razvojnom okruženju
### 1. [Forkujte](http://help.github.com/fork-a-repo/) Yii repozitorijum na GitHub-u i klonirajte vaš fork na vašem razvojnom okruženju
```
git clone git@github.com:VASE-GITHUB-KORISNICKO-IME/yii2.git
@ -34,8 +34,8 @@ git remote add upstream git://github.com/yiisoft/yii2.git
Sledeći koraci nisu neophodni ako želite da radite samo na prevodima i dokumentaciji.
- pokrenite `composer update` kako bi instalirali neophodne pakete (podrazumeva se da imate [composer instaliran globalno](https://getcomposer.org/doc/00-intro.md#globally)).
- pokrenite `php build/build dev/app basic` kako bi klonirali "basic" aplikaciju i instalirali composer neophonde pakete "basic" aplikacije.
Ova komanda će instlirati spoljne composer pakete i ulinkovati yii2 repozitorujum sa trenutnim preuzetim repozitorijumom, tako da imate samo jednu instancu celog instaliranog koda.
- pokrenite `php build/build dev/app basic` kako bi klonirali "basic" aplikaciju i instalirali composer neophodne pakete "basic" aplikacije.
Ova komanda će instalirati spoljne composer pakete i ulinkovati yii2 repozitorujum sa trenutnim preuzetim repozitorijumom, tako da imate samo jednu instancu celog instaliranog koda.
Ponovite postupak za "advanced" aplikaciju ako je potrebno, pokretanjem: `php build/build dev/app advanced`.
@ -47,9 +47,9 @@ Sledeći koraci su neobavezni.
### Unit testovi
Možete izvršiti unit testove pokretanjem `phpunit` unutr root direktorijuma repozitorijuma. Ako nemate phpunit instaliran globalno možete pokrenuti `php vendor/bin/phpunit` umesto toga.
Možete izvršiti unit testove pokretanjem `phpunit` unutar root direktorijuma repozitorijuma. Ako nemate phpunit instaliran globalno možete pokrenuti `php vendor/bin/phpunit` umesto toga.
Neki testovi zahtevaju dodatne baze podataka da budu postavljene i podešene. Možete napraviti `tests/data/config.local.php` fajl kako bi pregazili podešavanja koja su definisana unutar `tests/data/config.php` fajla.
Neki testovi zahtevaju dodatne baze podataka da budu postavljene i podešene. Možete napraviti `tests/data/config.local.php` fajl kako bi pregazili podešavanja koja su definisana unutar `tests/data/config.php` fajla.
Možete ograničiti testove na grupu testova na kojima radite, na primer, da pokrenete testove za samo validaciju i redis koristite `phpunit --group=validators,redis`. Listu dostupnih grupa možete dobiti pokretanjem `phpunit --list-groups`.
@ -64,7 +64,7 @@ php build/build dev/ext <extension-name>
gde je `<extension-name>` ime ekstenzije, na primer `redis`.
Ako želite da testirate ekstenziju u jednom od aplikacijskih šablona, samo dodajte repozitorijum u `composer.json` aplikacije kao što bi to radili normalno, na primer dodali bi `"yiisoft/yii2-redis": "*"` unutar`require` sekcije za "basic" aplikaciju.
Pokretanjem `php build/build dev/app basic` ćete instalirati ekstenziju i njene neophonde pakete i ulinkovaće se `extensions/redis` direktorijum kako ne bi radili u vendor direktorijumu nego u yii2 repozitorijumu direktno.
Pokretanjem `php build/build dev/app basic` ćete instalirati ekstenziju i njene neophodne pakete i ulinkovaće se `extensions/redis` direktorijum kako ne bi radili u vendor direktorijumu nego u yii2 repozitorijumu direktno.
Rad na bagovima i poboljšanjima
@ -74,10 +74,10 @@ Pošto je razvojno okruženje spremno kako je objašnjeno iznad možete započet
### 1. Postarajte se da je problem prijavljen za bug na kom radite ako zahteva značajniji rad na ispravljanju
Sve nove funkcionalnosti i bugovi bi trebali imati povezanu temu koju bi koristili kao jedinstvenu tačku za diskusiju i dokumentaciju. Bacite pogled na postojeću listu koja ima temu koja se poklapa sa onim na čemu bi želeli da radite. Ako pronađete da tema već postoji u listi, onda ostavite komentar na toj temi u kome iskažite da želite da radite na tome. Ako ne pronađete postojeću temu/problem koja se poklapa sa onim na čemu bi želeli da radite, molimo da [postavite temu/prijavite problem](report-an-issue.md) ili napravite pull zahtev direktno ako nije komplikovano rešenje. Na ovaj način, tim će moći da pogleda vaše rešenje i uputi vas sa dodatno.
Sve nove funkcionalnosti i bugovi bi trebali imati povezanu temu koju bi koristili kao jedinstvenu tačku za diskusiju i dokumentaciju. Bacite pogled na postojeću listu koja ima temu koja se poklapa sa onim na čemu bi želeli da radite. Ako pronađete da tema već postoji u listi, onda ostavite komentar na toj temi u kome iskažite da želite da radite na tome. Ako ne pronađete postojeću temu/problem koja se poklapa sa onim na čemu bi želeli da radite, molimo da [postavite temu/prijavite problem](report-an-issue.md) ili napravite pull zahtev direktno ako nije komplikovano rešenje. Na ovaj način, tim će moći da pogleda vaše rešenje i dodatno vas uputi.
> Za site izmene ili dokumentacijske probleme ili za jednostavnije probleme, nije potrebno praviti posebnu temu, pull zahtev je više nego dovoljan u ovom slučaju.
> Za sitne izmene ili dokumentacijske probleme ili za jednostavnije probleme, nije potrebno praviti posebnu temu, pull zahtev je više nego dovoljan u ovom slučaju.
### 2. Dohvatite poslednji kod sa glavne Yii grane
@ -95,7 +95,7 @@ Svako posebno rešenje baga ili izmena bi trebala da se nalazi u svojoj posebnoj
```
git checkout upstream/master
git checkout -b 999-name-of-your-branch-goes-here
git checkout -b 999-IME-VASE-GRANE
```
### 4. Bacite se na posao, napišite vaš kod
@ -103,19 +103,19 @@ git checkout -b 999-name-of-your-branch-goes-here
Potrudite se da funkcioniše :)
Unit testovi su uvek dobrodošli. Testiranje i dobro pokriven kod značajno pojednostavljuje proveru koda.
Neuspeli unit testovi kao opis teme su takođe prihvataju.
Neuspeli unit testovi kao opis teme se takođe prihvataju.
### 5. Izmenite CHANGELOG
Izmenite CHANGELOG fajl kako bi uključili vašu izmenu, trebali bi uneti je na vrhu fajla ispod "Work in progress" naslova, linija u CHNAGELOG fajlu bi trebalo da izgleda nešto nalik sledećem:
Izmenite CHANGELOG fajl kako bi uključili vašu izmenu, trebali bi je uneti na vrhu fajla ispod "Work in progress" naslova, linija u CHNAGELOG fajlu bi trebalo da izgleda nešto nalik sledećem:
```
Bug #999: a description of the bug fix (Your Name)
Enh #999: a description of the enhancement (Your Name)
Bug #999: opis vaše ispravke (vaše ime)
Enh #999: opis vašeg poboljšanja (vaše ime)
```
`#999` je broj teme na koju se `Bug` ili `Enh`odnosi.
CHANGELOG no trebao biti grupisan po tipu (`Bug`,`Enh`) i sortiran po broju teme.
`#999` je broj teme na koju se `Bug` ili `Enh` odnosi.
CHANGELOG bi trebao biti grupisan po tipu (`Bug`,`Enh`) i sortiran po broju teme.
Za veoma male izmene, na primer, greške u tekstu, izmene na dokumentaciji, nije potrebno menjati CHANGELOG.
@ -129,10 +129,10 @@ git add path/to/my/file.php
Možete koristit `-p` opciju kako bi izabrali izmene koje želite da komitujete.
Komitujte vaše izmene sa opisnom porukom komita. Potrudite se napomente broj teme sa `#XXX` kako bi GitHub automatski ulinkovao vaš komit sa temom:
Komitujte vaše izmene sa opisnom porukom komita. Potrudite se da napomente broj teme sa `#XXX` kako bi GitHub automatski ulinkovao vaš komit sa temom:
```
git commit -m "A brief description of this change which fixes #999 goes here"
git commit -m "Ovde napišite kratak opis promene koja ispravlja #999"
```
### 7. Preuzmite poslednji Yii kod sa upstream-a u vašu granu
@ -146,7 +146,7 @@ Ovo nas osigurava da imamo poslednji kod u vašoj lokalnoj grani pre nego naprav
### 8. Nakon razrešenih svih konflikata, postavite vaš kod na GitHub
```
git push -u origin 999-name-of-your-branch-goes-here
git push -u origin 999-IME-VASE-GRANE
```
Parametar `-u` će osigurati da će vaša grana moći da šalje pull i push zahteve sa GitHub grane. To znači da ako pozovete `git push` sledeći put će znati gde treba kod da se pošalje. Ovo je korisno ako budete hteli da kasnije dodate više komitova u jednom pull zahtevu.
@ -167,8 +167,8 @@ Nakom što je vaš kod ili prihvaćen ili odbijen možete obrisati vaše grane n
```
git checkout master
git branch -D 999-name-of-your-branch-goes-here
git push origin --delete 999-name-of-your-branch-goes-here
git branch -D 999-IME-VASE-GRANE
git push origin --delete 999-IME-VASE-GRANE
```
### Napomena:
@ -180,24 +180,24 @@ Kako bi rano otkrili regresije u Yii kodu prilikom svake integracije na GitHub-u
* osvežava dokumentaciju,
* menja samo fiksne stringove (npr. izmene u prevodu)
Na ovaj način će travi započinjati testiranje samo izmena koje nisu prvenstveno pokrivene testovima.
Na ovaj način će Travis započinjati testiranje samo izmena koje nisu prvenstveno pokrivene testovima.
### Pregled komandi (za napredne saradnike)
```
git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git
git clone git@github.com:VASE-GITHUB-KORISNICKO-IME/yii2.git
git remote add upstream git://github.com/yiisoft/yii2.git
```
```
git fetch upstream
git checkout upstream/master
git checkout -b 999-name-of-your-branch-goes-here
git checkout -b 999-IME-VASE-GRANE
/* bacite se na posao, izmenite changelog ako je potrebno */
git add path/to/my/file.php
git commit -m "A brief description of this change which fixes #999 goes here"
git commit -m "Ovde napišite kratak opis promene koja ispravlja #999"
git pull upstream master
git push -u origin 999-name-of-your-branch-goes-here
git push -u origin 999-IME-VASE-GRANE
```

2
docs/internals-sr-Latn/report-an-issue.md

@ -1,4 +1,4 @@
Prijavite Problem
Prijavite problem
=================
Molimo da ispratite smernice ispod kada prijavljujete problem kako bi vaš problem bio što pre razrešen:

Some files were not shown because too many files have changed in this diff Show More

Loading…
Cancel
Save