yii/docs/guide/fr/form.model.txt

Créer le modèle
===============

En amont de l'écriture du code HTML d'un formulaire, il est nécessaire de réfléchir
aux types de données que nous demanderons aux utilisateurs et quelles règles
s'appliqueront à ces données. Une classe représentant un modèle de données
pourra être utilisée pour sauvegarder ces données. Un modèle, tel que défini
dans la sous section [Modèle](/doc/guide/basics.model), est le point central
pour sauvegarder les entrées utilisateurs et pour les valider.

Selon ce que l'on souhaite faire des données entrées par l'utilisateur, il est possible
de créer deux types de modèles. Si les données sont utilisées puis immédiatement supprimées,
un [form model](/doc/guide/basics.model) sera utilisé; si les données sont récupérées pour
etre enregistrées dans une base de données, un [active record](/doc/guide/database.ar) sera utilisé.
Ces deux types de modèles partagent la même classe mère [CModel] qui défini une interface commune
requise pour les formulaires.

> Note: Nous utiliserons principalement des modèles form dans les exemples suivants.
Cependant, tout est applicable sur des modèles [active record](/doc/guide/database.ar).

Définir une classe pour un modèle
---------------------------------

Ci dessous nous créons une classe pour le modèle `LoginForm` afin de récupérer les données utilisateurs
sur une page de connection. Comme ces informations de connection ne seront utilisées que pour
authentifier l'utilisateur, sans être enregistrées, nous créerons `LoginForm` comme un modèle form.

~~~
[php]
class LoginForm extends CFormModel
{
	public $username;
	public $password;
	public $rememberMe=false;
}
~~~

Trois attributs sont déclarés dans `LoginForm`: `$username`, `$password` et
`$rememberMe`. Ils servent à stocker le nom d'utilisateur et le mot de passe
entrés par l'utilisateur, ainsi que l'option pour rester connecté.
Comme `$rememberMe` à pour valeur par défaut `false`, l'option correspondante
quand le formulaire sera affiché sera décochée.

> Info: Plutot que d'appeler ces variables des propriétés, le terme 
d'attribut est préféré afin de les distinguer des propriétés normales. Un
attribut est une propriété qui est principalement utilisé pour stocker des
données venant d'entrées utilisateur ou de la base de données.

Déclarer des règles de validation
---------------------------------

Une fois que l'utilisateur à envoyé son formulaire et que les données sont
stockées dans le modèle, il faut vérifier que ces données sont valides avant
de les utiliser. Pour cela un ensemble de règles sont appliquées à ces données
afin de les valider. Pour spécifier ces règles, on utilise la méthode `rules()`
qui retourne un tableau avec ces règles.

~~~
[php]
class LoginForm extends CFormModel
{
	public $username;
	public $password;
	public $rememberMe=false;

	private $_identity;

	public function rules()
	{
		return array(
			array('username, password', 'required'),
			array('rememberMe', 'boolean'),
			array('password', 'authenticate'),
		);
	}

	public function authenticate($attribute,$params)
	{
		$this->_identity=new UserIdentity($this->username,$this->password);
		if(!$this->_identity->authenticate())
			$this->addError('password','Incorrect username or password.');
	}
}
~~~

Le code ci dessus déclare que `username` et `password` sont tout deux requis,
`password` doit être un champ mot de passe qui correspondra avec le login, et `rememberMe`
doit etre un booléen.

Chaque règle retournée par `rules()` doit suivre le format suivant:

~~~
[php]
array('AttributeList', 'Validator', 'on'=>'ScenarioList', ...options supplémentaires)
~~~

où `AttributeList` est une chaine de caractères d'attributs séparés par des virgules qui
doivent être validés selon la règle; `Validator` spécifie quel type de
validation doit être effectuée; le paramètre `on`, optionel, spécifie une liste de
scénarios pour lesquels la règle doit être appliquée; et les options supplémentaires
sont des paires de noms-valeurs qui sont utilisés pour initialiser les valeurs des propriétés
correspondantes du validateur.

Il existe trois méthodes pour spécifier un `Validator` dans une règle de validation.


