Les exceptions de premier niveau

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

La version 2.28 apporte une nouvelle gestion des exceptions et erreurs de premier niveau,

Après quelques balbutiements en version 2.27, une première avancée dans la gestion et la reconnaissance plus fine des erreurs bloquantes de l'application est introduite en version 2.28. Avec l'ajout d'une classe spéciale au gestionnaire d'erreur PHP, la majorité des erreurs générées par la racine de l'application ou de son cœur est désormais interceptée par des classes d'exception renvoyant un code et un message unique. Tous ces codes et messages sont regroupés dans un énumérateur. Les exceptions sont si possible traitées suivant différents paramètres (mode debug, mode CLI...) puis renvoyées à l'utilisateur.

Fault class in debug mode

Liste d'erreurs :

susceptible de changer dans les versions à venir

503 : AppException : Site temporarily unavailable
400 : BadRequestException : Bad Request
570 : BlogException : Blog handling error
551 : ConfigException : Application configuration error
409 : ConflictException : Conflict
553 : ContextException : Application context error
560 : DatabaseException : Database connection error
404 : NotFoundException : Not Found
412 : PreconditionException : Precondition Failed
552 : ProcessException : Application process error
561 : SessionException : Session handling error
571 : TemplateException : Template handling error
401 : UnauthorizedException : Unauthorized
500 : InternalServerException : Internal Server Error

Deux grandes catégories sont présentes avec :

4xx : Erreur client
5xx : Erreur serveur

Traitement

Les exceptions et erreurs interceptées par l'application sont alors envoyées à la classe Fault pour traitement et affichage à l'utilisateur. Il est possible d'intervenir avant l'affichage en définissant dans la constante DC_ERRORFILE un fichier à appeler, ce fichier php aura accès à toute la classe Fault.
Si la plateforme à déjà déclaré un gestionnaire d'exception à PHP, il sera alors utilisé.

Incompatibilité

Les méthodes de la classe Fault introduites en version 2.27 sont déjà obsolètes et tout simplement supprimées.

Le contenu de ce document a été écrit suivant le code de la version 2.28 de Dotclear.

La classe d'erreur

Jean-Christian Denis — Fri, 14 Jul 2023 09:11:00 +0100

Dotclear version 2.27 introduit une classe d'erreur nommée Fault en remplacement de la fonction __error() et du fichier error.php.

La classe Dotclear\Fault n'est pas à proprement parler un gestionnaire d'erreur, elle ne se substitue pas aux Exception et Error. Elle va simplement permettre à l'application d'uniformiser son comportement sur certains défauts (erreurs) connus. Normalement seules la classe Dotclear\App et les classes Dotclear\Core\Xxx\Utility l'utilisent. Elle est utilisée lors de défauts ne permettant pas de continuer la bonne exécution du script.

Constantes

La classe définit des constantes de niveau d'erreur, ces niveaux seront reportés en code de réponse HTTP le cas échéant, et sont toutes de niveau supérieur à 500 (Internal server error).

550 : UNDEFINED_ISSUE : Uncoded or undefined error (before as 0)
555 : SETUP_ISSUE : Server configuration issue (before as 0)
560 : CONFIG_ISSUE : Dotclear configuration file issue (before as 10)
565 : DATABASE_ISSUE :Database connexion issue (before as 20)
570 : BLOG_ISSUE : Blog definition issue (before as 30)
575 : TEMPLATE_CREATION_ISSUE : Template file creation issue (before as 40)
580 : THEME_ISSUE : Theme issue (before as 50)
585 : TEMPLATE_PROCESSING_ISSUE : Template processing issue (before as 60)
590 : BLOG_OFFLINE : Blog is offline (before as 70)

Lancement

Il y a deux façons lancer un défaut, par la création d'une instance en passant en arguments le titre, le message et le niveau, ou de manière statique en passant en arguments le titre et l'exception.

<?php
use Dotclear\Fault;

// Dynamique
if (!defined('DC_CONTEXT_ADMIN')) {
    new Fault('Server error', 'Site temporarily unavailable', Fault::SETUP_ISSUE);
}
// Statique
try {
    if ($a < 1) {
        throw new Exception('a est inferieur à 1', Fault::CONFIG_ISSUE);
    }
    if ($a > 10) {
        throw new Exception('a est supérieur à 10', Fault::CONFIG_ISSUE);
    }
 } catch (Exception $e) {
    Fault::throw('Mauvaise valeur de a', $e);
 }

Retour

La classe permet plusieurs façons de reporter le défaut.

Si le script est exécuté en mode CLI (ligne de commande) comme pour une mise à jour depuis une console, la classe répondra par un simple message dans la console.
Si le script est exécuté normalement, une page web indiquant le niveau d'erreur, son titre et un message explicatif sera retourné avec en code de réponse HTTP le niveau d'erreur.
Si au moment du lancement de la classe la constante DC_DEBUG est déjà définie et est à true, l'erreur php sera retournée, comme si la classe n'existait pas.

Personnalisation

Il est possible de personnaliser la page web de défaut. Pour cela il faut renseigner la constante DC_ERRORFILE en la définissant avec le chemin complet vers un fichier qui sera inclu dans la méthode retournant le défaut. Ce fichier devra rendre à la sortie standard de PHP (echo) du code HTML complet et valide. Les variables $summary, $message et $code lui sont accessibles.

Reponse HTML de la classe Fault

Le contenu de ce document a été écrit suivant le code de la version 2.27 de Dotclear.

DotclearWatch / Blog - Mot-clé - error