L'antisèche des exceptions PHP

Publié le 02/10/2021 • Actualisé le 02/10/2021

Cet article est un peu différent de ce que j'ai l'habitude de faire. C'est une référence, une antisèche présentant les erreurs et exceptions disponibles en PHP. C'est parti ! 😎


English language detected! 🇬🇧

  We noticed that your browser is using English. Do you want to read this post in this language?

Read the english version 🇬🇧 Close

Prérequis

Je présumerai que vous avez au moins des connaissances de base de PHP.

Configuration

L'article suivant est basé sur PHP 7.4, mais il y a peu de différences avec PHP 8.

Introduction

Parfois, quand je code, je ne suis pas toujours sûr de la "meilleure" exception à utiliser. Aussi, comme je n'ai pas une mémoire exceptionnelle, je dois toujours fouiller dans la documentation ou sur le web. C'est pourquoi je voulais avoir une page de référence regroupant tout pour que je puisse trouver rapidement ce que je recherche.

But

Le but est de présenter toutes les erreurs et exceptions de deux manières différentes. Dans un premier temps, je les afficherai sous forme d'arbres. Puis, je les afficherai sous forme de tableaux de manière plus propre et plus complète.

Les arbres

Tout d'abord, voyons un arbre simple hiérarchique donnant une vue globale des erreurs, exceptions et des sous-classes associées :



Cliquez ici pour voir le code permettant de récupérer cet arbre dynamiquement. On doit appeler la fonction printTree().
                                    'fqcn' => \UnderflowException::class,
                                    'doc' => 'https://www.php.net/manual/en/class.underflowexception',
                                    'stackoverflow' => 'https://stackoverflow.com/q/69301995/633864',
                                    'parent' => \RuntimeException::class,
                                    'links' => ['https://airbrake.io/blog/php-exception-handling/underflowexception'],
                                ],
                                \UnexpectedValueException::class => [
                                    'fqcn' => \UnexpectedValueException::class,
                                    'doc' => 'https://www.php.net/manual/en/class.unexpectedvalueexception',
                                    'stackoverflow' => 'https://stackoverflow.com/q/34133049/633864',
                                    'parent' => \RuntimeException::class,
                                    'links' => ['https://airbrake.io/blog/php-exception-handling/unexpectedvalueexception-2'],
                                ],
                            ],
                        ],
                        \SoapFault::class => [
                            'fqcn' => \SoapFault::class,
                            'doc' => 'https://www.php.net/manual/en/soapfault.construct',
                            'stackoverflow' => 'https://stackoverflow.com/q/19612481/633864',
                            'parent' => \Exception::class,
                            'links' => ['https://hotexamples.com/examples/-/SoapFault/-/php-soapfault-class-examples.html'],
                        ],
                        \SodiumException::class => [
                            'fqcn' => \SodiumException::class,
                            'doc' => 'https://www.php.net/manual/en/class.sodiumexception',
                            'stackoverflow' => 'https://stackoverflow.com/q/54587528/633864',
                            'parent' => \Exception::class,
                        ],
                    ],
                ],
            ],
        ],
    ];

    /**
     * @return array<string>
     */
    private function listThrowableClasses(): array
    {
        $result = [];
        if (interface_exists('Throwable')) {
            foreach (get_declared_classes() as $cn) {
                $implements = class_implements($cn);
                if ($implements === false) {
                    continue;
                }

                if (isset($implements['Throwable'])) {
                    $result[] = $cn;
                }
            }
        } else {
            foreach (get_declared_classes() as $cn) {
                if ($cn === 'Exception' || is_subclass_of($cn, 'Exception')) {
                    $result[] = $cn;
                }
            }
        }

        return $result;
    }

    /**
     * @param array<string> $classes
     *
     * @return array<mixed>
     */
    private function groupByParents(array $classes): array
    {
        $result = [];
        foreach ($classes as $cn) {
            $parent = (string) get_parent_class($cn);
            if (isset($result[$parent])) {
                $result[$parent][] = $cn;
            } else {
                $result[$parent] = [$cn];
            }
        }

        return $result;
    }

    /**
     * @return array<mixed>
     */
    public function getExceptionsHierarchy(): array
    {
        $throwables = $this->listThrowableClasses();

        return $this->groupByParents($throwables);
    }

    public function printTree(): void
    {
        $tree = $this->getExceptionsHierarchy();

        // echo '<pre>';
        $this->printLeaves($tree, '', 0);
        // die();
    }

    /**
     * @param array<mixed> $tree
     */
    public function printLeaves(array &$tree, string $parent, int $level): void
    {
        if (isset($tree[$parent])) {
            /** @var array<string> $leaves */
            $leaves = $tree[$parent];
            unset($tree[$parent]);
            natcasesort($leaves);
            $leaves = array_values($leaves);
            foreach ($leaves as $leaf) {
                echo str_repeat('   ', $level), $leaf, "\n";
                $this->printLeaves($tree, $leaf, $level + 1);
            }
        }
    }
}

Vous pouvez trouver les sources originales ici :

