Introduction

L'extension PHP Data Objects (PDO) définit une excellente interface pour accéder à une base de données depuis PHP. Chaque pilote de base de données implémenté dans l'interface PDO peut utiliser des fonctionnalités spécifiques de chacune des bases de données en utilisant des extensions de fonctions. Notez que vous ne pouvez exécuter aucune fonction de base de données en utilisant l'extension PDO par elle-même ; vous devez utiliser un driver PDO spécifique à la base de données pour accéder au serveur de base de données.

PDO fournit une interface d'abstraction à l'accès de données, ce qui signifie que vous utilisez les mêmes fonctions pour exécuter des requêtes ou récupérer les données quelque soit la base de données utilisée. PDO ne fournit pas une abstraction de base de données : il ne réécrit pas le SQL, n'émule pas des fonctionnalités manquantes. Vous devriez utiliser une interface d'abstraction complète si vous avez besoin de cela.

PDO est fournit avec PHP 5.1 et est disponible en tant qu'extension PECL pour PHP 5.0 ; PDO requiert les nouvelles fonctionnalités OO fournies par PHP 5 et donc, ne fonctionne pas avec les versions antérieures de PHP.

Installation

Configuration à l'exécution

Le comportement de ces fonctions est affecté par la configuration dans le fichier php.ini.

Voici un éclaircissement sur l'utilisation des directives de configuration.

Drivers PDO

Les drivers suivants sont actuellement implémentés dans l'interface PDO :

Connexions et gestionnaire de connexion

Les connexions sont établies en créant des instances de la classe de base de PDO. Peut importe quel driver vous voulez utiliser ; vous utilisez toujours le nom de la classe PDO. Le constructeur accepte des paramètres pour spécifier la source de la base de données (connue en tant que DSN) et optionnellement, le nom d'utilisateur et le mot de passe (s'il y en a un).

Exemple 1. Connexion à MySQL <?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass); ?>

S'il y a des erreurs de connexion, un objet PDOException est lancé. Vous pouvez attraper cette exception si vous voulez gérer cette erreur, ou laisser le gestionnaire global d'exception défini via la fonction set_exception_handler() la traiter.

Exemple 2. Gestion des erreurs de connexion <?php try {    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);    foreach ($dbh->query('SELECT * from FOO') as $row) {       print_r($row);    }    $dbh = null; } catch (PDOException $e) { print "Erreur ! : " . $e->getMessage() . "<br/>"; die(); } ?>

Lorsque la connexion à la base de données a réussi, une instance de la classe PDO est retournée à votre script. La connexion est active tant que l'objet PDO l'est. Pour clore la connexion, vous devez détruire l'objet en vous assurant que toutes ses références sont effacées. Vous pouvez faire cela en assignant NULL à la variable gérant l'objet. Si vous ne le faites pas explicitement, PHP fermera automatiquement la connexion lorsque le script arrivera à la fin.

Exemple 3. Fermeture d'une connexion <?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass); // utiliser la connexion ici // et maintenant, fermez-la ! $dbh = null; ?>

Beaucoup d'applications web utilisent des connexions persistantes aux serveurs de base de données. Les connexions persistantes ne sont pas fermées à la fin du script, mais sont mises en cache et réutilisées lorsqu'un autre script demande une connexion en utilisant les mêmes paramètres. Le cache des connexions persistantes vous permet d'éviter d'établir une nouvelle connexion à chaque fois qu'un script doit accéder à une base de données, rendant l'application web plus rapide.

Exemple 4. Connexions persistantes <?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(    PDO::ATTR_PERSISTENT => true )); ?>

Transactions et validation automatique (auto-commit)

Maintenant que vous êtes connecté via PDO, vous devez comprendre comment PDO gère les transactions avant d'exécuter des requêtes. Si vous n'avez jamais utilisé les transactions, elles offrent 4 fonctionnalités majeures : Atomicité, Consistance, Isolation et Durabilité (ACID). En d'autres termes, n'importe quel travail mené à bien dans une transaction, même s'il est effectué par étapes, est garanti d'être appliqué à la base de données sans risque, et sans interférence pour les autres connexions, quand il est validé. Le travail des transactions peut également être automatiquement annulé à votre demande (en supposant que vous n'avez encore rien validé), ce qui rend la gestion des erreurs bien plus simple dans vos scripts.

Les transactions sont typiquement implémentées pour appliquer toutes vos modifications en une seule fois ; ceci a le bel effet d'éprouver drastiquement l'efficacité de vos mises à jour. Dans d'autres termes, les transactions rendent vos scripts plus rapides et potentiellement plus robustes (vous devez les utiliser correctement pour avoir ces bénéfices).

Malheureusement, toutes les bases de données ne supportent pas les transactions, donc, PDO doit s'exécuter en mode "auto-commit" lorsque vous ouvrez pour la première fois la connexion. Le mode "auto-commit" signifie que toutes les requêtes que vous exécutez ont leurs transactions implicites, si la base de données le supporte ou aucune transaction si la base de données ne les supporte pas. Si vous avez besoin d'une transaction, vous devez utiliser la méthode PDO::beginTransaction() pour l'initialiser. Si le driver utilisé ne supporte pas les transactions, une exception PDO sera lancée (en accord avec votre gestionnaire d'erreurs : ceci est toujours une erreur sérieuse). Une fois que vous êtes dans une transaction, vous devez utiliser la fonction PDO::commit() ou la fonction PDO::rollBack() pour la terminer, suivant le succès de votre code durant la transaction.

