SALT > Manuel > Tutoriel > Base de données >

SALT permet de mapper une classe depuis une table en base de données.
Il est possible de mapper n'importe quelle table sans aucun prérequis.
Il est possible de mapper n'importe quelle colonne si celle-ci ne commence pas par "_salt" ni ne vaut l'une des valeurs suivantes : view, form, column, sql qui sont des valeurs réservées. (Cette restriction sera levée dans une version future du framework)
La présence d'une clé primaire est conseillée mais non obligatoire.

Il suffit de déclarer une classe pour chaque table en héritant de la classe salt\Base et d'implémenter la méthode abstraite metadata() qui va décrire essentiellement les différentes colonnes que l'on souhaite voir dans le framework. On peut ne pas décrire certaines colonnes présentes en base si on le souhaite, mais si on insère des données et que ces colonnes ne peuvent pas être NULL, l'insertion échouera.
<?php
use salt\Field;
class MaTable extends salt\Base {
    protected function metadata() {
        parent::MODEL()
        ->registerId('id') // nom de la colonne correspondant à la clé primaire. Facultatif
        ->registerTableName('ma_table') // nom de la table en base de données. OBLIGATOIRE
        ->registerFields(
            Field::newNumber( 'id', 'ID'),
            Field::newText(   'name', 'Nom'),
            Field::newText(   'other_field', 'Autre champ')
        );
    }
} La classe Field permet de mapper un champ sur l'un des 4 types du framework SALT : Number, Text, Date, Boolean
Mais elle permet aussi de spécifier le type SQL de mapping ainsi que la manière d'afficher un formulaire pour le champ

Mapping d'un type Number

Le mapping d'un champ de type nombre se fait avec l'API : <?php
/**
 * @param string $name column name
 * @param string $text    literal description of the column. Displayed in column header
 * @param boolean $nullable (optional, FALSE) TRUE if the field can be NULL : set an empty string for set a NULL. Explicit set EMPTY_STRING for set an empty string
 * @param int $defaultValue (optional, NULL) default value for new created object
 * @param mixed[] $values (optional, array()) List of all possible values for the field : number => mixed
 * @param string $useName (optional, NULL) in case $name is a reserved word, $useName will be used instead for DAO (obviously $name is still used in query SQL text)
 */
Field::newNumber($name, $text, $nullable = FALSE, $defaultValue = NULL, array $values = array(), $useName = NULL); Les paramètres sont :

• $name
  Nom de la colonne de la table.
  Sera également le nom de la propriété dans l'objet mappé.
• $text
  Courte description textuelle du champ.
  Sera affiché dans l'entête de colonne si on utilise le rendu du framework avec la classe DBResult. Cette classe sera décrite lorsqu'on parlera des requêtes.
• $nullable Optionnel, FALSE par défault
  Indique si le champ peut être NULL.
  Si c'est le cas, affecter une chaine vide au champ lui donnera la valeur NULL. Si on souhaite lui affecter réellement une chaine vide, on peut lui donner la valeur de Field::EMPTY_STRING
• $defaultValue Optionnel, NULL par défault
  La valeur par défaut du champ.
  Le champ d'un nouvel objet sera affecté à cette valeur.
  
• $values Optionnel, array() par défault
  Une liste de valeurs finie pour le champ.
  Si le tableau est associatif, le format attendu est : valeur => texte où "valeur" est une valeur possible pour le champ et "texte" une description textuelle de la valeur.
  Par exemple :
  <?php
Field::newNumber('field_type', 'Type de champ', FALSE, 0, array(
    0 => 'Nombre',
    1 => 'Texte',
    2 => 'Date',
    3 => 'Booléen',
)); La description textuelle de la valeur pourra être affichée à la place de la valeur brute du champ, ou encore être utilisé pour construire les balises de formulaire <option> lors de l'écriture d'un formulaire de modification de l'objet.
  Cela est décrit dans l'affichage d'objet et l'affichage de formulaire
• $useName Optionnel, NULL par défault
  
  Le fonctionnement de ce champ n'est pas encore implémenté.
  Si la colonne à mapper, c'est à dire le paramètre $name, vaut une valeur réservée, il sera possible d'indiquer un autre nom ici. $useName sera utilisé à la place de $name pour le nom du champ dans l'objet uniquement, le nom de la colonne restant mappée sur $name.

