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

<!-- EN-Revision: c81a48e58fc530a74827316027fae74668d17a1d Maintainer: yannick Status: ready -->

<!-- Reviewed: no -->

<chapter xml:id="language.exceptions" xmlns="http://docbook.org/ns/docbook">

<title>Les exceptions</title>

<para>

PHP a une gestion des exceptions similaire à ce qu'offrent les autres

langages de programmation.

Une exception peut être lancée ("&throw;") et attrapée

("&catch;") dans PHP. Le code devra être entouré

d'un bloc &try; pour faciliter la saisie d'une exception

potentielle. Chaque &try; doit avoir au moins

un bloc &catch; ou &finally; correspondant.

</para>

<para>

Si une exception est lancée et que la portée courante de la fonction n'a pas

de bloc &catch;, l'exception "remontera" la pile d'appel de la fonction appelante

jusqu'à trouver un bloc &catch; correspondant. Tous les blocs &finally; rencontrés

seront exécutés. Si la pile d'appel est déroulée jusqu'à la portée globale sans

rencontrer de bloc &catch; correspondant, le programme sera terminé avec

une erreur fatale sauf si un gestionnaire global d'exception a été défini.

</para>

<para>

L'objet lancé doit être une &instanceof; <interfacename>Throwable</interfacename>.

Tenter de lancer un objet qui ne l'est pas résultera en une erreur fatale émise par PHP.

</para>

<para>

À partir de PHP 8.0.0, le mot clé &throw; est une expression et peut être

utilisé dans n'importe quel contexte d'expressions. Dans les versions

antérieures c'était une déclaration qui devait être sur sa propre ligne.

</para>

<sect1 annotations="chunk:false" xml:id="language.exceptions.catch">

<title><literal>catch</literal></title>

<para>

Un bloc &catch; définit comment réagir à une exception qui a été lancée.

Un bloc &catch; définit un ou plusieurs types d'exceptions ou erreurs qu'il peut

gérer, et optionnellement une variable dans laquelle assigner l'exception.

(Cette variable était requise dans les versions antérieures à PHP 8.0.0)

Le premier bloc &catch; qu'une exception ou erreur lancée rencontre et qui correspond au

type de l'objet lancé gérera l'objet.

</para>

<para>

Plusieurs blocs &catch; peuvent être utilisés pour attraper différentes

classes d'exceptions. L'exécution normale (lorsqu'aucune exception n'est lancée

dans le bloc &try;) continue après le dernier

bloc &catch; défini dans la séquence. Les exceptions

peuvent être lancées (&throw;) ou relancées dans un bloc &catch;. Sinon,

l'exécution continuera après le bloc &catch; qui a été déclenché.

</para>

<para>

Lorsqu'une exception est lancée, le code suivant le traitement ne sera pas

exécuté et PHP tentera de trouver le premier bloc &catch; correspondant.

Si une exception n'est pas attrapée, une erreur fatale issue de PHP sera

envoyée avec un message "<literal>Uncaught Exception ...</literal>"

indiquant que l'exception n'a pu être attrapée à moins qu'un gestionnaire

d'exceptions ne soit défini avec la fonction

<function>set_exception_handler</function>.

</para>

<para>

À partir de PHP 7.1, un bloc &catch; peut spécifier plusieurs exceptions à

l'aide du caractère pipe (<literal>|</literal>). Ceci est utile lorsque

différentes exceptions de hiérarchies de classes différentes sont traitées

de la même manière.

</para>

<para>

À partir de PHP 8.0.0, le nom de variable pour l'exception attrapée est

optionnel. Si non spécifié, le bloc &catch; sera toujours exécuté mais

n'aura pas accès à l'objet lancé.

</para>

</sect1>

<sect1 annotations="chunk:false" xml:id="language.exceptions.finally">

<title><literal>finally</literal></title>

<para>

Un bloc &finally; peut aussi être

spécifié après ou à la place des blocs &catch;. Le code à l'intérieur

du bloc &finally; sera toujours exécuté après les blocs

