',
'route' => 'post/index',
'defaults' => ['page' => 1],
]
```
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, reportez-vous à la section [Utiliser Yii 1.1 et 2.0 ensemble](tutorial-yii-integration.md).
================================================
FILE: docs/guide-fr/intro-yii.md
================================================
Qu'est ce que Yii ?
=================
Yii est un framework PHP hautes performances à base de composants qui permet de développer rapidement des applications Web modernes.
Le nom Yii (prononcer `Yee` ou `[ji:]`) signifie "simple et évolutif" en Chinois. Il peut également
être considéré comme un acronyme de **Yes It Is**!
Pour quel usage Yii est il optimal ?
-----------------------------------
Yii est un framework Web générique, c'est à dire qu'il peut être utilisé pour développer tous types
d'applications Web basées sur PHP. De par son architecture à base de composants et son système de cache sophistiqué,
il est particulièrement adapté au développement d'applications à forte audience telles que des portails, des forums,
des systèmes de gestion de contenu (CMS), des sites e-commerce, des services Web RESTFul, etc.
Comment se positionne Yii vis-à-vis des autres Frameworks ?
----------------------------------------------------------
- Comme la plupart des frameworks PHP, Yii est basé sur le modèle de conception MVC (Modèle-Vue-Contrôleur) et encourage à une
organisation du code basée sur ce modèle.
- Yii repose sur l'idée que le code doit être écrit de façon simple et élégante. Il ne sera jamais question de
compliquer le code de Yii uniquement pour respecter un modèle de conception.
- Yii est un framework complet offrant de nombreuses caractéristiques éprouvées et prêtes à l'emploi, telles que:
constructeur de requêtes et ActiveRecord, à la fois pour les bases de données relationnelles et NoSQL; prise en charge RESTful API;
prise en charge de caches multi-niveaux; et plus.
- Yii est extrêmement flexible. Vous pouvez personnaliser ou remplacer presque chaque partie du code du noyau. Vous pouvez également
profiter de son architecture extensible solide, afin d'utiliser ou développer des extensions distribuables.
- La haute performance est toujours un des principaux objectifs de Yii.
Yii n'est pas un one-man show, il est soutenu par une [solide équipe de développement du noyau][yii_team] ainsi que d'une grande communauté
avec de nombreux professionnels qui contribuent constamment au développement de Yii. L'équipe de développeurs de Yii
garde un œil attentif sur les dernières tendances en développement Web, et sur les meilleures pratiques et caractéristiques
trouvées dans d'autres frameworks ou projets. Les meilleures pratiques et caractéristiques les plus pertinentes trouvées ailleurs sont régulièrement intégrées dans le code du noyau et utilisables
via des interfaces simples et élégantes.
[yii_team]: https://www.yiiframework.com/team
Versions de Yii
---------------
Yii est actuellement disponible en deux versions majeures : 1.1 et 2.0. La version 1.1, l'ancienne génération, est désormais en mode maintenance. La version 2.0 est une réécriture complète de Yii, adoptant les dernières technologies et protocoles, y compris Composer, PSR, les espaces de noms, les traits, et ainsi de suite. La version 2.0 est la dernière génération du framework et recevra nos principaux efforts de développement dans les prochaines années.
Ce guide est principalement pour la version 2.0.
Configuration nécessaire
------------------------
Yii 2.0 nécessite PHP 7.4.0 ou plus. Vous pouvez trouver plus de détails sur la configuration requise pour chaque fonctionnalité
en utilisant le script de test de la configuration inclus dans chaque distribution de Yii.
Utiliser Yii requiert des connaissances de base sur la programmation objet (OOP), en effet Yii est un framework basé sur ce type de programmation.
Yii 2.0 utilise aussi des fonctionnalités récentes de PHP, telles que les [espaces de noms](https://www.php.net/manual/fr/language.namespaces.php) et les [traits](https://www.php.net/manual/fr/language.oop5.traits.php).
Comprendre ces concepts vous aidera à mieux prendre en main Yii.
================================================
FILE: docs/guide-fr/output-client-scripts.md
================================================
Travail avec des scripts clients
===================================
> Note: cette section est encore en développement.
### Enregistrement des scripts
Avec l'objet [[yii\web\View]] vous êtes en mesure d'enregistrer des scripts. Il existe deux méthodes dédiées pour cela :
[[yii\web\View::registerJs()|registerJs()]] pour les scripts en ligne et [[yii\web\View::registerJsFile()|registerJsFile()]] pour les scripts externes.
Les scripts en ligne sont utiles pour la configuration et le code généré dynamiquement. La méthode pour les ajouter est la suivante :
```php
$this->registerJs("var options = ".json_encode($options).";", View::POS_END, 'my-options');
```
Le premier argument est le code JS réel à insérer dans la page. Le deuxième argument détermine à quel endroit le script doit être inséré dans la page. Les valeurs possibles sont :
- [[yii\web\View::POS_HEAD|View::POS_HEAD]] pour le placer dans la section d'entête (``).
- [[yii\web\View::POS_BEGIN|View::POS_BEGIN]] pour le placer juste après la balise d'ouverture du corps de la page (``).
- [[yii\web\View::POS_END|View::POS_END]] pour le placer juste avant la balise de fermeture du corps de la page (``).
- [[yii\web\View::POS_READY|View::POS_READY]] pour l'exéuter sur l'événement « document `ready` ». Cela enregistre [[yii\web\JqueryAsset|jQuery]] automatiquement.
- [[yii\web\View::POS_LOAD|View::POS_LOAD]] pour l'exécuter sur l'événement « document `load` » . Cela enregistre [[yii\web\JqueryAsset|jQuery]] automatiquement.
Le dernier argument est un identifiant unique du script utilisé pour identifier le bloc de code et remplacer un bloc existant de même identifiant au lieu de simplement l'ajouter. Si vous ne le fournissez pas, le code JS lui-même est utilisé en tant qu'identifiant.
Un script externe peut être ajouté comme expliqué ci-dessous :
```php
$this->registerJsFile('https://example.com/js/main.js', ['depends' => [\yii\web\JqueryAsset::class]]);
```
Les arguments pour [[yii\web\View::registerJsFile()|registerJsFile()]] sont semblables à ceux utilisés pour [[yii\web\View::registerCssFile()|registerCssFile()]]. Dans l'exemple précédent, nous enregistrons le fichier `main.js` avec une dépendance sur `JqueryAsset`. Cela siginifie que le fichier `main.js` sera ajouté APRÈS `jquery.js`. Sans la spécification de cette dépendance, l'ordre relatif entre `main.js` et `jquery.js` resterait indéfini.
Comme pour [[yii\web\View::registerCssFile()|registerCssFile()]], il est également fortement recommandé que vous utilisiez les [paquets de ressources](structure-assets.md) (asset bundles) pour enregistrer des fichiers JS externes plutôt que d'utiliser [[yii\web\View::registerJsFile()|registerJsFile()]].
### Enregistrement de paquets de ressources
Comme cela a été mentionné plus tôt, il est préférable d'utiliser des paquets de ressources plutôt que d'utiliser CSS et JavaScript directement. Vous pouvez obtenir des détails sur les paquets de ressources dans la section [Ressources](structure-assets.md) de ce guide. Comme lors de l'utilisation des paquets de ressources déjà définis, c'est très simple :
```php
\frontend\assets\AppAsset::register($this);
```
### Enregistrement des CSS
Vous pouvez enregistrer les CSS en utilisant [[yii\web\View::registerCss()|registerCss()]] ou [[yii\web\View::registerCssFile()|registerCssFile()]]. Le premier enregistre un bloc de code CSS tandis que le second enregistre un fichier CSS externe. Par exemple :
```php
$this->registerCss("body { background: #f00; }");
```
Le code ci-dessus provoque l'ajout de ce qui suit à la section « head » :
```html
```
Si vous désirez spécifier des propriétés additionnelles du style balise, passez un tableau des paires nom-valeur en tant que troisième argument. Si vous avez besoin de vous assurer qu'il y a seulement une balise style unique, utilisez un quatrième argument comme cela a été mentionné dans la description des balises méta.
```php
$this->registerCssFile("https://example.com/css/themes/black-and-white.css", [
'depends' => [BootstrapAsset::class],
'media' => 'print',
], 'css-print-theme');
```
Le code ci-dessus provoque l'ajout d'un lien vers un fichier CSS à la section « head » de la page.
* Le premier argument spécifie le fichier CSS à enregistrer.
* Le deuxième argument spécifie l'attribut HTML pour la balise `` résultant. L'option `depends` fait l'objet d'une interprétation particulière. Elle spécifie de quel paquet de ressources ce fichier dépend. Dans ce cas, le paquet de ressources dont le ficher dépend est [[yii\bootstrap\BootstrapAsset|BootstrapAsset]]. Cela veut dire que le fichier CSS sera ajouté *après* les fichiers CSS contenus dans [[yii\bootstrap\BootstrapAsset|BootstrapAsset]].
* Le dernier argument spécifie un identifiant pour ce fichier CSS. S'il n'est pas fourni, l'URL du fichier CSS est utilisée à sa place.
Il est fortement recommandé que vous utilisiez des [paquets de ressources](structure-assets.md) pour enregistrer des fichers CSS externes plutôt que [[yii\web\View::registerCssFile()|registerCssFile()]]. L'utilisation des paquets de ressources vous permet de combiner et de comprimer plusieurs fichiers CSS, ce qui est souhaitable pour les sites Web à trafic intense.
================================================
FILE: docs/guide-fr/output-data-providers.md
================================================
Fournisseurs de données
=======================
Dans les sections [Pagination](output-pagination.md) et [Tri](output-sorting.md), nous avons décrit comment permettre à l'utilisateur de choisir une page particulière de données à afficher et de trier ces données en fonction de certaines colonnes. Comme les tâches de pagination et de tri sont très courantes, Yii met à votre disposition un jeu de classes *fournisseurs de données* pour les encapsuler.
Un fournisseur de données est une classe qui implémente l'interface [[yii\data\DataProviderInterface]]. Il prend en essentiellement en charge l'extraction de données paginées et triées. Il fonctionne ordinairement avec des [composants graphiques de données](output-data-widgets.md) pour que l'utilisateur final puisse paginer et trier les données de manière interactive.
Les classes fournisseurs de données suivantes sont incluses dans les versions publiées de Yii :
* [[yii\data\ActiveDataProvider]]: utilise [[yii\db\Query]] ou [[yii\db\ActiveQuery]] pour demander des données à des bases de données et les retourner sous forme de tableaux ou d'instances d'[enregistrement actif](db-active-record.md).
* [[yii\data\SqlDataProvider]]: exécute une instruction SQL et retourne les données sous forme de tableaux.
* [[yii\data\ArrayDataProvider]]: prend un gros tableau et en retourne une tranche en se basant sur les spécifications de pagination et de tri.
Tous ces fournisseurs de données sont utilisés selon un schéma commun :
```php
// créer le fournisseur de données en configurant ses propriétés de pagination et de tri
$provider = new XyzDataProvider([
'pagination' => [...],
'sort' => [...],
]);
// retrouver les données paginées et triées
$models = $provider->getModels();
// obtenir le nombre d'items de données dans la page courante
$count = $provider->getCount();
// obtenir le nombre total d'items de données de l'ensemble des pages
$totalCount = $provider->getTotalCount();
```
Vous spécifiez les comportements de pagination et de tri d'un fournisseur de données en configurant ses propriétés [[yii\data\BaseDataProvider::pagination|pagination]] et [[yii\data\BaseDataProvider::sort|sort (tri)]] qui correspondent aux configurations de [[yii\data\Pagination]] et [[yii\data\Sort]], respectivement. Vous pouvez également les configurer à `false` pour désactiver la pagination et/ou le tri.
Les [composants graphiques de données](output-data-widgets.md), tels que [[yii\grid\GridView]], disposent d'une propriété nommée `dataProvider` qui accepte une instance de fournisseur de données et affiche les données qu'il fournit. Par exemple :
```php
echo yii\grid\GridView::widget([
'dataProvider' => $dataProvider,
]);
```
Ces fournisseurs de données varient essentiellement en fonction de la manière dont la source de données est spécifiée. Dans les sections qui suivent, nous expliquons l'utilisation détaillée de chacun des ces fournisseurs de données.
## Fournisseur de données actif
Pour utiliser le [[yii\data\ActiveDataProvider|fournisseur de données actif (classe *ActiveDataProvider*)]], vous devez configurer sa propriété [[yii\data\ActiveDataProvider::query|query]]. Elle accepte soit un objet [[yii\db\Query]], soit un objet [[yii\db\ActiveQuery]]. Avec le premier, les données peuvent être soit des tableaux, soit des instances d'[enregistrement actif](db-active-record.md). Par exemple :
```php
use yii\data\ActiveDataProvider;
$query = Post::find()->where(['status' => 1]);
$provider = new ActiveDataProvider([
'query' => $query,
'pagination' => [
'pageSize' => 10,
],
'sort' => [
'defaultOrder' => [
'created_at' => SORT_DESC,
'title' => SORT_ASC,
]
],
]);
// retourne un tableau d'objets Post
$posts = $provider->getModels();
```
Si la requête `$query` de l'exemple ci-dessus est créée en utilisant le code suivant, alors le fournisseur de données retourne des tableaux bruts.
```php
use yii\db\Query;
$query = (new Query())->from('post')->where(['status' => 1]);
```
> Note: si une requête spécifie déjà la clause `orderBy`, les nouvelles instructions de tri données par l'utilisateur final (via la configuration `sort`) sont ajoutées à la clause `orderBy` existante. Toute clause `limit` et `offset` existante est écrasée par la requête de pagination de l'utilisateur final (via la configuration `pagination`).
Par défaut, [[yii\data\ActiveDataProvider]] utilise le composant d'application `db` comme connexion à la base de données. Vous pouvez utiliser une connexion différente en configurant la propriété [[yii\data\ActiveDataProvider::db]].
## Fournisseur de données SQL
[[yii\data\SqlDataProvider]] travaille avec des instructions SQL brutes pour aller chercher les données. Selon les spécifications de [[yii\data\SqlDataProvider::sort|sort]] et de [[yii\data\SqlDataProvider::pagination|pagination]], le fournisseur ajuste les clauses `ORDER BY` et `LIMIT` de l'instruction SQL en conséquence pour n'aller chercher que la page de données requise dans l'ordre désiré.
Pour utiliser [[yii\data\SqlDataProvider]], vous devez spécifier la propriété [[yii\data\SqlDataProvider::sql|sql]], ainsi que la propriété [[yii\data\SqlDataProvider::totalCount|totalCount]]. Par exemple :
```php
use yii\data\SqlDataProvider;
$count = Yii::$app->db->createCommand('
SELECT COUNT(*) FROM post WHERE status=:status
', [':status' => 1])->queryScalar();
$provider = new SqlDataProvider([
'sql' => 'SELECT * FROM post WHERE status=:status',
'params' => [':status' => 1],
'totalCount' => $count,
'pagination' => [
'pageSize' => 10,
],
'sort' => [
'attributes' => [
'title',
'view_count',
'created_at',
],
],
]);
// retourne un tableau de lignes de données
$models = $provider->getModels();
```
> Info: la propriété [[yii\data\SqlDataProvider::totalCount|totalCount]] est requise seulement si vous avez besoin de paginer les données.Cela est dû au fait que l'instruction SQL spécifiée via [[yii\data\SqlDataProvider::sql|sql]] est modifiée par le fournisseur pour ne retourner que la page de données couramment requise. Le fournisseur a donc besoin de connaître le nombre total d'items de données pour calculer correctement le nombre de pages disponibles.
## Fournisseur de données tableau
L'utilisation de [[yii\data\ArrayDataProvider]] est préférable lorsque vous travaillez avec un grand tableau. Le fournisseur vous permet de retourner une page des données du tableau, triées selon une ou plusieurs colonnes. Pour utiliser [[yii\data\ArrayDataProvider]], vous devez spécifier la propriété [[yii\data\ArrayDataProvider::allModels|*allModels* (tous les modèles)]] comme un grand tableau. Les éléments dans le grand tableau peuvent être, soit des tableaux associatifs (p. ex. des résultats de requête d'[objets d'accès aux données (DAO)](db-dao.md)) ou des objets (p. ex. les instances d'[Active Record](db-active-record.md). Par exemple :
```php
use yii\data\ArrayDataProvider;
$data = [
['id' => 1, 'name' => 'name 1', ...],
['id' => 2, 'name' => 'name 2', ...],
...
['id' => 100, 'name' => 'name 100', ...],
];
$provider = new ArrayDataProvider([
'allModels' => $data,
'pagination' => [
'pageSize' => 10,
],
'sort' => [
'attributes' => ['id', 'name'],
],
]);
// obtient les lignes de la page couramment requise
$rows = $provider->getModels();
```
> Note: comparé au [fournisseur de données actif](#active-data-provider) et au fournisseur de données SQL](#sql-data-provider), le fournisseur de données tableau est moins efficient car il requiert de charger *toutes* les données en mémoire.
## Travail avec les clés de données
Lorsque vous utilisez les items de données retournés par le fournisseur de données, vous avez souvent besoin d'identifier chacun des items de données par une clé unique. Par exemple, si les items de donnés représentent des informations sur un client, vous désirez peut-être utiliser l'identifiant du client en tant que clé pour chacun de lots d'informations sur un client. Les fournisseurs de données peuvent retourner une liste de telles clés correspondant aux items de données retournés par [[yii\data\DataProviderInterface::getModels()]]. Par exemple :
```php
use yii\data\ActiveDataProvider;
$query = Post::find()->where(['status' => 1]);
$provider = new ActiveDataProvider([
'query' => $query,
]);
// retourne un tableau d'objets Post
$posts = $provider->getModels();
// retourne les valeurs des clés primaires correspondant à $posts
```
Dans l'exemple ci-dessus, comme vous fournissez un objet [[yii\db\ActiveQuery]] à [[yii\data\ActiveDataProvider]]. Il est suffisamment intelligent pour retourner les valeurs de la clé primaire en tant que clés. Vous pouvez aussi spécifier comment les valeurs de la clé sont calculées en configurant [[yii\data\ActiveDataProvider::key]] avec un nom de colonne ou une fonction de rappel qui calcule les valeurs de la clé. Par exemple :
```php
// utilise la colonne "slug" comme valeurs de la clé
$provider = new ActiveDataProvider([
'query' => Post::find(),
'key' => 'slug',
]);
// utilise le résultat de md5(id) comme valeurs de la clé
$provider = new ActiveDataProvider([
'query' => Post::find(),
'key' => function ($model) {
return md5($model->id);
}
]);
```
## Création d'un fournisseur de données personnalisé
Pour créer votre fournisseur de données personnalisé, vous devez implémenter [[yii\data\DataProviderInterface]]. Une manière plus facile est d'étendre [[yii\data\BaseDataProvider]],ce qui vous permet de vous concentrer sur la logique centrale du fournisseur de données. En particulier, vous devez essentiellement implémenter les méthodes suivantes :
- [[yii\data\BaseDataProvider::prepareModels()|prepareModels()]]: prépare les modèles de données qui seront disponibles dans la page courante et les retourne sous forme de tableau.
- [[yii\data\BaseDataProvider::prepareKeys()|prepareKeys()]]: accepte un tableau de modèles de données couramment disponibles et retourne les clés qui leur sont associés.
- [[yii\data\BaseDataProvider::prepareTotalCount()|prepareTotalCount]]: retourne une valeur indiquant le nombre total de modèles de données dans le fournisseur.
Nous présentons ci-dessous un exemple de fournisseur de données que lit des données CSV efficacement :
```php
fileObject = new SplFileObject($this->filename);
}
/**
* {@inheritdoc}
*/
protected function prepareModels()
{
$models = [];
$pagination = $this->getPagination();
if ($pagination === false) {
// dans le cas où il n'y a pas de pagination, lit toutes les lignes
while (!$this->fileObject->eof()) {
$models[] = $this->fileObject->fgetcsv();
$this->fileObject->next();
}
} else {
// s'il y a une pagination, ne lit qu'une seule page
$pagination->totalCount = $this->getTotalCount();
$this->fileObject->seek($pagination->getOffset());
$limit = $pagination->getLimit();
for ($count = 0; $count < $limit; ++$count) {
$models[] = $this->fileObject->fgetcsv();
$this->fileObject->next();
}
}
return $models;
}
/**
* {@inheritdoc}
*/
protected function prepareKeys($models)
{
if ($this->key !== null) {
$keys = [];
foreach ($models as $model) {
if (is_string($this->key)) {
$keys[] = $model[$this->key];
} else {
$keys[] = call_user_func($this->key, $model);
}
}
return $keys;
} else {
return array_keys($models);
}
}
/**
* {@inheritdoc}
*/
protected function prepareTotalCount()
{
$count = 0;
while (!$this->fileObject->eof()) {
$this->fileObject->next();
++$count;
}
return $count;
}
}
```
================================================
FILE: docs/guide-fr/output-data-widgets.md
================================================
Composants graphiques d'affichage de données
============================================
Yii fournit un jeu de [composants graphiques](structure-widgets.md) utilisables pour afficher des données. Tandis que le componsant graphique [DetailView](#detail-view) (vue détaillée) peut être utilisé pour afficher un enregistrement unique, les composants graphiques [ListView](#list-view) (vue en liste) et [GridView](#grid-view) (vue en grille) peuvent être utilisés pour afficher plusieurs enregistrements en liste ou en grille assortis de fonctionnalités telles que la pagination, le tri et le filtrage.
Vue détaillée (classe *DetailView*)
----------------------------------
Le composant graphique [[yii\widgets\DetailView|DetailView]] (vue détaillée) affiche les détails d'un [[yii\widgets\DetailView::$model|modèle]] de données unique.
Il est le plus adapté à l'affichage d'un modèle dans un format courant (p. ex. chacun des attributs du modèle est affiché en tant que ligne d'une grille). Le modèle peut être, soit une instance, ou une classe fille, de [[\yii\base\Model]] telle que la classe [ActiveRecord](db-active-record.md), soit un tableau associatif.
*DetailView* utilise la propriété [[yii\widgets\DetailView::$attributes|$attributes]] pour déterminer quels attributs du modèle doivent être affichés et comment ils doivent être formatés. Reportez-vous à la section [formatage des données](output-formatting.md) pour des informations sur les options de formatage.
Une utilisation typique de *DetailView* ressemble à ce qui suit :
```php
echo DetailView::widget([
'model' => $model,
'attributes' => [
'title', // attribut title (en texte simple)
'description:html', // attribut description formaté en HTML
[ // le nom du propriétaire du modèle
'label' => 'Owner',
'value' => $model->owner->name,
],
'created_at:datetime', // date de création formaté comme une date/temps
],
]);
```
Vue en liste (class *ListView*)
------------------------------
Le composant graphique [[yii\widgets\ListView|ListView]] (vue en liste) est utilisé pour afficher des données issues d'un [fournisseur de données](output-data-providers.md). Chacun des modèles est rendu en utilisant le composant [[yii\widgets\ListView::$itemView|ListView]] (vue en liste) spécifié. Comme ce composant fournit des fonctionnalités telles que la pagination, le tri et le filtrage de base, il est pratique, à la fois pour afficher des informations et pour créer des interfaces utilisateur de gestion des données.
Typiquement, on l'utilise comme ceci :
```php
use yii\widgets\ListView;
use yii\data\ActiveDataProvider;
$dataProvider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 20,
],
]);
echo ListView::widget([
'dataProvider' => $dataProvider,
'itemView' => '_post',
]);
```
Le fichier de vue, `_post`, contient ce qui suit :
```php
title) ?>
text) ?>
```
Dans le fichier ci-dessus, le modèle de données courant est disponible comme `$model`. En outre, les variables suivantes sont disponibles :
- `$key`: mixed, la valeur de la clé associée à l'item de données
- `$index`: integer, l'index commençant à zéro de l'item de données dans le tableau d'items retourné par le fournisseur de données.
- `$widget`: ListView, l'instance de ce composant graphique.
Si vous avez besoin de passer des données additionnelles à chacune des vues, vous pouvez utiliser la propriété [[yii\widgets\ListView::$viewParams|$viewParams]] pour passer des paires clé valeur, comme ceci :
```php
echo ListView::widget([
'dataProvider' => $dataProvider,
'itemView' => '_post',
'viewParams' => [
'fullView' => true,
'context' => 'main-page',
// ...
],
]);
```
Celles-ci sont alors disponibles aussi dans la vue en tant que variables.
Vue en grille (classe *GridView*)
--------------------------------
La vue en grille, ou composant [[yii\grid\GridView|GridView]], est un des composants les plus puissants de Yii. Ce composant est extrêmement utile si vous devez rapidement construire l'interface d'administration du système. Il accepte des données d'un [fournisseur de données](output-data-providers.md) et rend chacune des lignes en utilisant un jeu de [[yii\grid\GridView::columns|columns]] (colonnes), présentant ainsi l'ensemble des données sous forme d'une grille.
Chacune des lignes de la grille représente un item unique de données, et une colonne représente ordinairement un attribut de l'item (quelques colonnes peuvent correspondre à des expressions complexes utilisant les attributs ou à un texte statique).
Le code minimal pour utiliser le composant *GridView* se présente comme suit :
```php
use yii\grid\GridView;
use yii\data\ActiveDataProvider;
$dataProvider = new ActiveDataProvider([
'query' => Post::find(),
'pagination' => [
'pageSize' => 20,
],
]);
echo GridView::widget([
'dataProvider' => $dataProvider,
]);
```
Le code précédent crée un fournisseur de données, puis utilise le composant *GridView* pour afficher chacun des attributs dans une ligne en le prélevant dans le fournisseur de données. La grille affichée est doté de fonctionnalités de pagination et de tri sans autre intervention.
### Colonnes de la grille
Les colonnes de la grille sont exprimées en terme de classe [[yii\grid\Column]], qui sont configurées dans la propriété [[yii\grid\GridView::columns|columns]] (colonnes) de la configuration du composant *GridView*. En fonction du type de colonne et des réglages, celles-ci sont en mesure de présenter les données différemment. La classe par défaut est [[yii\grid\DataColumn]] (colonne de données), qui représente un attribut de modèle et peut être triée et filtrée.
```php
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
['class' => 'yii\grid\SerialColumn'],
// colonnes simples définies par les données contenues dans le fournisseur de données
// les données de la colonne du modèle sont utilisées
'id',
'username',
// un exemple plus complexe
[
'class' => 'yii\grid\DataColumn', // peut être omis car c'est la valeur par défaut
'value' => function ($data) {
return $data->name; // $data['name'] pour une donnée tableau p. ex. en utilisant SqlDataProvider.
},
],
],
]);
```
Notez que si la partie [[yii\grid\GridView::columns|columns]] de la configuration n'est pas spécifiée, Yii essaye de montrer toutes les colonnes possibles du modèle du fournisseur de données.
### Classes de colonne
Les colonnes du composant *GridView* peuvent être personnalisées en utilisant différentes classes de colonnes :
```php
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
[
'class' => 'yii\grid\SerialColumn', // <-- ici
// vous pouvez configurer des propriété additionnelles ici
],
```
En plus des classes de colonne fournies par Yii que nous allons passer en revue ci-après, vous pouvez créer vos propres classes de colonne.
Chacune des classes de colonne étend la classe [[yii\grid\Column]] afin que quelques options communes soient disponibles lors de la configuration des colonnes.
- [[yii\grid\Column::header|header]] permet de définir une ligne d'entête
- [[yii\grid\Column::footer|footer]] permet de définir le contenu d'une ligne de pied de grille
- [[yii\grid\Column::visible|visible]] définit si la colonne doit être visible.
- [[yii\grid\Column::content|content]] vous permet de passer une fonction de rappel PHP valide qui retourne les données d'une ligne. Le format est le suivant :
```php
function ($model, $key, $index, $column) {
return 'a string';
}
```
Vous pouvez spécifier différentes options HTML de conteneurs en passant des tableaux à :
- [[yii\grid\Column::headerOptions|headerOptions]]
- [[yii\grid\Column::footerOptions|footerOptions]]
- [[yii\grid\Column::filterOptions|filterOptions]]
- [[yii\grid\Column::contentOptions|contentOptions]]
#### Colonne de données (*DataColumn*)
La classe [[yii\grid\DataColumn|DataColumn]] (colonne de données) est utilisée pour afficher et trier des données. C'est le type de colonne par défaut, c'est pourquoi la spécification de la classe peut être omise.
Le réglage principal de la colonne de données est celui de sa propriété [[yii\grid\DataColumn::format|format]]. Ses valeurs correspondent aux méthodes du [composant d'application](structure-application-components.md) `formatter` qui est de classe [[\yii\i18n\Formatter|Formatter]] par défaut :
```php
echo GridView::widget([
'columns' => [
[
'attribute' => 'name',
'format' => 'text'
],
[
'attribute' => 'birthday',
'format' => ['date', 'php:Y-m-d']
],
],
]);La valeur de la colonne est passée en tant que premier argument
```
Dans cet exemple, `text` correspond à la méthode [[\yii\i18n\Formatter::asText()]]. La valeur de la colonne est passée en tant que premier argument. Dans la deuxième définition de colonne, `date` correspond à la méthode [[\yii\i18n\Formatter::asDate()]]. La valeur de la colonne est passée en tant que premier argument tandis que 'php:Y-m-d' est utilisé en tant que valeur du deuxième argument.
Pour une liste complète de tous les formateurs, reportez-vous à la section [Formatage des données](output-formatting.md).
Pour configurer des colonnes de données, il y a aussi un format raccourci qui est décrit dans la documentation de l'API de [[yii\grid\GridView::columns|columns]].
#### Colonne d'actions (*ActionColumn*)
La classe [[yii\grid\ActionColumn|ActionColumn]] (colonne d'action) affiche des boutons d'action tels que mise à jour ou supprimer pour chacune des lignes.
```php
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
[
'class' => 'yii\grid\ActionColumn',
// vous pouvez configurer des propriétés additionnelles ici
],
```
Les propriétés additionnelles configurables sont :
- [[yii\grid\ActionColumn::controller|controller]] qui est l'identifiant du contrôleur qui prend en charge l'action. Si cette propriété n'est pas définie, le contrôleur courant est utilisé.
- [[yii\grid\ActionColumn::template|template]] qui définit le modèle utilisé pour composer chacune des cellules dans la colonne d'actions. Les marqueurs (textes à l'intérieur d'accolades) sont traités comme des identifiants d'action (aussi appelé *noms de bouton* dans le contexte d'une colonne d'actions. Il sont remplacés par les fonctions de rappel correspondantes spécifiées dans la propriété [[yii\grid\ActionColumn::$buttons|buttons]]. Par exemple, le marqueur `{view}` sera remplacé par le résultat de la fonction de rappel `buttons['view']`. Si une fonction de rappel n'est pas trouvée, le texte est remplacé par une chaîne vide. Les marqueurs par défaut sont `{view} {update} et {delete}`.
- [[yii\grid\ActionColumn::buttons|buttons]] est un tableau de fonctions de rappel pour le rendu des boutons. Les clés du tableau sont les noms des boutons (sans les accolades), et les valeurs sont les fonctions de rappel de rendu des boutons. Les fonctions de rappel ont la signature suivante :
```php
function ($url, $model, $key) {
// retourne le code HTML du bouton
}
```
dans le code qui précède, `$url` est l'URL que la colonne crée pour le bouton, `$model` est l'objet modèle qui est en train d'être rendu pour la ligne courante, et `$key` est la clé du modèle dans le tableau du fournisseur de données.
- [[yii\grid\ActionColumn::urlCreator|urlCreator]] est une fonction de rappel qui crée une URL de bouton en utilisant les informations spécifiées sur le modèle. La signature de la fonction de rappel doit être le même que celle de [[yii\grid\ActionColumn::createUrl()]]. Si cette propriété n'est pas définie, les URL de bouton sont créées en utilisant [[yii\grid\ActionColumn::createUrl()]].
- [[yii\grid\ActionColumn::visibleButtons|visibleButtons]] est un tableau des conditions de visibilité pour chacun des boutons. Les clés du tableau sont les noms des boutons (sans les accolades), et les valeurs sont les valeurs booleénnes `true` ou `false` (vrai ou faux) ou la fonction anonyme. Lorsque le nom du bouton n'est pas spécifié dans ce tableau, il est montré par défaut. Les fonctions de rappel utilisent la signature suivante :
```php
function ($model, $key, $index) {
return $model->status === 'editable';
}
```
Ou vous pouvez passer une valeur booléenne :
```php
[
'update' => \Yii::$app->user->can('update')
]
```
#### Colonne boîte à cocher (*CheckboxColumn*)
La classe [[yii\grid\CheckboxColumn|CheckboxColumn]] (colonne de boîtes à cocher) affiche une colonne de boîtes à cocher.
Pour ajouter une colonne de boîtes à cocher à la vue en grille (*GridView*), ajoutez la configuration de [[yii\grid\GridView::$columns|columns]] comme ceci :
```php
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
// ...
[
'class' => 'yii\grid\CheckboxColumn',
// vous pouvez configurer des propriétés additionnelles ici
],
],
```
L'utilisateur peut cliquer sur les boîtes à cocher pour sélectionner des lignes dans la grille. Les lignes sélectionnées peuvent être obtenues en appelant le code JavaScript suivant :
```javascript
var keys = $('#grid').yiiGridView('getSelectedRows');
// keys est un tableau constitué des clés associées aux lignes sélectionnées.
```
#### Colonne série (*SerialColumn*)
La classe [[yii\grid\SerialColumn|SerialColumn]] (colonne série) rend les numéros de ligne en commençant à `1` et en continuant.
L'utilisation est aussi simple que ce que nous présentons ci-après :
```php
echo GridView::widget([
'dataProvider' => $dataProvider,
'columns' => [
['class' => 'yii\grid\SerialColumn'], // <-- ici
// ...
```
### Tri des données
> Note: cette section est en cours de développement.
>
> - https://github.com/yiisoft/yii2/issues/1576
### Filtrage des données
Pour filtrer les données, la vue en grille (*GridView*) requiert un [modèle](structure-models.md) qui représente le critère de recherche qui est ordinairement pris dans les champs du filtre dans la vue en grille. Une pratique courante lorsqu'on utilise des [enregistrements actifs](db-active-record.md) est de créer une classe modèle de recherche qui fournit les fonctionnalités nécessaires (elle peut être générée pour vous par [Gii](start-gii.md)). Cette classe définit les règles de validation pour la recherche et fournit une méthode `search()` (recherche) qui retourne le fournisseur de données avec une requête ajustée qui respecte les critères de recherche.
Pour ajouter la fonctionnalité de recherche au modèle `Post`, nous pouvons créer un modèle `PostSearch` comme celui de l'exemple suivant :
```php
$query,
]);
// charge les données du formulaire de recherche et valide
if (!($this->load($params) && $this->validate())) {
return $dataProvider;
}
// ajuste la requête en ajoutant les filtres
$query->andFilterWhere(['id' => $this->id]);
$query->andFilterWhere(['like', 'title', $this->title])
->andFilterWhere(['like', 'creation_date', $this->creation_date]);
return $dataProvider;
}
}
```
> Tip: reportez-vous au [Constructeur de requêtes ](db-query-builder.md) (*Query Builder*) et en particulier aux [conditions de filtrage](db-query-builder.md#filter-conditions) pour savoir comment construire la requête de filtrage.
Vous pouvez utiliser cette fonction dans le contrôleur pour obtenir le fournisseur de données de la vue en grille :
```php
$searchModel = new PostSearch();
$dataProvider = $searchModel->search(Yii::$app->request->get());
return $this->render('myview', [
'dataProvider' => $dataProvider,
'searchModel' => $searchModel,
]);
```
Et dans la vue, vous assignez ensuite le fournisseur de données (`$dataProvider`) et le modèle de recherche (`$searchModel`) à la vue en grille (*GridView*) :
```php
echo GridView::widget([
'dataProvider' => $dataProvider,
'filterModel' => $searchModel,
'columns' => [
// ...
],
]);
```
### Formulaire de filtrage séparé
La plupart du temps, utiliser les filtres de l'entête de la vue en grille suffit, mais dans le cas où vous avez besoin d'un formulaire de filtrage séparé, vous pouvez facilement l'ajouter aussi. Vous pouvez créer une vue partielle `_search.php` avec le contenu suivant :
```php
['index'],
'method' => 'get',
]); ?>
field($model, 'title') ?>
field($model, 'creation_date') ?>
'btn btn-primary']) ?>
'btn btn-default']) ?>
Users
';
echo GridView::widget([
'dataProvider' => $userProvider,
]);
echo 'Posts
';
echo GridView::widget([
'dataProvider' => $postProvider,
]);
```
### Utilisation de la vue en grille avec Pjax
Le composant graphique [[yii\widgets\Pjax|Pjax]] vous permet de mettre à jour une certaine section de votre page plutôt que d'avoir à recharger la page toute entière. Vous pouvez l'utiliser pour mettre uniquement à jour le contenu de la [[yii\grid\GridView|GridView]] (vue en grille) lors de l'utilisation de filtres.
```php
use yii\widgets\Pjax;
use yii\grid\GridView;
Pjax::begin([
// PJax options
]);
Gridview::widget([
// GridView options
]);
Pjax::end();
```
Pjax fonctionne également pour les liens à l'intérieur du composant graphique [[yii\widgets\Pjax|Pjax]] et pour les liens spécifiés par [[yii\widgets\Pjax::$linkSelector|Pjax::$linkSelector]]. Mais cela peut être un problème pour les liens d'une [[yii\grid\ActionColumn|ActionColumn]] (colonne d'action). Pour empêcher cela, ajoutez l'attribut HTML `data-pjax="0"` aux liens lorsque vous définissez la propriété [[yii\grid\ActionColumn::$buttons|ActionColumn::$buttons]].
#### Vue en grille et vue en liste avec Pjax dans Gii
Depuis la version 2.0.5, le générateur d'actions CRUD de [Gii](start-gii.md) dispose d'une option appelée `$enablePjax` qui peut être utilisée, soit via l'interface web, soit en ligne de commande.
```php
yii gii/crud --controllerClass="backend\\controllers\PostController" \
--modelClass="common\\models\\Post" \
--enablePjax=1
```
Qui génère un composant graphique [[yii\widgets\Pjax|Pjax]] enveloppant les composants graphiques [[yii\grid\GridView|GridView]] ou [[yii\widgets\ListView|ListView]].
Lectures complémentaires
------------------------
- [Rendering Data in Yii 2 with GridView and ListView](https://www.sitepoint.com/rendering-data-in-yii-2-with-gridview-and-listview/) d'Arno Slatius.
================================================
FILE: docs/guide-fr/output-formatting.md
================================================
Formatage des données
=====================
Pour afficher des données dans un format plus facile à lire par les utilisateurs, vous pouvez les formater en utilisant le [composant d'application](structure-application-components.md) `formatter`. Par défaut, le formateur est mis en œuvre par [[yii\i18n\Formatter]] qui fournit un jeu de méthodes pour formater des données telles que des dates, des temps, des nombres, des monnaies et autres données couramment utilisées. Vous pouvez utiliser le formateur de la manière indiquée ci-dessous :
```php
$formatter = \Yii::$app->formatter;
// affiche : January 1, 2014
echo $formatter->asDate('2014-01-01', 'long');
// affiche : 12.50%
echo $formatter->asPercent(0.125, 2);
// affiche : cebe@example.com
echo $formatter->asEmail('cebe@example.com');
// affiche : Yes
echo $formatter->asBoolean(true);
// il prend aussi en charge l'affichage de valeurs nulles :
// affiche : (Not set)
echo $formatter->asDate(null);
```
Comme vous pouvez le voir, ces trois méthodes sont nommées selon le format suivant `asXyz()`, où `Xyz` représente un format pris en charge. En alternative, vous pouvez formater les données en utilisant la méthode générique [[yii\i18n\Formatter::format()|format()]], qui vous permet de contrôler le format désiré par programmation et qui est communément utilisé par les composants graphiques tels que [[yii\grid\GridView]] et [[yii\widgets\DetailView]]. Par exemple :
```php
// affiche : January 1, 2014
echo Yii::$app->formatter->format('2014-01-01', 'date');
// vous pouvez aussi utiliser un tableau pour spécifier les paramètres de votre méthode de formatage :
// `2` est la valeur du paramètre `$decimals` (nombre de décimales) pour la méthode asPercent().
// affiche : 12.50%
echo Yii::$app->formatter->format(0.125, ['percent', 2]);
```
> Note: le composant de formatage est conçu pour formater des valeurs à présenter à l'utilisateur. Si vous voulez convertir des entrées utilisateur en un format lisible par la machine, ou simplement formater une date dans un format lisible par la machine, le formateur n'est pas l'outil adapté à cela. Pour convertir une entrée utilisateur pour une date et un temps, vous pouvez utiliser [[yii\validators\DateValidator]] et [[yii\validators\NumberValidator]] respectivement. Pour une simple conversion entre les formats lisibles par la machine de date et de temps, la fonction PHP [date()](https://www.php.net/manual/fr/function.date.php) suffit.
## Configuration du formateur
Vous pouvez configurer les règles de formatage en configurant le composant `formatter` dans la [configuration de l'application](concept-configurations.md#application-configurations). Par exemple :
```php
return [
'components' => [
'formatter' => [
'dateFormat' => 'dd.MM.yyyy',
'decimalSeparator' => ',',
'thousandSeparator' => ' ',
'currencyCode' => 'EUR',
],
],
];
```
Reportez-vous à la classe [[yii\i18n\Formatter]] pour connaître les propriétés qui peuvent être configurées.
## Formatage de valeurs de dates et de temps
Le formateur prend en charge les formats de sortie suivants en relation avec les dates et les temps :
- [[yii\i18n\Formatter::asDate()|date]]: la valeur est formatée sous la forme d'une date, p. ex. `January 01, 2014`.
- [[yii\i18n\Formatter::asTime()|time]]: la valeur est formatée sous la forme d'un temps, p. ex. `14:23`.
- [[yii\i18n\Formatter::asDatetime()|datetime]]: la valeur est formatée sous la forme d'une date et d'un temps, p. ex. `January 01, 2014 14:23`.
- [[yii\i18n\Formatter::asTimestamp()|timestamp]]: la valeur est formatée sous la forme d'un [horodatage unix ](https://fr.wikipedia.org/wiki/Heure_Unix), p. ex. `1412609982`.
- [[yii\i18n\Formatter::asRelativeTime()|relativeTime]]: la valeur est formatée sous la forme d'un intervalle de temps entre un temps et le temps actuel dans une forme lisible par l'homme, p.ex. `1 hour ago`.
- [[yii\i18n\Formatter::asDuration()|duration]]: la valeur est formatée comme une durée dans un format lisible par l'homme, p. ex. `1 day, 2 minutes`.
Les formats par défaut pour les dates et les temps utilisés pour les méthodes [[yii\i18n\Formatter::asDate()|date]], [[yii\i18n\Formatter::asTime()|time]],
et [[yii\i18n\Formatter::asDatetime()|datetime]] peuvent être configurés globalement en configurant [[yii\i18n\Formatter::dateFormat|dateFormat]], [[yii\i18n\Formatter::timeFormat|timeFormat]], et [[yii\i18n\Formatter::datetimeFormat|datetimeFormat]].
Vous pouvez spécifier les formats de date et de temps en utilisant la [syntaxe ICU](https://unicode-org.github.io/icu/userguide/format_parse/datetime/). Vous pouvez aussi utiliser la [syntaxe date() de PHP](https://www.php.net/manual/fr/function.date.php) avec le préfixe `php:` pour la différentier de la syntaxe ICU. Par exemple :
```php
// format ICU
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06
// format date() de PHP
echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06
```
Lorsque vous travaillez avec des applications qui requièrent une prise en charge de plusieurs langues, vous devez souvent spécifier différents formats de dates et de temps pour différentes locales. Pour simplifier cette tâche, vous pouvez utiliser les raccourcis de formats (p. ex. `long`, `short`), à la place. Le formateur transforme un raccourci de formats en un format approprié en prenant en compte la [[yii\i18n\Formatter::locale|locale]] courante. Les raccourcis de formats suivants sont pris en charge (les exemples supposent que `en_GB` est la locale courante) :
- `short`: affiche `06/10/2014` pour une date et `15:58` pour un temps;
- `medium`: affiche `6 Oct 2014` et `15:58:42`;
- `long`: affiche `6 October 2014` et `15:58:42 GMT`;
- `full`: affiche `Monday, 6 October 2014` et `15:58:42 GMT`.
Depuis la version 2.0.7, il est aussi possible de formater les dates dans différents systèmes calendaires. Reportez-vous à la documentation de l'API pour la propriété [[yii\i18n\Formatter::$calendar|$calendar]] des formateurs pour savoir comment définir un autre système calendaire.
### Fuseaux horaires
Lors du formatage des dates et des temps, Yii les convertit dans le [[yii\i18n\Formatter::timeZone|fuseau horaire]] cible. La valeur à formater est supposée être donnée en UTC, sauf si un fuseau horaire est explicitement défini ou si vous avez configuré [[yii\i18n\Formatter::defaultTimeZone]].
Dans les exemples qui suivent, nous supposons que la cible [[yii\i18n\Formatter::timeZone|fuseau horaire]] est définie à `Europe/Berlin`.
```php
// formatage d'un horodatage UNIX comme un temps
echo Yii::$app->formatter->asTime(1412599260); // 14:41:00
// formatage d'une chaîne de caractère date-temps (en UTC) comme un temps
echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00
// formatage d'une chaîne de caractères date-temps (en CEST) comme un temps
echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00
```
> Note: comme les fuseaux horaires sont assujettis à des règles fixées par les gouvernements du monde entier, et que ces règles peuvent varier fréquemment, il est vraisemblable que vous n'ayez pas la dernière information dans la base de données des fuseaux horaires installée sur votre système. Vous pouvez vous reporter au [manuel d'ICU](https://unicode-org.github.io/icu/userguide/datetime/timezone/#updating-the-time-zone-data) pour des informations sur la manière de mettre cette base de données à jour. Reportez-vous aussi au tutoriel [Configurer votre environnement PHP pour l'internationalisation](tutorial-i18n.md#setup-environment).
## Formatage des nombres
Pour les nombres, le formateur prend en charge les formats de sortie suivants :
- [[yii\i18n\Formatter::asInteger()|integer]]: la valeur est formatée comme un entier, p. ex. `42`.
- [[yii\i18n\Formatter::asDecimal()|decimal]]: la valeur est formatée comme un nombre décimal en portant attention aux décimales et aux séparateurs de milliers, p. ex. `2,542.123` ou `2.542,123`.
- [[yii\i18n\Formatter::asPercent()|percent]]: la valeur est formatée comme un pourcentage p. ex. `42%`.
- [[yii\i18n\Formatter::asScientific()|scientific]]: la valeur est formatée comme un nombre dans le format scientifique p. ex. `4.2E4`.
- [[yii\i18n\Formatter::asCurrency()|currency]]: la valeur est formatée comme une valeur monétaire, p. ex. `£420.00`. Notez que pour que cette fonction fonctionne correctement, la locale doit inclure la partie correspondant au pays p. ex. `en_GB` ou `en_US` parce que la partie langue seulement reste ambigüe dans ce cas.
- [[yii\i18n\Formatter::asSize()|size]]: la valeur, qui est un nombre d'octets est formatée sous une forme lisible par l'homme, p. ex. `410 kibibytes`.
- [[yii\i18n\Formatter::asShortSize()|shortSize]]: est la version courte de [[yii\i18n\Formatter::asSize()|size]], e.g. `410 KiB`.
Le format pour un nombre peut être ajusté en utilisant [[yii\i18n\Formatter::decimalSeparator|decimalSeparator (séparateur de décimales)]] et
[[yii\i18n\Formatter::thousandSeparator|thousandSeparator (séparateur de milliers) ]], qui prennent tous les deux les valeurs par défaut déterminées par la [[yii\i18n\Formatter::locale|locale]] courante.
Pour une configuration plus avancée, [[yii\i18n\Formatter::numberFormatterOptions]] et [[yii\i18n\Formatter::numberFormatterTextOptions]] peuvent être utilisés pour configurer la classe [NumberFormater (formateur de nombres)](https://www.php.net/manual/fr/class.numberformatter.php) utilisée en interne pour implémenter le formateur. Par exemple, pour ajuster la valeur minimum et maximum des chiffres fractionnaires, vous pouvez configurer la propriété [[yii\i18n\Formatter::numberFormatterOptions]] comme ceci :
```php
'numberFormatterOptions' => [
NumberFormatter::MIN_FRACTION_DIGITS => 0,
NumberFormatter::MAX_FRACTION_DIGITS => 2,
]
```
## Autres formats
En plus des formats de date, temps et nombre, Yii prend aussi en charge les autres formats communément utilisés, y compris :
- [[yii\i18n\Formatter::asRaw()|raw]]: la valeur est affichée telle quelle, il s'agit d'un pseudo-formateur qui n'a pas d'effet, à l'exception des valeurs `null` qui sont affichées en utilisant la propriété [[nullDisplay]].
- [[yii\i18n\Formatter::asText()|text]]: la valeur est encodée HTML. C'est le format par défaut utilisé par les [données des colonnes du widget GridView](output-data-widgets.md#data-column).
- [[yii\i18n\Formatter::asNtext()|ntext]]: la valeur est formatée comme un texte simple encodé HTML avec conversion des retours à la ligne en balise break.
- [[yii\i18n\Formatter::asParagraphs()|paragraphs]]: la valeur est formatée comme un paragraphe de texte encodé HTML à l'intérieur d'une balise ``.
- [[yii\i18n\Formatter::asHtml()|html]]: la valeur est purifiée en utilisant [[HtmlPurifier]] pour éviter les attaques XSS. Vous pouvez passer les options additionnelles telles que `['html', ['Attr.AllowedFrameTargets' => ['_blank']]]`.
- [[yii\i18n\Formatter::asEmail()|email]]: la valeur est encodé comme un lien `mailto`.
- [[yii\i18n\Formatter::asImage()|image]]: la valeur est formatée comme une balise image.
- [[yii\i18n\Formatter::asUrl()|url]]: la valeur est formatée comme un hyperlien.
- [[yii\i18n\Formatter::asBoolean()|boolean]]: la valeur est formatée comme une valeur booléenne. Par défaut `true` est rendu par `Yes` et `false` par `No`, traduit dans la langue courante de l'application. Vous pouvez ajuster cela en configurant la propriété [[yii\i18n\Formatter::booleanFormat]].
## Valeurs nulles (null)
Les valeurs *null* sont formatées spécialement. Au lieu d'afficher une chaîne de caractères vide, le formateur la convertit en une chaîne de caractères prédéfinie dont la valeur par défaut est `(not set)` traduite dans la langue courante de l'application. Vous pouvez configurer la propriété [[yii\i18n\Formatter::nullDisplay|nullDisplay]] pour personnaliser cette chaîne de caractères.
## Localisation des formats de données
Comme nous l'avons mentionné précédemment, le formateur utilise la [[yii\i18n\Formatter::locale|locale]] courante pour déterminer comment formater une valeur qui soit convenable dans la cible pays/région. Par exemple, la même valeur de date est formatée différemment pour différentes locales :
```php
Yii::$app->formatter->locale = 'en-US';
echo Yii::$app->formatter->asDate('2014-01-01'); // affiche : January 1, 2014
Yii::$app->formatter->locale = 'de-DE';
echo Yii::$app->formatter->asDate('2014-01-01'); // affiche : 1. Januar 2014
Yii::$app->formatter->locale = 'ru-RU';
echo Yii::$app->formatter->asDate('2014-01-01'); // affiche : 1 января 2014 г.
```
Par défaut, la [[yii\i18n\Formatter::locale|locale]] est déterminée par la valeur de [[yii\base\Application::language]]. Vous pouvez la redéfinir en définissant la propriété [[yii\i18n\Formatter::locale]] explicitement.
> Note: le formateur de Yii a besoin de l'[extension intl de PHP](https://www.php.net/manual/fr/book.intl.php) pour prendre en charge la localisation des formats de données. Parce que différentes versions de la bibliothèque ICU compilées par PHP produisent des résultats de formatage différents, il est recommandé que vous utilisiez la même version de la bibliothèque ICU pour tous vos environnements. Pour plus de détails, reportez-vous au tutoriel [Configuration de votre environnement PHP pour l'internationalisation](tutorial-i18n.md#setup-environment).
>
> Si l'extension intl extension n'est pas installée, les données ne sont pas localisées.
>
> Notez que pour les valeurs de dates qui sont antérieures à l'année 1901, ou postérieures à 2038, la localisation n'est pas faite sur les systèmes 32 bits, même si l'extension intl est installée. Cela est dû au fait que, dans ce cas, ICU utilise des horodatages UNIX 32 bits pour les valeurs de date.
================================================
FILE: docs/guide-fr/output-pagination.md
================================================
Pagination
==========
Lorsqu'il y a trop de données à afficher sur une seule page, une stratégie courante consiste à les afficher en de multiples pages, et sur chacune des pages, à n'afficher qu'une fraction réduite des données. Cette stratégie est connue sous le nom de *pagination*.
Yii utilise un objet [[yii\data\Pagination]] pour représenter les informations d'un schéma de pagination. En particulier :
* [[yii\data\Pagination::$totalCount|nombre total (*total count*)]] spécifie le nombre total d'items de données. Notez que cela est ordinairement beaucoup plus élevé que le nombre d'items de données que l'on a besoin d'afficher sur une unique page.
* [[yii\data\Pagination::$pageSize|taille de la page (*page size*)]] spécifie combien d'items de données chaque page contient. La valeur par défaut est 20.
* [[yii\data\Pagination::$page|page courante (*current page*)]] donne la numéro de la page courante (qui commence à zéro). La valeur par défaut est 0, ce qui indique la première page.
Avec un objet [[yii\data\Pagination]] pleinement spécifié, vous pouvez retrouver et afficher partiellement des données. Par exemple, si vous allez chercher des données dans une base de données, vous pouvez spécifier les clauses `OFFSET` et `LIMIT` de la requête de base de données avec les valeurs correspondantes fournies par l'objet pagination. Un exemple est présenté ci-dessous.
```php
use yii\data\Pagination;
// construit une requêt de base de données pour obtenir tous les articles dont le *status* vaut 1
$query = Article::find()->where(['status' => 1]);
// obtient le nombre total d'articles (mais ne va pas chercher les données articles pour le moment)
$count = $query->count();
// crée un objet pagination en lui passant le nombre total d'items
$pagination = new Pagination(['totalCount' => $count]);
// limite la requête en utilisant l'objet pagination et va chercher les articles
$articles = $query->offset($pagination->offset)
->limit($pagination->limit)
->all();
```
Mais quelle page d'article est retournée par l'exemple ci-dessus ? Cela dépend d'un paramètre de la requête nommé `page`. Par défaut, l'objet pagination essaye de définir le paramètre `page` avec la valeur de la [[yii\data\Pagination::$page|page courante (*current page*)]]. Si le paramètre n'est pas fourni, il prend la valeur par défaut `0`.
Pour faciliter la construction des élément de l'interface utilisateur qui prennent en charge la pagination, Yii fournit le composant graphique [[yii\widgets\LinkPager]] qui affiche une liste de boutons de page sur lesquels l'utilisateur peut cliquer pour préciser quelle page de données doit être affichée. Ce composant graphique accepte en paramètre un objet pagination afin de savoir quelle est la page courante et combien de boutons de page afficher. Par exemple :
```php
use yii\widgets\LinkPager;
echo LinkPager::widget([
'pagination' => $pagination,
]);
```
Si vous voulez construire des éléments d'interface graphique à la main, vous pouvez utiliser [[yii\data\Pagination::createUrl()]] pour créer des URL qui conduisent à différentes pages. La méthode requiert un paramètre de page et crée une URL formatée correctement qui contient le paramètre de page. Par exemple :
```php
// spécifie la route que l'URL à créer doit utiliser,
// si vous ne la spécifiez pas, la route actuellement requise est utilisée
$pagination->route = 'article/index';
// affiche : /index.php?r=article%2Findex&page=100
echo $pagination->createUrl(100);
// affiche : /index.php?r=article%2Findex&page=101
echo $pagination->createUrl(101);
```
> Tip: vous pouvez personnaliser le nom du paramètre de requête `page` en configurant la propriété [[yii\data\Pagination::pageParam|pageParam]] lors de la création de l'objet pagination.
================================================
FILE: docs/guide-fr/output-sorting.md
================================================
Tri
===
Lors de l'affichage de multiples lignes de données, on a souvent besoin des trier les données en fonction des valeurs de certaines colonnes spécifiées par l'utilisateur. Yii utilise l'objet [[yii\data\Sort]] pour représenter les information sur le schéma de triage. En particulier :
* [[yii\data\Sort::$attributes|attributes]] spécifie les *attributs* grâce auxquels les données peuvent être triées. Un attribut peut être aussi simple qu'un [attribut de modèle](structure-models.md#attributes). Il peut aussi être un composite combinant le multiples attributs de modèles ou de colonnes de base de données. Nous apportons des informations plus détaillées dans la suite de cette page.
* [[yii\data\Sort::$attributeOrders|attributeOrders]] fournit la direction de l'ordre de tri pour chacun des attributs.
* [[yii\data\Sort::$orders|orders]] fournit les directions de tri en terme de colonnes de bas niveau.
Pour utiliser [[yii\data\Sort]], commencez par déclarer quels attributs peuvent être triés. Puis retrouvez les informations d'ordre de tri courantes de [[yii\data\Sort::$attributeOrders|attributeOrders]] ou [[yii\data\Sort::$orders|orders]], et utilisez-les pour personnaliser votre requête de données. Par exemple :
```php
use yii\data\Sort;
$sort = new Sort([
'attributes' => [
'age',
'name' => [
'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
'default' => SORT_DESC,
'label' => 'Name',
],
],
]);
$articles = Article::find()
->where(['status' => 1])
->orderBy($sort->orders)
->all();
```
Dans l'exemple qui précède, deux attributs sont déclarés pour l'objet [[yii\data\Sort|Sort]] : `age` et `name`.
L'attribut `age` est un attribut *simple* correspondant à l'attribut `age` de la classe d'enregistrement actif `Article`. Il équivaut à la déclaration suivante :
```php
'age' => [
'asc' => ['age' => SORT_ASC],
'desc' => ['age' => SORT_DESC],
'default' => SORT_ASC,
'label' => Inflector::camel2words('age'),
]
```
L'attribut `name` est un attribut *composite* défini par `first_name` et `last_name` de la classe `Article`. Il est déclaré en utilisant la structure de tableau suivante :
- Les éléments `asc` et `desc` spécifient comment trier selon l'attribut dans la direction croissante et décroissante, respectivement. Leurs valeurs représentent les colonnes réelles et les directions dans lesquelles les données sont triées. Vous pouvez spécifier une ou plusieurs colonnes pour préciser un tri simple ou un tri composite.
- L'élément `default` spécifie la direction dans laquelle l'attribut doit être trié lorsqu'il est initialement requis. Sa valeur par défaut est l'ordre croissant, ce qui signifie que si les données n'ont pas été triées auparavant et que vous demandez leur tri par cet attribut, elles sont triées par cette attribut dans la direction croissante.
- L'élément `label` spécifie quelle étiquette doit être utilisée lors de l'appel de [[yii\data\Sort::link()]] pour créer un lien de tri. Si cet élément n'est pas spécifié, la fonction [[yii\helpers\Inflector::camel2words()]] est appelée pour générer une étiquette à partir du nom de l'attribut. Notez que cette étiquette n'est pas encodée HTML.
> Info: vous pouvez fournir la valeur de [[yii\data\Sort::$orders|orders]] à la requête de base de données pour construire sa clause `ORDER BY`. N'utilisez pas [[yii\data\Sort::$attributeOrders|attributeOrders]], parce que certains attributs peuvent être composites et ne peuvent pas être reconnus par la requête de base de données.
Vous pouvez appeler [[yii\data\Sort::link()]] pour générer un hyperlien sur lequel l'utilisateur peut cliquer pour demander le tri des données selon l'attribut spécifié. Vous pouvez aussi appeler [[yii\data\Sort::createUrl()]] pour créer une URL susceptible d'être triée. Par exemple :
```php
// spécifie la route que l'URL à créer doit utiliser,
// si vous ne la spécifiez pas, la route couramment requise est utilisée
$sort->route = 'article/index';
// affiche des liens conduisant à trier par *name* (nom) et *age*, respectivement
echo $sort->link('name') . ' | ' . $sort->link('age');
// affiche : /index.php?r=article%2Findex&sort=age
echo $sort->createUrl('age');
```
[[yii\data\Sort]] vérifie le paramètre `sort` pour savoir quels attributs sont requis pour le tri. Vous pouvez spécifier un ordre de tri par défaut via [[yii\data\Sort::defaultOrder]] lorsque le paramètre de requête est absent. Vous pouvez aussi personnaliser le nom du paramètre de requête en configurant la porpriété [[yii\data\Sort::sortParam|sortParam]].
================================================
FILE: docs/guide-fr/runtime-bootstrapping.md
================================================
Amorçage
=============
L'amorçage fait référence au processus de préparation de l'environnement avant qu'une application ne démarre, pour résoudre et traiter une requête d'entrée. L'amorçage se fait en deux endroits : le [script d'entrée](structure-entry-scripts.md) et l'[application](structure-applications.md).
Dans le [script d'entrée](structure-entry-scripts.md), les classes de chargement automatique (*autoloaders*) pour différentes bibliothèques sont enregistrées. Cela inclut la classe de chargement automatique de Composer via son fichier `autoload.php` et la classe de chargement automatique de Yii via son fichier de classe `Yii`. Ensuite, le script d'entrée charge la [configuration](concept-configurations.md) de l'application et crée une instance d'[application](structure-applications.md).
Dans le constructeur de l'application, le travail d'amorçage suivant est effectué :
1. La méthode [[yii\base\Application::preInit()|preInit()]] est appelée. Elle configure quelques propriétés de haute priorité de l'application, comme [[yii\base\Application::basePath|le chemin de base (*basePath*)]].
2. Le [[yii\base\Application::errorHandler|gestionnaire d'erreurs]] est enregistré.
3. Les propriétés qui utilisent la configuration de l'application sont initialisées.
4. La méthode [[yii\base\Application::init()|init()]] est appelée. À son tour elle appelle la méthode [[yii\base\Application::bootstrap()|bootstrap()]] pour exécuter les composants d'amorçage.
- Le fichier de manifeste des extensions `vendor/yiisoft/extensions.php` est inclus.
- Les[composants d'amorçage](structure-extensions.md#bootstrapping-classes) déclarés par les extensions sont créés et exécutés
- Les [composants d'application(structure-application-components.md) et/ou les [modules](structure-modules.md) déclarés dans la [propriété bootstrap](structure-applications.md#bootstrap) de l'application sont créés et exécutés.
Comme le travail d'amorçage doit être fait avant *chacune* des requêtes, il est très important de conserver ce processus aussi léger et optimisé que possible.
Évitez d'enregistrer trop de composants d'amorçage. Un composant d'amorçage est seulement nécessaire s'il doit participer à tout le cycle de vie de la prise en charge des requêtes. Par exemple,si un module a besoin d'enregistrer des règles d'analyse additionnelles, il doit être listé dans la [propriété bootstrap](structure-applications.md#bootstrap) afin que les nouvelles règles d'URL prennent effet avant qu'elles ne soient utilisées pour résoudre des requêtes.
Dans le mode production, activez un cache bytecode, tel que [PHP OPcache] ou [APC], pour minimiser le temps nécessaire à l'inclusion et à l'analyse des fichiers PHP.
[PHP OPcache]: https://www.php.net/manual/fr/book.opcache.php
[APC]: https://www.php.net/manual/fr/book.apcu.php
Quelques applications volumineuses ont des [configurations](concept-configurations.md) d'application très complexes qui sont divisées en fichiers de configuration plus petits. Si c'est le cas, envisagez de mettre tout le tableau de configuration en cache et de le charger directement à partir cache avant la création de l'instance d'application dans le script d'entrée.
================================================
FILE: docs/guide-fr/runtime-handling-errors.md
================================================
Gestion des erreurs
===================
Yii inclut un [[yii\web\ErrorHandler|gestionnaire d'erreur]] pré-construit qui rend la gestion des erreurs bien plus agréable qu'auparavant. En particulier, le gestionnaire d'erreurs de Yii possède les fonctionnalités suivantes pour améliorer la gestion des erreurs.
* Toutes les erreurs PHP non fatales (p. ex. avertissements, notifications) sont converties en exceptions susceptibles d'être interceptées.
* Les exceptions et les erreurs fatales sont affichées avec les informations détaillées de la pile des appels et les lignes de code source en mode *debug*.
* Prise en charge de l'utilisation d'une [action de contrôleur](structure-controllers.md#actions) dédiée à l'affichage des erreurs.
* Prise en charge de différents formats de réponse d'erreur.
Le [[yii\web\ErrorHandler|gestionnaire d'erreur]] est activé par défaut. Vous pouvez le désactiver en définissant la constante `YII_ENABLE_ERROR_HANDLER` à `false` (faux) dans le [script d'entrée](structure-entry-scripts.md) de votre application.
## Utilisation du gestionnaire d'erreurs
Le [[yii\web\ErrorHandler|gestionnaire d'erreurs]] est enregistré en tant que [composant d'application](structure-application-components.md) nommé `errorHandler`. Vous pouvez le configurer dans la configuration de l'application comme indiqué ci-dessous :
```php
return [
'components' => [
'errorHandler' => [
'maxSourceLines' => 20,
],
],
];
```
Avec la configuration qui précède, le nombre de lignes de code source à afficher dans les pages d'exception est limité à 20.
Comme cela a déjà été dit, le gestionnaire d'erreur transforme toutes les erreurs PHP non fatales en exception susceptibles d'être interceptées. Cela signifie que vous pouvez utiliser le code suivant pour vous servir de cette gestion d'erreurs :
```php
use Yii;
use yii\base\ErrorException;
try {
10/0;
} catch (ErrorException $e) {
Yii::warning("Division by zero.");
}
// l'exécution continue...
```
Si vous désirez afficher une page d'erreur disant à l'utilisateur que sa requête est invalide ou inattendue, vous pouvez simplement lever une [[yii\web\HttpException|exception HTTP]], comme l'exception [[yii\web\NotFoundHttpException]]. Le gestionnaire d'erreurs définit alors correctement le code d'état HTTP de la réponse et utilise une vue d'erreur appropriée pour afficher le message d'erreur.
```php
use yii\web\NotFoundHttpException;
throw new NotFoundHttpException();
```
## Personnalisation de l'affichage des erreurs
Le [[yii\web\ErrorHandler|gestionnaire d'erreurs]] ajuste l'affichage de l'erreur en tenant compte de la valeur de la constante `YII_DEBUG`. Quand `YII_DEBUG` est égale à `true` (vrai) (ce qui signifie que le mode *debug* est activé), le gestionnaire d'erreurs affiche les exceptions avec le détail de la pile des appels et les lignes de code apportant de l'aide au débogage. Quand `YII_DEBUG` est égale à `false` (faux), seule le message d'erreur est affiché pour ne pas révéler des informations sensibles sur l'application.
> Info: si une exception est un descendant de la classe [[yii\base\UserException]], aucune pile des appels n'est affichée, et ceci indépendamment de la valeur `YII_DEBUG`. Cela tient au fait que de telles exceptions résultent d'erreurs commises par l'utilisateur et que les développeurs n'ont rien à corriger.
Par défaut, le [[yii\web\ErrorHandler|gestionnaire d'erreurs]] affiche les erreurs en utilisant deux [vues](structure-views.md):
* `@yii/views/errorHandler/error.php`: utilisée lorsque les erreurs doivent être affichées SANS les informations sur la pile des appels. Quand `YII_DEBUG` est égale à `false`, c'est la seule vue d'erreur à afficher.
* `@yii/views/errorHandler/exception.php`: utilisée lorsque les erreurs doivent être affichées AVEC les informations sur la pile des appels.
Vous pouvez configurer les propriétés [[yii\web\ErrorHandler::errorView|errorView]] et [[yii\web\ErrorHandler::exceptionView|exceptionView]] du gestionnaire d'erreur pour utiliser vos propres vues afin de personnaliser l'affichage des erreurs.
### Utilisation des actions d'erreurs
Une meilleure manière de personnaliser l'affichage des erreurs est d'utiliser des [actions](structure-controllers.md) d'erreur dédiées. Pour cela, commencez par configurer la propriété [[yii\web\ErrorHandler::errorAction|errorAction]] du composant `errorHandler` comme indiqué ci-après :
```php
return [
'components' => [
'errorHandler' => [
'errorAction' => 'site/error',
],
]
];
```
La propriété [[yii\web\ErrorHandler::errorAction|errorAction]] accepte une [route](structure-controllers.md#routes) vers une action. La configuration ci-dessus établit que lorsqu'une erreur doit être affichée sans information de la pile des appels, l'action `site/error` doit être exécutée.
Vous pouvez créer une action `site/error` comme ceci :
```php
namespace app\controllers;
use Yii;
use yii\web\Controller;
class SiteController extends Controller
{
public function actions()
{
return [
'error' => [
'class' => 'yii\web\ErrorAction',
],
];
}
}
```
Le code ci-dessus définit l'action `error` en utilisant la classe [[yii\web\ErrorAction]] qui rend une erreur en utilisant une vue nommée `error`.
En plus d'utiliser [[yii\web\ErrorAction]], vous pouvez aussi définir l'action `error` en utilisant une méthode d'action similaire à la suivante :
```php
public function actionError()
{
$exception = Yii::$app->errorHandler->exception;
if ($exception !== null) {
return $this->render('error', ['exception' => $exception]);
}
}
```
Vous devez maintenant créer un fichier de vue `views/site/error.php`. Dans ce fichier de vue, vous pouvez accéder aux variables suivantes si l'action d'erreur est définie en tant que [[yii\web\ErrorAction]]:
* `name`: le nom de l'erreur ;
* `message`: le message d'erreur ;
* `exception`: l'objet exception via lequel vous pouvez retrouver encore plus d'informations utiles telles que le code d'état HTTP, le code d'erreur, la pile des appels de l'erreur, etc.
> Info: si vous êtes en train d'utiliser le [modèle de projet *basic*](start-installation.md) ou le [modèle de projet avancé](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md), l'action d'erreur est la vue d'erreur sont déjà définies pour vous.
> Note: si vous avez besoin de rediriger dans un gestionnaire d'erreur, faites-le de la manière suivante :
>
> ```php
> Yii::$app->getResponse()->redirect($url)->send();
> return;
> ```
### Personnalisation du format de la réponse d'erreur
Le gestionnaire d'erreurs affiche les erreurs en respectant le réglage de format de la [réponse](runtime-responses.md). Si le [[yii\web\Response::format|format de la réponse]] est `html`, il utilise la vue d'erreur ou d'exception pour afficher les erreurs, comme c'est expliqué dans la sous-section précédente. Pour les autres formats de réponse, le gestionnaire d'erreurs assigne la représentation de l'erreur sous forme de tableau à la propriété [[yii\web\Response::data]] qui est ensuite convertie dans le format désiré. Par exemple, si le format de la réponse est `json`, vous pourriez voir une réponse similaire à la suivante :
```
HTTP/1.1 404 Not Found
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8
{
"name": "Not Found Exception",
"message": "The requested resource was not found.",
"code": 0,
"status": 404
}
```
Vous pouvez personnaliser le format de réponse d'erreur en répondant à l'événement `beforeSend` du composant `response` dans la configuration de l'application :
```php
return [
// ...
'components' => [
'response' => [
'class' => 'yii\web\Response',
'on beforeSend' => function ($event) {
$response = $event->sender;
if ($response->data !== null) {
$response->data = [
'success' => $response->isSuccessful,
'data' => $response->data,
];
$response->statusCode = 200;
}
},
],
],
];
```
Le code précédent formate la réponse d'erreur comme suit :
```
HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8
{
"success": false,
"data": {
"name": "Not Found Exception",
"message": "The requested resource was not found.",
"code": 0,
"status": 404
}
}
```
================================================
FILE: docs/guide-fr/runtime-logging.md
================================================
Enregistrements des messages
============================
Yii fournit une puissante base structurée (framework) d'enregistrement des messages qui est très personnalisable et extensible. En utilisant cette base structurée, vous pouvez facilement enregistrer des types variés de messages, les filtrer et les rassembler dans différentes cibles comme les bases de données et les courriels.
L'utilisation de la base structurée d'enregistrement des messages de Yii nécessite de suivre les étapes suivantes :
* Enregistrer les [messages](#log-messages) à différents endroits de votre code ;
* Configurer [cibles d'enregistrement](#log-targets) dans la configuration de l'application pour filtrer et exporter les messages enregistrés ;
* Examiner les messages enregistrés, filtrés et exportés par les différentes cibles (p. ex. [débogueur de Yii](tool-debugger.md)).
Dans cette section, nous décrivons principalement les deux premières étapes.
## Messages enregistrés
Enregistrer des messages est aussi simple que d'appeler une des méthodes suivantes :
* [[Yii::debug()]]: enregistre un message pour garder une trace de comment un morceau de code fonctionne. Cela est utilisé principalement en développement.
* [[Yii::info()]]: enregistre un message qui contient quelques informations utiles.
* [[Yii::warning()]]: enregistre un message d'avertissement qui indique que quelque chose d'inattendu s'est produit.
* [[Yii::error()]]: enregistre une erreur fatale qui doit être analysée dès que possible.
Ces méthodes enregistrent les messages à différents niveaux de sévérité et dans différentes catégories. Elles partagent la même signature `function ($message, $category = 'application')`, où `$message` représente le message à enregistrer, tandis que `$category` est la catégorie de ce message. Le code de l'exemple qui suit enregistre un message de trace dans la catégorie `application`:
```php
Yii::debug('start calculating average revenue');
```
> Info: les messages enregistrés peuvent être des chaînes de caractères aussi bien que des données complexes telles que des tableaux ou des objets. Il est de la responsabilité des [cibles d'enregistrement](#log-targets) de traiter correctement ces messages. Par défaut, si un message enregistré n'est pas un chaîne de caractères, il est exporté comme une chaîne de caractères en appelant la méthode [[yii\helpers\VarDumper::export()]].
Pour mieux organiser et filtrer les messages enregistrés, il est recommandé que vous spécifiiez une catégorie appropriée pour chacun des messages. Vous pouvez choisir une schéma de nommage hiérarchisé pour les catégories, ce qui facilitera le filtrage des messages par les [cibles d'enregistrement](#log-targets) sur la base de ces catégories. Un schéma de nommage simple et efficace est d'utiliser la constante magique `__METHOD__` de PHP dans les noms de catégorie. Par exemple :
```php
Yii::debug('start calculating average revenue', __METHOD__);
```
La constante magique `__METHOD__` est évaluée comme le nom de la méthode (préfixée par le nom pleinement qualifié de la classe), là où la constante apparaît. Par exemple, elle est égale à `'app\controllers\RevenueController::calculate'` si la ligne suivante est utilisée dans cette méthode.
> Info: les méthodes d'enregistrement décrites plus haut sont en fait des raccourcis pour la méthode [[yii\log\Logger::log()|log()]] de l'[[yii\log\Logger|objet logger]] qui est un singleton accessible via l'expression `Yii::getLogger()`. Lorsque suffisamment de messages ont été enregistrés, ou quand l'application se termine, l'objet *logger* appelle un [[yii\log\Dispatcher|distributeur de messages]] pour envoyer les messages enregistrés aux [cibles d'enregistrement](#log-targets).
## Cibles d'enregistrement
Une cible d'enregistrement est une instance de la classe [[yii\log\Target]] ou d'une de ses classe filles. Elle filtre les messages enregistrés selon leur degré de sévérité et leur catégorie et les exporte vers un média donné. Par exemple, une [[yii\log\DbTarget|cible base données]] exporte les messages enregistrés et filtrés vers une base de données, tandis qu'une [[yii\log\EmailTarget|cible courriel]] exporte les messages vers l'adresse de courriel spécifiée.
Vous pouvez enregistrer plusieurs cibles d'enregistrement dans votre application en les configurant, via le [composant d'application](structure-application-components.md)`log` dans la configuration de l'application, de la manière suivante :
```php
return [
// le composant "log" doit être chargé lors de la période d'amorçage
'bootstrap' => ['log'],
// le composant "log" traite les messages avec un horodatage (timestamp). Définissez le fuseau horaire PHP pour créer l'horodate correcte :
'timeZone' => 'America/Los_Angeles',
'components' => [
'log' => [
'targets' => [
[
'class' => 'yii\log\DbTarget',
'levels' => ['error', 'warning'],
],
[
'class' => 'yii\log\EmailTarget',
'levels' => ['error'],
'categories' => ['yii\db\*'],
'message' => [
'from' => ['log@example.com'],
'to' => ['admin@example.com', 'developer@example.com'],
'subject' => 'Database errors at example.com',
],
],
],
],
],
];
```
> Note: le composant `log` doit être chargé durant le [processus d'amorçage](runtime-bootstrapping.md) afin qu'il puisse distribuer les messages enregistrés aux cibles rapidement. C'est pourquoi il est listé dans le tableau `bootstrap` comme nous le montrons ci-dessus.
Dans le code précédent, deux cibles d'enregistrement sont enregistrées dan la propriété [[yii\log\Dispatcher::targets]] :
* la première cible sélectionne les messages d'erreurs et les avertissements et les sauvegarde dans une table de base de données ;
* la deuxième cible sélectionne les messages d'erreur dont le nom de la catégorie commence par `yii\db\`, et les envoie dans un courriel à la fois à `admin@example.com` et à `developer@example.com`.
Yii est fourni avec les cibles pré-construites suivantes. Reportez-vous à la documentation de l'API pour en savoir plus sur ces classes, en particulier comment les configurer et les utiliser.
* [[yii\log\DbTarget]]: stocke les messages enregistrés dans une table de base de données.
* [[yii\log\EmailTarget]]: envoie les messages enregistrés vers une adresse de courriel spécifiée préalablement.
* [[yii\log\FileTarget]]: sauvegarde les messages enregistrés dans des fichiers.
* [[yii\log\SyslogTarget]]: sauvegarde les messages enregistrés vers *syslog* en appelant la fonction PHP `syslog()`.
Dans la suite de ce document, nous décrivons les fonctionnalités communes à toutes les cibles d'enregistrement.
### Filtrage des messages
Vous pouvez configurer les propriétés [[yii\log\Target::levels|levels]] et [[yii\log\Target::categories|categories]] de chacune des cibles d'enregistrement pour spécifier les niveaux de sévérité et les catégories que la cible doit traiter.
La propriété [[yii\log\Target::levels|levels]] accepte un tableau constitué d'une ou plusieurs des valeurs suivantes :
* `error`: correspondant aux messages enregistrés par [[Yii::error()]].
* `warning`: correspondant aux messages enregistrés par [[Yii::warning()]].
* `info`: correspondant aux messages enregistrés par [[Yii::info()]].
* `trace`: correspondant aux messages enregistrés par [[Yii::debug()]].
* `profile`: correspondant aux messages enregistrés par [[Yii::beginProfile()]] et [[Yii::endProfile()]], et qui sera expliqué en détails dans la sous-section [Profilage de la performance](#performance-profiling).
Si vous ne spécifiez pas la propriété [[yii\log\Target::levels|levels]], cela signifie que la cible traitera les messages de *n'importe quel* niveau de sévérité.
La propriété [[yii\log\Target::categories|categories]] accepte un tableau constitué de noms ou de motifs de noms de catégorie de messages. Une cible ne traite
que les messages dont la catégorie est trouvée ou correspond aux motifs de ce tableau. Un motif de nom de catégorie est un préfixe de nom de catégorie
suivi d'une astérisque `*`. Un nom de catégorie correspond à un motif de nom de catégorie s'il commence par le préfixe du motif.
Par exemple, `yii\db\Command::execute` et `yii\db\Command::query` sont utilisés comme noms de catégorie pour les messages enregistrés dans la classe [[yii\db\Command]]. Ils correspondent tous deux au motif `yii\db\*`.
Si vous ne spécifiez pas la propriété [[yii\log\Target::categories|categories]], cela signifie que le cible traite les messages de *n'importe quelle* catégorie.
En plus d'inscrire des catégories en liste blanche via la propriété [[yii\log\Target::categories|categories]], vous pouvez également inscrire certaines catégories
en liste noire via la propriété [[yii\log\Target::except|except]]. Si la catégorie d'un message est trouvée ou correspond à un des motifs de cette propriété, ce message n'est PAS traité par la cible.
La configuration suivante de cible spécifie que la cible traitera les messages d'erreur ou d'avertissement des catégories dont le nom correspond soit à `yii\db\*`, soit `yii\web\HttpException:*`, mais pas `yii\web\HttpException:404`.
```php
[
'class' => 'yii\log\FileTarget',
'levels' => ['error', 'warning'],
'categories' => [
'yii\db\*',
'yii\web\HttpException:*',
],
'except' => [
'yii\web\HttpException:404',
],
]
```
> Info: lorsqu'une exception HTTP est capturée par le [gestionnaire d'erreur](runtime-handling-errors.md), un message d'erreur est enregistré avec un non de catégorie dont le format est `yii\web\HttpException:ErrorCode`. Par exemple, l'exception [[yii\web\NotFoundHttpException]] provoque un message d'erreur de catégorie `yii\web\HttpException:404`.
### Formatage des messages
Les cibles d'enregistrement exportent les messages enregistrés et filtrés dans un certain format. Par exemple, si vous installez une cible d'enregistrement de classe [[yii\log\FileTarget]], vous pouvez trouver un message enregistré similaire au suivant dans le fichier `runtime/log/app.log` file:
```
2014-10-04 18:10:15 [::1][][-][trace][yii\base\Module::getModule] Loading module: debug
```
Par défaut, les messages enregistrés sont formatés comme suit par la méthode [[yii\log\Target::formatMessage()]]:
```
Horodate [adresse IP][identifiant utilisateur][identifiant de session][niveau de sévérité][catégorie] Texte du message
```
Vous pouvez personnaliser ce format en configurant la propriété [[yii\log\Target::prefix]] qui accepte une fonction PHP appelable qui retourne un message de préfixe personnalisé. Par exemple, le code suivant configure une cible d'enregistrement pour qu'elle préfixe chaque message enregistré avec l'identifiant de l'utilisateur courant (l'adresse IP et l'identifiant de session étant retirés pour des raisons de protection de la vie privée).
```php
[
'class' => 'yii\log\FileTarget',
'prefix' => function ($message) {
$user = Yii::$app->has('user', true) ? Yii::$app->get('user') : null;
$userID = $user ? $user->getId(false) : '-';
return "[$userID]";
}
]
```
En plus des préfixes de messages, les cibles d'enregistrement ajoutent aussi quelques informations de contexte à chaque lot de messages enregistrés.
Par défaut, les valeurs de ces variables PHP globales sont incluses : `$_GET`, `$_POST`, `$_FILES`, `$_COOKIE`, `$_SESSION` et `$_SERVER`. Vous pouvez ajuster ce comportement en configurant la propriété [[yii\log\Target::logVars]] avec les noms des variables globales que vous voulez que la cible d'enregistrement inclue. Par exemple, la cible d'enregistrement suivante spécifie que seules les valeurs de la variable `$_SERVER` seront ajoutées aux messages enregistrés.
```php
[
'class' => 'yii\log\FileTarget',
'logVars' => ['_SERVER'],
]
```
Vous pouvez configurer `logVars` comme un tableau vide pour désactiver totalement l'inclusion d'informations de contexte. Ou si vous voulez mettre en œuvre votre propre façon de fournir les informations contextuelles, vous pouvez redéfinir la méthode [[yii\log\Target::getContextMessage()]].
### Niveaux de la trace de message
Lors du développement, vous cherchez souvent à voir d'où provient chacun des messages enregistrés. Cela est possible en configurant la propriété [[yii\log\Dispatcher::traceLevel|traceLevel]] du composant`log` de la façon suivante :
```php
return [
'bootstrap' => ['log'],
'components' => [
'log' => [
'traceLevel' => YII_DEBUG ? 3 : 0,
'targets' => [...],
],
],
];
```
La configuration de l'application ci-dessus statue que le [[yii\log\Dispatcher::traceLevel|niveau de trace ]] sera 3 si `YII_DEBUG` est activé et 0 si `YII_DEBUG` est désactivé. Cela veut dire que, si `YII_DEBUG` est activé, au plus trois niveaux de la pile des appels seront ajoutés à chaque message enregistré, là où le messages est enregistré ; et, si `YII_DEBUG` est désactivé, aucune information de la pile des appels ne sera incluse.
> Info: obtenir les informations de la pile des appels n'a rien de trivial. En conséquence, vous ne devriez utiliser cette fonctionnalité que durant le développement ou le débogage d'une application.
### Purge et exportation des messages
Comme nous l'avons dit plus haut, les messages enregistrés sont conservés dans un tableau par l'[[yii\log\Logger|objet *logger*]]. Pour limiter la consommation de mémoire par ce tableau, l'objet *logger* purge les messages enregistrés vers les [cibles d'enregistrement](#log-targets) chaque fois que leur nombre atteint une certaine valeur. Vous pouvez personnaliser ce nombre en configurant la propriété [[yii\log\Dispatcher::flushInterval|flushInterval]] du composant `log` :
```php
return [
'bootstrap' => ['log'],
'components' => [
'log' => [
'flushInterval' => 100, // default is 1000
'targets' => [...],
],
],
];
```
> Info: la purge des messages intervient aussi lorsque l'application se termine, ce qui garantit que les cibles d'enregistrement reçoivent des messages enregistrés complets.
Lorsque l'[[yii\log\Logger|objet *logger*]] purge les messages enregistrés vers les [cibles d'enregistrement](#log-targets), ils ne sont pas exportés immédiatement. Au lieu de cela, l'exportation des messages ne se produit que lorsque la cible d'enregistrement a accumulé un certain nombre de messages filtrés. Vous pouvez personnaliser ce nombre en configurant la propriété [[yii\log\Target::exportInterval|exportInterval]] de chacune des [cibles d'enregistrement](#log-targets), comme ceci :
```php
[
'class' => 'yii\log\FileTarget',
'exportInterval' => 100, // default is 1000
]
```
À cause des niveaux de purge et d'exportation, par défaut, lorsque vous appelez `Yii::debug()` ou toute autre méthode d'enregistrement, vous ne voyez PAS immédiatement le message enregistré dans la cible. Cela peut représenter un problème pour pour certaines applications de console qui durent longtemps. Pour faire en sorte que les messages apparaissent immédiatement dans les cibles d'enregistrement, vous devriez définir les propriétés [[yii\log\Dispatcher::flushInterval|flushInterval]] et [[yii\log\Target::exportInterval|exportInterval]] toutes deux à 1, comme montré ci-après :
```php
return [
'bootstrap' => ['log'],
'components' => [
'log' => [
'flushInterval' => 1,
'targets' => [
[
'class' => 'yii\log\FileTarget',
'exportInterval' => 1,
],
],
],
],
];
```
> Note: la purge et l'exportation fréquentes de vos messages dégradent la performance de votre application.
### Activation, désactivation des cibles d'enregistrement
Vous pouvez activer ou désactiver une cible d'enregistrement en configurant sa propriété [[yii\log\Target::enabled|enabled]]. Vous pouvez le faire via la configuration de la cible d'enregistrement ou en utilisant l'instruction suivante dans votre code PHP :
```php
Yii::$app->log->targets['file']->enabled = false;
```
Le code ci-dessus, nécessite que nommiez une cible `file`, comme montré ci-dessous en utilisant des clés sous forme de chaînes de caractères dans le tableau `targets` :
```php
return [
'bootstrap' => ['log'],
'components' => [
'log' => [
'targets' => [
'file' => [
'class' => 'yii\log\FileTarget',
],
'db' => [
'class' => 'yii\log\DbTarget',
],
],
],
],
];
```
### Création d'une cible d'enregistrement
La création d'une classe de cible d'enregistrement est très simple. Vous devez essentiellement implémenter [[yii\log\Target::export()]] en envoyant le contenu du tableau des [[yii\log\Target::messages]] vers un média désigné. Vous pouvez appeler la méthode [[yii\log\Target::formatMessage()]] pour formater chacun des messages. Pour plus de détails, reportez-vous à n'importe quelle classe de cible de messages incluse dans la version de Yii.
> Tip: au lieu de créer vos propres journaliseurs, vous pouvez essayez n'importe quel journaliseur compatible PSR-3 tel que [Monolog](https://github.com/Seldaek/monolog) en utilisant
[PSR log target extension](https://github.com/samdark/yii2-psr-log-target).
## Profilage de la performance
Le profilage de la performance est un type particulier d'enregistrement de messages qui est utilisé pour mesurer le temps d'exécution de certains blocs de code et pour déterminer les goulots d'étranglement. Par exemple, la classe [[yii\db\Command]] utilise le profilage de performance pour connaître le temps d'exécution de chacune des requêtes de base de données.
Pour utiliser le profilage de la performance, commencez par identifier les blocs de code qui ont besoin d'être profilés. Puis, entourez-les de la manière suivante :
```php
\Yii::beginProfile('myBenchmark');
...le bloc de code à profiler...
\Yii::endProfile('myBenchmark');
```
où `myBenchmark` représente un jeton unique identifiant un bloc de code. Plus tard, lorsque vous examinez le résultat du profilage, vous pouvez utiliser ce jeton pour localiser le temps d'exécution du bloc correspondant.
Il est important de vous assurer que les paires `beginProfile` et `endProfile` sont correctement imbriquées.
Par exemple,
```php
\Yii::beginProfile('block1');
// du code à profiler
\Yii::beginProfile('block2');
// un autre bloc de code à profiler
\Yii::endProfile('block2');
\Yii::endProfile('block1');
```
Si vous omettez `\Yii::endProfile('block1')` ou inversez l'ordre de `\Yii::endProfile('block1')` et de `\Yii::endProfile('block2')`, le profilage de performance ne fonctionnera pas.
Pour chaque bloc de code profilé, un message est enregistré avec le niveau de sévérité `profile`. Vous pouvez configurer une [cible d'enregistrement](#log-targets) pour collecter de tels messages et les exporter. L'outil [*Yii debugger*](tool-debugger.md) comporte un panneau d'affichage pré-construit des résultats de profilage.
================================================
FILE: docs/guide-fr/runtime-overview.md
================================================
Vue d'ensemble
==============
À chaque fois qu'une application Yii prend en charge une requête, elle entreprend un flux de travail similaire.
1. Un utilisateur effectue une requête auprès du [script d'entrée](structure-entry-scripts.md) `web/index.php`.
2. Le script d'entrée charge la [configuration](concept-configurations.md) de l'application et crée une instance d'[application](structure-applications.md) pour prendre en charge la requête.
3. L'application résoud la [route](runtime-routing.md) requise avec l'aide du composant d'application [request](runtime-requests.md).
4. L'application crée une instance de [contrôleur](structure-controllers.md) pour prendre en charge le requête.
5. Le contrôleur crée une instance d'[action](structure-controllers.md) et exécute les filtres de l'action.
6. Si un [filtre](structure-filters.md) échoue, l'exécution de l'action est annulée.
7. Si tous les filtres réussissent l'action est exécutée.
8. L'action charge un [modèle](structure-models.md) de données, possiblement à partir d'une base de données.
9. L'action rend une [vue](structure-views.md), en lui passant le modèle de données.
10. Le résultat rendu est retourné au composant d'application [response](runtime-responses.md).
11. Le composant *response* envoye le résultat rendu au navigateur de l'utilisateur.
Le diagramme ci-dessous illustre comment une application prend une requête en charge.
Dans cette section, nous décrivons en détails comment se déroulent quelques unes de ces étapes.
================================================
FILE: docs/guide-fr/runtime-requests.md
================================================
Requêtes
========
Les requêtes faites à l'application sont représentées en terme d'objets [[yii\web\Request]] qui fournissent des informations telles que les paramètres de requête, les entêtes HTTP, les cookies, etc.
Pour une requête donnée, vous avez accès au [composant d'application](structure-application-components.md)`request` qui, par défaut, est une instance de [[yii\web\Request]].
Dans cette section, nous décrivons comment utiliser ce composant dans vos applications.
## Paramètres de requête
Pour obtenir les paramètres de requête, vous pouvez appeler les méthodes [[yii\web\Request::get()|get()]] et [[yii\web\Request::post()|post()]] du composant `request` component.
Elles retournent les valeurs de `$_GET` et `$_POST`, respectivement. Pas exemple :
```php
$request = Yii::$app->request;
$get = $request->get();
// équivalent à : $get = $_GET;
$id = $request->get('id');
// équivalent à : $id = isset($_GET['id']) ? $_GET['id'] : null;
$id = $request->get('id', 1);
// équivalent à : $id = isset($_GET['id']) ? $_GET['id'] : 1;
$post = $request->post();
// équivalent à : $post = $_POST;
$name = $request->post('name');
// equivalent to: $name = isset($_POST['name']) ? $_POST['name'] : null;
$name = $request->post('name', '');
// équivalent à : $name = isset($_POST['name']) ? $_POST['name'] : '';
```
> Info: plutôt que d'accéder directement à `$_GET` et `$_POST` pour récupérer les paramètres de requête, il est recommandé de les obtenir via le composant `request` comme indiqué ci-dessus.
Cela rend l'écriture des tests plus facile parce que vous pouvez créer un simulacre de composant 'request' avec des données de requête factices.
Lorsque vous mettez en œuvre des [API pleinement REST](rest-quick-start.md), vous avez souvent besoin de récupérer les paramètres qui sont soumis via les [méthodes de requête](#request-methods) PUT, PATCH ou autre .
Vous pouvez obtenir ces paramètres en appelant la méthode [[yii\web\Request::getBodyParam()]]. par exemple :
```php
$request = Yii::$app->request;
// retourne tous les paramètres
$params = $request->bodyParams;
// retourne le paramètre "id"
$param = $request->getBodyParam('id');
```
> Info: à la différence des paramètres de `GET`, les paramètres soumis via `POST`, `PUT`, `PATCH` etc. sont envoyés dans le corps de la requête.
Le composant `request` analyse ces paramètres lorsque vous y accédez via les méthodes décrites ci-dessus.
Vous pouvez personnaliser la manière dont ces paramètres sont analysés en configurant la propriété [[yii\web\Request::parsers]].
## Méthodes de requête
Vous pouvez obtenir la méthode HTTP utilisée par la requête courante via l'expression `Yii::$app->request->method`.
Un jeu entier de propriétés booléennes est également fourni pour que vous puissiez déterminer le type de la méthode courante. Par exemple :
```php
$request = Yii::$app->request;
if ($request->isAjax) { /* la méthode de requête est requête AJAX */ }
if ($request->isGet) { /* la méthode de requête est requête GET */ }
if ($request->isPost) { /* la méthode de requête est requête POST */ }
if ($request->isPut) { /* la méthode de requête est requête PUT */ }
```
## URL de requête
Le composant `request` fournit plusieurs manières d'inspecter l'URL couramment requise.
En supposant que l'URL requise soit `https://example.com/admin/index.php/product?id=100`, vous pouvez obtenir différentes parties de cette URL comme c'est résumé ci-dessous :
* [[yii\web\Request::url|url]]: retourne`/admin/index.php/product?id=100`, qui est l'URL sans la partie hôte.
* [[yii\web\Request::absoluteUrl|absoluteUrl]]: retourne `https://example.com/admin/index.php/product?id=100`, qui est l'URL complète y compris la partie hôte.
* [[yii\web\Request::hostInfo|hostInfo]]: retourne `https://example.com`, qui est la partie hôte de l'URL.
* [[yii\web\Request::pathInfo|pathInfo]]: retourne `/product`, qui est la partie après le script d'entrée
et avant le point d'interrogation (chaîne de requête).
* [[yii\web\Request::queryString|queryString]]: retourne `id=100`, qui est la partie après le point d'interrogation.
* [[yii\web\Request::baseUrl|baseUrl]]: retourne `/admin`, qui est la partie après l'hôte
et avant le nom du script d'entrée.
* [[yii\web\Request::scriptUrl|scriptUrl]]: retourne `/admin/index.php`, qui set l'URL sans le chemin et la chaîne de requête.
* [[yii\web\Request::serverName|serverName]]: retourne `example.com`, qui est le nom d'hôte dans l'URL.
* [[yii\web\Request::serverPort|serverPort]]: retourne 80, qui est le numéro de port utilisé par le serveur Web.
## Entêtes HTTP
Vous pouvez obtenir les entêtes HTTP via la [[yii\web\HeaderCollection|collection d'entêtes]] qui est retournée par la propriété [[yii\web\Request::headers]]. Par exemple :
```php
// $headers est un objet yii\web\HeaderCollection
$headers = Yii::$app->request->headers;
// retourne la valeur de l'entête Accept
$accept = $headers->get('Accept');
if ($headers->has('User-Agent')) { /* il existe un entête User-Agent */ }
```
Le composant `request` fournit aussi la prise en charge de l'accès rapide à quelques entêtes couramment utilisés. Cela inclut :
* [[yii\web\Request::userAgent|userAgent]]: retourne la valeur de l'entête `User-Agent`.
* [[yii\web\Request::contentType|contentType]]: retourne la valeur de l'entête `Content-Type` qui indique le type MIME des données dans le corps de la requête.
* [[yii\web\Request::acceptableContentTypes|acceptableContentTypes]]: retourne les types MIME acceptés par l'utilisateur.
Les types retournés sont classés par ordre de score de qualité. Les types avec les plus hauts scores sont retournés en premier.
* [[yii\web\Request::acceptableLanguages|acceptableLanguages]]: retourne les langues acceptées par l'utilisateur.
Les langues retournées sont classées par niveau de préférence.
Le premier élément représente la langue préférée. Si votre application prend en charge plusieurs langues et que vous voulez afficher des pages dans la langue préférée de l'utilisateur, vous pouvez utiliser la méthode de négociation de la langue [[yii\web\Request::getPreferredLanguage()]].
Cette méthode accepte une liste des langues prises en charge par votre application, la compare avec les [[yii\web\Request::acceptableLanguages (langues acceptées)|acceptableLanguages]],
et retourne la langue la plus appropriée.
> Tip: vous pouvez également utiliser le filtre [[yii\filters\ContentNegotiator|ContentNegotiator]] pour déterminer dynamiquement quel type de contenu
et quelle langue utiliser dans la réponse.
Le filtre met en œuvre la négociation de contenu en plus des propriétés
et méthodes décrites ci-dessus.
## Informations sur le client
Vous pouvez obtenir le nom d'hôte et l'adresse IP de la machine cliente via [[yii\web\Request::userHost|userHost]]
et [[yii\web\Request::userIP|userIP]], respectivement.
Par exemple :
```php
$userHost = Yii::$app->request->userHost;
$userIP = Yii::$app->request->userIP;
## Mandataires de confiance et entêtes
Dans la section précédente, vous avez vu comment obtenir des informations sur l'utilisateur comme le nom d'hôte et l'adresse IP.
Cela fonctionne sans aucune configuration complémentaire dans une configuration normale dans laquelle une unique serveur Web est utilisé pour servir le site.
Cependant, si votre application s'exécute derrière un mandataire inverse, vous devez compléter la configuration pour retrouver ces informations car le client direct est désormais le mandataire
et l'adresse IP de l'utilisateur est passée à l'application Yii par une entête établie par le mandataire.
Vous ne devez pas faire confiance aveuglément aux entêtes fournies par un mandataire sauf si vous faites explicitement confiance à ce mandataire.
Depuis sa version 2.0.13, Yii prend en charge la configuration des mandataires de confiance via les propriétés
[[yii\web\Request::trustedHosts|trustedHosts]],
[[yii\web\Request::secureHeaders|secureHeaders]],
[[yii\web\Request::ipHeaders|ipHeaders]] and
[[yii\web\Request::secureProtocolHeaders|secureProtocolHeaders]]
du composant `request`.
Ce qui suit est la configuration d'une requête pour une application qui s'exécute derrière une tableau de mandataires inverses
situés dans le réseau IP `10.0.2.0/24` IP network:
```php
'request' => [
// ...
'trustedHosts' => [
'10.0.2.0/24',
],
],
```
L'adresse IP est envoyée par défaut par le mandataire dans l'entête `X-Forwarded-For` , et le protocole (`http` ou `https`) est envoyé dans `X-Forwarded-Proto`.
Dans le cas où vos mandataires utilisent différentes entêtes, vous pouvez utiliser la configuration de la requête pour les ajuster, p. ex. :
```php
'request' => [
// ...
'trustedHosts' => [
'10.0.2.0/24' => [
'X-ProxyUser-Ip',
'Front-End-Https',
],
],
'secureHeaders' => [
'X-Forwarded-For',
'X-Forwarded-Host',
'X-Forwarded-Proto',
'X-Proxy-User-Ip',
'Front-End-Https',
],
'ipHeaders' => [
'X-Proxy-User-Ip',
],
'secureProtocolHeaders' => [
'Front-End-Https' => ['on']
],
],
```
Avec la configuration précédente, toutes les entêtes listées dans `secureHeaders` sont filtrées de la requête à l'exception des entêtes `X-ProxyUser-Ip` et `Front-End-Https` pour le cas où la requête est élaborée par le mandataire.
Dans un tel cas, le précédent est utilisé pour retrouver l'adresse IP de l'utilisateur comme configuré dans `ipHeaders` et le dernier est utilisé pour déterminer le résultat de [[yii\web\Request::getIsSecureConnection()]].
```
================================================
FILE: docs/guide-fr/runtime-responses.md
================================================
Réponses
=========
Quand une application a terminé la prise en charge d'une [requête](runtime-requests.md), elle génère un objet [[yii\web\Response|response]] et l'envoie à l'utilisateur final. L'objet `response` contient des informations telles que le code d'état HTTP, les entêtes HTTP et le corps. Le but ultime du développement d'applications Web est essentiellement du construire de tels objets `response` pour des requêtes variées.
Dans la plupart des cas, vous devez travailler avec le [composant d'application](structure-application-components.md) `response` qui, par défaut, est une instance de [[yii\web\Response]]. Néanmoins, Yii vous permet également de créer vos propres objets `response` et de les envoyer à l'utilisateur final comme nous l'expliquons dans ce qui suit.
Dans cette section, nous décrivons comment composer et envoyer des réponses à l'utilisateur final.
## Code d'état
Une des premières choses que vous devez faire lorsque vous construisez une réponse est de déclarer si la requête a été correctement prise en charge ou pas. Cela se fait en définissant la propriété
[[yii\web\Response::statusCode|code d'état]]
qui peut prendre un des [codes d'état HTTP](https://tools.ietf.org/html/rfc2616#section-10) valides. Par exemple, pour indiquer que la requête a été prise en charge avec succès, vous pouvez définir le code à 200, comme ceci :
```php
Yii::$app->response->statusCode = 200;
```
Néanmoins, dans la plupart des cas, vous n'avez pas besoin de définir ce code explicitement. Cela tient au fait que la valeur par défaut de [[yii\web\Response::statusCode]] est 200. Et, si vous voulez indiquer que la prise en charge de la requête a échoué vous pouvez lever une exception appropriée comme ceci :
```php
throw new \yii\web\NotFoundHttpException;
```
Lorsque le [gestionnaire d'erreurs](runtime-handling-errors.md) intercepte l'exception, il extraie le code d'état de l'exception et l'assigne à la réponse. Concernant l'exception [[yii\web\NotFoundHttpException]] ci-dessus, elle est associée au code d'état HTTP 404. Les exception HTTP suivantes sont prédéfinies dans Yii :
* [[yii\web\BadRequestHttpException]]: code d'état 400.
* [[yii\web\ConflictHttpException]]: code d'état 409.
* [[yii\web\ForbiddenHttpException]]: code d'état 403.
* [[yii\web\GoneHttpException]]: code d'état 410.
* [[yii\web\MethodNotAllowedHttpException]]: code d'état 405.
* [[yii\web\NotAcceptableHttpException]]: code d'état 406.
* [[yii\web\NotFoundHttpException]]: code d'état 404.
* [[yii\web\ServerErrorHttpException]]: code d'état 500.
* [[yii\web\TooManyRequestsHttpException]]: code d'état 429.
* [[yii\web\UnauthorizedHttpException]]: code d'état 401.
* [[yii\web\UnsupportedMediaTypeHttpException]]: code d'état 415.
Si l'exception que vous voulez lever ne fait pas partie de cette liste, vous pouvez en créer une en étendant la classe [[yii\web\HttpException]], ou en en levant une à laquelle vous passez directement le code d'état. Par exemple :
```php
throw new \yii\web\HttpException(402);
```
## Entêtes HTTP
Vous pouvez envoyer les entêtes HTTP en manipulant la [[yii\web\Response::headers|collection d'entêtes]] dans le composant `response`. Par exemple :
```php
$headers = Yii::$app->response->headers;
// ajoute un entête Pragma . L'entête Pragma existant n'est PAS écrasé.
$headers->add('Pragma', 'no-cache');
// définit un entête Pragma. Tout entête Pragma existant est supprimé.
$headers->set('Pragma', 'no-cache');
// retire un (des) entêtes Pragma et retourne les valeurs de l'entête Pragma retiré dans un tableau
$values = $headers->remove('Pragma');
```
> Info: les noms d'entête ne sont pas sensibles à la casse. Les nouveaux entêtes enregistrés ne sont pas envoyés à l'utilisateur tant que la méthode [[yii\web\Response::send()]] n'est pas appelée.
## Corps de la réponse
La plupart des réponses doivent avoir un corps qui transporte le contenu que vous voulez montrer à l'utilisateur final.
Si vous disposez déjà d'une chaîne de caractères formatée pour le corps, vous pouvez l'assigner à la propriété [[yii\web\Response::content]] de la réponse. Par exemple :
```php
Yii::$app->response->content = 'hello world!';
```
Si vos données doivent être formatées avant l'envoi à l'utilisateur final, vous devez définir les propriétés [[yii\web\Response::format|format]] et [[yii\web\Response::data|data]]. La propriété [[yii\web\Response::format|format]] spécifie dans quel format les [[yii\web\Response::data|données]] doivent être formatées. Par exemple :
```php
$response = Yii::$app->response;
$response->format = \yii\web\Response::FORMAT_JSON;
$response->data = ['message' => 'hello world'];
```
De base, Yii prend en charge les formats suivants, chacun mis en œuvre par une classe [[yii\web\ResponseFormatterInterface|formatter]]. Vous pouvez personnaliser les formateurs ou en ajouter de nouveaux en configurant la propriété [[yii\web\Response::formatters]].
* [[yii\web\Response::FORMAT_HTML|HTML]]: mise en œuvre par [[yii\web\HtmlResponseFormatter]].
* [[yii\web\Response::FORMAT_XML|XML]]: mise en œuvre par [[yii\web\XmlResponseFormatter]].
* [[yii\web\Response::FORMAT_JSON|JSON]]: mise en œuvre par [[yii\web\JsonResponseFormatter]].
* [[yii\web\Response::FORMAT_JSONP|JSONP]]: mise en œuvre par [[yii\web\JsonResponseFormatter]].
* [[yii\web\Response::FORMAT_RAW|RAW]]: utilisez ce format si vous voulez envoyer la réponse directement sans lui appliquer aucun formatage.
Bien que le corps de la réponse puisse être défini explicitement comme montré ci-dessus, dans la plupart des cas, vous pouvez le définir implicitement en utilisant la valeur retournée par les méthodes d'[action](structure-controllers.md). Un cas d'usage courant ressemble à ceci :
```php
public function actionIndex()
{
return $this->render('index');
}
```
L'action `index` ci-dessus retourne le résultat du rendu de la vue `index`. La valeur de retour est interceptée par le composant `response`, formatée et envoyée à l'utilisateur final.
Parce que le format par défaut de la réponse est [[yii\web\Response::FORMAT_HTML|HTML]], vous devez seulement retourner un chaîne de caractères dans une méthode d'action. Si vous utilisez un format de réponse différent, vous devez le définir avant de retourner les donnés. Par exemple :
```php
public function actionInfo()
{
\Yii::$app->response->format = \yii\web\Response::FORMAT_JSON;
return [
'message' => 'hello world',
'code' => 100,
];
}
```
Comme mentionné plus haut, en plus d'utiliser le composant d'application `response`, vous pouvez également créer vos propres objets `response` et les envoyer à l'utilisateur final. Vous pouvez faire cela en retournant un tel objet dans une méthode d'action, comme le montre l'exemple suivant :
```php
public function actionInfo()
{
return \Yii::createObject([
'class' => 'yii\web\Response',
'format' => \yii\web\Response::FORMAT_JSON,
'data' => [
'message' => 'hello world',
'code' => 100,
],
]);
}
```
> Note : si vous êtes en train de créer vos propres objets `response`, vous ne pourrez par bénéficier des configurations que vous avez établies pour le composant `response` dans la configuration de l'application. Vous pouvez néanmoins, utiliser l'[injection de dépendances](concept-di-container.md) pour appliquer une configuration commune à vos nouveaux objets `response`.
## Redirection du navigateur
La redirection du navigateur s'appuie sur l'envoi d'un entête HTTP `Location`. Comme cette fonctionnalité est couramment utilisée, Yii fournit une prise en charge spéciale pour cela.
Vous pouvez rediriger le navigateur sur une URL en appelant la méthode [[yii\web\Response::redirect()]]. Cette méthode définit l'entête `Location` approprié avec l'URL donnée et retourne l'objet `response` lui-même. Dans une méthode d'action vous pouvez appeler sa version abrégée [[yii\web\Controller::redirect()]]. Par exemple :
```php
public function actionOld()
{
return $this->redirect('https://example.com/new', 301);
}
```
Dans le code précédent, la méthode d'action retourne le résultat de la méthode `redirect()`. Comme expliqué ci-dessus, l'objet `response` retourné par une méthode d'action est utilisé en tant que réponse à envoyer à l'utilisateur final.
Dans des endroits autres que les méthodes d'action, vous devez appeler la méthode [[yii\web\Response::redirect()]] directement, suivi d'un appel chaîné à la méthode [[yii\web\Response::send()]] pour garantir qu'aucun contenu supplémentaire ne sera ajouté à la réponse.
```php
\Yii::$app->response->redirect('https://example.com/new', 301)->send();
```
> Info: par défaut la méthode [[yii\web\Response::redirect()]] définit le code d'état à 302 pour indiquer au navigateur que la ressource requise est *temporairement* située sous un URI différent. Vous pouvez passer un code 301 pour dire au navigateur que la ressource a été déplacée *de manière permanente*.
Lorsque la requête courante est une requête AJAX, l'envoi d'un entête `Location` ne provoque pas automatiquement une redirection du navigateur. Pour pallier ce problème, la méthode [[yii\web\Response::redirect()]] définit un entête `X-Redirect` avec l'URL de redirection comme valeur. Du côté client, vous pouvez écrire un code JavaScript pour lire l'entête et rediriger le navigateur sur l'URL transmise.
> Info: Yii est fourni avec un fichier JavaScript `yii.js` qui fournit un jeu d'utilitaires JavaScript, y compris l'utilitaire de redirection basé sur l'entête `X-Redirect`. Par conséquent, si vous utilisez ce fichier JavaScript (en enregistrant le paquet de ressources [[yii\web\YiiAsset]] ), vous n'avez rien à écrire pour prendre en charge la redirection AJAX.
De l'information complémentaire sur `yii.js` est disponible à la [section Scripts client](output-client-scripts.md#yii.js).
## Envoi de fichiers
Comme la redirection du navigateur, l'envoi de fichiers est une autre fonctionnalité qui s'appuie sur les entêtes HTTP spécifiques. Yii fournit un jeu de méthodes pour prendre en charge différents besoins d'envoi de fichiers. Elles assurent toutes la prise en charge de la plage d'entêtes HTTP.
* [[yii\web\Response::sendFile()]]: envoie un fichier existant à un client.
* [[yii\web\Response::sendContentAsFile()]]: envoie un chaîne de caractères en tant que fichier à un client.
* [[yii\web\Response::sendStreamAsFile()]]: envoie un flux de fichier existant en tant que fichier à un client.
Ces méthodes ont la même signature avec l'objet `response` comme valeur de retour. Si le fichier à envoyer est trop gros, vous devez envisager d'utiliser [[yii\web\Response::sendStreamAsFile()]] parce qu'elle fait un usage plus efficace de la mémoire. L'exemple qui suit montre comment envoyer un fichier dans une action de contrôleur.
```php
public function actionDownload()
{
return \Yii::$app->response->sendFile('path/to/file.txt');
}
```
Si vous appelez la méthode d'envoi de fichiers dans des endroits autres qu'une méthode d'action, vous devez aussi appeler la méthode [[yii\web\Response::send()]] immédiatement après pour garantir qu'aucun contenu supplémentaire ne sera ajouté à la réponse.
```php
\Yii::$app->response->sendFile('path/to/file.txt')->send();
```
Quelques serveurs Web assurent une prise en charge spéciale de l'envoi de fichiers appelée *X-Sendfile*. L'idée est de rediriger la requête d'un fichier sur le serveur Web qui sert directement le fichier. En conséquence, l'application Web peut terminer plus rapidement tandis que le serveur Web est en train d'envoyer le fichier. Pour utiliser cette fonctionnalité, vous pouvez appeler la méthode [[yii\web\Response::xSendFile()]]. La liste suivante résume, comment activer la fonctionnalité `X-Sendfile` pour quelques serveurs Web populaires :
- Apache: [X-Sendfile](https://tn123.org/mod_xsendfile)
- Lighttpd v1.4: [X-LIGHTTPD-send-file](https://redmine.lighttpd.net/projects/lighttpd/wiki/X-LIGHTTPD-send-file)
- Lighttpd v1.5: [X-Sendfile](https://redmine.lighttpd.net/projects/lighttpd/wiki/X-LIGHTTPD-send-file)
- Nginx: [X-Accel-Redirect](https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/)
- Cherokee: [X-Sendfile and X-Accel-Redirect](https://www.cherokee-project.com/doc/other_goodies.html#x-sendfile)
## Envoi de la réponse
Le contenu d'une réponse n'est pas envoyé à l'utilisateur tant que la méthode [[yii\web\Response::send()]] n'est pas appelée. Par défaut, cette méthode est appelée automatiquement à la fin de [[yii\base\Application::run()]]. Vous pouvez néanmoins appeler cette méthode explicitement pour forcer l'envoi de la réponse immédiatement.
La méthode [[yii\web\Response::send()]] entreprend les étapes suivantes pour envoyer la réponse :
1. Elle déclenche l'événement [[yii\web\Response::EVENT_BEFORE_SEND]].
2. Elle appelle [[yii\web\Response::prepare()]] pour formater [[yii\web\Response::data|les données de la réponse]] du [[yii\web\Response::content|contenu de la réponse]].
3. Elle déclenche l'événement [[yii\web\Response::EVENT_AFTER_PREPARE]].
4. Elle appelle la méthode [[yii\web\Response::sendHeaders()]] pour envoyer les entêtes HTTP enregistrés.
5. Elle appelle la méthode [[yii\web\Response::sendContent()]] pour envoyer le corps de la réponse.
6. Elle déclenche l'événement [[yii\web\Response::EVENT_AFTER_SEND]].
Après que la méthode [[yii\web\Response::send()]] est appelée une fois, tout appel suivant de cette méthode est ignoré. Cela signifie qu'une fois la réponse expédiée, vous ne pouvez lui ajouter aucun contenu.
Comme vous pouvez le voir, la méthode [[yii\web\Response::send()]] déclenche plusieurs événements utiles. En répondant à ces événements, il est possible d'ajuster ou d'enjoliver la réponse.
================================================
FILE: docs/guide-fr/runtime-routing.md
================================================
Routage et création d'URL
=========================
Lorsqu'une application Yii commence à traiter une URL objet d'une requête, sa première étape consiste à analyser cette URL
pour la résoudre en une [route](structure-controllers.md#routes).
La route est ensuite utilisée pour instancier l'[action de contrôleur](structure-controllers.md) correspondante pour la prise en charge de la requête. Ce processus est appelé *routage*.
Le processus inverse du routage, qui consiste à créer une URL à partir d'une route et des paramètres associés de la requête,
est appelé *création d'URL*. Lorsque l'URL créée est ensuite requise, le processus de routage est capable de la résoudre en la route originale
avec les paramètres de requête.
L'élément central en charge du routage et de la création d'URL est le [[yii\web\UrlManager|gestionnaire d'URL]], qui est enregistré en tant que [composant d'application](structure-application-components.md) sous le nom `urlManager`.
Le [[yii\web\UrlManager|gestionnaire d'URL]] fournit la méthode [[yii\web\UrlManager::parseRequest()|parseRequest()]] pour analyser une requête entrante et la résoudre en
une route et les paramètres de requête associés,
et la méthode [[yii\web\UrlManager::createUrl()|createUrl()]] pour
créer une URL en partant d'une route avec ses paramètres de requête associés.
En configurant le composant `urlManager` dans la configuration de l'application, vous pouvez laisser votre application reconnaître les formats d'URL arbitraires sans modifier le code existant de votre application.
Par exemple, vous pouvez utiliser le code suivant pour créer une URL pour l'action `post/view` :
```php
use yii\helpers\Url;
// Url::to() appelle UrlManager::createUrl() pour créer une URL
$url = Url::to(['post/view', 'id' => 100]);
```
Selon la configuration de `urlManager`, l'URL créée peut ressembler à l'une des URL suivantes (ou autre formats).
Et si l'URL est requise plus tard, elle sera toujours analysée pour revenir à la route originale et aux valeurs des paramètres de la requête.
```
/index.php?r=post%2Fview&id=100
/index.php/post/100
/posts/100
```
## Formats d'URL
Le [[yii\web\UrlManager|gestionnaire d'URL]] prend en charge deux formats d'URL :
- le format d'URL par défaut,
- le format d'URL élégantes.
Le format d'URL par défaut utilise un [[yii\web\UrlManager::$routeParam|paramètre de requête]] nommé `r` qui représente la route et les paramètres de requête normaux associés à la route.
Par exemple, l'URL `/index.php?r=post/view&id=100` represente la route `post/view` et le paramètre de requête `id` dont la valeur est 100.
Le format d'URL par défaut ne requiert aucune configuration du [[yii\web\UrlManager|gestionnaire d'URL]
et fonctionne dans toutes les configurations de serveur Web.
Le format d'URL élégantes utilise le chemin additionnel qui suit le nom du script d'entrée pour représenter la route et les paramètres de requête associés.
Par exemple, le chemin additionnel dans l'URL `/index.php/post/100` est `/post/100` qui, avec une [[yii\web\UrlManager::rules|règle d'URL]] appropriée, peut représenter la route `post/view` et le paramètre des requête `id` avec une valeur de 100 .
Pour utiliser le format d'URL élégantes,
vous devez définir un jeu de [[yii\web\UrlManager::rules|règles d'URL]]
en cohérence avec les exigences réelles sur la présentation d'une URL.
Vous pouvez passer d'un format d'URL à l'autre en inversant la propriété [[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]] du [[yii\web\UrlManager|gestionnaire d'URL]]
sans changer quoi que ce soit au code de votre application.
## Routage
Le routage se fait en deux étapes :
- La requête entrante est analysée et résolue en une route et les paramètres de requête associés.
- L'[action de contrôleur](structure-controllers.md#actions)
correspondant à la route analysée est créée pour prendre la requête en charge.
Lors de l'utilisation du format d'URL par défaut,
la résolution d'une requête en route est aussi simple que d'obtenir le paramètre nommé `r` de la méthode `GET`.
Lors de l'utilisation du format d'URL élégantes, le [[yii\web\UrlManager|gestionnaire d'URL] examine les [[yii\web\UrlManager::rules|règles d'URL]] enregistrées pour trouver une règle qui correspond et résoudre la requête en une route.
Si une telle règle n'est pas trouvée, une exception [[yii\web\NotFoundHttpException]]
est levée.
Une fois que la requête est résolue en une route, il est temps de créer l'action de contrôleur identifiée par la route.
La route est éclatée en de multiples parties par des barres obliques de division.
Par exemple, `site/index` est éclatée en `site` et `index`.
Chacune des parties est considérée comme un identifiant qui peut faire référence à un module, un contrôleur ou une action.
En partant de la première partie dans la route, l'application entreprend les étapes suivantes pour créer un module (s'il en existe un), un contrôleur et une action :
1. Définit l'application comme étant le module courant.
2. Vérifie si la [[yii\base\Module::controllerMap|table de mise en correspondance des contrôleurs]] du module courant contient l'identifiant courant.
Si c'est le cas, un objet *controller* est créé en respectant la configuration du contrôleur trouvé dans la table de mise en correspondance,
et on passe à l'étape 5 pour prendre en compte le reste de la route.
3. Vérifie si l'identifiant fait référence à un module listé dans la propriété [[yii\base\Module::modules|modules]] du module courant.
Si c'est le cas, un module est créé en respectant la configuration trouvée dans la liste des modules et on passe à l'étape 2
pour prendre en compte le reste de la route dans le contexte du nouveau module.
4. Traite l'identifiant comme un [identifiant de contrôleur](structure-controllers.md#controller-ids), crée un objet *controller*
et passe à l'étape suivante avec le reste de la route.
5. Le contrôleur recherche l'identifiant courant dans sa [[yii\base\Controller::actions()|table de mise en correspondance des actions]]. S'il le trouve, il crée une action respectant la configuration trouvée dans la table de mise en correspondance.
Autrement, le contrôleur essaye de créer une action en ligne dont le nom de méthode correspond à l' [identifiant d'action](structure-controllers.md#action-ids) courant.
Si une erreur se produit dans l'une des étapes décrites ci-dessus, une exception [[yii\web\NotFoundHttpException]] est levée, indiquant l'échec du processus de routage.
### Route par défaut
Quand une requête est analysée et résolue en une route vide, la route dite *route par défaut* est utilisée à sa place.
Par défaut, la route par défaut est `site/index`, qui fait référence à l'action `index` du contrôleur `site`.
Vous pouvez la personnaliser en configurant la propriété [[yii\web\Application::defaultRoute|defaultRoute]] de l'application dans la configuration de l'application comme indiqué ci-dessous :
```php
[
// ...
'defaultRoute' => 'main/index',
];
```
De façon similaire à la route par défaut de l'application, il existe aussi une route par défaut pour les modules.
Ainsi s'il existe un module `user` (utilisateur) et que la requête est résolue en la route `user`, la propriété [[yii\base\Module::defaultRoute|defaultRoute]] du module est utilisée pour déterminer le contrôleur.
Par défaut, le nom du contrôleur est `default`. Si aucune action n'est spécifiée dans la propriété [[yii\base\Module::defaultRoute|defaultRoute]],
la propriété [[yii\base\Controller::defaultAction|defaultAction]] du contrôleur est utilisée pour déterminer l'action.
Dans cet exemple, la route complète serait `user/default/index`.
### La route `attrape-tout`
Parfois, vous désirez mettre votre application Web en mode maintenance temporairement
et afficher la même page d'information pour toutes les requêtes. Il y a plusieurs moyens de faire cela.
L'une des manières les plus simples est de configurer la propriété [[yii\web\Application::catchAll]] dans la configuration de l'application comme indiqué ci-dessous :
```php
[
// ...
'catchAll' => ['site/offline'],
];
```
Avec la configuration ci-dessus, l'action `site/offline` est utilisée pour prendre toutes les requêtes entrantes en charge.
La propriété `catchAll` accepte un tableau dont le premier élément spécifie une route
et le reste des éléments des couples clé-valeur pour les paramètres [liés à l'action](structure-controllers.md#action-parameters).
> Info: le [panneau de débogage] ](https://github.com/yiisoft/yii2-debug/blob/master/docs/guide/README.md) de l'environnement de développement
ne fonctionne pas lorsque cette propriété est activée.
## Création d'URL
Yii fournit une méthode d'aide [[yii\helpers\Url::to()]] pour créer différentes sortes d'URL à partir de routes données et de leurs paramètres de requête associés.
Par exemple :
```php
use yii\helpers\Url;
// crée une URL d'une route: /index.php?r=post%2Findex
echo Url::to(['post/index']);
// crée une URL d'une route avec paramètres : /index.php?r=post%2Fview&id=100
echo Url::to(['post/view', 'id' => 100]);
// crée une URL avec ancre : /index.php?r=post%2Fview&id=100#content
echo Url::to(['post/view', 'id' => 100, '#' => 'content']);
// crée une URL absolue : https://www.example.com/index.php?r=post%2Findex
echo Url::to(['post/index'], true);
// crée une URL absolue en utilisant le schéma https : https://www.example.com/index.php?r=post%2Findex
echo Url::to(['post/index'], 'https');
```
Notez que dans l'exemple ci-dessus, nous supposons que le format d'URL est le format par défaut.
Si le format d'URL élégantes est activé, les URL créées sont différentes et respectent les [[yii\web\UrlManager::rules|règles d'URL]] en cours d'utilisation.
La route passée à la méthode [[yii\helpers\Url::to()]] est sensible au contexte.
Elle peut être soit *relative*, soit *absolue* et normalisée en respect des règles suivantes :
- Si la route est une chaîne vide, la [[yii\web\Controller::route|route]] couramment requise est utilisée ;
- Si la route ne contient aucune barre oblique de division, elle est considérée comme un identifiant d'action du contrôleur courant
et est préfixée par la valeur de l'identifiant [[\yii\web\Controller::uniqueId|uniqueId]] du contrôleur courant ;
- Si la route n'a pas de barre oblique de division en tête, elle est considérée comme une route relative au module courant
et préfixée par la valeur de l'identifiant [[\yii\base\Module::uniqueId|uniqueId]] du module courant.
À partir de la version 2.0.2, vous pouvez spécifier une route en terme d'[alias](concept-aliases.md). Si c'est le cas,
l'alias est d'abord converti en la route réelle qui est ensuite transformée en route absolue dans le respect des règles précédentes.
Par exemple, en supposant que le module courant est `admin` et que le contrôleur courant est `post`,
```php
use yii\helpers\Url;
// route couramment requise : /index.php?r=admin%2Fpost%2Findex
echo Url::to(['']);
// une route relative avec un identifiant d'action seulement : /index.php?r=admin%2Fpost%2Findex
echo Url::to(['index']);
// une route relative : /index.php?r=admin%2Fpost%2Findex
echo Url::to(['post/index']);
// une route absoulue : /index.php?r=post%2Findex
echo Url::to(['/post/index']);
// /index.php?r=post%2Findex suppose que l'alias "@posts" est défini comme "/post/index"
echo Url::to(['@posts']);
```
La méthode [[yii\helpers\Url::to()]] est mise en œuvre en appelant les méthodes [[yii\web\UrlManager::createUrl()|createUrl()]]
et [[yii\web\UrlManager::createAbsoluteUrl()|createAbsoluteUrl()]]
du [[yii\web\UrlManager|gestionnaire d'URL]].
Dans les quelques sous-sections suivantes, nous expliquons comment configurer le [[yii\web\UrlManager|gestionnaire d'URL]] pour personnaliser le format des URL créées.
La méthode [[yii\helpers\Url::to()]] prend aussi en charge la création d'URL qui n'ont **pas** de relation avec des routes particulières.
Au lieu de passer un tableau comme premier paramètre, vous devez, dans ce cas, passer une chaîne de caractères. Par exemple :
```php
use yii\helpers\Url;
// URL couramment requise : /index.php?r=admin%2Fpost%2Findex
echo Url::to();
// un alias d'URL: https://example.com
Yii::setAlias('@example', 'https://example.com/');
echo Url::to('@example');
// une URL absolue : https://example.com/images/logo.gif
echo Url::to('/images/logo.gif', true);
```
En plus de la méthode `to()`, la classe d'aide [[yii\helpers\Url]] fournit aussi plusieurs méthode pratiques de création d'URL.
Par exemple :
```php
use yii\helpers\Url;
// URL de page d'accueil: /index.php?r=site%2Findex
echo Url::home();
// URL de base, utile si l'application est déployée dans un sous-dossier du dossier Web racine
echo Url::base();
// l'URL canonique de l'URL couramment requise
// voir https://fr.wikipedia.org/wiki/%C3%89l%C3%A9ment_de_lien_canonique
echo Url::canonical();
// mémorise l'URL couramment requise et la retrouve dans les requêtes subséquentes
Url::remember();
echo Url::previous();
```
## Utilisation des URL élégantes
Pour utiliser les URL élégantes, configurez le composant `urlManager` dans la configuration de l'application comme indiqué ci-dessous :
```php
[
'components' => [
'urlManager' => [
'enablePrettyUrl' => true,
'showScriptName' => false,
'enableStrictParsing' => false,
'rules' => [
// ...
],
],
],
]
```
La propriété [[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]] est obligatoire car elle active/désactive le format d'URL élégantes. Le reste des propriétés est facultatif.
Néanmoins, leur configuration montrée plus haut est couramment utilisée.
* [[yii\web\UrlManager::showScriptName|showScriptName]]: cette propriété détermine si le script d'entrée doit être inclus dans l'URL créée.
Par exemple, au lieu de créer une URL `/index.php/post/100`,
en définissant cette propriété à `false`, l'URL `/post/100` est générée.
* [[yii\web\UrlManager::enableStrictParsing|enableStrictParsing]]: cette propriété détermine si l'analyse stricte est activée .
Si c'est le cas, l'URL entrante doit correspondre à au moins une des [[yii\web\UrlManager::rules|règles]] afin d'être traitée comme une requête valide, sinon une exception [[yii\web\NotFoundHttpException]] est levée.
Si l'analyse stricte est désactivée, lorsqu'aucune
[[yii\web\UrlManager::rules|règle]] ne correspond à l'URL requise,
la partie chemin de l'URL est considérée comme étant la route requise.
* [[yii\web\UrlManager::rules|rules]]: cette propriété contient une liste de règles spécifiant comme analyser et créer des URL.
C'est la propriété principale avec laquelle vous devez travailler afin de créer des URL dont le format satisfait les exigences particulières de votre application.
> Note: afin de cacher le nom du script d'entrée dans l'URL créée, en plus de définir la propriété
[[yii\web\UrlManager::showScriptName|showScriptName]]
à `false`, vous pouvez aussi configurer votre serveur Web de manière à ce qu'il puisse identifier correctement quel script PHP doit être exécuté lorsqu'une URL requise n'en précise aucun explicitement.
Si vous utilisez un serveur Apache ou nginx, vous pouvez vous reporter à la configuration recommandée décrite dans la section [Installation](start-installation.md#recommended-apache-configuration).
### Règles d'URL
Une règle d'URL est une classe mettant en œuvre l'interface [[yii\web\UrlRuleInterface]], généralement une instance de la classe [[yii\web\UrlRule]].
Chaque règle d'URL consiste en un motif utilisé pour être mis en correspondance avec la partie chemin de l'URL, une route, et quelques paramètres de requête.
Une règle d'URL peut être utilisée pour analyser une requête si son motif correspond à l'URL requise.
Une règle d'URL peut être utilisée pour créer une URL si sa route et le nom de ses paramètres de requête correspondent à ceux qui sont fournis.
Quand le format d'URL élégantes est activé, le [[yii\web\UrlManager|gestionnaire d'URL]] utilise les règles d'URL déclarées dans sa propriété
[[yii\web\UrlManager::rules|rules]] pour analyser les requêtes entrantes et créer des URL.
En particulier, pour analyser une requête entrante, le [[yii\web\UrlManager|gestionnaire d'URL]] examine les règles dans l'ordre de leur déclaration et cherche la *première* règle qui correspond à l'URL requise.
La règle correspondante est ensuite utilisée pour analyser l'URL et la résoudre en une route et ses paramètres de requête associés.
De façon similaire, pour créer une URL, le [[yii\web\UrlManager|gestionnaire d'URL]] cherche la première règle qui correspond à la route donnée et aux paramètres et l'utilise pour créer l'URL.
Vous pouvez configurer la propriété [[yii\web\UrlManager::rules]] sous forme de tableau dont les clés sont les [[yii\web\UrlRule::$pattern|motifs]]
et les valeurs, les [[yii\web\UrlRule::$route|routes]] correspondantes.
Chacune des paires motif-route construit une règle d'URL.
Par exemple, la configuration des [[yii\web\UrlManager::rules|règles]] suivante déclare deux règles d'URL.
La première correspond à l'URL `posts` et la met en correspondance avec la route `post/index`. La seconde correspond à une URL qui correspond à l'expression régulière `post/(\d+)` et la met en correspondance avec la route `post/view` et le paramètre nommé `id`.
```php
[
'posts' => 'post/index',
'post/' => 'post/view',
]
```
> Info: le motif dans une règle est utilisé pour correspondre à la partie chemin d'une URL.
Par exemple, la partie chemin de `/index.php/post/100?source=ad` est `post/100` (les barres obliques de division de début et de fin sont ignorées) et correspond au motif `post/(\d+)`.
En plus de déclarer des règles d'URL sous forme de paires motif-route, vous pouvez aussi les déclarer sous forme de tableaux de configuration.
Chacun des tableaux de configuration est utilisé pour configurer un simple objet règle d'URL.
C'est souvent nécessaire lorsque vous voulez configurer d'autres propriétés d'une règle d'URL. Par exemple :
```php
'rules' => [
// ...autres règles d'URL...
[
'pattern' => 'posts',
'route' => 'post/index',
'suffix' => '.json',
],
]
```
Par défaut, si vous ne spécifiez pas l'option `class` pour une configuration de règle,
elle prend la valeur par défaut [[yii\web\UrlRule]] qui est la valeur par défaut définie dans
[[yii\web\UrlManager::$ruleConfig]].
### Paramètres nommés
Une règle d'URL peut être associée à quelques paramètres de requête nommés qui sont spécifiés dans le motif et respectent le format ``,
dans lequel `ParamName` spécifie le nom du paramètre et `RegExp` est une expression régulière facultative utilisée pour établir la correspondance avec une valeur de paramètre.
Si `RegExp` n'est pas spécifié, cela signifie que la valeur du paramètre doit être une chaîne de caractères sans aucune barre oblique de division.
> Note: vous pouvez seulement spécifier des expressions régulières pour les paramètres. La partie restante du motif est considérée être du texte simple.
Lorsqu'une règle est utilisée pour analyser une URL,
elle remplit les paramètres associés avec les valeurs des parties de l'URL qui leur correspondent,
et ces paramètres sont rendus disponibles dans `$_GET` et plus tard dans le composant d'application `request`.
Lorsque la règle est utilisée pour créer une URL, elle prend les valeurs des paramètres fournis et les insère à l'endroit où ces paramètres sont déclarés.
Prenons quelques exemples pour illustrer comment les paramètres nommés fonctionnent. Supposons que nous ayons déclaré les règles d'URL suivantes :
```php
[
'posts//' => 'post/index',
'posts' => 'post/index',
'post/' => 'post/view',
]
```
Lorsque les règles sont utilisées pour analyser des URL :
- `/index.php/posts` est analysée et résolue en la route `post/index` en utilisant la deuxième règle ;
- `/index.php/posts/2014/php` est analysée et résolue en la route `post/index`, le paramètre `year` dont la valeur est 2014
et le paramètre `category` dont la valeur est `php` en utilisant la première règle ;
- `/index.php/post/100` est analysée et résolue en la route `post/view`
et le paramètre `id` dont la valeur est 100 en utilisant la troisième règle ;
- `/index.php/posts/php` provoque la levée d'une exception [[yii\web\NotFoundHttpException]] quand la propriété [[yii\web\UrlManager::enableStrictParsing]]
est définie à `true`, parce qu'elle ne correspond à aucun des motifs.
Si [[yii\web\UrlManager::enableStrictParsing]] est définie à `false` (la valeur par défaut), la partie chemin `posts/php` est retournée en tant que route. Cela provoque l'exécution de l'action correspondante si elle existe, ou lève une exception [[yii\web\NotFoundHttpException]] autrement.
Et quand les règles sont utilisées pour créer des URL :
- `Url::to(['post/index'])` crée `/index.php/posts` en utilisant la deuxième règle ;
- `Url::to(['post/index', 'year' => 2014, 'category' => 'php'])` crée `/index.php/posts/2014/php` en utilisant la première règle ;
- `Url::to(['post/view', 'id' => 100])` crée `/index.php/post/100` en utilisant la troisième règle ;
- `Url::to(['post/view', 'id' => 100, 'source' => 'ad'])` crée `/index.php/post/100?source=ad` en utilisant la troisième règle.
Comme le paramètre `source` n'est pas spécifié dans la règle, il est ajouté en tant que paramètre de requête à l'URL créée.
- `Url::to(['post/index', 'category' => 'php'])` crée `/index.php/post/index?category=php` en utilisant aucune des règles.
Notez que, aucune des règles n'étant utilisée, l'URL est créée en ajoutant simplement la route en tant que partie chemin
et tous les paramètres en tant que partie de la chaîne de requête.
### Paramétrage des routes
Vous pouvez inclure les noms des paramètres dans la route d'une règle d'URL. Cela permet à une règle d'URL d'être utilisée pour correspondre à de multiples routes.
Par exemple, les règles suivantes incluent les paramètres `controller` et `action` dans les routes.
```php
'rules' => [
'/create' => '/create',
'//' => '/',
'/' => '/view',
's' => '/index',
]
```
Pour analyser l'URL `/index.php/comment/100/update`, la deuxième règle s'applique et définit le paramètre `controller`
comme étant `comment` et le paramètre `action` comme étant `create`. La route `/` est par conséquent résolue comme `comment/update`.
De façon similaire, pour créer une URL à partir de la route `comment/index`, la dernière règle s'applique, ce qui donne l'URL `/index.php/comments`.
> Info: en paramétrant les routes, il est possible de réduire grandement le nombre de règles d'URL,
ce qui peut accroître significativement la performance du [[yii\web\UrlManager|gestionnaire d'URL]].
### Valeur par défaut des paramètres
Par défaut, tous les paramètres déclarés dans une règle sont requis.
Si une URL requise ne contient pas un paramètre particulier, ou si une URL est créée sans un paramètre particulier, la règle ne s'applique pas.
Pour rendre certains paramètres facultatifs, vous pouvez configurer la propriété [[yii\web\UrlRule::defaults|defaults]] de la règle.
Les paramètres listés dans cette propriété sont facultatifs et prennent les valeurs spécifiées lorsqu'elles ne sont pas fournies.
Dans la déclaration suivante d'une règle, les paramètres `page` et `tag` sont tous les deux facultatifs
et prennent la valeur 1 et vide, respectivement quand ils ne sont pas fournis.
```php
[
// ...autres règles...
[
'pattern' => 'posts//',
'route' => 'post/index',
'defaults' => ['page' => 1, 'tag' => ''],
],
]
```
La règle ci-dessus peut être utilisée pour analyser ou créer l'une quelconque des URL suivantes :
* `/index.php/posts`: `page` est 1, `tag` est ''.
* `/index.php/posts/2`: `page` est 2, `tag` est ''.
* `/index.php/posts/2/news`: `page` est 2, `tag` est `'news'`.
* `/index.php/posts/news`: `page` est 1, `tag` est `'news'`.
Sans les paramètres facultatifs, vous devriez créer quatre règles pour arriver au même résultat.
> Note: si [[yii\web\UrlRule::$pattern|pattern]] (motif) ne contient que des paramètres facultatifs et des barres obliques de division,
le premier paramètre peut être omis seulement si tous les autres paramètres le sont.
### Règles avec des noms de serveur
Il est possible d'inclure des noms de serveur Web dans le motif d'une règle d'URL. Cela est principalement utilisé lorsque votre application doit se comporter différemment selon le nom du serveur Web.
Par exemple, les règles suivantes analysent et résolvent l'URL `https://admin.example.com/login` en la route `admin/user/login`
et `https://www.example.com/login` en la route `site/login`.
```php
[
'https://admin.example.com/login' => 'admin/user/login',
'https://www.example.com/login' => 'site/login',
]
```
Vous pouvez aussi inclure des paramètres dans les noms de serveurs pour en extraire de l'information dynamique.
Par exemple, la règle suivante analyse et résout l'URL `https://en.example.com/posts` en la route `post/index` et le paramètre `language=en`.
```php
[
'http://.example.com/posts' => 'post/index',
]
```
Depuis la version 2.0.11, vous pouvez également utiliser des motifs relatifs au protocole qui marchent à la fois pour `http` et `https`.
La syntaxe est la même que ci-dessus mais en sautant la partie `http`, p. ex. `'//www.example.com/login' => 'site/login'`.
> Note: les règles avec des noms de serveur ne doivent **pas** comprendre le sous-dossier du script d'entrée dans leur motif.
Par exemple, si l'application est sous `https://www.example.com/sandbox/blog`, alors vous devez utiliser le motif `https://www.example.com/posts` au lieu de `https://www.example.com/sandbox/blog/posts`.
Cela permet à votre application d'être déployée sous n'importe quel dossier sans avoir à changer son code.
Yii détecte automatiquement l'URL de base de l'application.
### Suffixes d'URL
Vous désirez peut-être ajouter des suffixes aux URL pour des raisons variées.
Par exemple, vous pouvez ajouter `.html` aux URL de manière à ce qu'elles ressemblent à des URL de pages HTML statiques.
Vous pouvez aussi y ajouter `.json` pour indiquer le type de contenu attendu pour la réponse.
Vous pouvez faire cela en configurant la propriété [[yii\web\UrlManager::suffix]] dans la configuration de l'application comme ceci :
```php
[
// ...
'components' => [
'urlManager' => [
'enablePrettyUrl' => true,
// ...
'suffix' => '.html',
'rules' => [
// ...
],
],
],
]
```
La configuration ci-dessus permet au [[yii\web\UrlManager|gestionnaire d'URL]] de reconnaître les URL requises
et aussi de créer des URL avec le suffixe `.html`.
> Tip: vous pouvez définir `/` en tant que suffixe des URL de manière à ce que tous les URL se terminent par la barre oblique de division.
> Note: lorsque vous configurez un suffixe d'URL, si une URL requise ne contient pas ce suffixe, elle est considérée comme une URL non reconnue.
Cela est une pratique recommandée pour l'optimisation des moteurs de recherche (SE0 – Search Engine Optimization).
Parfois vous désirez utiliser des suffixes différents pour différentes URL.
Cela peut être fait en configurant la propriété [[yii\web\UrlRule::suffix|suffix]] des règles d'URL individuelles.
Lorsqu'une URL a cette propriété définie, elle écrase la valeur définie au niveau du [[yii\web\UrlManager|gestionnaire d'URL]].
Par exemple, la configuration suivante contient une règle d'URL personnalisée qui utilise `.json` en tant que suffixe à la place du suffixe défini globalement `.html`.
```php
[
'components' => [
'urlManager' => [
'enablePrettyUrl' => true,
// ...
'suffix' => '.html',
'rules' => [
// ...
[
'pattern' => 'posts',
'route' => 'post/index',
'suffix' => '.json',
],
],
],
],
]
```
### Méthodes HTTP
En mettant en œuvre des API pleinement REST, il est couramment nécessaire que la même URL puisse être résolue en différentes routes selon la méthode HTTP utilisée par la requête.
Cela peut être fait facilement en préfixant les motifs des règles avec les méthodes HTTP prises en charge.
Si une règle prend en charge plusieurs méthodes HTTP, il faut séparer les noms de méthode par une virgule.
Par exemple, les règles suivantes ont le même motif `post/` mais des méthodes HTTP différentes.
Une requête de `PUT post/100` est résolue en la route `post/update`, tandis que la requête de `GET post/100` en la route `post/view`.
```php
'rules' => [
'PUT,POST post/' => 'post/update',
'DELETE post/' => 'post/delete',
'post/' => 'post/view',
]
```
> Note: si une règle d'URL contient des méthodes HTTP dans son motif, la règle n'est utilisée qu'à des fins d'analyse sauf si `GET` fait partie des verbes spécifiés.
Elle est ignorée quand le [[yii\web\UrlManager|gestionnaire d'URL]] est sollicité pour créer une URL.
> Tip: pour simplifier le routage des API pleinement REST, Yii fournit la classe spéciale de règle d'URL [[yii\rest\UrlRule]]
qui est très efficace et prend en charge quelques fonctionnalités originales comme la pluralisation automatique des identifiants de contrôleur.
Pour plus de détails, reportez-vous à la section [Routage](rest-routing.md) dans le chapitre API pleinement REST.
### Ajout dynamique de règles
Des règles d'URL peuvent être ajoutées dynamiquement au [[yii\web\UrlManager|gestionnaire d'URL]].
Cela est souvent nécessaire pour les [modules](structure-modules.md) distribuables qui veulent gérer leurs propres règles d'URL.
Pour que les règles ajoutées dynamiquement prennent effet dans de processus de routage, vous devez les ajouter dans l'étape d'[amorçage](runtime-bootstrapping.md).
Pour les modules, cela signifie qu'ils doivent implémenter l'interface [[yii\base\BootstrapInterface]]
et ajouter les règles dans leur méthode [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] comme l'exemple suivant le montre :
```php
public function bootstrap($app)
{
$app->getUrlManager()->addRules([
// rule declarations here
], false);
}
```
Notez que vous devez également lister ces modules dans la propriété [[yii\web\Application::bootstrap]]
afin qu'ils puissent participer au processus d'[amorçage](runtime-bootstrapping.md).
### Création des classes règles
En dépit du fait que la classe par défaut [[yii\web\UrlRule]] est suffisamment flexible pour la majorité des projets,
il y a des situations dans lesquelles vous devez créer votre propres classes de règle.
Par exemple, dans un site Web de vendeur de voitures, vous désirerez peut-être prendre en charge des formats d'URL du type `/Manufacturer/Model`, où `Manufacturer` et `Model` doivent correspondre à quelques données stockées dans une base de données.
La classe de règle par défaut ne fonctionne pas dans ce cas car elle s'appuie sur des motifs déclarés de manière statique.
Vous pouvez créer les classes de règle d'URL suivantes pour résoudre ce problème :
```php
getPathInfo();
if (preg_match('%^(\w+)(/(\w+))?$%', $pathInfo, $matches)) {
// vérifie $matches[1] et $matches[3] pour voir si
// elles correspondent à un manufacturer et à un model dans la base de données
// si oui, définit $params['manufacturer'] et/ou $params['model']
// et retourne ['car/index', $params]
}
return false; // cette règle ne s'applique pas
}
}
```
Et utilisez la nouvelle classe de règle dans la configuration de [[yii\web\UrlManager::rules]] :
```php
[
// ...other rules...
[
'class' => 'app\components\CarUrlRule',
// ...configure d'autres propriétés...
],
]
```
## Normalisation d'URL
Depuis la version 2.0.10, le [[yii\web\UrlManager|gestionnaire d'URL]] peut être configuré pour utiliser le [[yii\web\UrlNormalizer|normalisateur d'URL]] pour prendre en compte les variations de la même URL, p. ex. avec et sans la barre oblique de division de fin.
Parce que, techniquement, `https://example.com/path`
et `https://example.com/path/` sont des URL différentes, servir le même contenu pour chacune d'elles peut dégrader le classement SEO.
Par défaut, le normalisateur fusionne les barres obliques de division consécutives, ajoute ou retire des barres de division de fin selon que le suffixe comporte une barre de division de fin ou pas, et redirige vers la version normalisée de l'URL en utilisant la [redirection permanente](https://fr.wikipedia.org/wiki/HTTP_301).
Le normalisateur peut être configuré globalement pour le gestionnaire d'URL ou individuellement pour chacune des règles — par défaut, chacune des règles utilise le normalisateur du gestionnaire d'URL.
Vous pouvez définir [[yii\web\UrlRule::$normalizer|UrlRule::$normalizer]] à `false` pour désactiver la normalisation pour une règle d'URL particulière.
Ce qui suit est un exemple de configuration pour le [[yii\web\UrlNormalizer|normalisateur d'URL]]:
```php
'urlManager' => [
'enablePrettyUrl' => true,
'showScriptName' => false,
'enableStrictParsing' => true,
'suffix' => '.html',
'normalizer' => [
'class' => 'yii\web\UrlNormalizer',
// utilise la redirection temporaire au lieu de la redirection permanente pour le débogage
'action' => UrlNormalizer::ACTION_REDIRECT_TEMPORARY,
],
'rules' => [
// ...autres règles...
[
'pattern' => 'posts',
'route' => 'post/index',
'suffix' => '/',
'normalizer' => false, // désactive le normalisateur pour cette règle
],
[
'pattern' => 'tags',
'route' => 'tag/index',
'normalizer' => [
// ne fusionne pas les barres obliques de division consécutives pour cette règle
'collapseSlashes' => false,
],
],
],
]
```
> Note: par défaut [[yii\web\UrlManager::$normalizer|UrlManager::$normalizer]] est désactivé.
Vous devez le configure explicitement pour activer la normalisation d'URL.
## Considérations de performance
Lors du développement d'une application Web complexe, il est important d'optimiser les règles d'URL afin que l'analyse des requêtes et la création d'URL prennent moins de temps.
En utilisant les routes paramétrées, vous pouvez réduire le nombre de règles d'URL, ce qui accroît significativement la performance.
Lors de l'analyse d'URL ou de la création d'URL, le [[yii\web\UrlManager|gestionnaire d'URL]] examine les règles d'URL dans l'ordre de leur déclaration. En conséquence, vous devez envisager d'ajuster cet ordre afin que les règles les plus spécifiques et/ou utilisées couramment soient placées avant les règles les moins utilisées.
Si quelques règles d'URL partagent le même préfixe dans leur motif ou dans leur route, vous pouvez envisager d'utiliser [[yii\web\GroupUrlRule]] pour qu'elles puissent être examinées plus efficacement par le [[yii\web\UrlManager|gestionnaire d'URL]] en tant que groupe.
Cela est souvent le cas quand votre application est composée de modules, chacun ayant son propre jeu de règles d'URL avec l'identifiant de module comme préfixe commun.
================================================
FILE: docs/guide-fr/runtime-sessions-cookies.md
================================================
Sessions et témoins de connexion
================================
Les sessions et les témoins de connexion permettent à des données d'être conservées à travers des requêtes multiples. Avec le langage PHP simple, vous pouvez y accéder via les variables globales `$_SESSION` et `$_COOKIE`, respectivement. Yii encapsule les sessions et les témoins de connexion sous forme d'objets et, par conséquent, vous permet d'y accéder d'une manière orientée objet avec des améliorations utiles.
## Sessions
Comme pour les [requêtes](runtime-requests.md) et les [réponses](runtime-responses.md), vous pouvez accéder aux sessions via le [composant d'application](structure-application-components.md) `session` qui, par défaut, est une instance de la classe [[yii\web\Session]].
### Ouverture et fermeture d'une session
Pour ouvrir et fermer une session, vous pouvez procéder comme suit :
```php
$session = Yii::$app->session;
// vérifie si une session est déjà ouverte
if ($session->isActive) ...
// ouvre une session
$session->open();
// ferme une session
$session->close();
// détruit toutes les données enregistrées dans une session.
$session->destroy();
```
Vous pouvez appeler les méthodes [[yii\web\Session::open()|open()]] et [[yii\web\Session::close()|close()]] plusieurs fois sans causer d'erreur ; en interne les méthodes commencent par vérifier si la session n'est pas déjà ouverte.
### Accès aux données de session
Pour accéder aux données stockées dans une session, vous pouvez procéder comme indiqué ci-après :
```php
$session = Yii::$app->session;
// obtient une variable de session. Les utilisations suivantes sont équivalentes :
$language = $session->get('language');
$language = $session['language'];
$language = isset($_SESSION['language']) ? $_SESSION['language'] : null;
// définit une variable de session variable. Les utilisations suivantes sont équivalentes :
$session->set('language', 'en-US');
$session['language'] = 'en-US';
$_SESSION['language'] = 'en-US';
// supprime une variable session. Les utilisations suivantes sont équivalentes :
$session->remove('language');
unset($session['language']);
unset($_SESSION['language']);
// vérifie si une session possède la variable 'language'. Les utilisations suivantes sont équivalentes :
if ($session->has('language')) ...
if (isset($session['language'])) ...
if (isset($_SESSION['language'])) ...
// boucle sur toutes les sessions. Les utilisations suivantes sont équivalentes :
foreach ($session as $name => $value) ...
foreach ($_SESSION as $name => $value) ...
```
> Info: lorsque vous accédez aux données d'une session via le composant `session`, une session est automatiquement ouverte si elle ne l'a pas déjà été. Cela est différent de l'accès aux données via la variable globale `$_SESSION`, qui réclame un appel préalable explicite de `session_start()`.
Lorsque vous travaillez avec les données de session qui sont des tableaux, le composant `session` possède une limitation qui vous empêche de modifier directement un des élément de ces tableaux. Par exemple :
```php
$session = Yii::$app->session;
// le code suivant ne fonctionne PAS
$session['captcha']['number'] = 5;
$session['captcha']['lifetime'] = 3600;
// le code suivant fonctionne :
$session['captcha'] = [
'number' => 5,
'lifetime' => 3600,
];
// le code suivant fonctionne également :
echo $session['captcha']['lifetime'];
```
Vous pouvez utiliser une des solutions de contournement suivantes pour résoudre ce problème :
```php
$session = Yii::$app->session;
// utiliser directement $_SESSION (assurez-vous que Yii::$app->session->open() a été appelée)
$_SESSION['captcha']['number'] = 5;
$_SESSION['captcha']['lifetime'] = 3600;
// obtenir le tableau complet d'abord, le modifier et le sauvegarder
$captcha = $session['captcha'];
$captcha['number'] = 5;
$captcha['lifetime'] = 3600;
$session['captcha'] = $captcha;
// utiliser un ArrayObject au lieu d'un tableau
$session['captcha'] = new \ArrayObject;
...
$session['captcha']['number'] = 5;
$session['captcha']['lifetime'] = 3600;
// stocker les données du tableau par une clé avec un préfixe commun
$session['captcha.number'] = 5;
$session['captcha.lifetime'] = 3600;
```
Pour une meilleure performance et une meilleure lisibilité du code, nous recommandons la dernière solution de contournement. Elle consiste, au lieu de stocker un tableau comme une donnée de session unique, à stocker chacun des éléments du tableau comme une variable de session qui partage le même préfixe de clé avec le reste des éléments de ce tableau.
### Stockage de session personnalisé
La classe par défaut [[yii\web\Session]] stocke les données de session sous forme de fichiers sur le serveur. Yii fournit également des classes de session qui mettent en œuvre des procédés de stockage différents. En voici la liste :
* [[yii\web\DbSession]]: stocke les données de session dans une base de données.
* [[yii\web\CacheSession]]: stocke les données de session dans un cache avec l'aide d'un [composant cache](caching-data.md#cache-components) configuré.
* [[yii\redis\Session]]: stocke les données de session en utilisant le médium de stockage [redis](https://redis.io/) as the storage medium.
* [[yii\mongodb\Session]]: stocke les données de session dans une base de données de documents [MongoDB](https://www.mongodb.com/).
Toutes ces classes de session prennent en charge le même jeu de méthodes d'API. En conséquence, vous pouvez changer de support de stockage sans avoir à modifier le code de votre application qui utilise ces sessions.
> Note: si vous voulez accéder aux données de session via `$_SESSION` quand vous êtes en train d'utiliser une session à stockage personnalisé, vous devez vous assurer que cette session a été préalablement démarrée via [[yii\web\Session::open()]]. Cela est dû au fait que les gestionnaires de stockage des sessions personnalisées sont enregistrés à l'intérieur de cette méthode.
> Note : si vous utilisez un stockage de session personnalisé, vous devez configurer le collecteur de déchets de session explicitement.
Quelques installations de PHP (p. ex. Debian) utilisent une probabilité de collecteur de déchets de 0 et nettoient les fichiers de session hors ligne dans une tâche de cron. Ce processus ne s'applique pas à votre stockage personnalisé, c'est pourquoi vous devez configurer
[[yii\web\Session::$GCProbability]] pour utiliser une valeur non nulle.
Pour savoir comment configurer et utiliser ces classes de composant, reportez-vous à leur documentation d'API. Ci-dessous, nous présentons un exemple de configuration de [[yii\web\DbSession]] dans la configuration de l'application pour utiliser une base de données en tant que support de stockage d'une session :
```php
return [
'components' => [
'session' => [
'class' => 'yii\web\DbSession',
// 'db' => 'mydb', // l'identifiant du composant d'application de la connexion à la base de données. Valeur par défaut : 'db'.
// 'sessionTable' => 'my_session', // nom de la table 'session' . Valeur par défaut : 'session'.
],
],
];
```
Vous devez aussi créer la base de données suivante pour stocker les données de session :
```sql
CREATE TABLE session
(
id CHAR(40) NOT NULL PRIMARY KEY,
expire INTEGER,
data BLOB
)
```
où 'BLOB' fait référence au type « grand objet binaire » (binary large objet — BLOB) de votre système de gestion de base de données (DBMS) préféré. Ci-dessous, vous trouverez les types de BLOB qui peuvent être utilisés par quelques DBMS populaires :
- MySQL: LONGBLOB
- PostgreSQL: BYTEA
- MSSQL: BLOB
> Note: en fonction des réglages de `session.hash_function` dans votre fichier php.ini, vous devez peut-être ajuster la longueur de la colonne `id`. Par exemple, si `session.hash_function=sha256`, vous devez utiliser une longueur de 64 au lieu de 40.
Cela peut être accompli d'une façon alternative avec la migration suivante :
```php
createTable('{{%session}}', [
'id' => $this->char(64)->notNull(),
'expire' => $this->integer(),
'data' => $this->binary()
]);
$this->addPrimaryKey('pk-id', '{{%session}}', 'id');
}
public function down()
{
$this->dropTable('{{%session}}');
}
}
```
### Donnés flash
Les données flash sont une sorte de données de session spéciale qui, une fois définies dans une requête, ne restent disponibles que durant la requête suivante et sont détruites automatiquement ensuite. Les données flash sont le plus communément utilisées pour mettre en œuvre des messages qui doivent être présentés une seule fois, comme les messages de confirmation affichés après une soumission réussie de formulaire.
Vous pouvez définir des données flash et y accéder via le composant d'application `session`. Par exemple :
```php
$session = Yii::$app->session;
// Request #1
// définit un message flash nommé "commentDeleted"
$session->setFlash('commentDeleted', 'Vous avez réussi la suppression de votre commentaire.');
// Request #2
// affiche le message flash nommé "commentDeleted"
echo $session->getFlash('commentDeleted');
// Request #3
// $result est faux puisque le message flash a été automatiquement supprimé
$result = $session->hasFlash('commentDeleted');
```
Comme les données de session ordinaires, vous pouvez stocker des données arbitraires sous forme de données flash.
Vous pouvez appeler [[yii\web\Session::setFlash()]], cela écrase toute donnée flash préexistante qui a le même nom. Pour ajouter une nouvelle donnée flash à un message existant, vous pouvez utiliser [[yii\web\Session::addFlash()]] à la place. Par exemple :
```php
$session = Yii::$app->session;
// Request #1
// ajoute un message flash nommé "alerts"
$session->addFlash('alerts', 'Vous avez réussi la suppression de votre commentaire');
$session->addFlash('alerts', 'Vous avez réussi l'ajout d'un ami.');
$session->addFlash('alerts', 'Vous êtes promu.');
// Request #2
// $alerts est un tableau de messages flash nommé "alerts"
$alerts = $session->getFlash('alerts');
```
> Note: évitez d'utiliser [[yii\web\Session::setFlash()]] en même temps que [[yii\web\Session::addFlash()]] pour des données flash de même nom. C'est parce que la deuxième méthode transforme automatiquement les données flash en tableau pour pouvoir y ajouter des données. En conséquence, quand vous appelez [[yii\web\Session::getFlash()]], vous pouvez parfois recevoir un tableau ou une chaîne de caractères selon l'ordre dans lequel ces méthodes ont été appelées.
> Tip: pour afficher des messages Flash vous pouvez utiliser l'objet graphique [[yii\bootstrap\Alert|bootstrap Alert]] de la manière suivante :
>
> ```php
> echo Alert::widget([
> 'options' => ['class' => 'alert-info'],
> 'body' => Yii::$app->session->getFlash('postDeleted'),
> ]);
> ```
## Témoins de connexion
Yii représente chacun des témoins de connexion sous forme d'objet de classe [[yii\web\Cookie]]. Les objets [[yii\web\Request]] et [[yii\web\Response]] contiennent une collection de témoins de connexion via la propriété nommée `cookies`. La collection de témoins de connexion dans le premier de ces objets est celle soumise dans une requête, tandis que celle du deuxième objet représente les témoins de connexion envoyés à l'utilisateur.
La partie de l'application qui traite la requête et la réponse directement est le contrôleur. Par conséquent, les témoins de connexion doivent être lus et envoyés dans le contrôleur.
### Lecture des témoins de connexion
Vous pouvez obtenir les témoins de connexion de la requête courante en utilisant le code suivant :
```php
// obtient la collection de témoins de connexion (yii\web\CookieCollection) du composant "request"
$cookies = Yii::$app->request->cookies;
// obtient la valeur du témoin de connexion "language". Si le témoin de connexion n'existe pas, retourne "en" par défaut.
$language = $cookies->getValue('language', 'en');
// une façon alternative d'obtenir la valeur du témoin de connexion "language"
if (($cookie = $cookies->get('language')) !== null) {
$language = $cookie->value;
}
// vous pouvez aussi utiliser $cookies comme un tableau
if (isset($cookies['language'])) {
$language = $cookies['language']->value;
}
// vérifie si un témoin de connexion "language" existe
if ($cookies->has('language')) ...
if (isset($cookies['language'])) ...
```
### Envoi de témoins de connexion
Vous pouvez envoyer des témoins de connexion à l'utilisateur final avec le code suivant :
```php
// obtient la collection de témoins de connexion (yii\web\CookieCollection) du composant "response"
$cookies = Yii::$app->response->cookies;
// ajoute un témoin de connexion à la réponse à envoyer
$cookies->add(new \yii\web\Cookie([
'name' => 'language',
'value' => 'zh-CN',
]));
// supprime un cookie
$cookies->remove('language');
// équivalent à
unset($cookies['language']);
```
En plus des propriétés [[yii\web\Cookie::name|name (nom)]], [[yii\web\Cookie::value|value (valeur)]] montrées dans les exemples ci-dessus, la classe [[yii\web\Cookie]] définit également d'autres propriétés pour représenter complètement toutes les informations de témoin de connexion disponibles, comme les propriétés [[yii\web\Cookie::domain|domain (domaine)]], [[yii\web\Cookie::expire|expire (date d'expiration)]]. Vous pouvez configurer ces propriété selon vos besoins pour préparer un témoin de connexion et ensuite l'ajouter à la collection de témoins de connexion de la réponse.
> Note: pour une meilleure sécurité, la valeur par défaut de la propriété [[yii\web\Cookie::httpOnly]] est définie à `true`. Cela permet de limiter le risque qu'un script client n'accède à un témoin de connexion protégé (si le navigateur le prend en charge). Reportez-vous à l'[article de wiki httpOnly](https://owasp.org/www-community/HttpOnly) pour plus de détails.
### Validation des témoins de connexion
Lorsque vous lisez ou envoyez des témoins de connexion via les composants `request` et `response` comme expliqué dans les sous-sections qui précèdent, vous appréciez la sécurité additionnelle de validation des témoins de connexion qui protège vos témoins de connexion de la modification côté client. Cela est réalisé en signant chacun des témoins de connexion avec une valeur de hachage qui permet à l'application de dire si un témoin de connexion a été modifié ou pas du côté client. Si c'est le cas, le témoin de connexion n'est PLUS accessible via la [[yii\web\Request::cookies|collection de témoins de connexion]] du composant `request`.
> Note: la validation des témoins de connexion ne protège que contre les effets de la modification des valeurs de témoins de connexion. Néanmoins, si un témoin de connexion ne peut être validé, vous pouvez continuer à y accéder via la variable globale `$_COOKIE`. Ceci est dû au fait que les bibliothèques de tierces parties peuvent manipuler les témoins de connexion d'une façon qui leur est propre, sans forcément impliquer la validation des témoins de connexion.
La validation des témoins de connexion est activée par défaut. Vous pouvez la désactiver en définissant la propriété [[yii\web\Request::enableCookieValidation]] à `false` (faux) mais nous vous recommandons fortement de ne pas le faire.
> Note: les témoins de connexion qui sont lus/écrits directement via `$_COOKIE` et `setcookie()` ne seront PAS validés.
Quand vous utilisez la validation des témoins de connexion, vous devez spécifier une [[yii\web\Request::cookieValidationKey |clé de validation des témoins de connexion]] gui sera utilisée pour générer la valeur de hachage dont nous avons parlé plus haut. Vous pouvez faire ça en configurant le composant `request` dans la configuration de l'application configuration comme indiqué ci-après :
```php
return [
'components' => [
'request' => [
'cookieValidationKey' => 'entrez une clé secrète ici',
],
],
];
```
> Info: la [[yii\web\Request::cookieValidationKey|clé de validation des témoins de connexion (cookieValidationKey)]] est un élément critique de la sécurité de votre application. Elle ne devrait être connue que des personnes à qui vous faites confiance. Ne le stockez pas dans le système de gestion des version.
================================================
FILE: docs/guide-fr/security-authentication.md
================================================
Authentification
================
L'authentification est le processus qui consiste à vérifier l'identité d'un utilisateur. Elle utilise ordinairement un identifiant (p. ex. un nom d'utilisateur ou une adresse de courriels) et un jeton secret (p. ex. un mot de passe ou un jeton d'accès) pour juger si l'utilisateur est bien qui il prétend être. L'authentification est à la base de la fonctionnalité de connexion.
Yii fournit une base structurée d'authentification qui interconnecte des composants variés pour prendre en charge la connexion. Pour utiliser cette base structurée, vous devez essentiellement accomplir les tâches suivantes :
* Configurer le composant d'application [[yii\web\User|user]] ;
* Créer une classe qui implémente l'interface [[yii\web\IdentityInterface]].
## Configuration de [[yii\web\User]]
Le composant d'application [[yii\web\User|user]] gère l'état d'authentification de l'utilisateur. Il requiert que vous spécifiiez une [[yii\web\User::identityClass|classe d'identité]] contenant la logique réelle d'authentification.
Dans la configuration suivante de l'application, la [[yii\web\User::identityClass|classe d'identité]] pour [[yii\web\User|user]] est configurée sous le nom `app\models\User` dont la mise en œuvre est expliquée dans la sous-section suivante :
```php
return [
'components' => [
'user' => [
'identityClass' => 'app\models\User',
],
],
];
```
## Mise en œuvre de [[yii\web\IdentityInterface]]
La [[yii\web\User::identityClass|classe d'identité]] doit implémenter l'interface [[yii\web\IdentityInterface]] qui comprend les méthodes suivantes :
* [[yii\web\IdentityInterface::findIdentity()|findIdentity()]]: cette méthode recherche une instance de la classe d'identité à partir de l'identifiant utilisateur spécifié. Elle est utilisée lorsque vous devez conserver l'état de connexion via et durant la session.
* [[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]]: cette méthode recherche une instance de la classe d'identité à partir du jeton d'accès spécifié. Elle est utilisée lorsque vous avez besoin d'authentifier un utilisateur par un jeton secret (p. ex. dans une application pleinement REST sans état).
* [[yii\web\IdentityInterface::getId()|getId()]]: cette méthode retourne l'identifiant de l'utilisateur que cette instance de la classe d'identité représente.
* [[yii\web\IdentityInterface::getAuthKey()|getAuthKey()]]: cette méthode retourne une clé utilisée pour vérifier la connexion basée sur les témoins de connexion (*cookies*). La clé est stockée dans le témoin de connexion `login` et est ensuite comparée avec la version côté serveur pour s'assurer que le témoin de connexion est valide.
* [[yii\web\IdentityInterface::validateAuthKey()|validateAuthKey()]]: cette méthode met en œuvre la logique de vérification de la clé de connexion basée sur les témoins de connexion.
Si une méthode particulière n'est pas nécessaire, vous devez l'implémenter avec un corps vide. Par exemple, si votre application est une application sans état et pleinement REST, vous devez seulement implémenter [[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]] et [[yii\web\IdentityInterface::getId()|getId()]] et laisser toutes les autres méthodes avec un corps vide.
Dans l'exemple qui suit, une [[yii\web\User::identityClass|classe d'identité]] est mise en œuvre en tant que classe [Active Record](db-active-record.md) associée à la table de base de données `user`.
```php
$token]);
}
/**
* @return int|string l'identifiant de l'utilisateur courant
*/
public function getId()
{
return $this->id;
}
/**
* @return string la clé d'authentification de l'utilisateur courant
*/
public function getAuthKey()
{
return $this->auth_key;
}
/**
* @param string $authKey
* @return bool si la clé d'authentification est valide pour l'utilisateur courant
*/
public function validateAuthKey($authKey)
{
return $this->getAuthKey() === $authKey;
}
}
```
Comme nous l'avons expliqué précédemment, vous devez seulement implémenter `getAuthKey()` et `validateAuthKey()` si votre application utilise la fonctionnalité de connexion basée sur les témoins de connexion. Dans ce cas, vous devez utiliser le code suivant pour générer une clé d'authentification pour chacun des utilisateurs et la stocker dans la table `user` :
```php
class User extends ActiveRecord implements IdentityInterface
{
......
public function beforeSave($insert)
{
if (parent::beforeSave($insert)) {
if ($this->isNewRecord) {
$this->auth_key = \Yii::$app->security->generateRandomString();
}
return true;
}
return false;
}
}
```
> Note: ne confondez pas la classe d'identité `User` avec la classe [[yii\web\User]]. La première est la classe mettant en œuvre la logique d'authentification. Elle est souvent mise en œuvre sous forme de classe [Active Record](db-active-record.md) associée à un moyen de stockage persistant pour conserver les éléments d'authentification de l'utilisateur. La deuxième est une classe de composant d'application qui gère l'état d'authentification de l'utilisateur.
## Utilisation de [[yii\web\User]]
Vous utilisez [[yii\web\User]] essentiellement en terme de composant d'application `user`.
Vous pouvez détecter l'identité de l'utilisateur courant en utilisant l'expression `Yii::$app->user->identity`. Elle retourne une instance de la [[yii\web\User::identityClass|classe d'identité]] représentant l'utilisateur connecté actuellement ou `null` si l'utilisateur courant n'est pas authentifié (soit un simple visiteur). Le code suivant montre comment retrouver les autres informations relatives à l'authentification à partir de [[yii\web\User]]:
```php
// l'identité de l'utilisateur courant. Null si l'utilisateur n'est pas authentifié.
$identity = Yii::$app->user->identity;
// l'identifiant de l'utilisateur courant. Null si l'utilisateur n'est pas authentifié.
$id = Yii::$app->user->id;
// si l'utilisateur courant est un visiteur (non authentifié).
$isGuest = Yii::$app->user->isGuest;
```
Pour connecter un utilisateur, vous devez utiliser le code suivant :
```php
// trouve une identité d'utilisateur à partir du nom d'utilisateur spécifié
// notez que vous pouvez vouloir vérifier le mot de passe si besoin.
$identity = User::findOne(['username' => $username]);
// connecte l'utilisateur
Yii::$app->user->login($identity);
```
La méthode [[yii\web\User::login()]] assigne l'identité de l'utilisateur courant à [[yii\web\User]]. Si la session est [[yii\web\User::enableSession|activée]], elle conserve l'identité de façon à ce que l'état d'authentification de l'utilisateur soit maintenu durant la session tout entière. Si la connexion basée sur les témoins de connexion (*cookies*) est [[yii\web\User::enableAutoLogin|activée]], elle sauvegarde également l'identité dans un témoin de connexion de façon à ce que l'état d'authentification de l'utilisateur puisse être récupéré du témoin de connexion durant toute la période de validité du témoin de connexion.
Pour activer la connexion basée sur les témoins de connexion, vous devez configurer [[yii\web\User::enableAutoLogin]] à `true` (vrai) dans la configuration de l'application. Vous devez également fournir une durée de vie lorsque vous appelez la méthode [[yii\web\User::login()]].
Pour déconnecter un utilisateur, appelez simplement
```php
Yii::$app->user->logout();
```
Notez que déconnecter un utilisateur n'a de sens que si la session est activée. La méthode nettoie l'état d'authentification de l'utilisateur à la fois de la mémoire et de la session. Et, par défaut, elle détruit aussi *toutes* les données de session. Si vous voulez conserver les données de session, vous devez appeler `Yii::$app->user->logout(false)`, à la place.
## Événement d'authentification
La classe [[yii\web\User]] lève quelques événements durant le processus de connexion et celui de déconnexion.
* [[yii\web\User::EVENT_BEFORE_LOGIN|EVENT_BEFORE_LOGIN]]: levé au début de [[yii\web\User::login()]].
Si le gestionnaire d'événement définit la propriété [[yii\web\UserEvent::isValid|isValid]] de l'objet événement à `false` (faux), le processus de connexion avorte.
* [[yii\web\User::EVENT_AFTER_LOGIN|EVENT_AFTER_LOGIN]]: levé après une connexion réussie.
* [[yii\web\User::EVENT_BEFORE_LOGOUT|EVENT_BEFORE_LOGOUT]]: levé au début de [[yii\web\User::logout()]].
Si le gestionnaire d'événement définit la propriété [[yii\web\UserEvent::isValid|isValid]] à `false` (faux) le processus de déconnexion avorte.
* [[yii\web\User::EVENT_AFTER_LOGOUT|EVENT_AFTER_LOGOUT]]: levé après une déconnexion réussie.
Vous pouvez répondre à ces événements pour mettre en œuvre des fonctionnalités telles que l'audit de connexion, les statistiques d'utilisateurs en ligne. Par exemple, dans le gestionnaire pour l'événement [[yii\web\User::EVENT_AFTER_LOGIN|EVENT_AFTER_LOGIN]], vous pouvez enregistrer le temps de connexion et l'adresse IP dans la tale `user`.
================================================
FILE: docs/guide-fr/security-authorization.md
================================================
Autorisation
=============
L'autorisation est le processus qui vérifie si un utilisateur dispose des permissions suffisantes pour faire quelque chose. Yii fournit deux méthodes d'autorisation : le filtre de contrôle d'accès (ACF — Access Control Filter) et le contrôle d'accès basé sur les rôles (RBAC — Role-Based Access Control).
## Filtre de contrôle d'accès
Le filtre de contrôle d'accès (ACF) est une simple méthode d'autorisation mise en œuvre sous le nom [[yii\filters\AccessControl]] qui trouve son meilleur domaine d'application dans les applications qui n'ont besoin que d'un contrôle d'accès simplifié. Comme son nom l'indique, le filtre de contrôle d'accès est un [filtre](structure-filters.md) d'action qui peut être utilisé dans un contrôleur ou dans un module. Quand un utilisateur requiert l'exécution d'une action, le filtre de contrôle d'accès vérifie une liste de [[yii\filters\AccessControl::rules|règles d'accès]] pour déterminer si l'utilisateur est autorisé à accéder à l'action requise.
Le code ci-dessous montre comment utiliser le filtre de contrôle d'accès dans le contrôleur `site` :
```php
use yii\web\Controller;
use yii\filters\AccessControl;
class SiteController extends Controller
{
public function behaviors()
{
return [
'access' => [
'class' => AccessControl::class,
'only' => ['login', 'logout', 'signup'],
'rules' => [
[
'allow' => true,
'actions' => ['login', 'signup'],
'roles' => ['?'],
],
[
'allow' => true,
'actions' => ['logout'],
'roles' => ['@'],
],
],
],
];
}
// ...
}
```
Dans le code précédent, le filtre de contrôle d'accès est attaché au contrôleur `site` en tant que comportement (*behavior*). C'est la manière typique d'utiliser un filtre d'action. L'option `only` spécifie que le filtre de contrôle d'accès doit seulement être appliqué aux actions `login`, `logout` et `signup`. Toutes les autres actions dans le contrôleur `site`ne sont pas sujettes au contrôle d'accès. L'option `rules` liste les [[yii\filters\AccessRule|règles d'accès]], qui se lisent comme suit :
- Autorise tous les visiteurs (non encore authentifiés) à accéder aux actions `login` et `signup`. l'option `roles` contient un point d'interrogation `?` qui est un signe particulier représentant les « visiteurs non authentifiés ».
- Autorise les utilisateurs authentifiés à accéder à l'action `logout`. L'arobase `@` est un autre signe particulier représentant les « utilisateurs authentifiés ».
Le filtre de contrôle d'accès effectue les vérifications d'autorisation en examinant les règles d'accès une par une en commençant par le haut, jusqu'à ce qu'il trouve une règle qui correspond au contexte d'exécution courant. La valeur `allow` de la règle correspondante est utilisée ensuite pour juger si l'utilisateur est autorisé ou pas. Si aucune des règles ne correspond, cela signifie que l'utilisateur n'est PAS autorisé, et le filtre de contrôle d'accès arrête la suite de l'exécution de l'action.
Quand le filtre de contrôle d'accès détermine qu'un utilisateur n'est pas autorisé à accéder à l'action courante, par défaut, il prend les mesures suivantes :
* Si l'utilisateur est un simple visiteur, il appelle [[yii\web\User::loginRequired()]] pour rediriger le navigateur de l'utilisateur sur la page de connexion.
* Si l'utilisateur est déjà authentifié, il lève une exception [[yii\web\ForbiddenHttpException]].
Vous pouvez personnaliser ce comportement en configurant la propriété [[yii\filters\AccessControl::denyCallback]] comme indiqué ci-après :
```php
[
'class' => AccessControl::class,
...
'denyCallback' => function ($rule, $action) {
throw new \Exception('You are not allowed to access this page');
}
]
```
Les [[yii\filters\AccessRule|règles d'accès]] acceptent beaucoup d'options. Ci-dessous, nous présentons un résumé des options acceptées. Vous pouvez aussi étendre la classe [[yii\filters\AccessRule]] pour créer vos propres classe de règles d'accès.
* [[yii\filters\AccessRule::allow|allow]]: spécifie s'il s'agit d'une règle "allow" (autorise) ou "deny" (refuse).
* [[yii\filters\AccessRule::actions|actions]]: spécifie à quelles actions cette règle correspond. Ce doit être un tableau d'identifiants d'action. La comparaison est sensible à la casse. Si cette option est vide ou non définie, cela signifie que la règle s'applique à toutes les actions.
* [[yii\filters\AccessRule::controllers|controllers]]: spécifie à quels contrôleurs cette règle correspond. Ce doit être un tableau d'identifiants de contrôleurs. Si cette option est vide ou non définie, la règle s'applique à tous les contrôleurs.
* [[yii\filters\AccessRule::roles|roles]]: spécifie à quels rôles utilisateur cette règle correspond. Deux rôles spéciaux sont reconnus, et ils sont vérifiés via [[yii\web\User::isGuest]]:
- `?`: correspond à un visiteur non authentifié.
- `@`: correspond à un visiteur authentifié.
L'utilisation d'autres noms de rôle déclenche l'appel de [[yii\web\User::can()]], qui requiert l'activation du contrôle d'accès basé sur les rôles qui sera décrit dans la prochaine sous-section. Si cette option est vide ou non définie, cela signifie que la règle s'applique à tous les rôles.
* [[yii\filters\AccessRule::ips|ips]]: spécifie à quelles [[yii\web\Request::userIP|adresses IP de client]] cette règle correspond. Une adresse IP peut contenir le caractère générique `*` à la fin pour indiquer que la règle correspond à des adresses IP ayant le même préfixe. Par exemple, '192.168.*' correspond à toutes les adresse IP dans le segment '192.168.'. Si cette option est vide ou non définie, cela signifie que la règle s'applique à toutes les adresses IP.
* [[yii\filters\AccessRule::verbs|verbs]]: spécifie à quelles méthodes de requête (p. ex. `GET`, `POST`) cette règle correspond. La comparaison est insensible à la casse.
* [[yii\filters\AccessRule::matchCallback|matchCallback]]: spécifie une fonction de rappel PHP qui peut être appelée pour déterminer si cette règle s'applique.
* [[yii\filters\AccessRule::denyCallback|denyCallback]]: spécifie une fonction de rappel PHP qui peut être appelée lorsqu'une règle refuse l'accès.
Ci-dessous nous présentons un exemple qui montre comment utiliser l'option `matchCallback`, qui vous permet d'écrire une logique d'accès arbitraire :
```php
use yii\filters\AccessControl;
class SiteController extends Controller
{
public function behaviors()
{
return [
'access' => [
'class' => AccessControl::class,
'only' => ['special-callback'],
'rules' => [
[
'actions' => ['special-callback'],
'allow' => true,
'matchCallback' => function ($rule, $action) {
return date('d-m') === '31-10';
}
],
],
],
];
}
// Fonction de rappel appelée ! Cette page ne peut être accédée que chaque 31 octobre
public function actionSpecialCallback()
{
return $this->render('happy-halloween');
}
}
```
## Contrôle d'accès basé sur les rôles
Le contrôle d'accès basé sur les rôles (Role-Based Access Control – RBAC) fournit un contrôle d'accès centralisé simple mais puissant. Reportez-vous à [Wikipedia](https://fr.wikipedia.org/wiki/Contr%C3%B4le_d%27acc%C3%A8s_%C3%A0_base_de_r%C3%B4les) pour des détails comparatifs entre le contrôle d'accès basé sur les rôles et d'autres schéma de contrôle d'accès plus traditionnels.
Yii met en œuvre un contrôle d'accès basé sur les rôles général hiérarchisé, qui suit le [modèle NIST RBAC](https://csrc.nist.gov/CSRC/media/Publications/conference-paper/1992/10/13/role-based-access-controls/documents/ferraiolo-kuhn-92.pdf). Il fournit la fonctionnalité de contrôle d'accès basé sur les rôles via le [composant d'application](structure-application-components.md)[[yii\RBAC\ManagerInterface|authManager]].
L'utilisation du contrôle d'accès basé sur les rôles implique deux partie de travail. La première partie est de construire les données d'autorisation du contrôle d'accès basé sur les rôles, et la seconde partie est d'utiliser les données d'autorisation pour effectuer les vérifications d'autorisation d'accès là où elles sont nécessaires.
Pour faciliter la description qui suit, nous allons d'abord introduire quelques concepts sur le contrôle d'accès basé sur les rôles.
### Concepts de base
Un rôle représente une collection de *permissions* (p. ex. créer des articles, mettre des articles à jour). Un rôle peut être assigné à un ou plusieurs utilisateurs. Pour vérifier qu'un utilisateur dispose d'une permission spécifiée, nous pouvons vérifier si un rôle contenant cette permission a été assigné à l'utilisateur.
Associée à chacun des rôles, il peut y avoir une *règle*. Une règle représente un morceau de code à exécuter lors de l'accès pour vérifier si le rôle correspondant, ou la permission correspondante, s'applique à l'utilisateur courant. Par exemple, la permission « mettre un article à jour » peut disposer d'une règle qui vérifie si l'utilisateur courant est celui qui a créé l'article. Durant la vérification de l'accès, si l'utilisateur n'est PAS le créateur de l'article, il est considéré comme ne disposant pas la permission « mettre un article à jour ».
À la fois les rôles et les permissions peuvent être organisés en une hiérarchie. En particulier, un rôle peut être constitué d'autres rôles ou permissions ; Yii met en œuvre une hiérarchie *d'ordre partiel* qui inclut la hiérarchie plus spécifique dite *en arbre*. Tandis qu'un rôle peut contenir une permission, l'inverse n'est pas vrai.
### Configuration du contrôle d'accès basé sur les rôles
Avant que nous ne nous lancions dans la définition des données d'autorisation et effectuions la vérification d'autorisation d'accès, nous devons configurer le composant d'application [[yii\base\Application::authManager|gestionnaire d'autorisations (*authManager*)]]. Yii fournit deux types de gestionnaires d'autorisations : [[yii\rbac\PhpManager]] et [[yii\rbac\DbManager]]. Le premier utilise un script PHP pour stocker les données d'autorisation, tandis que le second stocke les données d'autorisation dans une base de données. Vous pouvez envisager d'utiliser le premier si votre application n'a pas besoin d'une gestion des rôles et des permissions très dynamique.
#### Utilisation de `PhpManager`
Le code qui suit montre comment configurer la propriété `authManager` dans la configuration de l'application en utilisant la classe [[yii\rbac\PhpManager]] :
```php
return [
// ...
'components' => [
'authManager' => [
'class' => 'yii\rbac\PhpManager',
],
// ...
],
];
```
Le gestionnaire `authManager` peut désormais être obtenu via `\Yii::$app->authManager`.
Par défaut, [[yii\rbac\PhpManager]] stocke les données du contrôle d'accès basé sur les rôles dans des fichiers du dossier `@app/rbac`. Assurez-vous que le dossier et tous les fichiers qui sont dedans sont accessibles en écriture par le processus du serveur Web si la hiérarchie des permissions a besoin d'être changée en ligne.
#### Utilisation de `DbManager`
Le code qui suit monte comment configurer la propriété `authManager` dans la configuration de l'application en utilisant la classe [[yii\rbac\DbManager]] :
```php
return [
// ...
'components' => [
'authManager' => [
'class' => 'yii\rbac\DbManager',
],
// ...
],
];
```
> Note: si vous utilisez le modèle d'application yii2-basic-app, il y a un fichier de configuration `config/console.php` où la propriété `authManager` doit être également déclarée en plus de `config/web.php`.
> Dans le cas du modèle yii2-advanced-app, la propriété `authManager` doit être déclarée seulement une fois dans `common/config/main.php`.
`DbManager` utilise quatre tables de base de données pour stocker ses données :
- [[yii\rbac\DbManager::$itemTable|itemTable]]: la table pour stocker les items d'autorisation. Valeur par défaut « auth_item ».
- [[yii\rbac\DbManager::$itemChildTable|itemChildTable]]: la table pour stocker la hiérarchie des items d'autorisation. Valeur par défaut « auth_item_child ».
- [[yii\rbac\DbManager::$assignmentTable|assignmentTable]]: la table pour stocker les assignations d'items d'autorisation. Valeur par défaut « auth_assignment ».
- [[yii\rbac\DbManager::$ruleTable|ruleTable]]: la table pour stocker les règles. Valeur par défaut « auth_rule ».
Avant de continuer vous devez créer ces tables dans la base de données. Pour le faire , vous pouvez utiliser la migration stockée dans `@yii/rbac/migrations`:
`yii migrate --migrationPath=@yii/rbac/migrations`
Le gestionnaire d'autorisations `authManager` peut désormais être obtenu par `\Yii::$app->authManager`.
### Construction des données d'autorisation
Construire les donnés d'autorisation consiste à effectuer les tâches suivantes :
- définir les rôles et les permissions ;
- établir les relations entre les rôles et les permissions ;
- définir les règles ;
- associer les règles avec les rôles et les permissions ;
- assigner des rôles aux utilisateurs.
Selon les exigences de flexibilité des autorisations, les tâches énumérées ci-dessus peuvent être accomplies de différentes manières :
Si la hiérarchie de vos permissions ne change pas du tout et que vous avez un nombre fixé d'utilisateurs, vous pouvez créer une [commande de console](tutorial-console.md#create-command) qui initialise les données d'autorisation une fois via l'API que fournit `authManager`:
```php
authManager;
// ajoute une permission "createPost"
$createPost = $auth->createPermission('createPost');
$createPost->description = 'Créer un article';
$auth->add($createPost);
// ajoute une permission "updatePost"
$updatePost = $auth->createPermission('updatePost');
$updatePost->description = 'Mettre à jour un article';
$auth->add($updatePost);
// ajoute un rôle "author" et donne à ce rôle la permission "createPost"
$author = $auth->createRole('author');
$auth->add($author);
$auth->addChild($author, $createPost);
// ajoute un rôle "admin" role et donne à ce rôle la permission "updatePost"
// aussi bien que les permissions du rôle "author"
$admin = $auth->createRole('admin');
$auth->add($admin);
$auth->addChild($admin, $updatePost);
$auth->addChild($admin, $author);
// Assigne des rôles aux utilisateurs. 1 et 2 sont des identifiants retournés par IdentityInterface::getId()
// ordinairement mis en œuvre dans votre modèle User .
$auth->assign($author, 2);
$auth->assign($admin, 1);
}
}
```
> Note: si vous utilisez le modèle avancé, vous devez mettre votre `RbacController` dans le dossier `console/controllers` et changer l'espace de noms en `console\controllers`.
Après avoir exécuté la commande `yii rbac/init` vous vous retrouverez avec la hiérarchie suivante :
Le rôle *Author* peut créer des articles, le rôle *admin* peut mettre les articles à jour et faire tout ce que le rôle *author* peut faire.
Si votre application autorise l'enregistrement des utilisateurs, vous devez assigner des rôles à ces nouveaux utilisateurs une fois. Par exemple, afin que tous les utilisateurs enregistrés deviennent des auteurs (rôle *author*) dans votre modèle de projet avancé, vous devez modifier la méthode `frontend\models\SignupForm::signup()` comme indiqué ci-dessous :
```php
public function signup()
{
if ($this->validate()) {
$user = new User();
$user->username = $this->username;
$user->email = $this->email;
$user->setPassword($this->password);
$user->generateAuthKey();
$user->save(false);
// Ces trois lignes ont été ajoutées
$auth = Yii::$app->authManager;
$authorRole = $auth->getRole('author');
$auth->assign($authorRole, $user->getId());
return $user;
}
return null;
}
```
Pour les applications qui requièrent un contrôle d'accès complexe avec des autorisations mises à jour dynamiquement, des interfaces utilisateur spéciales (c.-à-d. un panneau d'administration) doivent être développées en utilisant l'API offerte par `authManager`.
### Utilisation des règles
Comme mentionné plus haut, les règles ajoutent des contraintes supplémentaires aux rôles et aux permissions. Une règle est une classe qui étend la classe [[yii\rbac\Rule]]. Elle doit implémenter la méthode [[yii\rbac\Rule::execute()|execute()]]. Dans la hiérarchie, que nous avons créée précédemment le rôle *author* ne peut pas modifier ses propres articles. Essayons de régler ce problème. Tout d'abord, nous devons vérifier que l'utilisateur courant est l'auteur de l'article :
```php
namespace app\rbac;
use yii\rbac\Rule;
/**
* Vérifie si l'identifiant de l'auteur correspond à celui passé en paramètre
*/
class AuthorRule extends Rule
{
public $name = 'isAuthor';
/**
* @param string|int $user l'identifiant de l'utilisateur.
* @param Item $item le rôle ou la permission avec laquelle cette règle est associée
* @param array $params les paramètres passés à ManagerInterface::checkAccess().
* @return bool une valeur indiquant si la règles autorise le rôle ou la permission qui lui est associé.
*/
public function execute($user, $item, $params)
{
return isset($params['post']) ? $params['post']->createdBy == $user : false;
}
}
```
La règles ci-dessus vérifie si l'article `post` a été créé par l'utilisateur `$user`. Nous allons créer une permission spéciale `updateOwnPost` dans la commande que nous avons utilisée précédemment :
```php
$auth = Yii::$app->authManager;
// ajoute la règle
$rule = new \app\rbac\AuthorRule;
$auth->add($rule);
// ajoute la permission "updateOwnPost" et associe lui la règle
$updateOwnPost = $auth->createPermission('updateOwnPost');
$updateOwnPost->description = 'Mettre à jour un des ses propres articles';
$updateOwnPost->ruleName = $rule->name;
$auth->add($updateOwnPost);
// "updateOwnPost" sera utilisé depuis "updatePost"
$auth->addChild($updateOwnPost, $updatePost);
// autorise les utilisateurs ayant le rôle "author" à mettre à jour leurs propres articles.
$auth->addChild($author, $updateOwnPost);
```
Nous nous retrouvons avec la hiérarchie suivante :
### Vérification de l'autorisation d'accès
Avec les données d'autorisation préparées, la vérification de l'autorisation d'accès est aussi simple que d'appeler la méthode [[yii\rbac\ManagerInterface::checkAccess()]]. Étant donné que la plupart des vérification d'autorisation d'accès concernent l'utilisateur courant, pour commodité, Yii procure une méthode raccourcie [[yii\web\User::can()]], qui peut être utilisée comme suit :
```php
if (\Yii::$app->user->can('createPost')) {
// create post
}
```
Si l'utilisateur courant est Jane avec l'identifiant `ID=1`, nous commençons à `createPost` et essayons d'arriver à `Jane`:
Afin de vérifier sur un utilisateur peut mettre un article à jour, nous devons passer un paramètre supplémentaire qui est requis par la règle `AuthorRule` décrite précédemment :
```php
if (\Yii::$app->user->can('updatePost', ['post' => $post])) {
// met à jour l'article
}
```
Ici que se passe-t-il si l'utilisateur courant est John:
Nous commençons à `updatePost` et passons par `updateOwnPost`. Afin d'obtenir l'autorisation, la méthode `execute()` de `AuthorRule` doit retourner `true` (vrai). La méthode reçoit ses paramètres `$params` de l'appel à la méthode `can()` et sa valeur est ainsi `['post' => $post]`. Si tout est bon, nous arrivons à `author` auquel John est assigné.
Dans le cas de Jane, c'est un peu plus simple puisqu'elle a le rôle admin:
Dans votre contrôleur, il y a quelques façons de mettre en œuvre les autorisations. Si vous voulez des permission granulaires qui séparent l'accès entre ajouter et supprimer, alors vous devez vérifier l'accès pour chacune des actions. Vous pouvez soit utiliser la condition ci-dessus dans chacune des méthodes d'action, ou utiliser [[yii\filters\AccessControl]] :
```php
public function behaviors()
{
return [
'access' => [
'class' => AccessControl::class,
'rules' => [
[
'allow' => true,
'actions' => ['index'],
'roles' => ['managePost'],
],
[
'allow' => true,
'actions' => ['view'],
'roles' => ['viewPost'],
],
[
'allow' => true,
'actions' => ['create'],
'roles' => ['createPost'],
],
[
'allow' => true,
'actions' => ['update'],
'roles' => ['updatePost'],
],
[
'allow' => true,
'actions' => ['delete'],
'roles' => ['deletePost'],
],
],
],
];
}
```
Si toutes les opérations CRUD sont gérées ensemble, alors c'est une bonne idée que d'utiliser une permission unique comme `managePost` (gérer article), et de la vérifier dans [[yii\web\Controller::beforeAction()]].
### Utilisation des rôles par défaut
Un rôle par défaut est un rôle qui est assigné *implicitement* à tous les *utilisateurs*. L'appel de la méthode [[yii\rbac\ManagerInterface::assign()]] n'est pas nécessaire, et les données d'autorisations ne contiennent pas ses informations d'assignation.
Un rôle par défaut est ordinairement associé à une règle qui détermine si le rôle s'applique à l'utilisateur en cours de vérification.
Les rôles par défaut sont souvent utilisés dans des applications qui ont déjà une sorte d'assignation de rôles. Par exemple, un application peut avoir une colonne « group » dans sa table des utilisateurs pour représenter à quel groupe de privilèges chacun des utilisateurs appartient. Si chaque groupe de privilèges peut être mis en correspondance avec un rôle du contrôle d'accès basé sur les rôles, vous pouvez utiliser la fonctionnalité de rôle par défaut pour assigner automatiquement un rôle du contrôle d'accès basé sur les rôles à chacun des utilisateurs. Prenons un exemple pour montrer comment cela se fait.
Supposons que dans la table des utilisateurs, il existe en colonne `group` qui utilise la valeur 1 pour représenter le groupe des administrateurs et la valeur 2 pour représenter le groupe des auteurs. Vous envisagez d'avoir deux rôles dans le contrôle d'accès basé sur les rôles `admin` et`author` pour représenter les permissions de ces deux groupes respectivement. Vous pouvez configurer le contrôle d'accès basé sur les rôles comme suit :
```php
namespace app\rbac;
use Yii;
use yii\rbac\Rule;
/**
* Vérifie si le groupe utilisateurs correspond
*/
class UserGroupRule extends Rule
{
public $name = 'userGroup';
public function execute($user, $item, $params)
{
if (!Yii::$app->user->isGuest) {
$group = Yii::$app->user->identity->group;
if ($item->name === 'admin') {
return $group == 1;
} elseif ($item->name === 'author') {
return $group == 1 || $group == 2;
}
}
return false;
}
}
$auth = Yii::$app->authManager;
$rule = new \app\rbac\UserGroupRule;
$auth->add($rule);
$author = $auth->createRole('author');
$author->ruleName = $rule->name;
$auth->add($author);
// ... ajoute les permissions en tant qu'enfant de $author ...
$admin = $auth->createRole('admin');
$admin->ruleName = $rule->name;
$auth->add($admin);
$auth->addChild($admin, $author);
// ... ajoute les permissions en tant qu'enfant de $admin ...
```
Notez que dans ce qui est présenté ci-dessus, comme « author » est ajouté en tant qu'enfant de « admin », lorsque vous implémentez la méthode `execute()` de la classe de règle, vous devez respecter cette hiérarchie elle aussi. C'est pourquoi, lorsque le nom de rôle est « author », la méthode `execute()` retourne `true` (vrai) si le groupe de l'utilisateur est soit 1, soit 2 (ce qui signifie que l'utilisateur est soit dans le groupe « admin », soit dans le groupe « author »).
Ensuite, configurez `authManager` en listant les deux rôles dans [[yii\rbac\BaseManager::$defaultRoles]]:
```php
return [
// ...
'components' => [
'authManager' => [
'class' => 'yii\rbac\PhpManager',
'defaultRoles' => ['admin', 'author'],
],
// ...
],
];
```
Désormais, si vous effectuez une vérification d'autorisation d'accès, les deux rôles `admin` et `author` seront vérifiés en évaluant les règles qui leur sont associées. Si les règles retournent `true` (vrai), cela signifie que le rôle s'applique à l'utilisateur courant. En se basant sur la mise en œuvre des règles ci-dessus, cela signifie que si la valeur du `group` d'un utilisateur est 1, le rôle `admin` s'applique à l'utilisateur, si la valeur du `group` est 2, le rôle `author` s'applique.
================================================
FILE: docs/guide-fr/security-best-practices.md
================================================
Meilleures pratiques de sécurité
================================
Ci-dessous, nous passons en revue les principes de sécurité courants et décrivons comment éviter les menaces lorsque vous développez une application Yii.
Principes de base
-----------------
Il y a deux principes essentiels quand on en vient à traiter de la sécurité des applications quelles qu'elles soient :
1. Filtrer les entrées.
2. Échapper les sorties.
### Filtrer les entrées
Filtrer les entrées signifie que les entrées ne doivent jamais être considérées comme sures et que vous devriez toujours vérifier qu'une valeur que vous avez obtenue fait réellement partie de celles qui sont autorisées. Par exemple, si nous savons qu'un tri doit être fait sur la base de trois champs `title`, `created_at` et `status`, et que ces champs sont fournis sous forme d'entrées de l'utilisateur, il vaut mieux vérifier les valeurs exactement là où nous les recevons. En terme de PHP de base, ça devrait ressembler à ceci :
```php
$sortBy = $_GET['sort'];
if (!in_array($sortBy, ['title', 'created_at', 'status'])) {
throw new Exception('Invalid sort value.');
}
```
Dans Yii, le plus probablement, vous utilisez la [validation de formulaire](input-validation.md) pour faire de telles vérifications.
### Échapper les sorties
Échapper les sorties signifie que, selon le contexte dans lequel vous utilisez les données, elles doivent être échappées c.-à-d. dans le contexte de HTML vous devez échapper les caractères `<`, `>` et autres caractères similaires. Dans le contexte de JavaScript ou de SQL, il s'agira d'un jeu différent de caractères. Comme échapper tout à la main serait propice aux erreurs, Yii fournit des outils variés pour effectuer l'échappement dans différents contextes.
Éviter les injections SQL
----------------------------
Les injections SQL se produisent lorsque le texte d'une requête est formé en concaténant des chaînes non échappées comme la suivante :
```php
$username = $_GET['username'];
$sql = "SELECT * FROM user WHERE username = '$username'";
```
Au lieu de fournir un nom d'utilisateur réel, l'attaquant pourrait donner à votre application quelque chose comme `'; DROP TABLE user; --`.
Ce qui aboutirait à la requête SQL suivante :
```sql
SELECT * FROM user WHERE username = ''; DROP TABLE user; --'
```
Cela est une requête tout à fait valide qui recherche les utilisateurs avec un nom vide et détruit probablement la table `user`, ce qui conduit à un site Web cassé et à une perte de données (vous faites des sauvegardes régulières, pas vrai ?).
Dans Yii la plupart des requêtes de base de données se produisent via la classe [Active Record](db-active-record.md) qui utilise correctement des instructions PDO préparées en interne. En cas d'instructions préparées, il n'est pas possible de manipuler la requête comme nous le montrons ci-dessus.
Cependant, parfois, vous avez encore besoin de [requêtes brutes](db-dao.md) ou du [constructeur de requêtes](db-query-builder.md). Dans ce cas, vous devriez passer les données de manière sure. Si les données sont utilisées pour des valeurs de colonnes, il est préférable d'utiliser des instructions préparées :
```php
// query builder
$userIDs = (new Query())
->select('id')
->from('user')
->where('status=:status', [':status' => $status])
->all();
// DAO
$userIDs = $connection
->createCommand('SELECT id FROM user where status=:status')
->bindValues([':status' => $status])
->queryColumn();
```
Si les données sont utilisées pour spécifier des noms de colonne ou des noms de table, la meilleure chose à faire est d'autoriser uniquement des jeux prédéfinis de valeurs :
```php
function actionList($orderBy = null)
{
if (!in_array($orderBy, ['name', 'status'])) {
throw new BadRequestHttpException('Only name and status are allowed to order by.')
}
// ...
}
```
Dans le cas où cela n'est pas possible, les noms de colonne et de table doivent être échappés. Yii a recours à une syntaxe spéciale pour un tel échappement qui permet de le faire d'une manière identique pour toutes les bases de données prises en charge :
```php
$sql = "SELECT COUNT([[$column]]) FROM {{table}}";
$rowCount = $connection->createCommand($sql)->queryScalar();
```
Vous pouvez obtenir tous les détails sur cette syntaxe dans la section [Échappement des noms de colonne et de table](db-dao.md#quoting-table-and-column-names).
Éviter le XSS
----------------
Le XSS ou scriptage inter site se produit lorsque la sortie n'est pas échappée correctement lors de l'envoi de code HTML au navigateur. Par exemple, si l'utilisateur peut entrer son nom, et qu'au lieu de saisir `Alexander` il saisit ``, chaque page qui émet sont nom sans échappement exécute le code JavaScript `alert('Hello!');` ce qui se traduit par une boîte d'alerte jaillissant dans le navigateur. Selon le site web, au lieu de quelque chose d'aussi innocent, le script pourrait envoyer des messages en votre nom ou même effectuer des transactions bancaires. L'évitement de XSS est tout à fait facile. Il y a en général deux cas :
1. Vous voulez que vos données soient transmises sous forme de texte simple.
2. Vous voulez que vos données soient transmises sous forme de code HTML.
Si vous désirez seulement du texte simple, l'échappement est aussi simple à réaliser que ce qui suit :
```php
```
Si ce doit être du code HTML vous pouvez obtenir de l'aide de HtmlPurifier:
```php
```
Notez que le processus de HtmlPurifier est très lourd, c'est pourquoi vous devez envisager la mise en cache.
Éviter le CSRF
-----------------
La CSRF est une abréviation de cross-site request forgery (falsification de requête inter sites). L'idée est que beaucoup d'applications partent du principe que les requêtes provenant d'un navigateur sont fabriquées par l'utilisateur lui-même. Cela peut être faux.
Par exemple, un site web `an.example.com` a une URL `/logout`, qui, lorsqu'elle est accédée en utilisant une simple requête GET, déconnecte l'utilisateur. Tant qu'il s'agit d'une requête de l'utilisateur lui-même, tout va bien. Mais, un jour, des gens mal intentionnés, postent `
` sur un forum que l'utilisateur visite fréquemment. Le navigateur ne fait pas de différence entre la requête d'une image et celle d'une page. C'est pourquoi, lorsque l'utilisateur ouvre une page avec une telle balise `img`, le navigateur envoie la requête GET vers cette URL, et l'utilisateur est déconnecté du site `an.example.com`.
C'est l'idée de base. D'aucuns diront que déconnecter un utilisateur n'a rien de très sérieux, mais les gens mal intentionnés peuvent faire bien plus, à partir de cette idée. Imaginez qu'un site web possède une URL `https://an.example.com/purse/transfer?to=anotherUser&amount=2000`. Accéder à cette URL en utilisant une requête GET, provoque le transfert de 2000 € d'un compte autorisé à l'utilisateur vers un autre compte `anotherUser`. Nous savons que le navigateur envoie toujours une requête GET pour charger une image. Nous pouvons donc modifier le code pour que seules des requêtes POST soient acceptées sur cette URL. Malheureusement, cela ne nous est pas d'un grand secours parce qu'un attaquant peut placer un peu le JavaScript à la place de la balise `![]()
`, ce qui permet d'envoyer des requêtes POST sur cette URL:
Afin d'éviter la falsification des requêtes inter-sites vous devez toujours :
1. Suivre la spécification HTTP c.-à-d. GET ne doit pas changer l'état de l'application.
2. Tenir la protection Yii CSRF activée.
Parfois vous avez besoin de désactiver la validation CSRF pour un contrôleur ou une action. Cela peut être fait en définissant sa propriété :
```php
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
public $enableCsrfValidation = false;
public function actionIndex()
{
// la validation CSRF ne sera pas appliquée à cette action ainsi qu'aux autres.
}
}
```
Pour désactiver la validation CSRF pour des actions personnalisées vous pouvez faire :
```php
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
public function beforeAction($action)
{
// ...définit `$this->enableCsrfValidation` ici en se basant sur quelques conditions...
// appelle la méthode du parent qui vérifie CSRF si une telle propriété est vraie
return parent::beforeAction($action);
}
}
```
Éviter l'exposition de fichiers
-------------------------------------
Par défaut, le racine du serveur web est censé pointer sur le dossier `web`, là où se trouve le fichier `index.php`. Dans le cas d'un hébergement partagé, il peut être impossible de réaliser cela et vous pouvez vous retrouver avec tout le code, configurations et journaux sous la racine du serveur web.
Si c'est le cas, n'oubliez-pas de refuser l'accès à tout sauf au dossier `web`. Si cela n'est pas possible, envisagez d'héberger votre application ailleurs.
Éviter les informations et des outils de débogage en mode production
----------------------------------------------------------------------
En mode débogage, Yii présente les erreurs de façon très verbeuse, ce qui s'avère très utile en développement. Le problème est que des erreurs aussi verbeuses sont pleines de renseignement pour l'attaquant lui aussi et peuvent révéler la structure de la base de données, les valeurs de configuration et des parties de votre code. Ne faites jamais tourner vos applications avec `YII_DEBUG` définit à `true` dans votre fichier `index.php`.
Vous ne devriez jamais activer Gii en production. Il pourrait être utilisé pour obtenir des informations sur la structure de la base de données, sur le code et tout simplement réécrire du code avec celui généré par Gii.
La barre de débogage devrait être neutralisée en production sauf si vous en avez réellement besoin. Elle expose toute l'application et les détails de configuration. Si vous avez absolument besoin de cette barre, vérifier que cet accès est correctement réservé à votre adresse IP seulement.
Utilisation de connexions sécurisées via TLS
--------------------------------------------
Yii fournit des fonctionnalités qui comptent sur les témoins de connexion et/ou sur les sessions PHP. Cela peut créer des vulnérabilités dans le cas où votre connexion est compromise. Le risque est réduit si l'application utilise une connexion sécurisée via TLS.
Reportez-vous à la documentation de votre serveur web pour des instructions sur la manière de la configurer. Vous pouvez aussi jeter un coup d'œil aux exemples de configuration du projet H5BP :
- [Nginx](https://github.com/h5bp/server-configs-nginx)
- [Apache](https://github.com/h5bp/server-configs-apache).
- [IIS](https://github.com/h5bp/server-configs-iis).
- [Lighttpd](https://github.com/h5bp/server-configs-lighttpd).
================================================
FILE: docs/guide-fr/security-cryptography.md
================================================
Cryptographie
=============
Dans cette section nous allons passer en revue les aspects suivants relatifs à la sécurité :
- Génération de données aléatoires
- Chiffrage et déchiffrage
- Confirmation de l'intégrité des données
Génération de données pseudo-aléatoires
---------------------------------------
Les données pseudo-aléatoires sont utiles dans de nombreuses situations. Par exemple, lors de la réinitialisation d'un mot de passe via courriel, vous devez générer un jeton, le sauvegarder dans la base de données, et l'envoyer à l'utilisateur afin qu'il puisse prouver qu'il est le détenteur du compte concerné. Il est très important que ce jeton soit unique et difficile à deviner, sinon il y aurait une possibilité que l'attaquant le devine et réinitialise le mot de passe de l'utilisateur.
Les fonctions d'aide à la sécurité de Yii facilite la création de données pseudo-aléatoires :
```php
$key = Yii::$app->getSecurity()->generateRandomString();
```
Chiffrage et déchiffrage
----------------------
Yii fournit des fonctions d'aide pratiques qui vous permettent de chiffrer/déchiffrer les données en utilisant une clé secrète. Les données sont passées à la fonction de chiffrage de façon à ce que, seule la personne qui possède la clé secrète soit en mesure de les déchiffrer.
Par exemple, nous avons besoin de stocker quelques informations dans notre base de données mais nous avons besoin de garantir que seul l'utilisateur qui dispose de la clé secrète soit en mesure des les visualiser (même si la base de données de l'application est compromise) :
```php
// $data et $secretKey sont obtenues du formulaire
$encryptedData = Yii::$app->getSecurity()->encryptByPassword($data, $secretKey);
// stocke $encryptedData dans la base de données
```
Par la suite, lorsqu'un utilisateur désire lire les données :
```php
// $secretKey est obtenue de la saisie de l'utilisateur, $encryptedData provient de la base de données
$data = Yii::$app->getSecurity()->decryptByPassword($encryptedData, $secretKey);
```
Il est également possible d'utiliser une clé à la place d'un mot de passe via [[\yii\base\Security::encryptByKey()]] et
[[\yii\base\Security::decryptByKey()]].
Confirmation de l'intégrité des données
---------------------------------------
Il y a des situations dans lesquelles vous avez besoin de vérifier que vos données n'ont pas été trafiquées par une tierce partie ou corrompue. Yii vous offre un moyen facile de confirmer l'intégrité des données sous forme d'une fonction d'aide.
Préfixez les données par une valeur de hachage obtenue à l'aide de la clé secrète et des données.
```php
// $secretKey notre clé secrèe pour l'application ou l'utilisateur, $genuineData les données authentiques obtenues d'une source fiable.
$data = Yii::$app->getSecurity()->hashData($genuineData, $secretKey);
```
Vérifiez si l'intégrité des données est compromise.
```php
// $secretKey notre clé secrèe pour l'application ou l'utilisateur, $data données obtenues d'une source peu sûre
$data = Yii::$app->getSecurity()->validateData($data, $secretKey);
```
================================================
FILE: docs/guide-fr/security-overview.md
================================================
Sécurité
========
Une bonne sécurité est vitale pour la santé et le succès de toute application. Malheureusement, beaucoup de développeurs lésinent un peu quand ils en arrivent à la sécurité, soit par manque de compréhension ou parce que sa mise en œuvre n'est pas une mince affaire. Pour rendre votre application Yii aussi sûre que possible, Yii inclut plusieurs fonctionnalités de sécurité, excellentes et faciles à mettre en œuvre.
* L'[authentification](security-authentication.md)
* L'[autorisation](security-authorization.md)
* Le [travail avec des mots de passe](security-passwords.md)
* La [cryptographie](security-cryptography.md)
* La [sécurité des vues](structure-views.md#security)
* L'extension [Auth Clients](https://github.com/yiisoft/yii2-authclient/blob/master/docs/guide/README.md)
* Les [bonnes pratiques](security-best-practices.md)
================================================
FILE: docs/guide-fr/security-passwords.md
================================================
Utilisation de mots de passe
============================
La plupart des développeurs savent que les mots de passe ne peuvent pas être stockés « en clair », mais beaucoup d'entre-eux croient qu'il est toujours sûr des les hacher avec `md5` ou `sha1`. Il fut un temps où utiliser ces algorithmes de hachage était suffisant, mais les matériels modernes font qu'il est désormais possible de casser de tels hachages – même les plus robustes – très rapidement en utilisant des attaques en force brute.
Pour apporter une sécurité améliorée pour les mots de passe des utilisateurs, même dans le pire des scénario (une brèche est ouverte dans votre application), vous devez utiliser des algorithmes de hachage qui résistent aux attaques en force brute. Le choix le meilleur couramment utilisé est `bcrypt`.
En PHP, vous pouvez créer une valeur de hachage `bcrypt` à l'aide de la [fonction crypt](https://www.php.net/manual/fr/function.crypt.php). Yii fournit deux fonctions d'aide qui facilitent l'utilisation de `crypt` pour générer et vérifier des valeurs de hachage de manière sure.
Quand un utilisateur fournit un mot de passe pour la première fois (p. ex. à l'enregistrement), le mot de passe doit être haché :
```php
$hash = Yii::$app->getSecurity()->generatePasswordHash($password);
```
La valeur de hachage peut ensuite être associée à l'attribut du modèle correspondant afin de pouvoir être stockée dans la base de données pour utilisation ultérieure.
Lorsqu'un utilisateur essaye ensuite de se connecter, le mot de passe soumis est comparé au mot de passe précédemment haché et stocké :
```php
if (Yii::$app->getSecurity()->validatePassword($password, $hash)) {
// tout va bien, nous connectons l'utilisateur
} else {
// wrong password
}
```
================================================
FILE: docs/guide-fr/start-databases.md
================================================
Travailler avec des bases de données
======================
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), définir une [action](structure-controllers.md), et créer une
[vue](structure-views.md).
Au long de ce tutoriel, vous apprendrez comment :
* Configurer une connexion à une base de données
* Définir une classe Active Record
* Demander des données en utilisant la classe Active Record (enregistrement actif)
* Afficher des données dans une vue paginée
Notez que, pour finir cette section, vous aurez besoin d'avoir une connaissance basique des bases de données.
En particulier, vous devez savoir créer une base de données et exécuter des déclarations SQL en utilisant un client de
gestion de bases de données.
Préparer la Base de Données
--------------------
Pour commencer, créez une base de données appelée `yii2basic`, depuis laquelle vous irez chercher les données dans votre application.
Vous pouvez créer une base de données SQLite, MySQL, PostgreSQL, MSSQL ou Oracle, car Yii gère nativement de nombreuses applications de base de données. Pour simplifier, nous supposerons que vous utilisez MySQL dans les descriptions qui suivent.
>Note : bien que MariaDB a été un remplacement direct de MySQL, cela n'est plus complètement vrai. Dans le cas où vous auriez besoin de fonctionnalités avancées telles que la prise en charge de `JSON`, jetez un coup d'œil à la liste des extensions de MariaDB ci-dessous.
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` (
`code` CHAR(2) NOT NULL PRIMARY KEY,
`name` CHAR(52) NOT NULL,
`population` INT(11) NOT NULL DEFAULT '0'
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
INSERT INTO `country` VALUES ('AU','Australia',24016400);
INSERT INTO `country` VALUES ('BR','Brazil',205722000);
INSERT INTO `country` VALUES ('CA','Canada',35985751);
INSERT INTO `country` VALUES ('CN','China',1375210000);
INSERT INTO `country` VALUES ('DE','Germany',81459000);
INSERT INTO `country` VALUES ('FR','France',64513242);
INSERT INTO `country` VALUES ('GB','United Kingdom',65097000);
INSERT INTO `country` VALUES ('IN','India',1285400000);
INSERT INTO `country` VALUES ('RU','Russia',146519759);
INSERT INTO `country` VALUES ('US','United States',322976000);
```
Vous avez désormais une base de données appelée `yii2basic` comprenant une table `country` comportant trois colonnes et contenant dix lignes de données.
Configurer une Connexion à la BDD
---------------------------
Avant de continuer, vérifiez que vous avez installé à la fois l'extension PHP
[PDO](https://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.
Une fois ces éléments installés, ouvrez le fichier `config/db.php` et modifiez les paramètres pour qu'ils correspondent à votre base de données. Par défaut, le fichier contient ce qui suit :
```php
'yii\db\Connection',
'dsn' => 'mysql:host=localhost;dbname=yii2basic',
'username' => 'root',
'password' => '',
'charset' => 'utf8',
];
```
Le fichier `config/db.php` est un exemple type d'outil de [configuration](concept-configurations.md) basé sur un fichier. Ce fichier de configuration en particulier spécifie les paramètres nécessaires à la création et l'initialisation d'une instance de [[yii\db\Connection]] grâce à laquelle vous pouvez effectuer des requêtes SQL 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 via l'expression `Yii::$app->db`.
> Info: le fichier `config/db.php` sera inclus par la configuration principale de l'application `config/web.php`,
qui spécifie comment l'instance d'[application](structure-applications.md) doit être initialisée.
Pour plus d'informations, reportez-vous à la section [Configurations](concept-configurations.md).
Si vous avez besoin de fonctionnalités de base de données dont la prise en charge n'est pas comprise dans Yii, examinez les extensions suivantes:
- [Informix](https://github.com/edgardmessias/yii2-informix)
- [IBM DB2](https://github.com/edgardmessias/yii2-ibm-db2)
- [Firebird](https://github.com/edgardmessias/yii2-firebird)
- [MariaDB](https://github.com/sam-it/yii2-mariadb)
Créer un Active Record
-------------------------
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
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 :
```php
use app\models\Country;
// chercher toutes les lignes de la table pays et les trier par "name"
$countries = Country::find()->orderBy('name')->all();
// chercher la ligne dont la clef primaire est "US"
$country = Country::findOne('US');
// afficher "United States"
echo $country->name;
// remplace le nom du pays par "U.S.A." et le sauvegarde dans la base de données
$country->name = 'U.S.A.';
$country->save();
```
> Info: Active Record (enregistrement actif) est un moyen puissant pour accéder et manipuler des données d'une base de manière orientée objet.
Vous pouvez trouver plus d'informations dans la section [Active Record](db-active-record.md). Sinon, vous pouvez également interagir avec une base de données en utilisant une méthode de plus bas niveau d'accès aux données appelée [Database Access Objects](db-dao.md).
Créer une Action
------------------
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é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
5,
'totalCount' => $query->count(),
]);
$countries = $query->orderBy('name')
->offset($pagination->offset)
->limit($pagination->limit)
->all();
return $this->render('index', [
'countries' => $countries,
'pagination' => $pagination,
]);
}
}
```
Enregistrez le code ci-dessus dans le fichier `controllers/CountryController.php`.
L'action `index` appelle `Country::find()`. Cette méthode Active Record construit une requête de BDD et récupère toutes
les données de la table `country`.
Pour limiter le nombre de pays retournés par chaque requête, la requête est paginée à l'aide d'un objet
[[yii\data\Pagination]]. L'objet `Pagination` dessert deux buts :
* 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 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.
Créer une Vue
---------------
Dans le dossier `views`, commencez par créer un sous-dossier nommé `country`. Ce dossier sera utilisé pour contenir
toutes les vues rendues par le contrôleur `country`. Dans le dossier `views/country`, créez un fichier nommé
`index.php` contenant ce qui suit :
```php
Countries
-
code} ({$country->name})") ?>:
population ?>
$pagination]) ?>
```
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 objet graphique [[yii\widgets\LinkPager]] est rendu en utilisant les informations de pagination transmises par l'action.
L'objet graphique `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
-------------
Pour voir comment tout le code ci-dessus fonctionne, pointez votre navigateur sur l'URL suivante :
```
https://hostname/index.php?r=country/index
```
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
```
https://hostname/index.php?r=country/index&page=2
```
En coulisse, [[yii\data\Pagination|Pagination]] fournit toutes les fonctionnalités permettant de paginer un ensemble de données :
* 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.
* L'objet graphique [[yii\widgets\LinkPager|LinkPager]] effectue le rendu des boutons de pages en utilisant les URL créées par
[[yii\data\Pagination::createUrl()|Pagination]]. Les URL 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
traitée.
[[yii\data\Pagination|Pagination]] lit le paramètre de requête `page` dans l'URL et met le numéro de page à 2.
La nouvelle requête de pays aura donc la clause `LIMIT 5 OFFSET 5` et retournera les cinq pays suivants pour être
affichés.
Résumé
-------
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 de [[yii\widgets\LinkPager]].
Dans la prochaine section, vous apprendrez comment utiliser le puissant outil de génération de code, appelé
[Gii](https://www.yiiframework.com/extension/yiisoft/yii2-gii/doc/guide), pour vous aider à rapidement mettre en œuvre des fonctionnalités communément requises, telles que les
opérations Créer, Lire, Mettre à Jour et Supprimer (CRUD : Create-Read-Update-Delete) pour travailler avec les données
dans une table de base de données. En fait, le code que vous venez d'écrire peut être généré automatiquement dans Yii
en utilisant l'outil Gii.
================================================
FILE: docs/guide-fr/start-forms.md
================================================
Travailler avec les formulaires
==================
Cette section décrit la création d'une nouvelle page comprenant un formulaire pour recevoir des données des
utilisateurs.
La page affichera un formulaire composé d'un champ de saisie nom et un champ de saisie email.
Une fois ces deux informations reçues de l'utilisateur, la page affichera les valeurs entrées pour confirmation.
Pour atteindre ce but, vous créerez non seulement une [action](structure-controllers.md) et deux
[vues](structure-views.md), mais aussi un [modèle](structure-models.md).
Au long de ce tutoriel, vous apprendrez à :
* Créer un [modèle](structure-models.md) pour représenter les données saisies par un utilisateur à travers un
formulaire
* Déclarer des règles pour valider les données entrées
* Construire un formulaire HTML dans une [vue](structure-views.md)
Créer un Modèle
----------------
Les données demandées à l'utilisateur seront représentées par une classe de modèle `EntryForm` comme montrée ci-dessous
enregistrée dans le fichier `models/EntryForm.php`. Merci de vous référer à la section
[Auto-chargement de Classes](concept-autoloading.md) pour plus de détails sur la convention de nommage de fichiers
classes.
```php
Info: [[yii\base\Model]] est utilisée en tant que parent pour des classes modèles qui ne sont *pas* associées à des
tables de base de données.
[[yii\db\ActiveRecord]] est normalement le parent pour les classes modèles qui correspondent à des tables de bases de
données.
La classe `EntryForm` contient deux membres publics, `nom` et `email`, qui sont utilisés pour stocker les données
saisies par l'utilisateur. Elle contient également une méthode nommée `rules()`, qui renvoie un assortiment de règles
pour valider les données. Les règles de validation déclarées ci-dessus énoncent que
* à la fois les valeurs de `nom` et `email` sont requises
* la donnée `email` doit être une adresse email syntaxiquement valide
Si vous avez un objet `EntryForm` peuplé par les données saisies par un utilisateur, vous pouvez appeler sa méthode
[[yii\base\Model::validate()|validate()]] pour déclencher les routines de validation de données. Un échec de validation
de données affectera la valeur `true` à la propriété [[yii\base\Model::hasErrors|hasErrors]], et vous pourrez connaître
quelles erreurs de validations sont apparues via [[yii\base\Model::getErrors|errors]].
```php
nom = 'Qiang';
$model->email = 'mauvais';
if ($model->validate()) {
// Bien!
} else {
// Echec!
// Use $model->getErrors()
}
```
Créer une Action
------------------
Maintenant, vous allez créer une action `entry` dans le contrôleur `site` qui utilisera le nouveau modèle. Le processus
de création et d'utilisation d'actions a été expliqué dans la section [Hello World](start-hello.md).
```php
load(Yii::$app->request->post()) && $model->validate()) {
// données valides reçues dans $model
// faire quelque chose de significatif ici avec $model ...
return $this->render('entry-confirm', ['model' => $model]);
} else {
// soit la page est affichée au début soit il y a des erreurs de validation
return $this->render('entry', ['model' => $model]);
}
}
}
```
L'action commence par créer un objet `EntryForm`. Puis, elle tente de peupler le modèle avec les données de `$_POST`,
fournies dans yii par [[yii\web\Request::post()]].
Si le modèle est peuplé avec succès (c'est à dire, si l'utilisateur a soumis le formulaire HTML), l'action appellera
[[yii\base\Model::validate()|validate()]] pour s'assurer de la validité de toutes les valeurs.
> Info: L'expression `Yii::$app` représente l'instance d'[application](structure-applications.md), qui est un singleton
accessible de manière globale. C'est aussi un [annuaire de services](concept-service-locator.md) qui fournit des
composants tels que `request`, `response`, `db`, etc. pour assister des fonctionnalités spécifiques. Dans le code
ci-dessus, le composant `request` de l'instance d'application est utilisé pour accéder aux données `$_POST`.
Si tout se passe bien, l'action effectuera le rendu d'une vue nommée `entry-confirm` pour confirmer le succès de la
soumission à l'utilisateur. Si aucune donnée n'est soumise ou si les données contiennent des erreurs, la vue `entry`
sera générée, dans laquelle le formulaire HTML sera affiché, ainsi que tout message d'erreur de validation.
> Note: Dans cet exemple très simple, nous effectuons le rendu de la page de confirmation après soumission de données
valides. En pratique, vous devriez envisager d'utiliser [[yii\web\Controller::refresh()|refresh()]] ou
[[yii\web\Controller::redirect()|redirect()]] pour éviter les
[problèmes de multiple soumission de formulaire](https://fr.wikipedia.org/wiki/Post-Redirect-Get).
Créer des Vues
--------------
Enfin, créez deux fichiers de vue nommés `entry-confirm` et `entry`. Ceux-ci seront rendus par l'action `entry`,
comme décrit précédemment.
La vue `entry-confirm` affiche simplement les données de nom et email. Elle doit être placée dans le fichier
`views/site/entry-confirm.php`.
```php
Vous avez entré les informations suivantes :
- : nom) ?>
- : email) ?>
```
La vue `entry` affiche un formulaire HTML. Elle doit être stockée dans le placée `views/site/entry.php`.
```php
field($model, 'nom') ?>
field($model, 'email') ?>
'btn btn-primary']) ?>
```
La vue utilise un [widget](structure-widgets.md) puissant appelé [[yii\widgets\ActiveForm|ActiveForm]] pour construire
le formulaire HTML. Les méthodes `begin()` et `end()` du widget effectuent respectivement le rendu des tags ouvrant et
fermant du formulaire. Entre les deux appels de méthode, des champs de saisie sont créés par la méthode
[[yii\widgets\ActiveForm::field()|field()]]. Le premier champ de saisie concerne la donnée "nom", et le second la
donnée "email". Après les champs de saisie, la méthode [[yii\helpers\Html::submitButton()]] est appelée pour générer un
bouton de soumission.
Essayer
-------------
Pour voir comment ça fonctionne, utilisez votre navigateur pour accéder à l'URL suivante :
```
https://hostname/index.php?r=site/entry
```
Vous verrez une page affichant un formulaire comportant deux champs de saisie. Devant chaque champ de saisie, une
étiquette indique quelle donnée est attendue. Si vous cliquez sur le bouton de soumission sans entrer quoi que ce soit,
ou si vous ne fournissez pas d'adresse email valide, vous verrez un message d'erreur s'afficher à coté de chaque champ
de saisie posant problème.
Après avoir saisi un nom et une adresse email valide et cliqué sur le bouton de soumission, vous verrez une nouvelle
page affichant les données que vous venez de saisir.
### La Magie expliquée
Vous vous demandez peut-être comment le formulaire HTML fonctionne en coulisse, parce qu'il semble presque magique
qu'il puisse afficher une étiquette pour chaque champ de saisie et afficher sans rafraichir la page des messages
d'erreur si vous n'entrez pas les données correctement.
Oui, la validation de données est initialement faite coté client en Javascript, et ensuite effectuée coté serveur en
PHP.
[[yii\widgets\ActiveForm]] est suffisamment intelligent pour extraire les règles de validation que vous avez déclarées
dans `EntryForm`, le transformer en code Javascript exécutable, et utiliser le Javascript pour effectuer la validation
des données. Dans le cas où vous auriez désactivé le Javascript sur votre navigateur, la validation sera tout de même
effectuée coté serveur, comme montré dans la méthode `actionEntry()`. Cela garantit la validité des données en toutes
circonstances.
> Warning: La validation coté client est un confort qui permet une meilleure expérience utilisateur. La validation coté serveur est toujours nécessaire, que la validation coté client soit ou non en place.
Les étiquettes des champs de saisie sont générés par la méthode `field()`, en utilisant les noms des propriété du
modèle.
Par exemple, l'étiquette `Nom` sera générée à partir de la propriété `nom`.
Vous pouvez personnaliser une étiquette dans une vue en employant le code suivant :
```php
field($model, 'nom')->label('Votre Nom') ?>
field($model, 'email')->label('Votre Email') ?>
```
> Info: Yii fournit ne nombreux widgets pour vous aider à construire rapidement des vues complexes et dynamiques.
Comme vous l'apprendrez plus tard, écrire un widget et aussi extrêmement simple. Vous voudrez sans doute transformer une grande partie de votre code de vues en widgets réutilisables pour simplifier les développements de vues futurs.
Résumé
-------
Dans cette section du guide, vous avez touché toutes les parties du patron de conception MVC. Vous avez appris à créer
une classe modèle pour représenter les données utilisateur et valider lesdites données.
Vous avez également appris comment recevoir des données des utilisateurs et comment les réafficher dans le navigateur.
C'est une tâche qui peut prendre beaucoup de temps lors du développement d'une application, mais Yii propose des
widgets puissants pour rendre cette tâche très facile.
Dans la prochaine section, vous apprendrez comment travailler avec des bases de données, qui sont nécessaires dans presque toutes les applications.
================================================
FILE: docs/guide-fr/start-gii.md
================================================
Générer du code avec Gii
========================
Cette section décrit comment utiliser [Gii](https://www.yiiframework.com/extension/yiisoft/yii2-gii/doc/guide) pour générer du code qui met automatiquement en œuvre des fonctionnalités courantes de sites Web. Utiliser Gii pour auto-générer du code consiste simplement à saisir les bonnes informations en suivant les instructions affichées sur les pages Web de Gii.
Au long de ce tutoriel, vous apprendrez comment :
* Activer Gii dans votre application
* Utiliser Gii pour générer des classes Active Record (enregistrement actif)
* Utiliser Gii pour générer du code mettant en œuvre les opérations CRUD pour une table de BDD
* Personnaliser le code généré par Gii
Démarrer Gii
------------
[Gii](https://www.yiiframework.com/extension/yiisoft/yii2-gii/doc/guide) est fourni dans Yii en tant que [module](structure-modules.md). Vous pouvez activer Gii en le
configurant dans la propriété [[yii\base\Application::modules|modules]] de l’application. En fonction de la manière dont vous avez créé votre application, il se peut que le code suivant soit déjà fourni dans le fichier de configuration `config/web.php`:
```php
$config = [ ... ];
if (YII_ENV_DEV) {
$config['bootstrap'][] = 'gii';
$config['modules']['gii'] = [
'class' => 'yii\gii\Module',
];
}
```
La configuration ci-dessus établit que dans un [environnement de développement](concept-configurations.md#environment-constants), l’application doit inclure un module appelé `gii`, qui est de classe [[yii\gii\Module]].
Si vous vérifiez le [script de démarrage](structure-entry-scripts.md) `web/index.php` de votre application, vous y trouverez les lignes suivantes, qui en gros, font que `YII_ENV_DEV` est défini à `true` (vrai).
```php
defined('YII_ENV') or define('YII_ENV', 'dev');
```
Grâce à cette ligne, votre application est en mode développement, et active Gii, suivant la configuration vue ci-dessus. Vous pouvez maintenant accéder à Gii via l’URL suivante :
```
https://hostname/index.php?r=gii
```
> Note : si vous accédez à Gii depuis une machine autre que localhost, l’accès sera refusé par défaut pour des raisons
> de sécurité. Vous pouvez configurer Gii pour ajouter les adresses IP autorisées comme suit,
>
```php
'gii' => [
'class' => 'yii\gii\Module',
'allowedIPs' => ['127.0.0.1', '::1', '192.168.0.*', '192.168.178.20'] // ajustez cela suivant vos besoins
],
```
Générer une Classe Active Record
---------------------------------
Pour générer une classe Active Record avec Gii, sélectionnez le "Model Generator" (générateur de modèle), en cliquant sur le lien dans la page d'accueil de Gii, puis complétez le formulaire comme suit :
* Table Name: `country`
* Model Class: `Country`
Ensuite, cliquez sur le bouton "Preview" (prévisualiser). Vous verrez que `models/Country.php` est listé comme fichier de classe à créer. Vous pouvez cliquer sur le nom du fichier de classe pour prévisualiser son contenu.
Si vous avez déjà créé le même fichier, il sera écrasé. Cliquez sur le bouton `diff`
à côté du nom de fichier pour voir les différences entre le fichier à générer et la version existante.
Pour écraser un fichier existant, cochez la case située à côté de "overwrite" (écraser), puis cliquez sur le bouton "Generate" (générer). Pour créer un nouveau fichier, il suffit de cliquer sur "Generate".
En fin d'opération, vous verrez une page de confirmation indiquant que le code a été généré avec succès. Si vous aviez un fichier existant, vous verrez également un message indiquant qu’il a été écrasé par le code nouvellement généré.
Générer du Code CRUD
--------------------
CRUD signifie Create, Read, Update, and Delete (Créer, Lire, Mettre à Jour et Supprimer), soit les quatre tâches communes concernant des données sur la plupart des sites Web. Pour créer les fonctionnalités CRUD en utilisant Gii, sélectionnez le "CRUD Generator" en cliquant sur le lien dans la page d'accueil de Gii. Pour l’exemple de "country", remplissez le formulaire résultant comme suit :
* Model Class: `app\models\Country`
* Search Model Class: `app\models\CountrySearch`
* Controller Class: `app\controllers\CountryController`
Ensuite, cliquez sur le bouton "Preview" (prévisualiser). Vous verrez une liste de fichiers à générer, comme ci-dessous.
Si vous aviez précédemment créé les fichiers `controllers/CountryController.php` et
`views/country/index.php` (dans la section bases de données du guide), cochez la case "overwrite" (écraser) pour les remplacer.
(Les versions précédentes ne prenaient pas totalement en charge les fonctionnalités CRUD).
Essayer
-------------
Pour voir comment ça fonctionne, utilisez votre navigateur pour accéder à l’URL suivant :
```
https://hostname/index.php?r=country/index
```
Vous verrez une grille de données montrant les pays de la table de la base de données. Vous pouvez trier la table, ou lui appliquer des filtres en entrant des conditions de filtrage dans les entêtes de colonnes.
Pour chaque pays affiché dans la grille, vous pouvez choisir de visualiser les détails, le mettre à jour ou le supprimer.
Vous pouvez aussi cliquer sur le bouton "Create Country" (créer un pays) en haut de la grille pour que Yii vous présente un formulaire permettant de créer un nouveau pays.
Ce qui suit est la liste des fichiers générés par Gii, au cas où vous souhaiteriez investiguer la manière dont ces fonctionnalités sont mises en œuvre, ou les personnaliser :
* Contrôleur: `controllers/CountryController.php`
* Modèles: `models/Country.php` et `models/CountrySearch.php`
* Vues: `views/country/*.php`
> Info: Gii est conçu pour être un outil de génération de code hautement personnalisable et extensible. L’utiliser avec sagesse peut grandement accélérer le développement de vos applications. Pour plus de détails, merci de vous référer à la section [Gii](tool-gii.md).
Résumé
-------
Dans cette section, vous avez appris à utiliser Gii pour générer le code qui met en œuvre une fonctionnalité CRUD complète pour des contenus stockés dans une table de base de données.
================================================
FILE: docs/guide-fr/start-hello.md
================================================
Hello World
============
Cette section decrit la méthode pour créer une nouvelle page "Hello" dans votre application.
Pour ce faire, vous allez créer une [action](structure-controllers.md#creating-actions) et une [vue](structure-views.md):
* L'application distribuera la requête à l'action
* et à son tour, l'action générera un rendu de la vue qui affiche le mot "Hello" à l'utilisateur.
A travers ce tutoriel, vous apprendrez trois choses :
1. Comment créer une [action](structure-controllers.md) pour répondre aux requêtes,
2. comment créer une [vue](structure-views.md) pour composer le contenu de la réponse, et
3. comment une application distribue les requêtes aux [actions](structure-controllers.md#creating-actions).
Créer une Action
------------------
Pour la tâche "Hello", vous allez créer une [action](structure-controllers.md#creating-actions) `dire` qui reçoit un paramètre
`message` de la requête et affiche ce message à l'utilisateur. Si la requête ne fournit pas de paramètre `message`, l'action affichera le message par défaut "Hello".
> Info: Les [actions](structure-controllers.md#creating-actions) sont les objets auxquels les utilisateurs peuvent directement se référer pour les exécuter. Les actions sont groupées par [contrôleurs](structure-controllers.md). Le résultat de l'exécution d'une action est la réponse que l'utilisateur recevra.
Les actions doivent être déclarées dans des [contrôleurs](structure-controllers.md). Par simplicité, vous pouvez déclarer l'action `dire` dans le contrôleur existant `SiteController`. Ce contrôleur est défini dans le fichier classe `controllers/SiteController.php`. Voici le début de la nouvelle action :
```php
render('dire', ['message' => $message]);
}
}
```
Dans le code ci-dessous, l'action `dire` est définie par une méthode nommée `actionDire` dans la classe `SiteController`.
Yii utilise le préfixe `action` pour faire la différence entre des méthodes actions et des méthodes non-actions dans une classe contrôleur.
Le nom suivant le préfixe `action` est associé à l'ID de l'action.
Quand vous choisissez le nom de vos actions, gardez à l'esprit comment Yii traite les IDs d'action. Les références aux IDs d'actions sont toujours effectuées en minuscules. Si un ID d'action nécessite plusieurs mots, ils seront concaténés à l'aide de tirets (par exemple `creer-commentaire`). Les noms de méthodes actions sont associés aux IDs d'actions en retirant tout tiret des IDs, en mettant la première lettre de chaque mot en majuscule, et en ajoutant un préfixe `action` au résultat. Par exemple,
l'ID d'action `creer-commentaire` correspond à l'action nommée `actionCreerCommentaire`.
La méthode action de notre exemple prend un paramètre `$message`, dont la valeur par défaut est `"Hello"` (de la même manière qu'on affecte une valeur par défaut à n'importe quel argument de fonction ou méthode en PHP). Quand l'application reçoit une requête et détermine que l'action `dire` est responsable de gérer ladite requête, l'application peuplera ce paramètre avec le paramètre du même nom trouvé dans la requête. En d'autres termes, si la requête contient un paramètre `message` ayant pour valeur `"Goodbye"`, la variable `$message` au sein de l'action recevra cette valeur.
Au sein de la méthode action, [[yii\web\Controller::render()|render()]] est appelé pour effectuer le rendu d'un fichier [vue](structure-views.md) appelé `dire`. Le paramètre `message` est également transmis à la vue afin qu'il puisse y être utilisé. Le résultat du rendu est renvoyé à l'utilisateur par la méthode action. Ce résultat sera reçu par l'application et présenté à l'utilisateur dans le navigateur (en tant qu'élément d'une page HTML complète).
Créer une Vue
---------------
Les [vues](structure-views.md) sont des scripts qu'on écrit pour générer le contenu d'une réponse.
Pour la tâche "Hello", vous allez créer une vue `dire` qui affiche le paramètre `message` reçu de la méthode action, et passé par l'action à la vue :
```php
```
La vue `dire` doit être enregistrée dans le fichier `views/site/dire.php`. Quand la méthode [[yii\web\Controller::render()|render()]]
est appelée dans une action, elle cherchera un fichier PHP nommé `views/ControllerID/NomDeLaVue.php`.
Notez que dans le code ci-dessus, le paramètre `message` est [[yii\helpers\Html::encode()|Encodé-HTML]]
avant d'être affiché. Cela est nécessaire car le paramètre vient de l'utilisateur, le rendant vulnérable aux [attaques cross-site scripting (XSS)](https://fr.wikipedia.org/wiki/Cross-site_scripting) en intégrant du code Javascript malicieux dans le paramètre.
Bien entendu, vous pouvez insérer plus de contenu dans la vue `dire`. Le contenu peut être des tags HTMML, du texte brut, ou même des expressions PHP.
En réalité, la vue `dire` est simplement un script PHP exécuté par la méthode [[yii\web\Controller::render()|render()]].
Le contenu affiché par le script de vue sera renvoyé à l'application en tant que résultat de réponse. L'application renverra à son tour ce résultat à l'utilisateur.
Essayer
-------------
Après avoir créé l'action et la vue, vous pouvez accéder à la nouvelle page en accédant à l'URL suivant :
```
https://hostname/index.php?r=site/dire&message=Hello+World
```
Le résultat de cet URL sera une page affichant "Hello World". La page a les mêmes entête et pied de page que les autres pages de l'application.
Si vous omettez le paramètre `message` dans l'URL, La page devrait simplement afficher "Hello". C'est parce que `message` est passé en paramètre de la méthode `actionDire()`, et quand il est omis, la valeur par défaut `"Hello"` sera employée à la place.
> Info: L nouvelle page a les mêmes entête et pied de page que les autres pages parce que la méthode [[yii\web\Controller::render()|render()]] intègrera automatiquement le résultat de la vue `dire` dans une pseudo [mise en page](structure-views.md#layouts) qui dans notre cas est située dans `views/layouts/main.php`.
Le paramètre `r` dans l'URL ci-dessus nécessite plus d'explications. Il signifie [route](runtime-routing.md), un ID unique commun toute l'application qui fait référence à une action. Le format de la route est `IDContrôleur/IDAction`. Quand l'application reçoit une requête, elle vérifie ce paramêtre, en utilisant la partie `IDContrôleur` pour déterminer quel classe contrôleur doit être instanciée pour traiter la requête. Ensuite, le contrôleur utilisera la partie `IDAction` pour déterminer quelle action doit être instanciée pour effectuer le vrait travail. Dans ce cas d'exemple, la route `site/dire`
sera comprise comme la classe contrôleur `SiteController` et l'action `dire`. Il en resultera que la méthode `SiteController::actionDire()` sera appelée pour traiter la requête.
> Info: De même que les actions, les contrôleurs ont des IDs qui les identifient de manière unique dans une application.
Les IDs de contrôleurs emploie les mêmes règles de nommage que les IDs d'actions. Les noms de classes Contrôleurs dérivent
des IDs de contrôleurs en retirant les tirets des IDs, en mettant la première lettre de chaque mot en majuscule,
et en suffixant la chaîne résultante du mot `Controller`. Par exemple, l'ID de contrôlleur `poster-commentaire` correspond
au nom de classe contrôleur `PosterCommentaireController`.
Résumé
-------
Dans cette section, vous avez touché aux parties contrôleur et vue du patron de conception MVC.
Vous avez créé une action au sein d'un contrôleur pour traiter une requête spécifique. Vous avez également créé une vue pour composer le contenu de la réponse. Dans ce simple exemple, aucun modèle n'a été impliqué car les seules données utilisées étaient le paramètre `message`.
Vous avez également appris ce que sont les routes dans Yii, qu'elles font office de pont entre les requêtes utilisateur et les actions des contrôleurs.
Dans la prochaine section, vous apprendrez comment créer un modèle, et ajouter une nouvelle page contenant un formulaire HTML.
================================================
FILE: docs/guide-fr/start-installation.md
================================================
Installer Yii
=============
Vous pouvez installer Yii de deux façons, en utilisant le gestionnaire de paquets [Composer](https://getcomposer.org/) ou en téléchargeant une archive.
La première méthode est conseillée, étant donné qu'elle permet d'installer de nouvelles [extensions](extend-creating-extensions.md) ou de mettre Yii à jour en exécutant simplement une commande.
Les installations standard de Yii provoquent le téléchargement et l'installation d'un modèle de projet. Un modèle de projet et un projet Yii fonctionnel qui met en œuvre quelques fonctionnalités de base, telles que la connexion, le formulaire de contact, etc.
Son code est organisé de la façon recommandée. En conséquence, c'est un bon point de départ pour vos propres projets.
Dans cette section et quelques-unes de ses suivantes, nous décrirons comment installer Yii avec le modèle baptisé *Basic Project Template* (modèle de projet de base) et comment mettre en œuvre de nouvelles fonctionnalités sur cette base. Yii vous offre également un autre modèle de projet appelé [Advanced Project Template ](https://www.yiiframework.com/extension/yiisoft/yii2-app-advanced/doc/guide) (modèle de projet avancé) qui convient mieux à un environnement de développement en équipe impliquant des tiers multiples.
> Note: le modèle de projet de base conviendra à 90 pourcent des application Web. Il diffère du modèle de projet avancé essentiellement sur la manière dont le code est organisé. Si vous débutez avec Yii, nous vous conseillons fortement de vous en tenir au modèle de projet de base pour sa simplicité tout en disposant des fonctionnalités suffisantes.
Installer via Composer
----------------------
### Installer Composer
Si vous n'avez pas déjà installé Composer, vous pouvez le faire en suivant les instructions du site [getcomposer.org](https://getcomposer.org/download/).
Sous Linux et Mac OS X, vous pouvez exécuter les commandes :
```bash
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer
```
Sous Windows, téléchargez et exécutez [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe).
En cas de problèmes, consultez la [section Troubleshooting (résolution des problèmes) de la documentation de Composer](https://getcomposer.org/doc/articles/troubleshooting.md),
Si vous débutez avec Composer, nous vous recommandons au minimum la lecture de la section [Basic usage (utilisation de base)](https://getcomposer.org/doc/01-basic-usage.md) de la documentation de Composer
Dans ce guide, toutes les commandes de Composer suppose que vous avez installé Composer [globalement](https://getcomposer.org/doc/00-intro.md#globally) et qu'il est disponible par la commande `composer`. Si, au lieu de cela, vous utilisez `composer.phar` depuis un dossier local, vous devez adapter les exemples fournis en conséquence.
Si Composer était déjà installé auparavant, assurez-vous d'utiliser une version à jour. Vous pouvez mettre Composer à jour avec la commande `composer self-update`.
> Note: durant l'installation de Yii, Composer aura besoin d'obtenir de nombreuses informations de l'API de Github. Le nombre de requêtes dépend du nombre de dépendances de votre application et peut excéder la **Github API rate limit**. Si vous arrivez à cette limite, Composer peut vous demander vos identifiants de connexion pour obtenir un jeton d'accès à l'API de Github. Avec une connexion rapide, vous pouvez atteindre cette limite plus vite que Composer n'est capable de gérer. C'est pourquoi, nous vous recommandons de configurer ce jeton d'accès avant d'installer Yii.
> Reportez-vous à la [documentation de Composer sur les jetons de l'API Github](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens)
> pour savoir comment procéder.
### Installer Yii
Avec Composer installé, vous pouvez installer le modèle de projet Yii en exécutant la commande suivante dans un dossier accessible via le Web :
```bash
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
```
Cette commande installera la dernière version stable du modèle de projet Yii dans le dossier `basic`. Vous êtes libre de choisir un autre dossier si vous le désirez.
> Note: si la commande `composer create-project` échoue, reportez-vous à la section
> [Troubleshooting (résolution des problèmes) de la documentation de Composer](https://getcomposer.org/doc/articles/troubleshooting.md)
> pour les erreurs communes. Une fois l'erreur corrigée, vous pouvez reprendre l'installation avortée en exécutant `composer update` dans le dossier `basic` (ou celui que vous aviez choisi).
> Tip: si vous souhaitez installer la dernière version de développement de Yii, vous pouvez utiliser la commande suivante qui ajoutera l'[option stability](https://getcomposer.org/doc/04-schema.md#minimum-stability) :
>
>```bash
>composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic basic
>```
>
> Notez que la version de développement de Yii ne doit pas être utilisée en production, vu qu'elle pourrait *casser* votre code existant.
Installer depuis une archive
----------------------------
Installer Yii depuis une archive se fait en trois étapes :
1. Télécharger l'archive sur le site [yiiframework.com](https://www.yiiframework.com/download/).
2. Décompresser l'archive dans un dossier accessible via le Web.
3. Modifier le fichier `config/web.php` en entrant une clé secrète pour la configuration de `cookieValidationKey` (cela est fait automatiquement si vous installez Yii avec Composer) :
```php
// !!! insert a secret key in the following (if it is empty) - this is required by cookie validation
'cookieValidationKey' => 'enter your secret key here',
```
Autres options d'installation
-----------------------------
Les instructions d'installation ci-dessus montrent comment installer Yii, ce qui installe également une application Web de base qui fonctionne *out of the box* (sans configuration supplémentaire).
Cette approche est un bon point de départ pour les petits projets, en particulier si vous débutez avec Yii.
Mais il y a d'autres options d'installation disponibles :
* Si vous voulez installer uniquement le framework et que vous souhaitez créer une application à partir de zéro, vous pouvez suivre les instructions dans la partie [Créer votre propre structure d'application](tutorial-start-from-scratch.md).
* Si vous voulez commencer par une application plus sophistiquée, mieux adaptée aux environnements d'équipe de développement, vous pouvez envisager l'installation du [Modèle d'application avancée](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md).
Installer les Assets (ici bibliothèques CSS et JavaScript)
-----------------
Yii s'appuie sur les paquets [Bower](https://bower.io/) et/ou [NPM](https://www.npmjs.com/) pour l'installation des bibliothèques CSS et JavaScript.
Il utilise Composer pour les obtenir, permettant ainsi aux versions de paquet de PHP et à celles de CSS/JavaScript, d'être résolues en même temps.
Cela peut être obtenue soit en utilisant [asset-packagist.org](https://asset-packagist.org) ou [composer asset plugin](https://github.com/fxpio/composer-asset-plugin).
Reportez-vous à la documentation sur les [Assets](structure-assets.md) pour plus de détail.
Vous pouvez souhaiter gérer vos « assets », soit via le client natif Bower/NPM, soit via CDN, soit éviter totalement leur installation.
Afin d'empêcher l'installation des « assets » via Composer, ajoutez les lignes suivantes à votre fichier 'composer.json' :
```json
"replace": {
"bower-asset/jquery": ">=1.11.0",
"bower-asset/inputmask": ">=3.2.0",
"bower-asset/punycode": ">=1.3.0",
"bower-asset/yii2-pjax": ">=2.0.0"
},
```
> Note: en cas de neutralisation de l'installation des « assets » via Composer, c'est à vous d'en assurer l'installation et de résoudre les problèmes de collision de versions. Attendez-vous à des incohérences possibles parmi les fichiers d'assets issus de vos différentes extensions.
Vérifier l'installation
-----------------------
Après l'installation, vous pouvez, soit configurer votre serveur Web (voir section suivante), soit utiliser le [serveur PHP web incorporé](https://www.php.net/manual/fr/features.commandline.webserver.php) en utilisant la commande en console suivante depuis le dossier racine de votre projet :
```bash
php yii serve
```
> Note: par défaut le serveur HTTP écoute le port 8080. Néanmoins, si ce port est déjà utilisé ou si vous voulez servir plusieurs applications de cette manière, vous pouvez spécifier le port à utiliser en ajoutant l'argument --port à la commande :
```bash
php yii serve --port=8888
```
Pour accéder à l'application Yii pointez votre navigateur sur l'URL suivante :
```
http://localhost:8080/
```
Vous devriez voir dans votre navigateur la page ci-dessus. Sinon, merci de vérifier que votre installation remplit bien les pré-requis de Yii. Vous pouvez vérifier cela en utilisant l'une des approches suivantes :
* Utilisez un navigateur pour accéder à l'URL `http://localhost/basic/requirements.php`
* Exécutez les commandes suivantes:
```bash
cd basic
php requirements.php
```
Vous devez configurer votre installation de PHP afin qu'elle réponde aux exigences minimales de Yii. Le plus important étant que vous ayez PHP 5.4 ou plus, idéalement PHP 7. Si votre application a besoin d'une base de données, vous devez également installer l'[extension PHP PDO](https://www.php.net/manual/fr/pdo.installation.php) ainsi qu'un pilote correspondant à votre système de base de données (par exemple `pdo_mysql` pour MySQL).
Configuration du serveur Web
----------------------------
> Note: si vous voulez juste tester Yii sans intention de l'utiliser sur un serveur de production, vous pouvez ignorer ce paragraphe.
L'application installée selon les instructions ci-dessus devrait fonctionner *out of the box* (sans configuration supplémentaire) avec le [serveur HTTP Apache](https://httpd.apache.org/) ou le [serveur HTTP Nginx](https://nginx.org/), sous Windows, Mac OX X, ou Linux avec PHP 5.4 ou plus récent. Yii 2.0 est aussi compatible avec
[HHVM](https://hhvm.com/) de Facebook. Cependant, il existe des cas marginaux pour lesquels HHVM se comporte différemment du PHP natif; c'est pourquoi vous devez faire plus attention en utilisant HHVM..
Sur un serveur de production, vous pouvez configurer votre serveur Web afin que l'application soit accessible via l'URL `https://www.example.com/index.php` au lieu de `https://www.example.com/basic/web/index.php`. Cela implique que le dossier racine de votre serveur Web pointe vers le dossier `basic/web`.
Vous pouvez également cacher `index.php` dans l'URL, comme décrit dans la partie [Génération et traitement des URL](runtime-url-handling.md), vous y apprendrez comment configurer votre serveur Apache ou Nginx pour atteindre ces objectifs.
> Note: en utilisant `basic/web` comme dossier racine, vous empêchez également aux utilisateurs finaux d'accéder à votre code d'application privé et fichiers de données sensibles qui sont stockés dans le dossier `basic`. Refuser l'accès à ces ressources est une amélioration de la sécurité.
> Note: si votre application s'exécute dans un environnement d'hébergement mutualisé où vous n'avez pas la permission de modifier la configuration du serveur Web, vous pouvez ajuster la structure de votre application pour une meilleure sécurité. Reportez-vous à la partie [Environnement d'hébergement mutualisé](tutorial-shared-hosting.md) pour en savoir plus.
> Note: si vous exécutez votre application Yii derrière un mandataire inverse, vous pourriez avoir besoin de configurer les
> [mandataires de confiance et entêtes](runtime-requests.md#trusted-proxies) dans le composant « request ».
### Configuration Apache recommandée
Utilisez la configuration suivante dans le fichier `httpd.conf`, ou dans la configuration de votre hôte virtuel. Notez que vous devez remplacer `path/to/basic/web` par le chemin vers le dossier `basic/web`.
```apache
# Configuration du dossier racine
DocumentRoot "path/to/basic/web"
# utiliser mod_rewrite pour la prise en charge des URL élégantes ("pretty URL")
RewriteEngine on
# Si le dossier ou fichier existe, répondre directement
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# Sinon on redirige vers index.php
RewriteRule . index.php
# si $showScriptName est à "false" dans UrlManager, ne pas autoriser l'accès aux URL incluant le nom du script
RewriteRule ^index.php/ - [L,R=404]
# ...other settings...
```
### Configuration Nginx recommandée
Pour utiliser Nginx, vous devez avoir installé PHP en utilisant [FPM SAPI](https://www.php.net/manual/fr/install.fpm.php).
Utilisez la configuration Nginx suivante, en remplaçant `path/to/basic/web` par le chemin vers le dossier `basic/web` et `mysite.test` par le nom d'hôte de votre serveur.
```nginx
server {
charset utf-8;
client_max_body_size 128M;
listen 80; ## listen for ipv4
#listen [::]:80 default_server ipv6only=on; ## listen for ipv6
server_name mysite.test;
root /path/to/basic/web;
index index.php;
access_log /path/to/basic/log/access.log;
error_log /path/to/basic/log/error.log;
location / {
# Rediriger tout ce qui n'est pas un fichier réel index.php
try_files $uri $uri/ /index.php$is_args$args;
}
# enlevez les commentaires de ces lignes pour évitez que Yii ne gère les requêtes vers des fichiers statiques inexistants
#location ~ \.(js|css|png|jpg|gif|swf|ico|pdf|mov|fla|zip|rar)$ {
# try_files $uri =404;
#}
#error_page 404 /404.html;
# refuser l'accès aux fichiers php pour le dossier /assets
location ~ ^/assets/.*\.php$ {
deny all;
location ~ \.php$ {
include fastcgi.conf;
fastcgi_pass 127.0.0.1:9000;
#fastcgi_pass unix:/var/run/php5-fpm.sock;
}
location ~ /\.(ht|svn|git) {
deny all;
}
}
```
Lorsque vous utilisez cette configuration, vous devez aussi mettre l'option `cgi.fix_pathinfo=0` dans le fichier `php.ini` afin d'éviter de nombreux appels système à `stat()`.
Notez également que lors de l'utilisation d'un serveur HTTPS, vous devez ajouter l'option `fastcgi_param HTTPS on;` afin que Yii puisse détecter correctement si une connexion est sécurisée.
================================================
FILE: docs/guide-fr/start-looking-ahead.md
================================================
En savoir plus
=============
Si vous avez entièrement lu la section "Mise en Route", vous avez maintenant créé une application Yii complète. Ce faisant, vous avez appris comment mettre en œuvre des fonctionnalités couramment utilisées, telles que recueillir des données d'un utilisateur via un formulaire HTML, chercher des données dans une base de données, et afficher des données
de manière paginée. Vous avez également appris à utiliser [Gii](https://www.yiiframework.com/extension/yiisoft/yii2-gii/doc/guide) pour générer du code automatiquement.
Utiliser Gii pour générer du code rend le gros de votre processus de développement Web aussi simple que de remplir de
simples formulaires.
Cette section va résumer les ressources Yii disponibles pour vous aider à être plus productif dans l'utilisation du framework.
* Documentation
- [Le Guide complet](https://www.yiiframework.com/doc-2.0/guide-README.html) :
Comme son nom l'indique, le guide définit précisément comment Yii fonctionne et fournit des instructions générales
sur l'utilisation de Yii. C'est le tutoriel pour Yii le plus important, un que vous devriez lire avant d'écrire le
moindre code Yii.
- [Le référentiel des Classes](https://www.yiiframework.com/doc-2.0/index.html) :
Il spécifie le mode d'utilisation de toutes les classes fournies par Yii. Il doit être principalement utilisé lorsque
vous écrivez du code et souhaitez comprendre le mode d'utilisation d'une classe, méthode ou propriété particulière.
L'utilisation du référentiel des classes est plus appropriée quand vous avez une compréhension contextuelle du framework entier.
- [Les Articles du Wiki](https://www.yiiframework.com/wiki/?tag=yii2):
Les articles wiki sont écrits par des utilisateurs de Yii sur la base de leurs propres expériences. Ils sont en
général écrits comme des recettes de cuisine, et montrent comment résoudre des problèmes pratiques en utilisant
Yii. Bien que la qualité de ces articles puisse être moindre que celle du Guide complet, ils sont utiles du fait
qu'ils couvrent des sujets plus vastes et peuvent fournir des solutions clef-en-main.
- [Livres](https://www.yiiframework.com/books)
* [Extensions](https://www.yiiframework.com/extensions/):
Yii est fort d'une librairie de milliers d'extensions créées par les utilisateurs, qui peuvent être facilement
ajoutées à votre application, rendant son développement encore plus facile et plus rapide.
* Communauté
- Forum :
- Chat IRC : Les canal #yii sur le réseau Libera ()
- Slack chanel:
- Gitter chat:
- GitHub:
- Facebook:
- Twitter:
- LinkedIn:
- Stackoverflow:
================================================
FILE: docs/guide-fr/start-prerequisites.md
================================================
# Que devez-vous connaître
La courbe d'apprentissage de Yii n’est pas aussi raide que celle des autres framework. Cependant, il y a un certain nombre de choses que vous devriez connaître avant de vous lancer avec Yii.
## PHP
Yii un framework (base structurée de développement) en PHP. C’est pourquoi vous devez vous assurer de [maîtriser ce langage en comprenant sa référence](https://www.php.net/manual/fr/langref.php).
Lors de votre développement avec Yii, vous écrirez du code dans le style « orienté objet ». Vous devez donc être familiarisé avec les [Classes et Objets](https://www.php.net/manual/fr/language.oop5.basic.php), ainsi qu'avec les [espaces de noms](https://www.php.net/manual/fr/language.namespaces.php).
## Programmation orientée Objet
Une compréhension de base de la programmation orientée objet est requise. Si vous n’êtes pas familiarisé avec elle, orientez-vous vers l’un des nombreux tutoriels disponibles tels que [celui de tuts+](https://code.tutsplus.com/tutorials/object-oriented-php-for-beginners--net-12762).
Notez que plus votre application sera complexe, plus vous devrez en savoir pour gérer cette complexité avec succès.
## Ligne de commande et composer
Yii utilise abondamment le gestionnaire de paquet [Composer](https://getcomposer.org/) qui est un standard de fait. Vous devez donc lire et comprendre son [guide](https://getcomposer.org/doc/01-basic-usage.md). Si vous n’êtes pas encore familiarisé avec la ligne de commande, c’est le moment de vous y essayer. Une fois les bases acquises, vous ne saurez plus vous en passer.
================================================
FILE: docs/guide-fr/start-workflow.md
================================================
Fonctionnement des applications
===============================
Après avoir installé Yii, vous obtenez une application Yii fonctionnelle accessible via l'URL `https://hostname/basic/web/index.php` ou `https://hostname/index.php`, en fonction
de votre configuration. Cette section vous initiera aux fonctionnalités intégrées à l'application,
à la manière dont le code est organisé et à la gestion des requêtes par l'application.
> Info: pour simplifier, au long de ce tutoriel de démarrage, nous supposerons que `basic/web` est la racine de votre
serveur Web, et que vous avez configuré l'URL pour accéder à votre application comme suit ou de façon similaire :
`https://hostname/index.php`.
Pour vos besoins, merci d'ajuster les URLs dans notre description comme il convient.
Notez que contrairement au framework lui-même, après avoir installé un modèle de projet, vous êtes entièrement libre d'en disposer. Vous êtes libre d'ajouter ou de supprimer du code selon vos besoins.
Fonctionnalité
--------------
L'application basique installée contient quatre pages :
* La page d'accueil, affichée quand vous accédez à l'URL `https://hostname/index.php`,
* la page "About" (À Propos),
* la page "Contact", qui présente un formulaire de contact permettant aux utilisateurs finaux de vous contacter par courriel,
* et la page "Login" (Connexion), qui présente un formulaire de connexion qui peut être utilisé pour authentifier des utilisateurs finaux. Essayez de vous connecter
avec "admin/admin", et vous verrez l'élément "Login" du menu principal être remplacé par "Logout" (Déconnexion).
Ces pages ont en commun une entête et un pied de page. L'entête contient une barre de menu principal qui permet la navigation
entre les différentes pages.
Vous devriez également voir une barre d'outils en bas de votre fenêtre de navigation.
C'est un [outil de débogage](https://github.com/yiisoft/yii2-debug/blob/master/docs/guide/README.md) utile fourni par Yii pour enregistrer et afficher de nombreuses informations de débogage, telles que des messages de journaux, les statuts de réponses, les requêtes lancées vers la base de données, etc.
En plus de l'application Web, il existe,dans le dossier de base de l'application, un script en console appelé `yii`. Ce script peut être utilisé pour exécuter des tâches de fond et de maintenance pour l'application; ces tâches sont décrites à la section [Applications en console](tutorial-console.md).
Structure de l'application
---------------------
Les répertoires et fichiers les plus importants de votre application sont (en supposant que le répertoire racine de l'application est `basic`) :
```
basic/ chemin de base de l'application
composer.json utilisé par Composer, décrit les information de paquets
config/ contient les configurations de l'application et autres
console.php configuration de l'application console
web.php configuration de l'application Web
commands/ contient les classes de commandes console
controllers/ contient les classes de contrôleurs
models/ contient les classes de modèles
runtime/ contient les fichiers générés par Yii au cours de l'exécution, tels que les fichiers de logs ou de cache and cache
vendor/ contient les paquets Composer installés, y compris le framework Yii
views/ contient les fichiers de vues
web/ racine Web de l'application, contient les fichiers accessibles via le Web
assets/ contient les fichiers assets (javascript et css) publiés par Yii
index.php le script de démarrage (ou bootstrap) pour l'application
yii le script d'exécution de Yii en commande console
```
Dans l'ensemble, les fichiers de l'application peuvent être séparés en deux types : ceux situés dans `basic/web` et ceux situés dans d'autres répertoires. Les premiers peuvent être atteints directement en HTTP (c'est à dire dans un navigateur), tandis que les seconds ne peuvent et ne doivent pas l'être.
Yii est mis en œuvre selon le modèle de conception [modèle-vue-contrôleur (MVC)](https://wikipedia.org/wiki/Model-view-controller),
ce qui se reflète dans l'organisation des répertoires ci-dessus. Le répertoire `models` contient toutes les [classes modèles](structure-models.md),
le répertoire `views` contient tous les [scripts de vue](structure-views.md), et le répertoire `controllers` contient toutes les [classes contrôleurs](structure-controllers.md).
Le schéma suivant présente la structure statique d'une application.
Chaque application dispose d'un script de démarrage `web/index.php` qui est le seul script PHP de l'application accessible depuis le Web.
Le script de démarrage reçoit une requête entrante et crée une instance d'[application](structure-applications.md) pour la traiter.
L'[application](structure-applications.md) résout la requête avec l'aide de ses [composants](concept-components.md),
et distribue la requête aux éléments MVC. Les [composants graphiques (widgets)](structure-widgets.md) sont utilisés dans les [vues](structure-views.md)
pour aider à créer des éléments d'interface complexes et dynamiques.
Cycle de vie d'une requête
-----------------
Le diagramme suivant présente la manière dont une application traite une requête.
1. Un utilisateur fait une requête au [script de démarrage](structure-entry-scripts.md) `web/index.php`.
2. Le script de démarrage charge la [configuration](concept-configurations.md) de l'application et crée une instance d'[application](structure-applications.md) pour traiter la requête.
3. L'application résout la [route](runtime-routing.md) requise avec l'aide du composant d'application [requête](runtime-requests.md).
4. L'application créé une instance de [contrôleur](structure-controllers.md) pour traiter la requête.
5. Le contrôleur crée une instance d'[action](structure-controllers.md) et applique les filtres pour l'action.
6. Si un filtre échoue, l'action est annulée.
7. Si tous les filtres sont validés, l'action est exécutée.
8. L'action charge un modèle de données, potentiellement depuis une base de données.
9. L'action génère une vue, lui fournissant le modèle de données.
10. Le résultat généré est renvoyé au composant d'application [response](runtime-responses.md).
11. Le composant « response » (réponse) envoie le résultat généré au navigateur de l'utilisateur.
================================================
FILE: docs/guide-fr/structure-application-components.md
================================================
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
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.
Vous pouvez également utiliser des « Closures » (Fermetures) pour amorcer des composants personnalisés. Il n'est pas nécessaire de retourner une instance de composant. Une « Closure » peut également être utilisée pour exécuter du code après l'instanciation de [[yii\base\Application]].
Par exemple, la configuration d'application suivante garantit que le composant `log` est toujours chargé.
```php
[
'bootstrap' => [
'log',
function($app){
return new ComponentX();
},
function($app){
// some code
return;
}
],
'components' => [
'log' => [
// configuration le composant "log"
],
],
]
```
## Composants d'application du noyau
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 [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 bases de 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|mailer]]: 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 [Routage 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.
================================================
FILE: docs/guide-fr/structure-applications.md
================================================
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
Lorsqu'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
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
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]]
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]]
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
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]]
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)]]
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)]]
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)]]
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 (Table de mise en correspondance des contrôleurs)]]
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]]
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)]]
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, l'objet graphique [[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 ](https://fr.wikipedia.org/wiki/%C3%89tiquette_d%27identification_de_langues_IETF) 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]]
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]]
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)]]
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)]]
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](https://fr.wikipedia.org/wiki/%C3%89tiquette_d%27identification_de_langues_IETF). 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)]]
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()](https://www.php.net/manual/fr/function.date-default-timezone-set.php). Par exemple :
```php
[
'timeZone' => 'America/Los_Angeles',
]
```
#### [[yii\base\Application::version|version]]
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
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)]]
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) ]]
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]]
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)]]
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)]]
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)]]
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)]]
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)]]
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)]]
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
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]]
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]]
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]]
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]]
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
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.
================================================
FILE: docs/guide-fr/structure-assets.md
================================================
Ressources
==========
Une ressource dans Yii est un fichier qui peut être référencé dans une page Web. Ça peut être un fichier CSS, un fichier JavaScript, une image, un fichier vidéo, etc.
Les ressources sont situées dans un dossier accessible du Web et sont servies directement par les serveurs Web.
Il est souvent préférable de gérer les ressources par programmation.
Par exemple, lorsque vous utilisez l'objet graphique [[yii\jui\DatePicker]] dans une page, il inclut automatiquement les fichiers CSS et JavaScript dont il a besoin, au lieu de vous demander de les inclure à la main.
De plus, lorsque vous mettez à jour l'objet graphique, il utilise une nouvelle version des fichiers de ressources.
Dans ce tutoriel, nous décrivons les puissantes possibilités de la gestion des ressources de Yii.
## Paquets de ressources
Yii gère les ressources sous forme de *paquets de ressources*.
Un paquet de ressources est simplement une collection de ressources situées dans un dossier.
Lorsque vous enregistrez un paquet de ressources dans une [vue](structure-views.md), cette vue inclut les fichiers CSS et JavaScript du paquet dans la page Web rendue.
## Définition de paquets de ressources
Les paquets de ressources sont spécifiés comme des classes PHP qui étendent [[yii\web\AssetBundle]].
Le nom du paquet est simplement le nom pleinement qualifié de la classe PHP correspondante (sans la barre oblique inversée de tête).
Une classe de paquet de ressources doit être [auto-chargeable](concept-autoloading.md).
Généralement, elle spécifie où les ressources sont situées, quels fichiers CSS et JavaScript le paquet contient, et si le paquet dépend d'autres paquets de ressources.
Le code suivant définit le paquet de ressources principal utilisé par le [modèle de projet *basic*](start-installation.md):
```php
'print'],
];
public $js = [
];
public $depends = [
'yii\web\YiiAsset',
'yii\bootstrap\BootstrapAsset',
];
}
```
La classe `AppAsset` ci-dessus spécifie que les fichiers de ressources sont situés dans le dossier `@webroot` qui correspond à l'URL `@web`;
le paquet contient un unique fichier CSS `css/site.css` et aucun fichier JavaScript ;
le paquet dépend de deux autres paquets : [[yii\web\YiiAsset]] et [[yii\bootstrap\BootstrapAsset]].
Des explications plus détaillées sur les propriétés d'[[yii\web\AssetBundle]] sont disponibles dans les ressources suivantes :
* [[yii\web\AssetBundle::sourcePath|sourcePath]] (chemin des sources): spécifie le dossier racine qui contient les fichiers de ressources dans ce paquet.
Cette propriété doit être définie si le dossier
racine n'est pas accessible du Web.
Autrement, vous devez définir les propriétés [[yii\web\AssetBundle::basePath|basePath]] et [[yii\web\AssetBundle::baseUrl|baseUrl]]. Des [alias de chemin](concept-aliases.md) sont utilisables ici.
* [[yii\web\AssetBundle::basePath|basePath ]] (chemin de base): spécifie un dossier accessible du Web qui contient les fichiers de ressources dans ce paquet.
Lorsque vous spécifiez la propriété[[yii\web\AssetBundle::sourcePath|sourcePath (chemin des sources)]], le [gestionnaire de ressources](#asset-manager) publie les ressources de ce paquet dans un dossier accessible du Web et redéfinit cette propriété en conséquence.
Vous devez définir cette propriété si vos fichiers de ressources sont déjà
dans un dossier accessible du Web et n'ont pas besoin d'être publiés.
Les [alias de chemin](concept-aliases.md) sont utilisables ici.
* [[yii\web\AssetBundle::baseUrl|baseUrl ]] (URL de base): spécifie l'URL qui correspond au dossier
[[yii\web\AssetBundle::basePath|basePath]].
Comme pour [[yii\web\AssetBundle::basePath|basePath]] (chemin de base),
si vous spécifiez la propriété [[yii\web\AssetBundle::sourcePath|sourcePath]], le [gestionnaire de ressources](#asset-manager) publie les ressources et redéfinit cette propriété en conséquence. Les [alias de chemin](concept-aliases.md) sont utilisables ici.
* [[yii\web\AssetBundle::css|css]]: un tableau listant les fichiers CSS contenu dans ce paquet de ressources.
Notez que seul la barre oblique "/" doit être utilisée en tant que séparateur de dossier. Chaque fichier peut être spécifié en lui-même comme une chaîne de caractères ou dans un tableau avec les balises attributs et leur valeur.
* [[yii\web\AssetBundle::js|js]]: un tableau listant les fichiers JavaScript contenus dans ce paquet.
Notez que seule la barre oblique de division "/" peut être utilisée en tant que séparateur de dossiers.
Chaque fichier JavaScript peut être spécifié dans l'un des formats suivants :
- Un chemin relatif représentant un fichier JavaScript local (p. ex. `js/main.js`).
Le chemin réel du fichier peut être déterminé en préfixant le chemin relatif avec le [[yii\web\AssetManager::basePath| chemin de base]],
et l'URL réelle du fichier peut être déterminée en préfixant le chemin relatif avec l'[[yii\web\AssetManager::baseUrl|URL de base]].
- Une URL absolue représentant un fichier JavaScript externe.
Par exemple , `https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js` ou
`//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js`.
* [[yii\web\AssetBundle::depends|depends (dépendances)]]:
un tableau listant les paquets de ressources dont ce paquet dépend (brièvement expliqué).
* [[yii\web\AssetBundle::jsOptions|jsOptions]]: spécifie les options qui sont passées à la méthode [[yii\web\View::registerJsFile()]]
lorsqu'elle est appelée pour enregistrer *chacun des* fichiers JavaScript de ce paquet.
* [[yii\web\AssetBundle::cssOptions|cssOptions]]: spécifie les options qui sont passées à la méthode
[[yii\web\View::registerCssFile()]] lorsqu'elle est appelée pour enregistrer *chacun des* fichiers CSS de ce paquet.
* [[yii\web\AssetBundle::publishOptions|publishOptions]]: spécifie les options qui sont passées à la méthode
[[yii\web\AssetManager::publish()]] lorsqu'elle est appelée pour publier les fichiers de ressources sources dans un dossier accessible du Web.
Cela n'est utilisé que si vous spécifiez la propriété [[yii\web\AssetBundle::sourcePath|sourcePath]].
### Emplacement des ressources
En se basant sur leur emplacement, les ressources peuvent être classifiées comme suit :
* Les ressources sources : les fichiers de ressources qui sont situés avec du code source PHP et qui ne peuvent être accéder directement depuis le Web.
Afin de pouvoir être utilisées dans une page, elles doivent être copiées dans un dossier accessible du Web et transformées en ressources publiées.
Ce processus est appelé *publication des ressources* et il sera décrit en détail bientôt.
* Les ressources publiées : les fichiers de ressources sont situés dans un dossier accessible du Web et peuvent par conséquent être accédés directement depuis le Web.
* Les ressources externes : les fichiers de ressources sont situés sur un serveur Web différent de celui qui héberge l'application Web.
Lors de la définition de classes de paquet de ressources, si vous spécifiez la propriété
[[yii\web\AssetBundle::sourcePath|sourcePath (chemin des sources)]], cela veut dire que les ressources listées en utilisant des chemins relatifs sont considérées comme des ressources sources.
Si vous ne spécifiez pas cette propriété, cela signifie que ces ressources sont des ressources publiées (vous devez en conséquence spécifier [[yii\web\AssetBundle::basePath (chemin de base)|basePath]] et [[yii\web\AssetBundle::baseUrl|baseUrl (URL de base)]]
pour faire connaître à Yii l'emplacement où elles se trouvent).
Il est recommandé de placer les ressources appartenant à une application dans un dossier accessible du Web de manière à éviter une publication non nécessaire de ressources.
C'est pourquoi `AppAsset` dans l'exemple précédent spécifie le [[yii\web\AssetBundle::basePath|chemin de base]]
plutôt que le [[yii\web\AssetBundle::sourcePath|chemin des sources]].
Quant aux [extensions](structure-extensions.md), comme leurs ressources sont situées avec le code source dans des dossiers non accessibles depuis le Web, vous devez spécifier la propriété
[[yii\web\AssetBundle::sourcePath|sourcePath]]
lorsque vous définissez des classes de paquet de ressources pour elles.
> Note: n'utilisez pas `@webroot/assets` en tant que [[yii\web\AssetBundle::sourcePath|chemin des sources]].
Ce dossier est utilisé par défaut par le
[[yii\web\AssetManager|gestionnaire de ressources]] pour sauvegarder les fichiers de ressources publiés depuis leur emplacement source.
Tout contenu dans ce dossier est considéré temporaire et sujet à suppression.
### Dépendances de ressources
Lorsque vous incluez plusieurs fichiers CSS ou JavaScript dans une page Web, ils doivent respecter un certain ordre pour éviter des problèmes de redéfinition.
Par exemple, si vous utilisez l'objet graphique jQuery Ui dans une page Web, vous devez vous assurer que le fichier JavaScript jQuery est inclus avant le fichier JavaScript jQuery UI.
Nous appelons un tel ordre : « dépendances entre ressources ».
Les dépendances entre ressources sont essentiellement spécifiées via la propriété
[[yii\web\AssetBundle::depends]].
Dans l'exemple `AppAsset`, le paquet de ressources dépend de deux autres paquets de ressources : [[yii\web\YiiAsset]] et [[yii\bootstrap\BootstrapAsset]],
ce qui veut dire que les fichiers CSS et JavaScript dans `AppAsset` sont inclus *après* les fichiers contenus dans ces deux paquets de ressources dont ils dépendent.
Les dépendances entre ressources sont transitives. Cela veut dire que si un paquet de ressources A dépend d'un paquet B qui lui-même dépend de C, A dépend de C également.
### Options des ressources
Vous pouvez spécifier les propriétés [[yii\web\AssetBundle::cssOptions|cssOptions]] et [[yii\web\AssetBundle::jsOptions|jsOptions]]
pour personnaliser la manière dont les fichiers CSS et JavaScript sont inclus dans une page.
Les valeurs de ces propriétés sont passées aux méthodes [[yii\web\View::registerCssFile()]] et [[yii\web\View::registerJsFile()]], respectivement, lorsqu'elles sont appelées par la
[vue](structure-views.md) pour inclure les fichiers CSS et JavaScript.
> Note: les options que vous définissez dans une classe de paquet de ressources s'appliquent à *chacun des* fichiers CSS/JavaScript du paquet.
Si vous voulez utiliser des options différentes entre fichiers, vous devez utiliser le format indiqué [[yii\web\AssetBundle::css|ci-dessus]]
ou créer des paquets de ressources séparés et utiliser un jeu d'options dans chacun des paquets.
Par exemple, pour inclure un fichier CSS sous condition que le navigateur soit IE9 ou inférieur, vous pouvez utiliser l'option suivante :
```php
public $cssOptions = ['condition' => 'lte IE9'];
```
Avec cela, le fichier CSS du paquet pourra être inclus avec le code HTML suivant :
```html
```
Pour envelopper le lien CSS généré dans une balise `