Mapping d'un type Text

Le mapping d'un champ de type texte se fait avec l'API : <?php
/**
 * @param string $name column name
 * @param string $text    literal description of the column. Displayed in column header
 * @param boolean $nullable (optional, FALSE) TRUE if the field can be NULL : set an empty string for set a NULL. Explicit set EMPTY_STRING for set an empty string
 * @param mixed $defaultValue (optional, NULL) default value for new created object
 * @param mixed[] $values (optional, array()) List of all possible values for the field
 * @param string $useName (optional, NULL) in case $name is a reserved word, $useName will be used instead for DAO (obviously $name is still used in query SQL text)
 */
Field::newText($name, $text, $nullable = FALSE, $defaultValue = NULL, array $values = array(), $useName = NULL);
On retrouve exactement les mêmes paramètres que pour le mapping d'un nombre. Ils ont la même signification.

Mapping d'un type Date

Dans un objet SALT, la valeur brute d'un champ mappé sur une date sera toujours un timestamp UNIX. On normalise automatiquement la date lorsqu'on la lit et lorsqu'on l'écrit en base de données.

Le mapping d'un champ de type date se fait avec l'API : <?php
/**
 * @param string $name column name
 * @param string $text    literal description of the column. Displayed in column header
 * @param string $sqlFormat SqlDateFormat or Mysql date format for date type field
 * @param string $displayFormat (optional, salt\DEFAULT_DATE_DISPLAY_FORMAT) PHP date() format for display date type field
 * @param boolean $nullable (optional, FALSE) TRUE if the field can be NULL : set an empty string for set a NULL. Explicit set EMPTY_STRING for set an empty string
 * @param mixed $defaultValue (optional, NULL) default value for new created object
 * @param string $useName (optional, NULL) in case $name is a reserved word, $useName will be used instead for DAO (obviously $name is still used in query SQL text)
 */
Field::newDate($name, $text, $sqlFormat, $displayFormat = salt\DEFAULT_DATE_DISPLAY_FORMAT, $nullable = FALSE, $defaultValue = NULL, $useName = NULL);
Les paramètres de même nom que pour le mapping d'un nombre ont la même signification.
Les différences sont les suivantes :

• $sqlFormat
  Ce paramètre représente la manière dont la date est stockée en base de données.
  Il est obligatoire car on a besoin de cette information pour convertir la date provenant de la base en timestamp UNIX et inversement.
  Le format attendu est le format utilisé par la méthode MySQL DATE_FORMAT et certains sont déjà préenregistrés dans la classe SqlDateFormat :
  • SqlDateFormat::DATE : Correspond au format d'un champ de type DATE
  • SqlDateFormat::DATETIME : Correspond au format d'un champ de type DATETIME
  • SqlDateFormat::SHORT_DATE : Correspond au format d'un champ de type INT ou VARCHAR contenant YYYYMMDD
  • SqlDateFormat::TIMESTAMP : Correspond au format d'un champ de type TIMESTAMP
  • SqlDateFormat::RAW_TIMESTAMP : Correspond au format d'un champ de type INT ou VARCHAR contenant un timestamp unix
  
  On peut aussi entrer un format libre, par exemple %d%m%Y ou encore %Y/%d/%m.
  
  
  Il n'est pas possible de mapper un champ SQL dans un type DATE si celui-ci ne contient pas assez d'information pour produire un timestamp unix valide, c'est à dire permettant de déduire l'année, le mois et le jour. En conséquence, le type MySQL "YEAR" ne pourra pas être mappé dans un champ de type DATE. Il peut toujours être mappé dans un NUMBER ou un TEXT et être géré manuellement.
  
  On peut voir un exemple d'utilisation ici
• $displayFormat Optionnel, salt\DEFAULT_DATE_DISPLAY_FORMAT par défaut
  Ce paramètre représente le format d'affichage par défaut de la date.
  Il s'agit cette fois du format PHP, c'est à dire celui utilisé par la méthode PHP date().
  
  Si le paramètre n'est pas renseigné, que la constante salt\DEFAULT_DATE_DISPLAY_FORMAT n'a pas été redéfinie, et que localement on ne change pas le format lors de l'affichage, la valeur par défaut est d/m/Y
  
  L'exemple précédent montre également une utilisation de ce champ.
  