&try; et &catch;, indépendamment du fait qu'une

exception a été lancée, avant de continuer l'exécution normale.

</para>

<para>

Une interaction notable est entre un bloc &finally; et une déclaration

&return;.

Si une déclaration &return; est rencontrée à l'intérieur des blocs &try;

ou &catch;, le bloc &finally; sera quand même exécuté. De plus,

la déclaration &return; est évaluée quand elle est rencontrée, mais le

résultat sera retourné après que le bloc &finally; soit exécuté.

Additionnellement, si le bloc &finally; contient aussi une déclaration

&return; la valeur du bloc &finally; est retournée.

</para>

<para>

Une autre interaction notable est entre une exception lancée dans un bloc &try;,

et une exception lancée dans un bloc &finally;. Si une exception est lancée dans les deux blocs,

alors, l'exception lancée dans le bloc &finally; sera celle qui sera propagée,

et l'exception lancée dans le bloc &try; sera utilisée comme exception précédente.

</para>

</sect1>

<sect1 annotations="chunk:false" xml:id="language.exceptions.exception-handler">

<title>Gestionnaire d'exceptions global</title>

<para>

Si une exception est autorisée à remonter jusqu'à la portée globale, elle peut

être attrapée par un gestionnaire d'exceptions global s'il a été défini. La fonction

<function>set_exception_handler</function> peut définir une fonction qui sera

appelée à la place d'un bloc &catch; si aucun autre bloc n'est invoqué.

L'effet est essentiellement identique à entourer le programme entier dans un

bloc &try;-&catch; avec cette fonction en tant que &catch;.

</para>

</sect1>

<sect1 annotations="chunk:false" xml:id="language.exceptions.notes">

&reftitle.notes;

<note>

<para>

Les fonctions internes de PHP utilisent principalement l'

<link linkend="ini.error-reporting">Error reporting</link>, seules les extensions

<link linkend="language.oop5">orientées objet</link> modernes

utilisent les exceptions. Quoi qu'il en soit, des erreurs peuvent facilement être traduites en

exceptions avec <link linkend="class.errorexception">ErrorException</link>.

Cependant, cette technique ne fonctionne que pour les erreurs non fatales.

</para>

<example>

<title>Convertir l'error reporting en exceptions</title>

<programlisting role="php">

<![CDATA[

<?php

function exceptions_error_handler($severity, $message, $filename, $lineno) {

throw new ErrorException($message, 0, $severity, $filename, $lineno);

}

set_error_handler('exceptions_error_handler');

?>

]]>

</programlisting>

</example>

</note>

<tip>

<para>

La <link linkend="intro.spl">bibliothèque standard PHP (SPL)</link> fournit

un bon nombre <link linkend="spl.exceptions">d'exceptions additionnelles</link>.

</para>

</tip>

</sect1>

<sect1 annotations="chunk:false" xml:id="language.exceptions.examples">

&reftitle.examples;

<example>

<title>Lancer une exception</title>

<programlisting role="php">

<![CDATA[

<?php

function inverse($x) {

if (!$x) {

throw new Exception('Division par zéro.');

}

return 1/$x;

}

try {

echo inverse(5) . "\n";

echo inverse(0) . "\n";

} catch (Exception $e) {

echo 'Exception reçue : ', $e->getMessage(), "\n";

}

// On continue l'exécution

echo "Bonjour le monde !\n";

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

0.2

Exception reçue : Division par zéro.

Bonjour le monde !

]]>

</screen>

</example>

<example>

<title>Gestion de l'exception avec un bloc &finally;</title>

<programlisting role="php">

<![CDATA[

<?php

function inverse($x) {

if (!$x) {

throw new Exception('Division par zéro.');

}

return 1/$x;

}

try {

echo inverse(5) . "\n";

} catch (Exception $e) {

echo 'Exception reçue : ', $e->getMessage(), "\n";

} finally {

echo "Première fin.\n";

}

try {

echo inverse(0) . "\n";

} catch (Exception $e) {

echo 'Exception reçue : ', $e->getMessage(), "\n";

} finally {

echo "Seconde fin.\n";

}

// On continue l'exécution

echo "Bonjour le monde !\n";

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

0.2

Première fin.

Exception reçue : Division par zéro.

Seconde fin.

Bonjour le monde !

]]>

