error-handling.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<chapter xml:id="pdo.error-handling" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Errors and error handling</title>
 <para>
  PDO offers you a choice of 3 different error handling strategies, to fit
  your style of application development.
 </para>
 <itemizedlist>
  <listitem>
   <para>
    <constant>PDO::ERRMODE_SILENT</constant>
   </para>
   <para>
     Prior to PHP 8.0.0, this was the default mode. PDO will simply set the error code for you
     to inspect using the <methodname>PDO::errorCode</methodname> and
     <methodname>PDO::errorInfo</methodname> methods on both the
     statement and database objects; if the error resulted from a call on a
     statement object, you would invoke the
     <methodname>PDOStatement::errorCode</methodname> or
     <methodname>PDOStatement::errorInfo</methodname>
     method on that object. If the error resulted from a call on the
     database object, you would invoke those methods on the database object
     instead.
    </para>
  </listitem>
  <listitem>
   <para>
    <constant>PDO::ERRMODE_WARNING</constant>
   </para>
   <para>
     In addition to setting the error code, PDO will emit a traditional
     E_WARNING message. This setting is useful during debugging/testing, if
     you just want to see what problems occurred without interrupting the
     flow of the application.
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>PDO::ERRMODE_EXCEPTION</constant>
    </para>
    <para>
     As of PHP 8.0.0, this is the default mode.
     In addition to setting the error code, PDO will throw a
     <classname>PDOException</classname>
     and set its properties to reflect the error code and error
     information. This setting is also useful during debugging, as it will
     effectively "blow up" the script at the point of the error, very
     quickly pointing a finger at potential problem areas in your code
     (remember: transactions are automatically rolled back if the exception
     causes the script to terminate).
    </para>
    <para>
     Exception mode is also useful because you can structure your error
     handling more clearly than with traditional PHP-style warnings, and
     with less code/nesting than by running in silent mode and explicitly
     checking the return value of each database call.
    </para>
    <para>
     See <link linkend="language.exceptions">Exceptions</link> for more
     information about Exceptions in PHP.
    </para>
   </listitem>
 </itemizedlist>
 <para>
  PDO standardizes on using SQL-92 SQLSTATE error code strings; individual
  PDO drivers are responsible for mapping their native codes to the
  appropriate SQLSTATE codes.   The <methodname>PDO::errorCode</methodname>
  method returns a single SQLSTATE code. If you need more specific
  information about an error, PDO also offers an
  <methodname>PDO::errorInfo</methodname> method which returns an array
  containing the SQLSTATE code, the driver specific error code and driver
  specific error string.
 </para>
 
 <para>
  <example>
   <title>Create a PDO instance and set the error mode</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);

// This will cause PDO to throw a PDOException (when the table doesn't exist)
$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> will always throw a <classname>PDOException</classname> if the connection fails
   regardless of which <constant>PDO::ATTR_ERRMODE</constant> is currently set.
  </para>
 </note>
 <para>
  <example>
   <title>Create a PDO instance and set the error mode from the constructor</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));

// This will cause PDO to throw an error of level E_WARNING instead of an exception (when the table doesn't exist)
$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
-->