ZF Zend Framework

Vous pouvez créer une instance d'un adaptateur en utilisant son constructeur. Celui-ci accepte un paramètre représentant un tableau d'options.

<?php
require_once 'Zend/Db/Adapter/Pdo/Mysql.php';

$db = new Zend_Db_Adapter_Pdo_Mysql(array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));

Alternativement, il est possible d'utiliser la méthode statique Zend_Db::factory(). Celle-ci charge dynamiquement la classe d'adaptateur correspondant en utilisant Zend_Loader::loadClass().

Le premier argument est une chaîne désignant l'adaptateur souhaité. Par exemple, "Pdo_Mysql" va correspondre à la classe Zend_Db_Adapter_Pdo_Mysql. Le second paramètre est un tableau d'options. C'est le même que celui que vous auriez passé au constructeur de la classe directement.

<?php
require_once 'Zend/Db.php';

// Charge automatiquement la classe Zend_Db_Adapter_Pdo_Mysql et en créer une instance.
$db = Zend_Db::factory('Pdo_Mysql', array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));

Si vous créez votre propre classe d'adaptateur qui étend Zend_Db_Adapter_Abstract et que celle-ci ne respecte pas la syntaxe du préfixe package "Zend_Db_Adapter", utilisez alors la clé "adapterNamespace" dans le tableau de configuration passé à la méthode factory() afin de charger votre adaptateur.

<?php
require_once 'Zend/Db.php';

// Charge automatiquement la classe MyProject_Db_Adapter_Pdo_Mysql et l'instantie.
$db = Zend_Db::factory('Pdo_Mysql', array(
    'host'             => '127.0.0.1',
    'username'         => 'webuser',
    'password'         => 'xxxxxxxx',
    'dbname'           => 'test',
    'adapterNamespace' => 'MyProject_Db_Adapter'
));

Optionnellement, vous pouvez passer un objet de type Zend_Config en tant qu'argument de la méthode factory(), concernant la configuration.

Il est alors nécessaire que l'objet de configuration contienne une propriété adapter, qui représente une chaîne de caractères décrivant l'adaptateur à utiliser. De plus, l'objet peut aussi contenir une propriété nommée params, avec toutes les sous propriétés requises pour la configuration de l'adaptateur.

<?php
require_once 'Zend/Config.php';
require_once 'Zend/Db.php';

$config = new Zend_Config(
    array(
        'database' => array(
            'adapter' => 'Mysqli',
            'params' => array(
                'dbname' => 'test',
                'username' => 'webuser',
                'password' => 'secret',
            )
        )
    )
);

$db = Zend_Db::factory($config->database);

Le second paramètre de la méthode factory() doit être un tableau associatif décrivant les paramètres de l'adaptateur à utiliser. Cet argument est optionnel, si un objet de type Zend_Config est utilisé en premier paramètre, alors il est supposé contenir les paramètres, et le second paramètre de factory() est alors ignoré.

La liste ci dessous explique les différents paramètres acceptés par les classes d'adaptateur Zend_Db.

