diff --git a/appendices/migration70/incompatible/error-handling.xml b/appendices/migration70/incompatible/error-handling.xml index c87c89e9ab..af0c2ecf1c 100644 --- a/appendices/migration70/incompatible/error-handling.xml +++ b/appendices/migration70/incompatible/error-handling.xml @@ -1,5 +1,5 @@ - + @@ -18,12 +18,12 @@ no interceptadas). - - Una descripción más completa de cómo funcionan los errores en PHP 7 se encuentra en la página de errores de PHP 7. + + Una descripción más completa de cómo funcionan los errores en PHP se encuentra en la página de errores Throwable. Esta guía de migración simplemente enumerará los cambios que afectan la retrocompatibilidad. - + diff --git a/appendices/reserved.xml b/appendices/reserved.xml index 248236e1e3..f66c84783b 100644 --- a/appendices/reserved.xml +++ b/appendices/reserved.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="utf-8"?> -<!-- EN-Revision: 4f7e802196f318a9b0305366c248254edeffd6c4 Maintainer: lacatoire Status: ready --> +<!-- EN-Revision: 7c915c0c28b8e2e4306333c64602ee4800c73754 Maintainer: lacatoire Status: ready --> <appendix xml:id="reserved" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Palabras reservadas en PHP @@ -56,7 +56,7 @@ case - catch + catch class @@ -135,7 +135,7 @@ final - finally + finally fn (disponible a partir de PHP 7.4) @@ -237,13 +237,13 @@ switch - throw + throw trait - try + try unset diff --git a/appendices/tokens.xml b/appendices/tokens.xml index 4778012515..bde9691249 100644 --- a/appendices/tokens.xml +++ b/appendices/tokens.xml @@ -1,5 +1,5 @@ - + Lista de tokens del analizador @@ -185,7 +185,7 @@ defined('T_FN') || define('T_FN', 10001); (int) catch - + @@ -560,7 +560,7 @@ defined('T_FN') || define('T_FN', 10001); (int) finally - + @@ -1237,7 +1237,7 @@ defined('T_FN') || define('T_FN', 10001); (int) throw - + @@ -1261,7 +1261,7 @@ defined('T_FN') || define('T_FN', 10001); (int) try - + diff --git a/language/control-structures.xml b/language/control-structures.xml index 5fb3ac1f27..d23b8e6aa8 100644 --- a/language/control-structures.xml +++ b/language/control-structures.xml @@ -1,6 +1,6 @@ - + Estructuras de Control @@ -56,6 +56,9 @@ &language.control-structures.require-once; &language.control-structures.include-once; &language.control-structures.goto; + &language.control-structures.throw; + &language.control-structures.try-catch; + &language.control-structures.finally; diff --git a/language/control-structures/finally.xml b/language/control-structures/finally.xml new file mode 100644 index 0000000000..2d6796f46c --- /dev/null +++ b/language/control-structures/finally.xml @@ -0,0 +1,495 @@ + + + + + finally + + + También puede especificarse un bloque &finally; después de los bloques + &catch;, o en lugar de ellos. + El código dentro del bloque &finally; siempre se ejecutará después de los + bloques &try; y &catch;, incluso si se encuentra una sentencia &return; o + &yield;, o si un error Throwable no es + capturado o es relanzado. + Se ejecutará antes de reanudar el flujo de ejecución normal. + La única excepción a esta regla es cuando el script se termina de forma + abrupta, por ejemplo mediante una llamada a exit o por + un error fatal (por ejemplo, cuando se supera el tiempo máximo de ejecución). + + + Manejo de un error <exceptionname>Throwable</exceptionname> con un bloque &finally; + +getMessage(), "\n"; +} finally { + echo "Primer finally.\n"; +} + +try { + echo inverse(0) . "\n"; +} catch (\DivisionByZeroError $e) { + echo 'Error capturado: ', $e->getMessage(), "\n"; +} finally { + echo "Segundo finally.\n"; +} + +// Continuar la ejecución +echo "Hola mundo\n"; +]]> + + &example.outputs.8; + + + + + + + Cuando la pila de llamadas se desenrolla tras lanzarse un error + Throwable, todos los bloques &finally; que + encuentra por el camino se ejecutarán. + En otras palabras, los bloques &finally; anidados se ejecutan incluso si el + error Throwable no es capturado por un bloque + &catch; adyacente. + + + Se ejecutarán todos los bloques &finally; + + + + &example.outputs; + + + + + + + Interacción entre un bloque &finally; y una sentencia &return; + + Una interacción notable se produce entre el bloque &finally; y una + sentencia &return;. + Si se encuentra una sentencia &return; dentro del bloque &try; o del bloque + &catch;, el bloque &finally; se ejecutará igualmente. Además, la sentencia + &return; se evalúa cuando se encuentra, pero el resultado se devolverá + después de ejecutar el bloque &finally;. Adicionalmente, si el bloque + &finally; también contiene una sentencia &return;, se devuelve el valor del + bloque &finally;. + + + Interacción entre &return; en un bloque &finally; y un &return; anterior + + + + &example.outputs; + + + + + + Interacción entre el bloque &finally; y &return; + + + + &example.outputs; + + + + + + + + Interacción entre un bloque &finally; y una excepción lanzada en un bloque &try; + + Si tanto el bloque &try; como el bloque &finally; lanzan una excepción, la + excepción lanzada desde el bloque &finally; es la que se propaga, y la + excepción lanzada desde el bloque &try; se utilizará como su excepción + previa. + + + Excepción en try y en finally + +getMessage(), + $e->getPrevious()->getMessage(), + $e->getPrevious()->getPrevious()->getMessage(), + $e->getPrevious()->getPrevious()->getPrevious()->getMessage(), + ); +} +]]> + + &example.outputs; + + + + + + + + + Comportamiento de un bloque &finally; en un + <link linkend="language.generators">generador</link> + + + + Si, durante el recorrido de un generador, se lanza un error + Throwable, el bloque &finally; dentro del + generador se ejecutará, ya que es el elemento previo de la pila de llamadas. + + + + Bloque &finally; ejecutado cuando se ha lanzado una + <exceptionname>Exception</exceptionname> + + + + + &example.outputs.similar; + + + + + + + Es posible utilizar &yield; dentro de un bloque &finally;, pero si se + produce un error Throwable y no es capturado + dentro del &foreach;, se lanza una Error + Cannot yield from finally in a force-closed generator. + + + + Error al utilizar &yield; en un bloque &finally; cuando se ha lanzado una + <exceptionname>Exception</exceptionname> + + + + + &example.outputs.similar; + + + + + + + + Interacción entre un bloque &finally; y una llamada a <function>exit</function> + + Cuando se llama a exit dentro de un bloque &try; o + &catch;, todos los bloques &finally; se omiten. + + + Interacción entre un bloque &finally; y <function>exit</function> llamado en un bloque &try; + + + + &example.outputs; + + + + + + Interacción entre un bloque &finally; y <function>exit</function> llamado en un bloque &catch; + + + + &example.outputs; + + + + + + Todos los bloques &finally; se omiten cuando se llama a <function>exit</function> + + + + &example.outputs; + + + + + + + Cuando se llama a exit dentro de un bloque &finally;, + se omiten todos los bloques &finally; externos. + + + Omisión de un bloque &finally; externo mediante una llamada a <function>exit</function> + + + + &example.outputs; + + + + + + + Caso límite de llamar a <function>exit</function> en un &foreach; sobre un generador + + Este caso límite depende en gran medida de la versión de PHP con la que se + ejecute el código. + + + + + + + + Salida del ejemplo anterior antes de PHP 7.1.14, en PHP 7.2.0 y 7.2.1, + y a partir de PHP 8.0.0 + + + + + + Salida del ejemplo anterior a partir de PHP 7.1.14 y 7.2.2, + y antes de PHP 8.0.0 + + + + + + + + diff --git a/language/control-structures/throw.xml b/language/control-structures/throw.xml new file mode 100644 index 0000000000..fea57d11db --- /dev/null +++ b/language/control-structures/throw.xml @@ -0,0 +1,148 @@ + + + + + throw + + + La palabra clave &throw; es una expresión y puede utilizarse en cualquier + contexto de expresión. + Toma un objeto Throwable como argumento. + + + + Antes de PHP 8.0.0, la palabra clave &throw; era una sentencia y no una + expresión. + + + + Intentar lanzar con &throw; un objeto que no es + Throwable lanzará una + Error. + Como las clases de usuario no pueden implementar directamente + Throwable, el objeto lanzado debe ser una + instancia de Error o de + Exception, o de una subclase de alguna de + ellas. + + + Lanzar un objeto que no es <exceptionname>Throwable</exceptionname> + + + + &example.outputs.similar; + + + + + + + + Después de utilizar &throw;, el flujo normal de ejecución se detiene y la + pila de llamadas se desenrolla hasta que el objeto es capturado por un bloque + &catch; o se alcanza el ámbito global. Todos los bloques &finally; + encontrados por el camino se ejecutan. + Si se alcanza el ámbito global, el objeto se pasa al manejador de + excepciones definido con set_exception_handler, si hay + uno, y el script termina una vez que el manejador retorna. De lo contrario, + el programa termina con un error fatal que contiene la traza de la pila que + indica dónde se lanzó el objeto Throwable. + + + Lanzar una excepción en el ámbito global + + + + &example.outputs.similar; + + + + + + Lanzar una excepción en una función + + + + &example.outputs.similar; + + + + + + + Como &throw; es una expresión, puede utilizarse para ramificar según el + resultado de otra expresión si su valor es inapropiado. + + + Uso de throw como expresión + Solo permitido a partir de PHP 8.0.0. + +getMessage(); +} +]]> + + &example.outputs; + + + + + + + Es posible manejar un Throwable lanzado + mediante un bloque try-catch. + Consulte la sección sobre el + manejo de errores + para más información. + + diff --git a/language/control-structures/try-catch.xml b/language/control-structures/try-catch.xml new file mode 100644 index 0000000000..02e5c17832 --- /dev/null +++ b/language/control-structures/try-catch.xml @@ -0,0 +1,246 @@ + + + + + try...catch + + try + + + Un bloque &try; delimita un segmento de código que puede lanzar con &throw; + un error Throwable que necesita ser manejado. + Un bloque &try; debe tener al menos un bloque &catch; + o &finally; correspondiente. + + + Cuando se lanza un error Throwable en un + bloque &try;, PHP intentará encontrar el primer bloque &catch; + correspondiente para manejar el error. Si no se encuentra ninguno, la pila + de llamadas se desenrolla hasta que se encuentra un bloque &catch; + correspondiente o se alcanza el ámbito global. + Un objeto no capturado se pasa entonces al manejador de excepciones definido + con set_exception_handler, si hay uno; de lo + contrario, el script termina con un error fatal. + + + + catch + + + Un bloque &catch; define cómo responder a un error + Throwable lanzado. + Especifica una o más subclases de Throwable + (lo más habitual es Exception) que puede + manejar, y opcionalmente una variable a la que se asigna la excepción. + + + El primer bloque &catch; que coincide con la clase del objeto + Throwable lanzado manejará el error. + La ejecución normal se reanuda después del bloque &catch; sin entrar en + ningún otro bloque &catch; que también coincida. + + + + No se recomienda capturar objetos + Error, ya que señalan un error de + programación. + + + + Captura de una excepción + +getMessage(), "\n"; +} + +// Continuar la ejecución +echo "Hola mundo\n"; +]]> + + &example.outputs; + + + + + + + A partir de PHP 7.1.0, un bloque &catch; puede especificar una unión de + subclases de Throwable que debe manejar, + utilizando el carácter de barra vertical (|). Esto es + útil cuando excepciones diferentes, de jerarquías de clases distintas, se + manejan de la misma manera. + + + Captura de una unión de clases a manejar + +testing(); +]]> + + &example.outputs; + + + + + + + Pueden utilizarse varios bloques &catch; para manejar de manera diferente + distintas clases de errores Throwable. + + + Bloques catch múltiples + + + + + + + Los errores Throwable pueden lanzarse con + &throw; (o relanzarse) dentro de un bloque &catch;. + + + Excepción anidada + +getMessage()); + } + } +} + +$foo = new Test; +$foo->testing(); +]]> + + &example.outputs; + + + + + + + Un objeto lanzado dentro de un bloque &catch; no será + capturado por un bloque &catch; adyacente. + + + Bloques catch secuenciales + + + + &example.outputs.similar; + + + + + + + + A partir de PHP 8.0.0, el nombre de la variable de un + Throwable capturado es opcional. + Si no se especifica, el bloque &catch; se ejecutará igualmente pero no + tendrá acceso al objeto lanzado. + + + Omisión de la variable capturada + Solo permitido a partir de PHP 8.0.0. + + + + &example.outputs; + + + + + + Consulte la sección sobre el + manejo de errores + para la jerarquía de Throwable y cómo + definir excepciones personalizadas. + + + diff --git a/language/error-handling.xml b/language/error-handling.xml new file mode 100644 index 0000000000..a966863cad --- /dev/null +++ b/language/error-handling.xml @@ -0,0 +1,366 @@ + + + + + Manejo de errores + + Los errores son una parte normal del desarrollo y del ciclo de vida de una + aplicación. Por ello, PHP proporciona varias formas de notificar y tratar + los errores. + + + PHP dispone de dos mecanismos principales para notificar errores: + + + + Los errores Throwable, que a su vez se + dividen en errores de programación, mediante la + jerarquía de clases Error, y errores + recuperables, mediante la jerarquía de clases + Exception. Estos errores pueden lanzarse + con la palabra clave &throw; y capturarse con la palabra clave &catch;. + + + + + Los errores de diagnóstico, que se clasifican en distintos + niveles de gravedad. + + + + + + + Errores <exceptionname>Throwable</exceptionname> + + + Un error Throwable es un evento de ejecución + que interrumpe el flujo normal de las instrucciones. Cuando se lanza con + &throw; un error Throwable, desenrolla la pila + de llamadas hasta que es capturado por un bloque &catch; o se alcanza el + ámbito global. + Todos los bloques &finally; que encuentra por el camino se ejecutarán. + Un error Throwable no capturado se pasa al + manejador de excepciones definido con + set_exception_handler, si hay uno; de lo contrario, el + programa termina con un error fatal. + + + Para lanzar un error Throwable desde código + PHP, utilice la palabra clave &throw;. + + + + La biblioteca estándar de PHP (SPL) + proporciona varias excepciones + integradas. + También es posible crear excepciones personalizadas + extendiendo la + clase Exception. + + + + Es posible manejar un error Throwable en PHP + rodeando el código que puede lanzar un error con un bloque &try;. + + + + Los objetos Throwable no pueden clonarse. + Intentar clonar un objeto de + este tipo lanza una Error con el siguiente + mensaje: + Trying to clone an uncloneable object of class ClassName. + Esto ocurre incluso si una subclase declara su propio método + __clone(). + Véanse Exception::__clone y + Error::__clone. + + + + + Manejador global de excepciones + + Es posible añadir un manejador para cualquier + Throwable no capturado con + set_exception_handler. + Esto es similar a envolver todo el código en un bloque &try;-&catch;, + salvo que la ejecución no se reanuda después: el script termina una vez + que el manejador retorna. + + + + + Extender las excepciones + + Una excepción definida por el usuario puede crearse extendiendo la clase + integrada Exception. + + + Si una clase extiende la clase integrada Exception + y redefine el constructor, se + recomienda encarecidamente que también llame a + parent::__construct() para asegurarse de que todos los datos + disponibles se han asignado correctamente. + El método __toString() puede + sobrescribirse para proporcionar una salida personalizada cuando el objeto + se utiliza como un string. + + + Extender <exceptionname>Exception</exceptionname> + +code}]: {$this->message}\n"; + } + + public function customFunction() { + echo "Una función personalizada para este tipo de excepción\n"; + } +} + +try { + throw new CustomException("Algo ha ocurrido", 5); +} catch (CustomException $e) { + echo "Excepción personalizada capturada\n", $e; + $e->customFunction(); +} +]]> + + &example.outputs; + + + + + + + + Jerarquía de <exceptionname>Throwable</exceptionname> + + + + Throwable + + + Error + + + ArithmeticError + + + DivisionByZeroError + + + + + AssertionError + + + CompileError + + + ParseError + + + + + TypeError + + + ArgumentCountError + + + + + ValueError + + + UnhandledMatchError + + + FiberError + + + + + Exception + + + + + + + La clase Exception tiene muchas subclases, + entre ellas las excepciones de SPL y + las definidas por las extensiones. + + + + + + Errores de diagnóstico + + Los errores de diagnóstico, también conocidos como errores tradicionales, se + utilizan para señalar diversas condiciones y pueden mostrarse y/o + registrarse según se necesite. + Por defecto, PHP notifica todos los errores de diagnóstico. (Antes de + PHP 8.0.0, los diagnósticos E_NOTICE y + E_DEPRECATED no se notificaban por defecto.) + + + A diferencia de los errores Throwable, la + mayoría de los errores de diagnóstico no interrumpen el + flujo normal de ejecución. + Los diagnósticos fatales, como E_ERROR, terminan el + script. + + + Los diagnósticos que se notifican y los que se ignoran se controlan + mediante la directiva de &php.ini; + error_reporting, + o en tiempo de ejecución llamando a error_reporting. + Se recomienda encarecidamente establecer la directiva de configuración, + ya que algunos errores pueden ocurrir antes de que comience la ejecución + del script. + + + + En un entorno de desarrollo, + error_reporting + debería establecerse siempre a E_ALL para que los + problemas señalados por PHP se noten y se corrijan. + En producción, el nivel de detalle puede reducirse a + E_ALL & ~E_NOTICE & ~E_DEPRECATED, aunque en muchos + casos E_ALL sigue siendo apropiado, ya que puede + proporcionar una alerta temprana de posibles problemas. + + + + + Lo que ocurre con los diagnósticos depende de otras dos directivas de + &php.ini;. + display_errors + controla si el diagnóstico se muestra como parte de la salida del script. + Esta debería estar siempre desactivada en un entorno de producción, ya que + la salida puede incluir información confidencial, como contraseñas de bases + de datos, pero a menudo es útil activarla en desarrollo, ya que garantiza + la notificación inmediata de los problemas. + + + + Además de mostrar los errores, PHP puede registrar los diagnósticos cuando + la directiva + log_errors + está activada. Esto registrará cualquier diagnóstico en el fichero o en el + syslog definido por + error_log. + Esto puede ser extremadamente útil en un entorno de producción, ya que los + diagnósticos se registran cuando ocurren y después pueden generarse informes + a partir de esos registros. + + + Los diagnósticos individuales pueden suprimirse utilizando el operador + @. + + + + + Antes de PHP 8.0.0, era posible suprimir diagnósticos críticos que + terminaban la ejecución del script PHP. + + + + + + Entre versiones de PHP, los diagnósticos pueden añadirse o eliminarse, + cambiar su gravedad o elevarse a errores + Throwable. + + + + + Manejador de diagnósticos definido por el usuario + + + Si el manejo de diagnósticos por defecto de PHP no es adecuado, es posible + sustituir el manejador de diagnósticos por defecto por uno personalizado, + que se establece con set_error_handler. + Algunos diagnósticos, como E_ERROR y + E_PARSE, no pueden manejarse de esta forma (véase + set_error_handler para la lista completa). + Los demás pueden manejarse de varias maneras. Por ejemplo, un manejador + personalizado puede mostrar una página de error al usuario y notificar el + error de forma más directa que un registro, por ejemplo enviando un correo + electrónico. + + + + Otro uso típico es elevar los errores de diagnóstico a excepciones con + ErrorException. + + + Elevar los errores de diagnóstico a excepciones + + + + + + Es importante comprobar que la gravedad está incluida en la lista actual + de diagnósticos notificables; de lo contrario, el operador + @ + dejará de funcionar, ya que se lanzaría una excepción para un + diagnóstico suprimido. + + + + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.5.0 + + Los errores fatales (como un tiempo máximo de ejecución superado) + ahora incluyen una traza de la pila en su mensaje de error. + + + + + + + + diff --git a/language/errors.xml b/language/errors.xml deleted file mode 100644 index 691c65e2fc..0000000000 --- a/language/errors.xml +++ /dev/null @@ -1,42 +0,0 @@ - - - - - - Errores - - - Introducción - - - Desarfortunadamente, no importa lo cuidadoso que uno sea escribiendo código; los errores - son un hecho de la vida. PHP notificará errores, advertencias y avisos para muchos problemas - comunes de codificación y de tiempo de ejecución, por lo que saber cómo detectar y manejar estos - errores hará la depuración mucho más sencilla. - - - - &language.errors.basics; - &language.errors.php7; - - - diff --git a/language/errors/basics.xml b/language/errors/basics.xml deleted file mode 100644 index 649d4267ed..0000000000 --- a/language/errors/basics.xml +++ /dev/null @@ -1,125 +0,0 @@ - - - - - - - Lo básico - - - PHP notifica errores en respuesta a varias condiciones de error internas. - Estas se pueden utilizar para señalar varias condiciones diferentes, - mostrándose y/o registrándose si fuera necesario. - - - - Cada error que genera PHP incluye un tipo. Existe una - lista de dichos tipos de error, - junto con una breve descripción de su comportamiento y sus posibles - causas. - - - - Manejo de errores con PHP - - - Si no se establece un manejador de errores, PHP manejará cada error que ocurra - según su configuración. Los errores que se notifican y los que se - ignoran se controla mediante la directiva - error_reporting - de php.ini, o durante la ejecución llamando a - error_reporting. Sin embargo, se recomienda encarecidamente - establecer la directiva de configuración, ya que algunos errores pueden ocurrir - antes de comenzar la ejecución de un script. - - - - En un entorno de desarrollo debería establecerse siempre - error_reporting - a E_ALL, debido a que es necesario reconocer y corregir los - problemas generados por PHP. En producción, se podría establecer esta directiva a - un nivel de menor verbosidad como - E_ALL & ~E_NOTICE & ~E_DEPRECATED, aunque - en muchos casos E_ALL también es apropiado, ya que puede - proporcionar advertencias precoces de problemas potenciales. - - - - Lo que PHP hace con estos errores depende de dos directivas más de php.ini. - display_errors - controla si el error es mostrado como parte de la salida del script. Esta - debería estar siempre deshabilitada en un entorno de producción, ya que puede incluir - información confidencial tal como contraseñas de bases de datos, aunque a menudo es útil - habilitarla en desarrollo debido a que asegura la notificación inmediata de problemas. - - - - Además de mostrar errores, PHP puede registrarlos cuando la directiva - log_errors - está habilitada. Esta registrará cualquier error en el fichero o registro del sistema - definido por - error_log. Esta directiva - puede ser extremadamente útil en un entorno de producción debido a que se pueden registrar - los errores que ocurran y generar informes basados en ellos. - - - - - Manejadores de errores de usuario - - - Si el manejo de errores predeterminado de PHP es inadecuado, también se pueden manejar muchos - tipos de error con un manejador de errores propio mediante - set_error_handler. Mientras que algunos tipos de error no se pueden - manejar de esta forma, aquellos que sí se pueden lo hacen de la manera - en que su script vea apropiada: por ejemplo, se puede emplear para mostrar al usuario - una página de error personalizada y luego notificar más directamente mediante un registro, - tal como el envío de un correo electrónico. - - - - - &reftitle.changelog; - - - - - &Version; - &Description; - - - - - 8.5.0 - - Los errores fatales (como un tiempo máximo de ejecución superado) ahora - incluyen una traza de la pila en su mensaje de error. - - - - - - - - - - diff --git a/language/errors/php7.xml b/language/errors/php7.xml deleted file mode 100644 index 1b12212e78..0000000000 --- a/language/errors/php7.xml +++ /dev/null @@ -1,118 +0,0 @@ - - - - - - - Errores en PHP 7 - - - PHP 7 cambia la mayoría de los errores notificados por PHP. En lugar de notificar - errores a través del mecanismo de notificación de errores tradicional de PHP 5, la mayoría - de los errores ahora son notificados lanzando excepciones Error. - - - - Al igual que las excepciones normales, las excepciones Error - se propagarán hasta alcanzar el primer bloque - catch - coincidente. Si no hay bloques coincidentes, será invocado cualquier manejador de - excepciones predeterminado instalado con set_exception_handler, - y si no hubiera ningún manejador de excepciones predeterminado, la excepción será - convertida en un error fatal y será manejada como un error tradicional. - - - - Debido a que la jerarquía de Error no hereda de - Exception, el código que emplee bloques - catch (Exception $e) { ... } para manejar excepciones no - capturadas en PHP 5 encontrará que estos Errores no - son capturados por dichos bloques. Se requiere, por tanto, un bloque catch (Error $e) { ... } - o un manejador set_exception_handler. - - - - Jerarquía de <classname>Error</classname> - - - - Throwable - - - Error - - - ArithmeticError - - - DivisionByZeroError - - - - - AssertionError - - - CompileError - - - ParseError - - - - - TypeError - - - ArgumentCountError - - - - - ValueError - - - UnhandledMatchError - - - FiberError - - - RequestParseBodyException - - - - - Exception - - - ... - - - - - - - - - - diff --git a/language/exceptions.xml b/language/exceptions.xml deleted file mode 100644 index 28d4f3b378..0000000000 --- a/language/exceptions.xml +++ /dev/null @@ -1,602 +0,0 @@ - - - - - - Las excepciones - - Vea también la clase Exception - - - PHP tiene un manejo de excepciones similar al que ofrecen otros - lenguajes de programación. - Una excepción puede ser lanzada ("&throw;") y capturada - ("&catch;") en PHP. El código deberá estar rodeado - de un bloque &try; para facilitar la captura de una excepción - potencial. Cada &try; debe tener al menos - un bloque &catch; o &finally; correspondiente. - - - Si una excepción es lanzada y el ámbito actual de la función no tiene - un bloque &catch;, la excepción "subirá" la pila de llamadas de la función llamadora - hasta encontrar un bloque &catch; correspondiente. Todos los bloques &finally; encontrados - serán ejecutados. Si la pila de llamadas se desenrolla hasta el ámbito global sin - encontrar un bloque &catch; correspondiente, el programa será terminado con - un error fatal a menos que se haya definido un manejador global de excepciones. - - - El objeto lanzado debe ser una &instanceof; Throwable. - Intentar lanzar un objeto que no lo es resultará en un error fatal emitido por PHP. - - - A partir de PHP 8.0.0, la palabra clave &throw; es una expresión y puede ser - utilizada en cualquier contexto de expresiones. En versiones anteriores era una declaración que debía estar en su propia línea. - - - - <literal>catch</literal> - - Un bloque &catch; define cómo reaccionar ante una excepción que ha sido lanzada. - Un bloque &catch; define uno o más tipos de excepciones o errores que puede - manejar, y opcionalmente una variable en la que asignar la excepción. - (Esta variable era requerida en versiones anteriores a PHP 8.0.0) - El primer bloque &catch; que una excepción o error lanzado encuentre y que corresponda al - tipo del objeto lanzado manejará el objeto. - - - Varios bloques &catch; pueden ser utilizados para atrapar diferentes - clases de excepciones. La ejecución normal (cuando ninguna excepción es lanzada - en el bloque &try;) continúa después del último - bloque &catch; definido en la secuencia. Las excepciones - pueden ser lanzadas (&throw;) o relanzadas en un bloque &catch;. De lo contrario, - la ejecución continuará después del bloque &catch; que haya sido activado. - - - Cuando una excepción es lanzada, el código siguiente al tratamiento no será - ejecutado y PHP intentará encontrar el primer bloque &catch; correspondiente. - Si una excepción no es capturada, un error fatal de PHP será - enviado con un mensaje "Uncaught Exception ..." - indicando que la excepción no pudo ser capturada a menos que un manejador - de excepciones sea definido con la función - set_exception_handler. - - - A partir de PHP 7.1, un bloque &catch; puede especificar múltiples excepciones a - través del carácter pipe (|). Esto es útil cuando - diferentes excepciones de diferentes jerarquías de clases son tratadas - de la misma manera. - - - A partir de PHP 8.0.0, el nombre de variable para la excepción capturada es - opcional. Si no se especifica, el bloque &catch; será siempre ejecutado pero - no tendrá acceso al objeto lanzado. - - - - - <literal>finally</literal> - - Un bloque &finally; también puede ser - especificado después de bloques &catch;. El código dentro - del bloque &finally; será siempre ejecutado después de los bloques - &try; y &catch;, independientemente de si - una excepción ha sido lanzada, antes de continuar con la ejecución normal. - - - Una interacción notable es entre un bloque &finally; y una declaración - &return;. - Si una declaración &return; es encontrada dentro de los bloques &try; - o &catch;, el bloque &finally; será igualmente ejecutado. Además, - la declaración &return; es evaluada cuando es encontrada, pero el - resultado será retornado después de que el bloque &finally; sea ejecutado. - Adicionalmente, si el bloque &finally; contiene también una declaración - &return; el valor del bloque &finally; es retornado. - - - Otra interacción notable es entre una excepción lanzada en un bloque &try;, - y una excepción lanzada en un bloque &finally;. Si una excepción es lanzada en ambos bloques, - entonces, la excepción lanzada en el bloque &finally; será la que se propagará, - y la excepción lanzada en el bloque &try; será utilizada como excepción previa. - - - - - Manejador global de excepciones - - Si una excepción es permitida para subir hasta el ámbito global, puede - ser capturada por un manejador de excepciones global si ha sido definido. La función - set_exception_handler puede definir una función que será - llamada en lugar de un bloque &catch; si ningún otro bloque es invocado. - El efecto es esencialmente idéntico a envolver el programa entero en un - bloque &try;-&catch; con esta función como &catch;. - - - - - &reftitle.notes; - - - - Las funciones internas de PHP utilizan principalmente el - Error reporting, solo las extensiones - orientadas a objetos - utilizan excepciones. Sin embargo, los errores pueden ser fácilmente convertidos en - excepciones con ErrorException. - Sin embargo, esta técnica solo funciona para errores no fatales. - - - Convertir el error reporting en excepciones - - - - - - - - La biblioteca estándar PHP (SPL) proporciona - un buen número de excepciones adicionales. - - - - - - &reftitle.examples; - - - Lanzar una excepción - -getMessage(), "\n"; -} - -// Continuar la ejecución -echo "¡Hola mundo!\n"; -]]> - - &example.outputs; - - - - - - Manejo de la excepción con un bloque &finally; - -getMessage(), "\n"; -} finally { - echo "Primer fin.\n"; -} - -try { - echo inverse(0) . "\n"; -} catch (Exception $e) { - echo 'Excepción recibida: ', $e->getMessage(), "\n"; -} finally { - echo "Segundo fin.\n"; -} - -// Continuar la ejecución -echo "¡Hola mundo!\n"; -]]> - - &example.outputs; - - - - - - Interacción entre el bloque &finally; y &return; - - - - &example.outputs; - - - - - - Herencia de una excepción - -getMessage()); - } - } -} - -$foo = new Test; -$foo->testing(); -]]> - - &example.outputs; - - - - - - Manejo de excepciones de captura múltiple - -testing(); -]]> - - &example.outputs; - - - - - - Omitir la variable capturada - Solo permitido en PHP 8.0.0 y versiones posteriores. - - - - &example.outputs; - - - - - - Throw como expresión - Solo permitido en PHP 8.0.0 y versiones posteriores. - -getMessage(); -} -]]> - - &example.outputs; - - - - - - Excepción en try y en finally - -getMessage(), - $e->getPrevious()->getMessage(), - $e->getPrevious()->getPrevious()->getMessage(), - $e->getPrevious()->getPrevious()->getPrevious()->getMessage(), - ); -} -]]> - - &example.outputs; - - - - - - - - Extender las Excepciones - - Una clase de excepción definida por el usuario puede ser definida extendiendo - la clase Exception integrada. Los miembros y las propiedades a continuación muestran - lo que está accesible en la clase hija que deriva de la clase Exception - integrada. - - - La clase de excepción integrada - - - - - - Si una clase extiende la clase Exception integrada y redefine el constructor, se recomienda fuertemente - que también llame a parent::__construct() - para asegurarse de que todos los datos disponibles han sido correctamente asignados. - El método __toString() puede ser - redefinido para proporcionar una salida personalizada cuando el objeto es presentado - en forma de string. - - - - Las excepciones no pueden ser clonadas. Intentar clonar una excepción lanza un - Error, incluso si una subclase declara su propio - método __clone(). - - - - Extender la clase Exception - -code}]: {$this->message}\n"; - } - - public function customFunction() { - echo "Una función personalizada para este tipo de excepción\n"; - } -} - -/** - * Crear una clase para probar la excepción - */ -class TestException -{ - public $var; - - const THROW_NONE = 0; - const THROW_CUSTOM = 1; - const THROW_DEFAULT = 2; - - function __construct($avalue = self::THROW_NONE) { - - switch ($avalue) { - case self::THROW_CUSTOM: - // Lanzar una excepción personalizada - throw new MyException('1 no es un parámetro válido', 5); - break; - - case self::THROW_DEFAULT: - // Lanzar la por defecto. - throw new Exception('2 no está permitido como parámetro', 6); - break; - - default: - // Ninguna excepción, el objeto será creado. - $this->var = $avalue; - break; - } - } -} - -echo "# Ejemplo 1\n"; -try { - $o = new TestException(TestException::THROW_CUSTOM); -} catch (MyException $e) { // Será capturada - echo "MyException capturada\n", $e; - $e->customFunction(); -} catch (Exception $e) { // Ignorado - echo "Exception por defecto capturada\n", $e; -} - -// Continuar la ejecución -var_dump($o); // Null - - -echo "\n\n# Ejemplo 2\n"; -try { - $o = new TestException(TestException::THROW_DEFAULT); -} catch (MyException $e) { // No coincide con este tipo - echo "MyException capturada\n", $e; - $e->customFunction(); -} catch (Exception $e) { // Será capturada - echo "Exception por defecto capturada\n", $e; -} - -// Continuar la ejecución -var_dump($o); // Null - - -echo "\n\n# Ejemplo 3\n"; -try { - $o = new TestException(TestException::THROW_CUSTOM); -} catch (Exception $e) { // Será capturada - echo "Exception por defecto capturada\n", $e; -} - -// Continuar la ejecución -var_dump($o); // Null - - -echo "\n\n# Ejemplo 4\n"; -try { - $o = new TestException(); -} catch (Exception $e) { // Saltado, ninguna excepción - echo "Exception por defecto capturada\n", $e; -} - -// Continuar la ejecución -var_dump($o); // TestException -]]> - - - - - - - diff --git a/language/oop5/basic.xml b/language/oop5/basic.xml index 5e8288e096..fa59a15220 100644 --- a/language/oop5/basic.xml +++ b/language/oop5/basic.xml @@ -1,5 +1,5 @@ - + Sintaxis básica @@ -196,14 +196,14 @@ readonly class Foo La palabra clave <literal>new</literal> - + Para crear una instancia de una clase, la palabra clave new debe ser utilizada. Un objeto será entonces sistemáticamente creado, a menos que tenga un constructor - definido que lance una excepción + definido que lance una Exception en caso de error. Las clases deben ser definidas antes de la instanciación (en algunos casos, esto es imprescindible). - + Si una variable string que contiene un nombre de clase es utilizada con new, una nueva instancia de esa clase será creada. diff --git a/language/oop5/changelog.xml b/language/oop5/changelog.xml index 0b2a426536..e670e908a5 100644 --- a/language/oop5/changelog.xml +++ b/language/oop5/changelog.xml @@ -1,5 +1,5 @@ - + Modificaciones en POO (Programación orientada a objetos) @@ -217,7 +217,7 @@ 5.5.0 - Adición: finally para manejar + Adición: finally para manejar las excepciones. @@ -276,9 +276,9 @@ Cambio: Anteriormente a 5.3.0, las excepciones lanzadas en la función __autoload no podían ser tratadas en un bloque - catch y resultaban en un error fatal. Ahora, las excepciones lanzadas en la función + catch y resultaban en un error fatal. Ahora, las excepciones lanzadas en la función __autoload pueden ser capturadas en un bloque - catch y tratadas. + catch y tratadas. Si una excepción personalizada es lanzada, entonces su clase debe estar disponible. La función __autoload puede ser utilizada recursivamente para autocargar la clase de excepción personalizada. diff --git a/language/operators/precedence.xml b/language/operators/precedence.xml index 3a96381b6a..921de86ab8 100644 --- a/language/operators/precedence.xml +++ b/language/operators/precedence.xml @@ -1,5 +1,5 @@ - + La prioridad de los operadores @@ -315,7 +315,7 @@ (n/a) throw - throw + throw diff --git a/language/predefined/error/clone.xml b/language/predefined/error/clone.xml index bceeeee7e4..bde27662cd 100644 --- a/language/predefined/error/clone.xml +++ b/language/predefined/error/clone.xml @@ -1,5 +1,5 @@ - + @@ -13,9 +13,18 @@ private voidError::__clone - - Un error no se pueden clonar, por lo que este método resulta en un error fatal. - + + Los errores no admiten clonación; este método existe únicamente para impedirla. + + + + Los errores no pueden ser clonados, ya sean instancias de + Error o de una subclase. + Intentar clonar un + error lanza un Error, que puede + ser capturado. + + @@ -32,9 +41,11 @@ &reftitle.errors; - - Los errores no son clonabes. - + + Intentar clonar un error lanza un Error + con el siguiente mensaje: + Trying to clone an uncloneable object of class ClassName. + diff --git a/language/predefined/exception/clone.xml b/language/predefined/exception/clone.xml index 2f1ed5631e..2f68f8f576 100644 --- a/language/predefined/exception/clone.xml +++ b/language/predefined/exception/clone.xml @@ -1,5 +1,5 @@ - + Exception::__clone @@ -40,9 +40,11 @@ &reftitle.errors; - - Las Excepciones no se pueden clonar. - + + Intentar clonar una excepción lanza un Error + con el siguiente mensaje: + Trying to clone an uncloneable object of class ClassName. + diff --git a/language/predefined/exceptions.xml b/language/predefined/exceptions.xml index 3e05536b78..5a6165abbd 100644 --- a/language/predefined/exceptions.xml +++ b/language/predefined/exceptions.xml @@ -1,5 +1,5 @@ - + @@ -16,7 +16,7 @@ &language.predefined.closedgeneratorexception; + language/error-handling.xml. --> &language.predefined.error; &language.predefined.argumentcounterror; &language.predefined.arithmeticerror; diff --git a/reference/dom/domexception.xml b/reference/dom/domexception.xml index 2efd64bb7f..f7326f8422 100644 --- a/reference/dom/domexception.xml +++ b/reference/dom/domexception.xml @@ -1,5 +1,5 @@ - + La clase DOMException / Dom\Exception @@ -16,9 +16,9 @@ Esta clase se aliasa bajo el nombre Dom\Exception en el espacio de nombres Dom. - - Ver también . - + + Ver también . + @@ -45,17 +45,11 @@ &InheritedProperties; - - - + &InheritedMethods; - - - - - - + + diff --git a/reference/errorfunc/functions/get-exception-handler.xml b/reference/errorfunc/functions/get-exception-handler.xml index 6ef4731b83..219e7a5237 100644 --- a/reference/errorfunc/functions/get-exception-handler.xml +++ b/reference/errorfunc/functions/get-exception-handler.xml @@ -1,5 +1,5 @@ - + @@ -93,7 +93,7 @@ if (!function_exists('get_exception_handler')) { restore_exception_handler restore_error_handler error_reporting - Excepciones + Excepciones diff --git a/reference/errorfunc/functions/set-exception-handler.xml b/reference/errorfunc/functions/set-exception-handler.xml index 11c3880d25..f3cd9de46f 100644 --- a/reference/errorfunc/functions/set-exception-handler.xml +++ b/reference/errorfunc/functions/set-exception-handler.xml @@ -1,5 +1,5 @@ - + set_exception_handler @@ -156,7 +156,7 @@ echo "No ejecutado\n"; restore_exception_handler restore_error_handler error_reporting - Las excepciones + Las excepciones diff --git a/reference/pdo/connections.xml b/reference/pdo/connections.xml index b95af3e693..902518beab 100644 --- a/reference/pdo/connections.xml +++ b/reference/pdo/connections.xml @@ -1,6 +1,6 @@ - + @@ -46,8 +46,8 @@ try { - - Al igual que todas las demás excepciones, + + Al igual que todas las demás excepciones, PDOException puede ser capturada ya sea explícitamente, mediante una instrucción &catch;, o implícitamente a través de set_exception_handler. De lo contrario, se producirá el comportamiento por defecto de convertir una excepción no capturada en una @@ -55,7 +55,7 @@ try { El error fatal contendrá un backtrace que podría revelar detalles sobre la conexión. Por lo tanto, la opción &php.ini; display_errors debe estar configurada a 0 en un servidor de producción. - + Cuando la conexión a la base de datos tiene éxito, se devuelve una instancia de la clase diff --git a/reference/pdo/error-handling.xml b/reference/pdo/error-handling.xml index cba757843f..e1b6205714 100644 --- a/reference/pdo/error-handling.xml +++ b/reference/pdo/error-handling.xml @@ -1,6 +1,6 @@ - + @@ -58,10 +58,10 @@ 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. - - Ver el capítulo sobre las excepciones - para más información sobre las excepciones en PHP. - + + Ver para más información + sobre el manejo de excepciones en PHP. + diff --git a/reference/pdo/pdoexception.xml b/reference/pdo/pdoexception.xml index 0afda162f8..4871716146 100644 --- a/reference/pdo/pdoexception.xml +++ b/reference/pdo/pdoexception.xml @@ -1,5 +1,5 @@ - + La clase PDOException @@ -10,13 +10,14 @@
&reftitle.intro; - + Representa un error emitido por PDO. No debe lanzarse una excepción PDOException desde - el propio código. Ver el capítulo sobre las - excepciones - para obtener más información sobre las excepciones en PHP. - + el propio código. + + + Ver también . +
@@ -48,17 +49,11 @@ &InheritedProperties; - - - + &InheritedMethods; - - - - - - + + diff --git a/reference/snmp/snmpexception.xml b/reference/snmp/snmpexception.xml index 2b390f95ca..c1cc7fb151 100644 --- a/reference/snmp/snmpexception.xml +++ b/reference/snmp/snmpexception.xml @@ -1,5 +1,5 @@ - + La clase SNMPException @@ -13,7 +13,7 @@ Representa un error lanzado por SNMP. No se debe lanzar una excepción SNMPException desde su código. - Ver las excepciones + Ver las excepciones para más información sobre las excepciones en PHP. @@ -34,17 +34,11 @@ &InheritedProperties; - - - + &InheritedMethods; - - - - - - + +