Lorsque le script se termine ou lorsque la connexion est sur le point de se fermer, si vous avez une transaction en cours, PDO l'annulera automatiquement. Ceci est une mesure de sécurité afin de garantir la consistance de vos données dans le cas où le script se termine d'une façon inattendue. Si vous ne validez pas explicitement la transaction, alors, on présume que quelque chose s'est mal passé et l'annulation de la transaction intervient afin de garantir la sécurité de vos données.

Exemple 5. Exécution d'un groupe dans une transaction Dans l'exemple suivant, supposons que nous allons créer un jeu d'entrées pour un nouvel employé, dont le numéro d'ID sera 23. En plus des données basiques sur cette personne, nous devons également lui enregistrer son salaire. Il est très simple d'effectuer deux mises à jour séparées, mais en les enfermant dans les appels des fonctions PDO::beginTransaction() et PDO::commit(), nous garantissons que personne ne pourra voir ces modifications tant qu'elles ne seront pas complètes. Si quelque chose tourne mal, le bloc de capture annulera toutes les modifications effectuées depuis le début de la transaction et affichera un message d'erreur. <?php try {     $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',         array(PDO::ATTR_PERSISTENT => true));     echo "Connecté\n";     $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);     $dbh->beginTransaction();     $dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");     $dbh->exec("insert into salarychange (id, amount, changedate)     values (23, 50000, NOW())");     $dbh->commit(); } catch (Exception $e) {     $dbh->rollBack();     echo "Échec : " . $e->getMessage(); } ?>

Vous n'êtes pas limité dans le nombre de mises à jour dans une transaction ; vous pouvez également y effectuer des requêtes complexes et bien sûr, utiliser ces informations pour construire d'autres mises à jour et requêtes ; durant l'activité de la transaction, vous êtes garanti que personne d'autre ne peut effectuer des modifications alors que vous êtes au milieu de vos modifications. En réalité, ceci n'est pas 100% correct, mais cela reste une très bonne introduction aux transactions.

Requêtes préparées et procédures stockées

La plupart des bases de données supportent le concept des requêtes préparées. Qu'est-ce donc ? Vous pouvez les voir comme une sorte de modèle compilé pour le SQL que vous voulez exécuter, qui peut être personnalisé en utilisant des variables en guise de paramètres. Les requêtes préparées offrent deux fonctionnalités essentielles :

• La requête ne doit être analysée (ou préparée) qu'une seule fois, mais peut être exécutée plusieurs fois avec des paramètres identiques ou différents. Lorsque la requête est préparée, la base de données va analyser, compiler et optimiser son plan pour exécuter la requête. Pour les requêtes complexes, ce processus peut prendre assez de temps, ce qui peut ralentir vos applications si vous devez répéter la même requête plusieurs fois avec différents paramètres. En utilisant les requêtes préparées, vous évitez ainsi de répéter le cycle analyser/compilation/optimisation. Pour résumer, les requêtes préparées utilisent moins de ressources et s'exécutent plus rapidement.