<?php
$options = array(
    Zend_Db::CASE_FOLDING => Zend_Db::CASE_UPPER
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Db2', $params);

<?php
$options = array(
    Zend_Db::AUTO_QUOTE_IDENTIFIERS => false
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Pdo_Mysql', $params);

<?php
$pdoParams = array(
    PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'driver_options' => $pdoParams
);

$db = Zend_Db::factory('Pdo_Mysql', $params);

echo $db->getConnection()->getAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY);

La création d'une instance d'une classe d'Adaptateur ne crée pas physiquement une connexion au SGBD. L'adaptateur sauvegarde les paramètres et se connectera physiquement à la demande, la première fois que vous aurez besoin d'exécuter une requête. Ceci permet d'assurer que la création de l'instance elle-même est rapide, et ne coûte rien en performances. Vous pouvez donc créer une instance de l'adaptateur, même si vous ne savez pas si vous allez l'utiliser. Ainsi, si vos paramètres sont incorrects, il faudra attendre la tentative de connexion au SGBD pour le vérifier réellement.

Si vous voulez forcer l'adaptateur à se connecter au SGBD, utilisez sa méthode getConnection(). Elle retournera alors un objet représentant la connexion, en fonction de l'extension PHP utilisée, ou une exception si la connexion n'a pas été réalisée. Par exemple, si votre adaptateur utilise PDO, le retour sera un objet PDO. La connexion physique au SGBD est alors réalisée.

Afin de vérifier si les paramètres de connexion au SGBD sont corrects, surveillez les exceptions envoyées par la méthode getConnection().

<?php
try {
    $db = Zend_Db::factory('Pdo_Mysql', $parameters);
    $db->getConnection();
} catch (Zend_Db_Adapter_Exception $e) {
    // probablement mauvais identifiants, ou alors le SGBD n'est pas joignable
} catch (Zend_Exception $e) {
    // probablement que factory() n'a pas réussi à charger la classe de l'adaptateur demandé
}

Vous pouvez à la fois exécuter une requête SELECT et récupérer tous ses résultats en une seule manipulation, grâce à la méthode fetchAll().

Le premier paramètre de cette méthode est une chaîne représentant la requête SELECT à exécuter. Aussi, ce premier paramètre peut être un objet Zend_Db_Select, qui sera alors converti en une chaîne automatiquement.

Le second paramètre de de fetchAll() est un tableau de substitutions des éventuels jokers présents dans la syntaxe SQL.

<?php
$sql = 'SELECT * FROM bugs WHERE bug_id = ?';

$result = $db->fetchAll($sql, 2);

Par défaut, fetchAll() retourne un tableau d'enregistrements. Chaque enregistrement étant un tableau associatif dont les clés sont les noms des colonnes SQL désirées, ou leurs alias.

Vous pouvez spécifier un mode de récupération de résultats différent, ceci par la méthode setFetchMode(). Les modes supportés sont identifiés par des constantes :

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAll('SELECT * FROM bugs WHERE bug_id = ?', 2);

// $result est un tableau d'objets
echo $result[0]->bug_description;

La méthode fetchAssoc() retourne des enregistrements sous forme de tableau de tableaux associatifs, quelque soit la valeur du fetch mode.

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAssoc('SELECT * FROM bugs WHERE bug_id = ?', 2);

// $result est un tableau de tableaux associatifs
echo $result[0]['bug_description'];

La méthode fetchCol() retourne les enregistrements dans un tableau de valeurs. Les valeurs correspondent à une des colonnes utilisées dans la requête SQL SELECT, par défaut : la première. Toute autre colonne sera ignorée. Si vous avez besoin de retourner une autre colonne, voyez Section 10.2.3.4, « Récupérer une colonne simple depuis un statement exécuté ». Cette méthode est indépendante de la valeur du fetch mode.

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchCol('SELECT bug_description, bug_id FROM bugs WHERE bug_id = ?', 2);

// Contient bug_description ; bug_id n'est pas retourné
echo $result[0];

La méthode fetchPairs() retourne un tableau de paires clés/valeurs. La clé est le résultat de la première colonne sélectionnée dans la requête, la valeur est le résultat de la deuxième colonne sélectionnée dans la requête. Il est donc inutile de sélectionner plus de deux colonnes avec cette méthode. De même, vous devez sélectionner exactement deux colonnes avec cette méthode, pas moins. Si des clés ont des doublons, alors ils seront écrasés.

Vous devriez réfléchir votre requête SELECT de manière à ce que la première colonne sélectionnée, correspondant à la clé du tableau de résultat, soit unique (une clé primaire par exemple). Cette méthode est indépendante du fetch mode éventuellement précédemment défini.

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchPairs('SELECT bug_id, bug_status FROM bugs');

echo $result[2]; // le bug_status correspondant au bug_id numéro 2

La méthode fetchRow() retourne un et un seul enregistrement (le premier si plusieurs correspondent), en fonction du fetch mode que vous aurez précédemment défini. Cette méthode ressemble donc à fetchAll() si ce n'est qu'elle ne retournera jamais plus d'un seul enregistrement. Arrangez vous donc pour que votre SELECT possède une clause WHERE sur une clé primaire.

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchRow('SELECT * FROM bugs WHERE bug_id = 2');

// Ce résultat sera un objet, car le fetch mode en a décidé ainsi
echo $result->bug_description;

La méthode fetchOne() est une combinaison des méthodes fetchRow() et fetchCol(), ainsi elle ne retourne que la première colonne, du premier enregistrement retourné. La valeur de retour est donc une chaîne de caractères. Toute requête retournant plusieurs colonnes et/ou plusieurs résultats est donc inutile avec cette méthode.

<?php
$result = $db->fetchOne('SELECT bug_status FROM bugs WHERE bug_id = 2');

// ceci est une chaine
echo $result;

Vous pouvez ajouter de nouveaux enregistrements dans une table, grâce à la méthode insert(). Son premier paramètre est une chaîne qui représente le nom de la table ciblée, le second paramètre est un tableau associatif liant les noms des colonnes de la table, aux valeurs souhaitées.

<?php
$data = array(
    'created_on'      => '2007-03-22',
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);

Les colonnes non citées dans le tableau associatif sont laissées telles quelles. Ainsi, si le SGBD possède une valeur DEFAULT pour les colonnes concernées, celle-ci sera utilisée, autrement, NULL sera utilisé.

Par défaut, les valeurs insérées avec cette méthode sont automatiquement échappées. Ceci pour des raisons de sécurité, vous n'avez donc pas besoin de vous occuper de ce point là.

Si vous avez besoin d'écrire de la syntaxe SQL, comme des mots réservés, des noms de fonctions SQL, vous voulez que ceux-ci ne soient pas échappés, et ne soient pas traités comme de vulgaires chaînes de caractères, mais plutôt comme des expressions. Pour ceci, vous devriez passer ces valeurs dans votre tableau de données, en tant qu'objets de type Zend_Db_Expr au lieu de chaînes de caractères banales.

<?php
$data = array(
    'created_on'      => new Zend_Db_Expr('CURDATE()'),
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);

Certains SGBDs supportent les clé primaires auto-incrémentées. Une table qui utilise un tel procédé génère la valeur de la clé automatiquement lors d'une insertion (INSERT). La valeur de retour de la méthode insert() n'est pas le dernier ID inséré car la table peut ne pas avoir de clé auto-incrémentée. La valeur de retour est le nombres d'enregistrements affectés (théoriquement 1).

Si votre table a été définie avec une clé auto-incrémentée, alors vous pouvez appeler la méthode lastInsertId() après une opération d'insertion. Cette méthode retourne la valeur auto-incrémentée, générée dans le cadre de la connexion au SGBD.

<?php
$db->insert('bugs', $data);

// retourne la dernière valeur générée par la clé auto-incrémentée
$id = $db->lastInsertId();

Certains SGBD supporte un objet de séquence, qui sert à générer des valeurs uniques qui vont servir pour les clé primaires. Pour supporter ce procédé, la méthode lastInsertId() accepte deux paramètres optionnels (chaînes de caractères). Ces paramètres nomment la table et la colonne en supposant que vous ayez respecté la convention qui définit que la séquence est nommée en utilisant le nom de la table et des colonnes utilisées, avec le suffixe "_seq". Ces conventions sont celles de PostgreSQL pour les colonnes de type SERIAL. Par exemple, une table "bugs" avec une clé primaire "bug_id" utilisera une séquence nommée "bugs_bug_id_seq".

<?php
$db->insert('bugs', $data);

// retourne la dernière valeur générée par la séquence 'bugs_bug_id_seq'.
$id = $db->lastInsertId('bugs', 'bug_id');

// ceci retourne la dernière valeur générée par la séquence 'bugs_seq'.
$id = $db->lastInsertId('bugs');

Si le nom de votre objet de séquence ne suit pas ces conventions de nommage, utilisez alors lastSequenceId(). Cette méthode prend un paramètre qui nomme la séquence explicitement.

<?php
$db->insert('bugs', $data);

// retourne la dernière valeur générée par la séquence 'bugs_id_gen'.
$id = $db->lastSequenceId('bugs_id_gen');

Pour les SGBDs ne supportant pas les séquences, comme MySQL, Microsoft SQL Server, et SQLite, les arguments passés à la méthode lastInsertId() sont ignorés. La valeur retournée est la dernière valeur générée pour la dernière requête INSERT, quelque soit la table concernée (pour cette connexion). Aussi, pour ces SGBDs, la méthode lastSequenceId() retournera toujours null.

Pourquoi ne pas utiliser "SELECT MAX(id) FROM table"?

Quelques fois, cette requête retourne la valeur la plus récente de clé primaire insérée dans la table en question. Cependant, cette technique n'est pas pertinente dans un environnement où beaucoup de clients insèrent beaucoup de données dans une même table. Il est donc possible qu'un client insère une donnée entre le moment où la dernière insertion est effectuée, et l'appel de MAX(id), aboutissant ainsi à un résultat erroné. Il est très difficile de se rendre compte d'un tel comportement. Utiliser un mode d'isolation transactionnelle très élevé, comme "repeatable read" peut mitiger plus ou moins les risques, mais certains SGBDs ne supportent pas ce mode de transactions. De plus, utiliser une requête du type "MAX(id)+1" pour générer une nouvelle valeur de clé primaire n'est pas sécurisé non plus, car deux client peuvent se connecter simultanément et créer des effets indésirables. Tous les SGBDs fournissent un mécanisme de génération de valeurs uniques, et une méthode pour les récupérer. Ces mécanismes travaillent en dehors du mode transactionnel, et empêchent ainsi deux clients de générer la même valeur, ou de "se marcher dessus".

Vous pouvez mettre à jour des données dans une table en utilisant la méthode update() de l'adaptateur. Cette méthode accepte trois arguments : le premier est le nom de la table, le deuxième est un tableau faisant correspondre les noms des colonnes SQL à leurs valeurs désirées.

Les valeurs dans ce tableau sont traitées comme des chaînes. Voyez Section 10.1.4.1, « Insérer des données » pour plus d'informations sur la gestion des expressions SQL dans ce tableau.

Le troisième argument est une chaîne contenant l'expression SQL utilisée comme critère pour la mise à jour des données dans la table. Les valeurs et les arguments dans ce paramètre ne sont pas échappés pour vous. Vous devez donc vous assurer de l'éventuel bon échappement des caractères. Voyez Section 10.1.5, « Échapper des valeurs ou des identifiant » pour plus d'informations.

La valeur de retour de cette méthode est le nombre d'enregistrements affectés par l'opération de mise à jour (UPDATE).

<?php
$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$n = $db->update('bugs', $data, 'bug_id = 2');

Si vous oubliez le troisième paramètre, alors tous les enregistrements de la table sont mis à jour avec les valeurs spécifiées dans le tableau de données.

Si vous spécifiez un tableau de chaîne en tant que troisième paramètre, alors ces chaînes sont jointes entre elles avec une opération AND.

<?php
$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$where[] = "reported_by = 'goofy'";
$where[] = "bug_status = 'OPEN'";

$n = $db->update('bugs', $data, $where);

// la requête SQL executée est:
//  UPDATE "bugs" SET "update_on" = '2007-03-23', "bug_status" = 'FIXED'
//  WHERE ("reported_by" = 'goofy') AND ("bug_status" = 'OPEN')

Il est possible de supprimer des enregistrements dans une table. La méthode delete() est faite pour cela. Elle accepte deux paramètres, le premier est une chaîne désignant la table.

Le second paramètre est une chaîne contenant l'expression SQL utilisée comme critère pour effacer les enregistrements. Les valeurs de cette expression de sont pas échappées automatiquement, vous devez donc vous en occuper le cas échéant. Voyez Section 10.1.5, « Échapper des valeurs ou des identifiant » pour les méthodes concernant l'échappement.

La valeur retournée par la méthode delete() est le nombre d'enregistrements affectés (effacés).

<?php
$n = $db->delete('bugs', 'bug_id = 3');

Si vous ne spécifiez pas le second paramètres, tous les enregistrements de la table seront alors supprimés.

Si le second paramètre est un tableau de chaînes, alors celles ci seront jointe en une expression SQL, séparées par l'opération AND.

La méthode quote() accepte un seul paramètre, une chaîne de caractère. Elle retourne une chaîne dont les caractères spéciaux ont été échappés d'une manière convenable en fonction du SGBD sous-jacent. De plus, la chaîne échappée est entourée d'apostrophes (quotes) ((')).C'est la valeur standard de délimitations des chaînes en SQL.

<?php
$name = $db->quote("O'Reilly");
echo $name;
// 'O\'Reilly'

$sql = "SELECT * FROM bugs WHERE reported_by = $name";

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'

Notez que la valeur de retour contient les apostrophes de délimitation autour de la chaîne. Ceci est différent de certaines fonctions qui se contentent juste d'échapper les caractères spéciaux, telle que mysql_real_escape_string().

Certaines valeurs en revanche n'ont pas besoin d'être délimitées. Certains SGBDs n'acceptent pas que les valeurs correspondant à des champs de type entier, soient délimitées. Autrement dit, l'exemple suivant est erroné dans certaines implémentations de SQL. Nous supposons intColumn ayant un type SQL INTEGER :

SELECT * FROM atable WHERE intColumn = '123'

Le second paramètre optionnel de quote() permet de spécifier un type SQL.

<?php
$value = '1234';
$sql = 'SELECT * FROM atable WHERE intColumn = '
     . $db->quote($value, 'INTEGER');

De plus, chaque classe Zend_Db_Adapter possèdent des constantes représentant les différents type SQL des SGBDs respectifs qu'elles représentent. Ainsi, les constantes Zend_Db::INT_TYPE, Zend_Db::BIGINT_TYPE, et Zend_Db::FLOAT_TYPE peuvent vous permettre d'écrire un code portable entre différents SGBDs.

Zend_Db_Table fournit les types SQL à quote() automatiquement en fonction des colonnes utilisées par la table référencée.

Une autre manière est d'échapper une expression SQL contenant une variable PHP. Vous pouvez utiliser quoteInto() pour cela. Cette méthode accepte trois arguments. Le premier est la chaîne représentant l'expression SQL dont les paramètres variables sont remplacés par un joker(?), et le second argument est la variable PHP à utiliser pour le remplacement du joker.

Le joker est le même symbole que celui utilisé par beaucoup de SGBDs pour la substitution de paramètre dans une requête préparée.quoteInto() ne fait qu'émuler ce comportement : la méthode ne fait que remplacer le joker par la valeur PHP, en lui appliquant la méthode quote. De vrais paramètres de requêtes préparées conservent une réelle isolation entre la requête et ses paramètres.

<?php
$sql = $db->quoteInto("SELECT * FROM bugs WHERE reported_by = ?", "O'Reilly");

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'

Le troisième paramètre optionnel s'utilise comme avec la méthode quote. Il sert à spécifier un type SQL, les types numériques ne sont pas délimités.

<?php
$sql = $db->quoteInto("SELECT * FROM bugs WHERE bug_id = ?", '1234', 'INTEGER');

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 1234

Les valeurs ne sont pas les seuls données qui peuvent être dynamiques dans une requête SQL,et donc passées par des variables PHP. Les noms des tables, des colonnes, ou tout autre identifiant SQL spécial de la requête peuvent aussi être dynamiques. En général, les identifiant spéciaux d'une requête ont une syntaxe identique à celle des variables PHP : pas d'espaces dans les noms, certains autres caractères interdits, la ponctuation est interdite, etc... Aussi, les identifiant ne peuvent valoir certaines valeurs de mots réservés : une table ne peut s'appeler "FROM". Il se peut donc que vous ayez besoin aussi d'échapper des paramètres voués à être substitués à des identifiant dans la requête SQL, et non plus à des valeurs.

Le langage SQL possède une caractéristique appelée identifiant délimités. Si vous entourez un identifiant SQL dans un type spécial de délimiteurs, alors vous pouvez écrire des requêtes qui auraient été invalides autrement. Ainsi, vous pouvez inclure des espaces, de la ponctuation ou des caractères internationaux dans vos identifiant, et aussi utiliser des mots réservés.

La méthode quoteIdentifier() fonctionne comme quote(), mais elle utilise un caractère de délimitation spécial, en fonction du SGBD sous-jacent. Par exemple, le standard SQL spécifie des doubles quotes (") et beaucoup de SGBDs utilisent ceci. MySQL utilise les apostrophes inverses (back-quotes) (`) par défaut. Les caractères spéciaux sont aussi échappés.

<?php
// nous possédons une table ayant un nom correspondant à un mot reservé en SQL
$tableName = $db->quoteIdentifier("order");

$sql = "SELECT * FROM $tableName";

echo $sql
// SELECT * FROM "order"

Les identifiant SQL délimités sont sensibles à la casse. Vous devriez toujours utiliser la casse telle qu'elle est utilisée dans votre base de données (nom des tables, des colonnes ...).

Dans les cas où le SQL est généré à l'intérieur des classes Zend_Db, alors les identifiant SQL seront automatiquement échappés. Vous pouvez changer ce comportement avec l'option Zend_Db::AUTO_QUOTE_IDENTIFIERS.Spécifiez la lors de l'instanciation de l'adaptateur. Voyez Exemple 10.6, « Passer l'option d'auto-échappement à la fabrique ».