</screen>

</example>

<example>

<title>Interaction entre le bloc &finally; et &return;</title>

<programlisting role="php">

<![CDATA[

<?php

function test() {

try {

throw new Exception('foo');

} catch (Exception $e) {

return 'catch';

} finally {

return 'finally';

}

}

echo test();

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

finally

]]>

</screen>

</example>

<example>

<title>Héritage d'une exception</title>

<programlisting role="php">

<![CDATA[

<?php

class MyException extends Exception { }

class Test {

public function testing() {

try {

try {

throw new MyException('foo!');

} catch (MyException $e) {

// on la relance

throw $e;

}

} catch (Exception $e) {

var_dump($e->getMessage());

}

}

}

$foo = new Test;

$foo->testing();

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

string(4) "foo!"

]]>

</screen>

</example>

<example>

<title>Gestion des exceptions de capture multiple</title>

<programlisting role="php">

<![CDATA[

<?php

class MyException extends Exception { }

class MyOtherException extends Exception { }

class Test {

public function testing() {

try {

throw new MyException();

} catch (MyException | MyOtherException $e) {

var_dump(get_class($e));

}

}

}

$foo = new Test;

$foo->testing();

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

string(11) "MyException"

]]>

</screen>

</example>

<example>

<title>Omettre la variable attrapée</title>

<para>Seulement permis dans PHP 8.0.0 et ultérieur.</para>

<programlisting role="php">

<![CDATA[

<?php

class SpecificException extends Exception {}

function test() {

throw new SpecificException('Oopsie');

}

try {

test();

} catch (SpecificException) {

print "Une SpecificException a été levée, mais les détails ne nous intéressent pas.";

}

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Une SpecificException a été levée, mais les détails ne nous intéressent pas.

]]>

</screen>

</example>

<example>

<title>Throw en tant qu'expression</title>

<para>Seulement permis dans PHP 8.0.0 et ultérieur.</para>

<programlisting role="php">

<![CDATA[

<?php

function test() {

do_something_risky() or throw new Exception("Cela n'a pas fonctionné");

}

function do_something_risky() {

return false; // Simuler un échec

}

try {

test();

} catch (Exception $e) {

print $e->getMessage();

}

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Cela n'a pas fonctionné

]]>

</screen>

</example>

<example>

<title>Exception dans try et dans finally</title>

<programlisting role="php">

<![CDATA[

<?php

try {

try {

throw new Exception(message: 'Third', previous: new Exception('Fourth'));

} finally {

throw new Exception(message: 'First', previous: new Exception('Second'));

}

} catch (Exception $e) {

var_dump(

$e->getMessage(),

$e->getPrevious()->getMessage(),

$e->getPrevious()->getPrevious()->getMessage(),

$e->getPrevious()->getPrevious()->getPrevious()->getMessage(),

);

}

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

string(5) "First"

string(6) "Second"

string(5) "Third"

string(6) "Fourth"

]]>

</screen>

</example>

</sect1>

<sect1 xml:id="language.exceptions.extending">

<title>Étendre les Exceptions</title>

<para>

Une classe d'exception définie par l'utilisateur peut être définie en étendant

la classe Exception intégrée. Les membres et les propriétés ci-dessous montrent

ce qui est accessible dans la classe enfant qui dérive de la classe Exception

intégrée.

</para>

<example>

<title>La classe d'exception intégrée</title>

<programlisting role="php">