Maintenant, voyons l'arbre complet. Cliquez sur les nœuds pour les développer et sur "children" pour voir tous les objets étendant cette classe parente. Les liens vers la documentation, le StackOverflow et les autres sont cliquables. Cliquez ce dessous sur "{1 item}" pour commencer :



Les données

Maintenant, affichons toutes ces informations de manière plus pratique. Depuis PHP 7, toutes les erreurs et exceptions étendent la classe Throwable. Les erreurs sont internes à PHP alors que les exceptions sont pour tous les autres cas.

Throwable

FQCN Description Parent Enfants Liens SO Doc
\Throwable Throwable est l'interface de base pour tout objet qui peut être jeté grâce à la déclaration throw, ceci inclus Error et Exception. - Error, Exception

Erreurs

FQCN Description Parent Enfants Liens SO Doc
\Error Error est la classe de base pour toutes les erreurs internes de PHP. Throwable ArithmeticError, AssertionError, CompileError, TypeError, ValueError, UnhandledMatchError, FiberError -
FQCN Description Parent Enfants Liens SO Doc
\ArithmeticError ArithmeticError est émit quand une erreur se produit lors d'une opération mathématique. Ces erreurs inclus les tentatives de réaliser un bitshift par un montant négatif, n'importe quel appel à intdiv() qui donnerait lieu à une valeur en dehors des bornes possibles d'un entier. Error DivisionByZeroError
FQCN Description Parent Enfants Liens SO Doc
\DivisionByZeroError DivisionByZeroError est émit quand un nombre essaye d'être divisé par zéro. ArithmeticError -
FQCN Description Parent Enfants Liens SO Doc
\AssertionError AssertionError est émit quand une assertion faite avec assert() échoue. Error -
FQCN Description Parent Enfants Liens SO Doc
\CompileError CompileError est émit quand une erreur de compilation se produit, précédemment une erreur fatale était émise. Error ParseError
FQCN Description Parent Enfants Liens SO Doc
\ParseError ParseError est émit quand une erreur se produit lors de l'analyse de code PHP, comme quand eval() est appelé. CompileError -
FQCN Description Parent Enfants Liens SO Doc
\TypeError Il y a trois scénario où une TypeError peut être lancée :
  • Le type de l'argument qui est passé à la fonction ne correspond pas à la déclaration du type du paramètre correspondant.
  • Une valeur qui est retourné par une fonction ne correspond pas au type de retour déclaré par la fonction.
  • Un nombre invalide d'arguments sont fournis à une fonction intégrée de PHP (mode stricte uniquement).
Error ArgumentCountError
FQCN Description Parent Enfants Liens SO Doc
\ArgumentCountError ArgumentCountError est émit quand trop peu d'arguments sont passés à une fonction ou méthode définit par l'utilisateur. TypeError - -
FQCN Description Parent Enfants Liens SO Doc
\ValueError A ValueError is thrown when the type of an argument is correct but the value of it is incorrect. For example, passing a negative integer when the function expects a positive one, or passing an empty string/array when the function expects it to not be empty. Error
FQCN Description Parent Enfants Liens SO Doc
\UnhandledMatchError An UnhandledMatchError is thrown when the subject passed to a match expression is not handled by any arm of the match expression. Error
FQCN Description Parent Enfants Liens SO Doc
\FiberError FiberError is thrown when an invalid operation is performed on a Fiber. Error

Exceptions