La première, où un `Validator` peut être le nom d'une méthode dans une classe,
tel que `authenticate` dans l'exemple ci dessus. La méthode de validation doit suivre
la signature suivante:

~~~
[php]
/**
 * @param string le nom de l'attribut à valider
 * @param array options spécifiée dans la règle de validation
 */
public function ValidatorName($attribute,$params) { ... }
~~~

Une deuxième où le `Validator` peut etre le nom d'une classe de validation. Quand la règle
est appliquée, une instance de cette classe sera créée pour exécuter la validation.
Les options supplémentaires dans la règle seront utilisées pour initialiser les attributs de
cette instance. Une classe de validation doit hériter de [CValidator].

Une troisième où le `Validator` sera un alias prédéfinit d'une classe de validation. Dans l'exemple
ci dessus, le nom `required` est un alias pour [CRequiredValidator]
qui s'assure que la valeur de l'attribut a validater n´est pas vide. Vous trouverez ci dessous
la liste complète des alias de `Validator` prédéfinis:

   - `boolean`: alias pour [CBooleanValidator], s'assure que l'attribut est
soit [CBooleanValidator::trueValue] ou [CBooleanValidator::falseValue].

   - `captcha`: alias pour [CCaptchaValidator], s'assure que l'attribut est
égal à un code de vérification affiché dans un [CAPTCHA](http://en.wikipedia.org/wiki/Captcha).

   - `compare`: alias pour [CCompareValidator], s'assure que the attribute est égal à un autre attribut ou constante.

   - `email`: alias pour [CEmailValidator], s'assure que l'attribut est une
adresse email valide.

   - `default`: alias pour [CDefaultValueValidator], assigne une valeur par défaut aux attributs.

   - `exist`: alias pour [CExistValidator], s'assure que la valeur de l'attribut
existe dans la colonne de la table spécifiée.

   - `file`: alias pour [CFileValidator], s'assure que l'attribute contient
le nome d'un fichier uploadé.

   - `filter`: alias pour [CFilterValidator], transforme un attribut grâce à un filtre.

   - `in`: alias pour [CRangeValidator], s'assure que les données sont contenu dans une
liste de valeurs pré-specifiées.

   - `length`: alias pour [CStringValidator], s'assure que la longueur de la valeur est
dans un certain interval.

   - `match`: alias pour [CRegularExpressionValidator], s'assure que la valeur satisfait
une expression régulière.

   - `numerical`: alias pour [CNumberValidator], s'assure que la valeur est un 
nombre valide.

   - `required`: alias pour [CRequiredValidator], s'assure que l'attribut n´est
pas vide.

   - `type`: alias pour [CTypeValidator], s'assure que l'attribut est d'un type de
donnée spécifique.

   - `unique`: alias pour [CUniqueValidator], s'assure que la valeur est unique dans
une colonne de table.

   - `url`: alias pour [CUrlValidator], s'assure que la valeur est une URL valide.

Quelques exemples d'utilisation de ces `Validator` prédéfinis:

~~~
[php]
// username est requis
array('username', 'required'),
// username doit être entre 3 et 12 caractères
array('username', 'length', 'min'=>3, 'max'=>12),
// quand dans un scénario d'inscription, password doit être égal à password2
array('password', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),
// quand dans un scénario de connection, password doit être correspondre avec login
array('password', 'authenticate', 'on'=>'login'),
~~~


Sécuriser l'assignation des attributs
-------------------------------------

Une fois que l'instance du modèle est créée, il est courant de devoir
assigner ses attributs avec les données soumises par les utilisateurs.
Cela peut être aisément fait grâce à cette assignation massive suivante:

~~~
[php]
$model=new LoginForm;
if(isset($_POST['LoginForm']))
	$model->attributes=$_POST['LoginForm'];
~~~

La dernière opération est appelée *assignation massive* en cela qu´elle assigne
toutes les entrées de `$_POST['LoginForm']` aux attributs correspondant du modèle.
Elle est équivalente aux assignations suivantes:

~~~
[php]
foreach($_POST['LoginForm'] as $name=>$value)
{
	if($name is a safe attribute)
		$model->$name=$value;
}
~~~

Il est crucial de déterminer quels attributs sont sains. Par exemple, si nous
déclarons une clé primaire d'une table comme étant saine, alors un attaquant pourrait
avoir la possibilité de modifier cette clé et ainsi altérer des données qu´il ne devrait
pas être autorisé à modifier.

La règle pour décider quels attributes sont sains est différent dans la version 1.0
et 1.1. Nous allons les décrire séparemment.

###Attributs sains in 1.1

Dans la version 1.1, un attribut est considéré comme sain si il apparait dans une
règle de validation qui est appliqué dans le scénario courant. Par exemple,

~~~
[php]
array('username, password', 'required', 'on'=>'login, register'),
array('email', 'required', 'on'=>'register'),
~~~

Dans le code ci dessus, les attributs `username` et `password` sont requis dans le
scénario `login`, alors que les attributs `username`, `password` et `email` sont requis
dans le scénario `register`. Ainsi, si une assignation massive est effectuée lors d'un
scénario `login`, seulement `username` et `password` seront assignés massivement
car ce sont les seuls apparaissant dans les règles de validation pour le scénario `login`.
Sinon, si le scénario est `register`, les trois attributs pourront être assignés massivement.

~~~
[php]
// scénario login
$model=new User('login');
if(isset($_POST['User']))
	$model->attributes=$_POST['User'];

// scénario register
$model=new User('register');
if(isset($_POST['User']))
	$model->attributes=$_POST['User'];
~~~

Pourquoi utiliser un telle politique pour déterminier si un attribut est sain ou non?
L´idée derrière ce principe est que si un attribut à déjà une ou plus règles de validation
qui lui sont appliquées pour le valider, pourquoi se soucier encore de lui?

Il est important de se rappeler que les règles de validation sont utilisées pour vérifier
les données provenant des utilisateurs plutot que les données générées par le code (par
exemple timestamp, clés primaires auto-générées).
Ainsi, ne PAS ajouter de règles de validation pour les attributes qui ne doivent pas
recevoir de données des utilisateurs.

Parfois, il est utile de déclarer un attribut comme sain, bien que nous n´ayons aucune
règle spécifique pour lui. Un exemple pourrait être un attribut représentant le contenu d'un
article qui pourrait recevoir potentiellement n´importe quelle valeur. Nous pouvont dans
ce cas utiliser la règle spéciale `safe` pour parvenir à nos fins:

~~~
[php]
array('content', 'safe')
~~~

Pour être complet, il existe aussi une règle `unsafe` qui est utilisé explicitement pour déclarer
un attribut comme unsafe:

~~~
[php]
array('permission', 'unsafe')
~~~

Cette règle `unsafe` est rarement utilisée, et c´est une exception à notre précédente définition
des attributs sains.


###Attributs sains in 1.0

Dans la version 1.0, la tache de décider si une donnée est saine ou non se fait
sur la base de la valeur de retour de la méthode `safeAttributes` et du scénario
spécifié. Par défaut, la méthode retourne toutes les variable publiques de [CFormModel]
en tant qu´attributs sains, alors qu´elle retourne toutes les colonnes de la table
comme attributs sains à l'exception de la clé primaire pour [CActiveRecord].
Il est possible de surcharger cette méthode pour limiter les attributs sains selon
les scénarios. Par exemple, un modèle utilisateur peut contenir de nombreux attributs,
mais pour le scénario `login`, seuls les attributs `username` et `password` sont utiles.
Cette limite s'effectue comme suivant:

~~~
[php]
public function safeAttributes()
{
	return array(
		parent::safeAttributes(),
		'login' => 'username, password',
	);
}
~~~

Plus exactement, la valeur de retour de la méthode `safeAttributes` doit avoir la
structure suivant:

~~~
[php]
array(
   // ces attributs peuvent être assignés massivement pour tous les scénarios
   // qui ne sont pas explicitement cités ci dessous
   'attr1, attr2, ...',
	 *
   // ces attributs peuvent être assignés massivement seulement pour le scénario 1
   'scenario1' => 'attr2, attr3, ...',
	 *
   // ces attributs peuvent être assignés massivement seulement pour le scénario 2
   'scenario2' => 'attr1, attr3, ...',
)
~~~

Si le modèle est indépendant de scénario (par exemple, si il est utilisé dans un
seul scénario, ou tous les scénarios partagent le même ensemble d'attributs sains),
la valeur de retour peut être simplifiée comme une simple chaine de caractères:

~~~
[php]
'attr1, attr2, ...'
~~~

Pour les données qui ne sont pas saines, il faut les assigner aux attributs
correspondants en utilisant les opérations d'assignation individuelle, comme suivant:

~~~
[php]
$model->permission='admin';
$model->id=1;
~~~


Déclenchement de la validation
------------------------------

Une fois que les données soumises par l'utilisateur ont été assignées au modèle,
il est possible d'appeler [CModel::validate()] pour déclencher le processus de validation
des données. Cette méthode retourne une valeur indiquant si la validation s'est déroulée
sans erreur ou non. Pour les modèles [CActiveRecord], la validation sera aussi
automatiquement déclenchée à l'appel de la méthode [CActiveRecord::save()].

Il est possible d'assigner un scénario avec la propriété [scenario|CModel::scenario]
et d'indiquer quel ensemble de règles de validation doit être appliqué.

La validation est effectué sur la base des scénario. La propriété [scenario|CModel::scenario]
spécifie dans quel scénario le modèle est actuellement utilisé et quel ensemble de règles de
validation doivent être utilisées. Par exemple, dans le scénario `login`, nous ne voulons
valider que les entrées `username` et `password` du modèle user; alors que dans le scénario
`register`, nous voulons valider plus d'entrées, telles que `email`, `address`, etc.
L'exemple suivant montre comment éffectuer une validation dans le scénario `register`:

~~~
[php]
// cré le modèle User dans un scénario register. Cela est équivalent à:
// $model=new User;
// $model->scenario='register';
$model=new User('register');

// assigne les données du modèle
$model->attributes=$_POST['User'];

// effectue la validation
if($model->validate())   // si les données sont valides
    ...
else
    ...
~~~

Les scénarios applicables associés à une règle sont spécifiés au travers
de l'option `on` dans la règle. Si l'option `on` n´est pas spécifiée, cela signifie
que la règle sera utilisée dans tous les scénarios. Par exemple,

~~~
[php]
public function rules()
{
	return array(
		array('username, password', 'required'),
		array('password_repeat', 'required', 'on'=>'register'),
		array('password', 'compare', 'on'=>'register'),
	);
}
~~~

La première règle sera appliquée dans tous les scénarios, alors que
les deux règles suvantes s'appliqueront uniquement au scénario `register`.


Récupération des erreurs de validation
--------------------------------------

Une fois que la validation est finie, toutes les erreurs susceptibles d'avoir
été rencontrées sont stockées dans l'objet. Il est alors possible de récupérer les
messages d'erreurs en appelant [CModel::getErrors()] et [CModel::getError()]. La
différence entre ces deux méthodes est que la première renvoie *toutes* les erreurrs
pour un certain attribut du modèle alors que la seconde méthode renverra uniquement
la *première* erreur.

Libellés des attributs
----------------------

A la conception d'un formulaire, il est souvent nécessaire d'afficher un libellé
pour chaque champs. Le libellé renseigne l'utilisateur sur le type d'information
qu´il est censé donner. Bien qu´il soit possible de l'écrire directement dans la
vue, il est plus pratique et cela offre plus de flexibilité de spécifier ces libellés
dans le modèle.

Par défaut, [CModel] retournera simplement le nom de l'attribut comme libellé.
Il est possible de personnaliser cela en surchargeant la méthode [attributeLabels()|CModel::attributeLabels]. Comme nous le verrons dans les sections suivantes, spécifier
des libellés au niveau du modèle permet de créer des formulaires plus rapidement.

<div class="revision">$Id: form.model.txt 2285 2010-07-28 20:40:00Z qiang.xue $</div>