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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1508d46d0998c4843a22d28460bb6c4244290129 Maintainer: PhilDaiguille 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>Los errores y su gestión</title>
 <para>
  PDO ofrece 3 formas diferentes de gestionar los errores para adaptarse mejor
  a la aplicación.
 </para>
 <itemizedlist>
  <listitem>
   <para>
    <constant>PDO::ERRMODE_SILENT</constant>
   </para>
   <para>
    Anterior a PHP 8.0.0, este es el modo por omisión.
    PDO define simplemente el código de error para ser inspeccionado
    mediante los métodos <methodname>PDO::errorCode</methodname> y
    <methodname>PDO::errorInfo</methodname> en los objetos que representan
    las consultas, así como en los que representan las bases de datos; si el error
    resulta de una llamada al objeto que representa la consulta, se puede llamar
    al método <methodname>PDOStatement::errorCode</methodname> o al método
    <methodname>PDOStatement::errorInfo</methodname> en el objeto.
    Si el error resulta de una llamada al objeto que representa una base de datos,
    también se pueden llamar estos dos mismos métodos en el objeto.
   </para>
  </listitem>
  <listitem>
   <para>
    <constant>PDO::ERRMODE_WARNING</constant>
   </para>
   <para>
    Además de definir el código de error, PDO emitirá un mensaje E_WARNING
    tradicional. Esta configuración es útil durante las pruebas y el depurado,
    si se desea ver el problema sin interrumpir la aplicación.
   </para>
  </listitem>
  <listitem>
   <para>
    <constant>PDO::ERRMODE_EXCEPTION</constant>
   </para>
   <para>
    A partir de PHP 8.0.0, este es el modo por omisión.
    Además de definir el código de error, PDO lanzará una excepción
    <classname>PDOException</classname> y definirá las propiedades
    para representar el código de error y la información complementaria.
    Esta configuración es igualmente útil durante el depurado, ya que
    permitirá "saltar" el punto crítico del código, mostrando rápidamente
    el problema encontrado (recuerde: las transacciones son automáticamente
    revertidas si la excepción hace que el script termine).
   </para>
   <para>
    El modo "excepción" es también muy útil ya que permite
    estructurar el gestor de errores de forma más clara que
    con las alertas tradicionales de PHP y, además, con menos código que
    cuando se ejecuta el código en modo silencio, y se verifica sistemáticamente
    los valores devueltos después de cada llamada a la base de datos.
   </para>
   <para>
    Ver el capítulo sobre las <link linkend="language.exceptions">excepciones</link>
    para más información sobre las excepciones en PHP.
   </para>
  </listitem>
 </itemizedlist>
 <para>
  PDO utiliza los códigos de error SQL-92 SQLSTATE; cada controlador PDO es
  responsable de vincular sus códigos nativos a los códigos SQLSTATE apropiados.
  El método <methodname>PDO::errorCode</methodname> devuelve un código
  SQLSTATE único. Si se necesitan información específica sobre el error, PDO
  también ofrece el método <methodname>PDO::errorInfo</methodname>
  que devuelve un array conteniendo el código SQLSTATE, el código de error específico
  del controlador y la cadena describiendo el error proveniente del controlador.
 </para>

 <para>
  <example><title>Creación de una instancia PDO y
   definición del modo de error</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);

// Esto provocará una PDOException (cuando la tabla no existe).
$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> siempre lanza una excepción
   <classname>PDOException</classname> si la conexión falla, independientemente de la configuración
   de <constant>PDO::ATTR_ERRMODE</constant>.
  </para>
 </note>
 <para>
  <example>
   <title>Crea una instancia PDO y define el modo de error desde el 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));

// Esto hará que PDO lance un error de nivel E_WARNING en lugar de una excepción (cuando la tabla no existe)
$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
-->