archived-doc-fr/reference/pdo/error-handling.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1508d46d0998c4843a22d28460bb6c4244290129 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->

<chapter xml:id="pdo.error-handling" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Les erreurs et leur gestion</title>
 <para>
  PDO offre 3 façons différentes de gérer les erreurs afin de mieux
  s'adapter à l'application.
 </para>
 <itemizedlist>
  <listitem>
   <para>
    <constant>PDO::ERRMODE_SILENT</constant>
   </para>
   <para>
    Antérieur à PHP 8.0.0, c'est le mode par défaut.
    PDO définit simplement le code d'erreur à inspecter
    grâce aux méthodes <methodname>PDO::errorCode</methodname> et
    <methodname>PDO::errorInfo</methodname> sur les objets représentant
    les requêtes, mais aussi ceux représentant les bases de données ; si l'erreur
    résulte d'un appel à l'objet représentant la requête, il est possible d'appeler
    la méthode <methodname>PDOStatement::errorCode</methodname> ou la méthode
    <methodname>PDOStatement::errorInfo</methodname> sur l'objet.
    Si l'erreur résulte d'un appel sur l'objet représentant une base de données,
    il est également possible d'appeler ces deux mêmes méthodes sur l'objet.
   </para>
  </listitem>
  <listitem>
   <para>
    <constant>PDO::ERRMODE_WARNING</constant>
   </para>
   <para>
    En plus de définir le code d'erreur, PDO émettra un message E_WARNING
    traditionnel. Cette configuration est utile lors des tests et du débogage,
    pour voir le problème sans interrompre l'application.
   </para>
  </listitem>
  <listitem>
   <para>
    <constant>PDO::ERRMODE_EXCEPTION</constant>
   </para>
   <para>
    À partir de PHP 8.0.0, c'est le mode par défaut.
    En plus de définir le code d'erreur, PDO lancera une exception
    <classname>PDOException</classname> et y définira les propriétés
    afin de représenter le code d'erreur et les informations complémentaires.
    Cette configuration est également utile lors du débogage, car elle
    va « contourner » le point critique du code, montrer
    rapidement le problème rencontré (il faut se rappeler : les transactions
    sont automatiquement annulées si l'exception fait que le script
    se termine).
   </para>
   <para>
    Le mode "exception" est également très utile car ainsi, il est possible de
    structurer le gestionnaire d'erreur plus clairement qu'avec
    les alertes traditionnelles PHP et, ce, avec moins de code que
    lorsque l'on exécute le code en mode silence, et que l'on
    vérifie systématiquement les valeurs retournées après chaque appel
    à la base de données.
   </para>
   <para>
    Voir le chapitre sur les <link linkend="language.exceptions">exceptions</link>
    pour plus d'informations sur les exceptions en PHP.
   </para>
  </listitem>
 </itemizedlist>
 <para>
  PDO utilise les codes erreurs SQL-92 SQLSTATE ; chaque pilote PDO est
  responsable de lier ses codes natifs aux codes SQLSTATE appropriés.
  La méthode <methodname>PDO::errorCode</methodname> retourne un code
  SQLSTATE unique. En cas de besoin d'informations spécifiques sur
  l'erreur, PDO propose également la méthode <methodname>PDO::errorInfo</methodname>
  qui retourne un tableau contenant le code SQLSTATE, le code d'erreur spécifique
  du pilote et la chaîne décrivant l'erreur provenant du pilote.
 </para>
 
 <para>
  <example><title>Création d'une instance PDO et
   définition du mode d'erreur</title>
   <programlisting role="php">
<![CDATA[
<?php
$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';

$dbh = new PDO($dsn, $user, $password);
$dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

// Cela provoquera une PDOException (lorsque la table n'existe pas).
$dbh->query("SELECT wrongcolumn FROM wrongtable");
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Fatal error: Uncaught PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'testdb.wrongtable' doesn't exist in /tmp/pdo_test.php:10
Stack trace:
#0 /tmp/pdo_test.php(10): PDO->query('SELECT wrongcol...')
#1 {main}
  thrown in /tmp/pdo_test.php on line 10
]]>
   </screen>
  </example>
 </para>
 <note>
  <para>
   <methodname>PDO::__construct</methodname> lance toujours une exception
   <classname>PDOException</classname> si la connexion échoue, quelle que soit la configuration
   de <constant>PDO::ATTR_ERRMODE</constant>.
  </para>
 </note>
 <para>
  <example>
   <title>Crée une instance PDO et définit le mode d'erreur depuis le constructeur</title>
   <programlisting role="php">
<![CDATA[
<?php
$dsn = 'mysql:dbname=test;host=127.0.0.1';
$user = 'googleguy';
$password = 'googleguy';

$dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));

// Ceci fera que PDO lancera une erreur de niveau E_WARNING au lieu d'une exception (lorsque la table n'existe pas)
$dbh->query("SELECT wrongcolumn FROM wrongtable");
?>
]]>
   </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Warning: PDO::query(): SQLSTATE[42S02]: Base table or view not found: 1146 Table 'test.wrongtable' doesn't exist in
/tmp/pdo_test.php on line 9
]]>
    </screen>
  </example>
 </para>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->