• Les paramètres pour préparer les requêtes n'ont pas besoin d'être entre guillemets ; le driver le gère pour vous. Si votre application utilise exclusivement les requêtes préparées, vous pouvez être sûr qu'aucune injection SQL n'est possible (Cependant, si vous construisez d'autres parties de la requête en vous basant sur des entrées utilisateurs, vous continuez à prendre un risque).

Les requêtes préparées sont tellement pratiques que c'est l'unique fonctionnalité que PDO émule pour les drivers qui ne les supportent pas. Ceci assure de pouvoir utiliser la même technique pour accéder aux données, sans se soucier des capacités de la base de données.

Exemple 6. Insertions répétitives en utilisant les requêtes préparées Cet exemple effectue une requête INSERT en y substituant un nom et une valeur pour les marqueurs nommés. <?php $stmt = $dbh->prepare("INSERT INTO REGISTRY (nom, valeur) VALUES (:nom, :valeur)"); $stmt->bindParam(':nom', $nom); $stmt->bindParam(':valeur', $valeur); // insertion d'une ligne $nom = 'one'; $valeur = 1; $stmt->execute(); // insertion d'une autre ligne avec des valeurs différentes $nom = 'two'; $valeur = 2; $stmt->execute(); ?>

Exemple 7. Insertions répétées en utilisant des requêtes réparées Cet exemple effectue une requête INSERT en y substituant un nom et une valeur pour les marqueurs ?. <?php $stmt = $dbh->prepare("INSERT INTO REGISTRY (nom, valeur) VALUES (?, ?)"); $stmt->bindParam(1, $nom); $stmt->bindParam(2, $valeur); // insertion d'une ligne $nom = 'one'; $valeur = 1; $stmt->execute(); // insertion d'une autre ligne avec différentes valeurs $nom = 'two'; $valeur = 2; $stmt->execute(); ?>

Exemple 8. Récupération des données en utilisant des requêtes préparées Cet exemple récupère des données basées sur la valeur d'une clé fournie par un formulaire. L'entrée utilisateur est automatiquement échappée, il n'y a donc aucun risque d'attaque par injection SQL. <?php $stmt = $dbh->prepare("SELECT * FROM REGISTRY where nom = ?"); if ($stmt->execute(array($_GET['nom']))) { while ($row = $stmt->fetch()) { print_r($row); } } ?>

Si le driver de la base de données le supporte, vous pouvez également lier des paramètres aussi bien pour l'entrée que pour la sortie. Les paramètres de sortie sont utilisés typiquement pour récupérer les valeurs d'une procédure stockée. Les paramètres de sortie sont un peu plus complexe à utiliser que les paramètres d'entrée car vous devez savoir la longueur d'un paramètre donné pourra atteindre lorsque vous le liez. Si la valeur retournée est plus longue que la taille qui vous auriez suggéré, une erreur sera émise.

Exemple 9. Appel d'une procédure stockée avec un paramètre de sortie <?php $stmt = $dbh->prepare("CALL sp_returns_string(?)"); $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000); // Appel de la procédure stockée $stmt->execute(); print "La procédure a retourné : $return_value\n"; ?>

Vous devez également spécifier les paramètres qui gèrent les valeurs aussi bien pour l'entrée que pour la sortie ; la syntaxe est similaire aux paramètres de sortie. Dans le prochain exemple, la chaîne 'Bonjour' est passée à la procédure stockée et lorsqu'elle retourne la valeur, 'Bonjour' est remplacée par la valeur retournée par la procédure.

Exemple 10. Appel d'une procédure stockée avec un paramètre d'entrée/sortie <?php $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)"); $value = 'Bonjour'; $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000); // appel de la procédure stockée $stmt->execute(); print "La procédure a retourné : $value\n"; ?>

Exemple 11. Utilisation invalide de marqueur <?php $stmt = $dbh->prepare("SELECT * FROM REGISTRY where nom LIKE '%?%'"); $stmt->execute(array($_GET['nom'])); // un marqueur doit être utilisé à la place d'une valeur complète $stmt = $dbh->prepare("SELECT * FROM REGISTRY where nom LIKE ?"); $stmt->execute(array("%$_GET[nom]%")); ?>

Erreurs et gestionnaire des erreurs

PDO offre la possibilité de gérer les erreurs de 3 façons différentes, pour coller au mieux au style de votre application.

• PDO::ERRMODE_SILENT

  C'est le mode par défaut. PDO définit simplement le code erreur pour vous afin de l'inspecter en utilisant les méthodes PDO::errorCode() et PDO::errorInfo() sur la requête ou sur les objets de la base de données ; si l'erreur est issue d'un appel à un objet de requête, vous devriez invoquer les méthodes PDOStatement::errorCode() ou PDOStatement::errorInfo() sur cet objet. Si l'erreur est issue d'un appel sur un objet de la base de données, vous devriez invoquer à la place les méthodes de cet objet.

• PDO::ERRMODE_WARNING

  En plus de définir le code erreur, PDO émettra un message de niveau E_WARNING. Ce comportement est très utile lors de la phase de test/débogage, si vous voulez juste voir le problème qui survient sans pour autant stopper le flot de l'application.