FQCN Description Parent Enfants Liens SO Doc
\Exception Exception est la classe de base pour toutes les exceptions utilisateur. Throwable ClosedGeneratorException, DOMException, ErrorException, IntlException, JsonException, LogicException, PharException, ReflectionException, RuntimeException, SoapFault, SodiumException
FQCN Description Parent Enfants Liens SO Doc
\ClosedGeneratorException Un exception ClosedGeneratorException arrive quand on essaie d'itérer sur un générateur qui a déjà été clos ou terminé. Exception - -
FQCN Description Parent Enfants Liens SO Doc
\DOMException Les opérations DOM lancent des exceptions lors de circonstances particulières, i.e., lorsqu'il est impossible d'exécuter une opération pour des raisons logiques. Exception -
FQCN Description Parent Enfants Liens SO Doc
\ErrorException Une exception pour les erreurs. Exception -
FQCN Description Parent Enfants Liens SO Doc
\IntlException Cette classe est utilisée pour générer des exceptions quand des erreurs sont rencontrées lors des appels aux fonctions de l'extension intl. Ces exceptions peuvent donc générées seulement si cette extension est activée. Exception -
FQCN Description Parent Enfants Liens SO Doc
\JsonException Exception émise si l'option JSON_THROW_ON_ERROR est définie pour json_encode() ou json_decode(). code contient le type d'erreur, pour les valeurs possible voir json_last_error(). Exception -
FQCN Description Parent Enfants Liens SO Doc
\LogicException Exception qui représente les erreurs dans la logique du programme. Ce type d'exceptions doit obligatoirement faire l'objet d'une correction de votre code. Exception BadFunctionCallException, DomainException, InvalidArgumentException, LengthException, OutOfRangeException
FQCN Description Parent Enfants Liens SO Doc
\BadFunctionCallException Exception émise si une fonction de rappel n'existe pas ou si certains de ses arguments sont manquants. LogicException BadMethodCallException
FQCN Description Parent Enfants Liens SO Doc
\BadMethodCallException Exception émise si une méthode de rappel n'existe pas ou si certains de ses arguments sont manquants. BadFunctionCallException -
FQCN Description Parent Enfants Liens SO Doc
\DomainException Exception lancée si une valeur n'adhère pas à un domaine de données défini et valide. LogicException -
FQCN Description Parent Enfants Liens SO Doc
\InvalidArgumentException Exception émise si un argument ne correspond pas au type attendu. LogicException -
FQCN Description Parent Enfants Liens SO Doc
\LengthException Exception émise si une taille est invalide. LogicException -
FQCN Description Parent Enfants Liens SO Doc
\OutOfRangeException Exception émise lorsqu'un index illégal est demandé. Elle représente les erreurs qui devraient être détectées au moment de la compilation. LogicException -
FQCN Description Parent Enfants Liens SO Doc
\PharException La classe PharException fournit une classe d'exception spécifique à phar pour les blocs try/catch. Exception -
FQCN Description Parent Enfants Liens SO Doc
\ReflectionException Execptions lancées lors de l'utilisation des fonctions liées à la réflection. Exception -
FQCN Description Parent Enfants Liens SO Doc
\RuntimeException Exception émise quand une erreur est rencontrée durant l'exécution. Exception OutOfBoundsException, OverflowException, PDOException, RangeException, UnderflowException, UnexpectedValueException
FQCN Description Parent Enfants Liens SO Doc
\OutOfBoundsException Exception émise quand une valeur n'est pas une clé valide. Elle représente les erreurs qui ne peuvent pas être détectées au moment de la compilation. RuntimeException -
FQCN Description Parent Enfants Liens SO Doc
\OverflowException Exception émise lors de l'ajout d'un élément à un conteneur plein. RuntimeException -
FQCN Description Parent Enfants Liens SO Doc
\PDOException Représente une erreur émise par PDO. Vous ne devez pas lancer une exception PDOException depuis votre propre code. Voir le chapitre sur les exceptions pour plus d'informations concernant les exceptions en PHP. RuntimeException -
FQCN Description Parent Enfants Liens SO Doc
\RangeException Exception émise pour indiquer des erreurs d'intervalle lors de l'exécution du programme. Normalement, cela signifie qu'il y a une erreur arithmétique autre qu'un débordement. C'est l'équivalent en cours d'exécution de DomainException. RuntimeException -
FQCN Description Parent Enfants Liens SO Doc
\UnderflowException Exception émise lorsqu'une opération invalide est effectuée sur un conteneur vide, tel qu'une suppression d'élément. RuntimeException -
FQCN Description Parent Enfants Liens SO Doc
\UnexpectedValueException Exception émise si une valeur ne fait pas partie d'une liste de valeurs. Typiquement, elle survient lorsqu'une fonction appelle une autre fonction et attend que la valeur retournée soit d'un certain type ou d'une certaine valeur, sans inclure les erreurs relatives à l'arithmétique ou au buffer. RuntimeException -
FQCN Description Parent Enfants Liens SO Doc
\SoapFault SoapFault sert à envoyer des erreurs SOAP depuis le PHP.faultcode, faultstring, faultactor et detail sont les éléments standards SOAP. Exception -
FQCN Description Parent Enfants Liens SO Doc
\SodiumException Exception lancée par les fonctions sodium. Exception - -

Comme c'est une référence, je mettrai à jour cette page au fur et à mesure que je trouverai des exemples ou explications à y ajouter.

Conclusion

Les exceptions ne sont pas si faciles à utiliser. Il est parfois difficile de choisir la bonne. Mais, avec la pratique, il devient de moins en moins difficile de faire le bon choix selon le cas d'utilisation. J'espère que cette anti-sèche vous aidera à faire les bons choix et vous donnera une meilleure compréhension de toutes les erreurs et exceptions PHP.

Et voilà ! J'espère que vous avez aimé. Découvrez d'autres informations en rapport à cet article avec les liens ci-dessous. Comme toujours, retours, likes et retweets sont les bienvenus. (voir la boîte ci-dessous) À tantôt ! COil. 😊

  Lire la doc  Plus sur le web  Plus sur Stackoverflow

  Travaillez avec moi !


A vous de jouer !

Ces articles vous ont été utiles ? Vous pouvez m'aider à votre tour de plusieurs manières : (cf le tweet à droite pour me contacter )

  • Me remonter des erreurs ou typos.
  • Me remonter des choses qui pourraient être améliorées.
  • Aimez et retweetez !
  • Suivez moi sur Twitter
  • Inscrivez-vous au flux RSS.
  • Cliquez sur les boutons Plus sur Stackoverflow pour me faire gagner des badges "annonceur" 🏅.

Merci d'avoir tenu jusque ici et à très bientôt sur Strangebuzz ! 😉

COil