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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: eae19eb5fe0f5bebcbce382ea7a505cedeb5a883 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 vous offre 3 façons différentes de gérer les erreurs afin de mieux
  s'adapter à votre 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, vous pouvez 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,
    vous pouvez également 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,
    si vous voulez 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éfinit 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 de votre code, vous montrer
    rapidement le problème rencontré (souvenez-vous : les transactions
    sont automatiquement annulées si l'exception fait que votre script
    se termine).
   </para>
   <para>
    Le mode "exception" est également très utile car ainsi, vous pouvez
    structurer votre gestionnaire d'erreur plus clairement qu'avec
    les alertes traditionnelles PHP et, ce, avec moins de code que
    lorsque vous exécutez votre code en mode silence, et que vous
    vérifiez 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. Si vous avez besoin d'informations spécifiques sur
  l'erreur, PDO vous 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';

try {
    $dbh = new PDO($dsn, $user, $password);
    $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch (PDOException $e) {
    echo 'Échec lors de la connexion : ' . $e->getMessage();
}

?>
]]>
   </programlisting>
  </example>
 </para>
 <note>
  <para>
   <methodname>PDO::__construct</methodname> va toujours lancer une exception
   <classname>PDOException</classname> si la connexion échoue suivant la configuration
   de <constant>PDO::ATTR_ERRMODE</constant>. Les exceptions non attrappées deviennent
   des erreurs fatales.
  </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';

/*
    L'utilisation des blocs try/catch autour du constructeur est toujours valide
    même si nous définissons le ERRMODE à WARNING sachant que PDO::__construct
    va toujours lancer une exception PDOException si la connexion échoue.
*/
try {
    $dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));
} catch (PDOException $e) {
    echo 'Échec de la connexion : ' . $e->getMessage();
    exit;
}

// 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 18
]]>
    </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
-->