<![CDATA[

<?php

class Exception implements Throwable

{

protected $message = 'Unknown exception'; // Message d'exception

private $string; // cache de __toString

protected $code = 0; // code d'exception défini par l'utilisateur

protected $file; // nom de fichier source de l'exception

protected $line; // ligne source de l'exception

private $trace; // trace de la pile d'exécution

private $previous; // exception précédente si exception imbriquée

public function __construct($message = '', $code = 0, ?Throwable $previous = null);

final private function __clone(); // Inhibe la duplication des exceptions.

final public function getMessage(); // message de l'exception

final public function getCode(); // code de l'exception

final public function getFile(); // nom du fichier source

final public function getLine(); // ligne source

final public function getTrace(); // tableau de la trace de la pile d'exécution

final public function getPrevious(); // l'exception précédente

final public function getTraceAsString(); // trace sous forme de chaîne de caractères

// Peut être redéfinie

public function __toString(); // chaîne formatée pour l'affichage

}

?>

]]>

</programlisting>

</example>

<para>

Si une classe étend la classe Exception intégrée et redéfinit le <link

linkend="language.oop5.decon">constructeur</link>, il est fortement recommandé

qu'elle appelle également <link

linkend="language.oop5.paamayim-nekudotayim">parent::__construct()</link>

pour s'assurer que toutes les données disponibles ont été correctement assignées.

La méthode <link linkend="language.oop5.magic">__toString()</link> peut être

redéfinie pour fournir une sortie personnalisée lorsque l'objet est présenté

sous forme de chaîne de caractères.

</para>

<note>

<para>

Les exceptions ne peuvent pas être clonées. Tenter de <link

linkend="language.oop5.cloning">cloner</link> une Exception entraînera une

erreur fatale <constant>E_ERROR</constant>.

</para>

</note>

<example>

<title>Étendre la classe Exception</title>

<programlisting role="php">

<![CDATA[

<?php

/**

* Définit une classe d'exception personnalisée.

*/

class MyException extends Exception

{

// Redéfinit l'exception pour que le message ne soit pas facultatif.

public function __construct($message, $code = 0, ?Throwable $previous = null) {

// du code

// s'assurer que tout est correctement assigné

parent::__construct($message, $code, $previous);

}

// Représentation personnalisée de l'objet sous forme de chaîne de caractères.

public function __toString() {

return __CLASS__ . ": [{$this->code}]: {$this->message}\n";

}

public function customFunction() {

echo "Une fonction personnalisée pour ce type d'exception\n";

}

}

/**

* Créer une classe pour tester l'exception

*/

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:

// Lance une exception personnalisée

throw new MyException('1 n\'est pas un paramètre valide', 5);

break;

case self::THROW_DEFAULT:

// Lance celle par défaut.

throw new Exception('2 n\'est pas autorisé comme paramètre', 6);

break;

default:

// Aucune exception, l'objet sera créé.

$this->var = $avalue;

break;

}

}

}

// Exemple 1

try {

$o = new TestException(TestException::THROW_CUSTOM);

} catch (MyException $e) { // Sera capturée

echo "MyException capturée\n", $e;

$e->customFunction();

} catch (Exception $e) { // Ignoré

echo "Exception par défaut capturée\n", $e;

}

// Poursuite de l'exécution

var_dump($o); // Null

echo "\n\n";

// Exemple 2

try {

$o = new TestException(TestException::THROW_DEFAULT);

} catch (MyException $e) { // Ne correspond pas à ce type

echo "MyException capturée\n", $e;

$e->customFunction();

} catch (Exception $e) { // Sera capturée

echo "Exception par défaut capturée\n", $e;

}

// Poursuite de l'exécution

var_dump($o); // Null

echo "\n\n";

// Exemple 3

try {

$o = new TestException(TestException::THROW_CUSTOM);

} catch (Exception $e) { // Sera capturée

echo "Exception par défaut capturée\n", $e;

}

// Poursuite de l'exécution

var_dump($o); // Null

echo "\n\n";

// Exemple 4

try {

$o = new TestException();

} catch (Exception $e) { // Sauté, aucune exception

echo "Exception par défaut capturée\n", $e;

}

// Poursuite de l'exécution

var_dump($o); // TestException

echo "\n\n";

?>

]]>

</programlisting>

</example>

</sect1>

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

-->