• PDO::ERRMODE_EXCEPTION

  En plus de définir le code erreur, PDO lancera une exception PDOException et y définit ces propriétés pour refléter le code erreur et l'information sur l'erreur. Ce comportement est utile également durant la période de débogage car il va stopper l'application à l'endroit même de l'erreur et pointer l'endroit où se trouve potentiellement l'erreur dans votre code (souvenez-vous : les transactions sont automatiquement annulées si l'exception fait que le script se termine).

  Le mode lançant des exceptions est également utile pour structurer la gestion de vos erreurs plus clairement que par la traditionnelle gestion des erreurs de PHP et avec moins de code, plutôt que le mode silencieux et l'analyse explicite des valeurs retournées par chaque appel à la base de données.

  Lisez la documentation sur les exceptions pour plus de détails sur les exceptions en PHP.

PDO standardise les codes erreurs en utilisant SQL-92 SQLSTATE ; les drivers individuels PDO sont responsables du mapping de leurs propres codes avec les codes SQLSTATE appropriées. La méthode PDO::errorCode() retourne un seul code SQLSTATE. Si vous avez besoin de plus d'informations sur une erreur, PDO fournit également la méthode PDO::errorInfo() qui retourne un tableau contenant le code SQLSTATE, le code erreur spécifique du driver et la chaîne erreur spécifique au driver.

Les objets larges (LOBs)

À un moment dans votre application, vous pourriez avoir besoin de stocker de larges données dans votre base de données. "Large" signifie typiquement des données d'environ 4ko ou plus, bien que certaines bases de données peuvent gérer plus de 32ko avant que les données deviennent "larges". Les objets larges peuvent être de nature textuelle ou binaire. PDO vous permet de travailler avec ce type de larges données en utilisant le code type PDO::PARAM_LOB dans vos appels aux fonctions PDOStatement::bindParam() ou PDOStatement::bindColumn(). PDO::PARAM_LOB demande à PDO de mapper les données en un flux que vous pourrez manipuler en utilisant l'API PHP sur les flux.

Exemple 12. Affichage d'une image depuis une base de données Cet exemple lie un LOB dans une variable nommée $lob et l'envoie au navigateur en utilisant la fonction fpassthru(). Étant donné qu'un LOB est représenté en un flux, les fonctions comme fgets(), fread() et stream_get_contents() peuvent être utilisées sur ce flux. <?php $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2'); $stmt = $db->prepare("select contenttype, imagedata from images where id=?"); $stmt->execute(array($_GET['id'])); $stmt->bindColumn(1, $type, PDO::PARAM_STR, 256); $stmt->bindColumn(2, $lob, PDO::PARAM_LOB); $stmt->fetch(PDO::FETCH_BOUND); header("Content-Type: $type"); fpassthru($lob); ?>

Exemple 13. Insertion d'une image dans une base de données Cet exemple ouvre un fichier et passe le pointeur de fichier à PDO pour l'insérer en tant que LOB. PDO fera son possible pour récupérer le contenu du fichier et l'insérer dans la base de données de la manière la plus efficace possible. <?php $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2'); $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)"); $id = get_new_id(); // fonction pour allouer un nouvel ID // assumons que nous récupérons un fichier depuis un formulaire // vous pouvez trouver plus de détails dans la documentation de PHP $fp = fopen($_FILES['file']['tmp_name'], 'rb'); $stmt->bindParam(1, $id); $stmt->bindParam(2, $_FILES['file']['type']); $stmt->bindParam(3, $fp, PDO::PARAM_LOB); $stmt->beginTransaction(); $stmt->execute(); $stmt->commit(); ?>

Exemple 14. Insertion d'une image dans une base de données Oracle Oracle requiert une syntaxe légèrement différente pour y insérer un LOB depuis un fichier. Il est également essentiel d'effectuer votre insertion au sein d'une transaction, sinon, votre nouveau LOB sera inséré avec une longueur de zéro : <?php $db = new PDO('oci:', 'scott', 'tiger'); $stmt = $db->prepare("insert into images (id, contenttype, imagedata) " . "VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?"); $id = get_new_id(); // fonction pour allouer un nouvel ID // assumons que nous récupérons un fichier depuis un formulaire // vous pouvez trouver plus de détails dans la documentation de PHP $fp = fopen($_FILES['file']['tmp_name'], 'rb'); $stmt->bindParam(1, $id); $stmt->bindParam(2, $_FILES['file']['type']); $stmt->bindParam(3, $fp, PDO::PARAM_LOB); $stmt->beginTransaction(); $stmt->execute(); $stmt->commit(); ?>

Classes pré-définies

Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.