• $values Absent
  Il n'est pas possible de définir une liste de valeurs fixe pour un type DATE. Ce paramètre n'existe pas ici.

Mapping d'un type Boolean

Les champs de type booléen sont convertis en booléen PHP (TRUE / FALSE) mais sont mappés en base de données sur des TINYINT(1).

Le mapping d'un champ de type booléen se fait avec l'API : <?php
/**
 * @param string $name column name
 * @param string $text    literal description of the column. Displayed in column header
 * @param boolean $nullable (optional, FALSE) TRUE if the field can be NULL : set an empty string for set a NULL. Explicit set EMPTY_STRING for set an empty string
 * @param mixed $defaultValue (optional, NULL) default value for new created object
 * @param string $useName (optional, NULL) in case $name is a reserved word, $useName will be used instead for DAO (obviously $name is still used in query SQL text)
 */
Field::newBoolean($name, $text, $nullable = FALSE, $defaultValue = NULL, $useName = NULL);
Les paramètres de même nom que pour le mapping d'un nombre ont la même signification.

Spécifier le mapping SQL

En général il n'est pas nécessaire de spécifier le mapping SQL exact car celui ci n'est pas utilisé lors la lecture ou l'écriture de données.
Ces informations ne servent que lors de création de la table si elle n'existe pas et qu'on le demande explicitement au framework SALT.

Lors de la création d'un Field, on peut faire suivre l'appel de la méthode newXXX par un appel à la méthode sqlType : <?php
protected function metadata() {
    // ...
    return array(
            Field::newText('name', 'Nom')->sqlType('VARCHAR(64) PRIMARY KEY'),
    );
}
On peut indiquer ici tout texte SQL nécessaire à la création de la colonne lors d'un CREATE TABLE, par exemple AUTO_INCREMENT, UNIQUE, etc...
Il n'est pas nécessaire d'indiquer NULL et NOT NULL puisque cette information est décrite par le paramètre $nullable et sera ajoutée après la définition du type.

Si sqlType() n'est pas utilisé et qu'on demande au framework SALT de créer la table d'un objet, il utilisera les types suivants :

Type SALT	Format SALT	Type MySQL
NUMBER		INT
TEXT		TEXT
BOOLEAN		TINYINT(1)
DATE	SqlDateFormat::RAW_TIMESTAMP	INT(10)
DATE	SqlDateFormat::TIMESTAMP	TIMESTAMP
DATE	SqlDateFormat::DATETIME	DATETIME
DATE	SqlDateFormat::SHORT_DATE	DATETIME
DATE	SqlDateFormat::DATE	DATE
DATE	Autre	TEXT

Spécifier l'affichage du formulaire d'un champ

La plupart du temps la manière d'afficher un formulaire pour un champ n'a pas vocation à être décrite dans les méta données d'un objet. Cependant, si on affiche souvent le champ en utilisant toujours le même format complexe on peut factoriser tout ou partie de ce comportement ici.

Lors de la création d'un Field, on peut faire suivre l'appel de la méthode newXXX par un appel à la méthode displayOptions :
<?php
protected function metadata() {
    // ...
    return array(
            Field::newBoolean('response', 'Réponse')->displayOptions(array(
                'type' => 'select',
                'options' => array(
                    1 => 'Oui',
                    0 => 'Non',
                ),
                'title' => 'Choisir une réponse',
            )),
    );
}
displayOptions prend en paramètre un tableau associatif dont chaque attribut sera ajouté à la balise HTML construite pour le champ.
C'est le cas de "title" ici.
Le tableau peut aussi contenir 3 clés spéciales qui seront interprétées différemment :

• type
  Permet de surcharger le type de balise à générer. Les types possibles sont : text, password, select, checkbox, textarea, radio
• options
  La valeur doit être un tableau associatif permettant de construire les balises options d'une liste déroulante. Le type doit être "select".
• class
  La valeur (textuelle) sera ajoutée à l'attribut class de la balise

Un exemple d'utilisation est visible ici
L'affichage de formulaire est décrit de manière plus détaillée dans la section dédiée