Introduction

Introduction – Comment utiliser la classe PEAR de base (destructeurs, gestion d'erreurs)

Synopsis

require_once "PEAR.php";
class classname extends PEAR { ... }

Description

La classe PEAR de base fournit des fonctions standards qui sont utilisées par la plupart des classes PEAR. Normalement vous ne créez jamais une instance de la classe PEAR directement, vous l'utilisez en créant des classes héritant de la classe PEAR.

Ses fonctions principales sont :

  • appel de "destructeurs" de l'objet (request-shutdown object "destructors")

  • gestion d'erreur

"Destructeurs" PEAR

Si une classe ClassName hérite de la classe PEAR, vous pouvez définir une méthode appelée _ClassName (le nom de la classe avec un underscore devant) qui sera appelée à la fin de la requête. Ce n'est pas un destructeur dans le sens où vous pouvez "détruire" l'objet et où le destructeur soit appelé, mais dans le sens où PHP offre un "callback" dans l'objet lorsque PHP finit son éxécution. Voir l'exemple ci-dessous.

Important !

Pour que les destructeurs fonctionnent correctement, vous devez instancier la classe avec l'opérateur "=& new" comme ceci :

<?php
$obj 
=& new MyClass();
?>

Si vous utilisez simplement "= new", l'objet enregistré dans la liste de fin d'execution de PEAR sera une copie de l'objet au moment de la construction de l'objet, et le destructeur sera appliqué à cette copie au moment de la fin d'éxécution.

Gestion d'erreur PEAR

La classe de base PEAR définit aussi un moyen de retourner des valeurs d'erreurs plus complexes qu'une simple valeur vrai/faux ou une valeur numérique. Une erreur PEAR est un objet qui est soit une instance de la classe PEAR_Error ou de toute classe héritant de PEAR_Error.

L'un des critères retenus pour la classe d'erreur de PEAR est qu'elle ne doit pas imposer un type de sortie particulier pour l'utilisateur et qu'il doit être possible de gérer les erreurs sans aucune sortie si cela est désiré. Cela permet de gérer les erreurs de manière plus "élégante", même lorsque le format de sortie est différent du HTML (par exemple WML, ou d'autres formats XML).

Lors de sa création, l'objet erreur peut être configuré pour réaliser un certain nombre de choses comme l'affichage d'un message d'erreur, l'affichage du message et l'arrêt de l'éxécution, le déclenchement d'une erreur par l'appel de la fonction PHP trigger_error(), l'appel d'une fonction de callback ou bien aucune de ces actions. Ces actions sont définies dans le constructeur de la classe PEAR_Error, mais tous les paramètres sont optionnels, et vous pouvez configurer le comportement par défaut des erreurs générées par chaque objet basé sur la classe PEAR. Voir les exemples de PEAR error pour la façon d'utiliser ces mécanismes d'erreurs et la documentation de la classe PEAR_Error pour tous les détails.

Exemples

L'exemple ci-dessous montre comment utiliser "la pauvre émulation de destructeur" de PEAR pour implémenter une simple classe qui contient le contenu d'un fichier, vous permet d'ajouter des données à l'objet et de les écrire dans ce fichier à la fin de la requête :

PEAR: destructeurs émulés

<?php
require_once "PEAR.php";

class 
FileContainer extends PEAR
{
    var 
$file '';
    var 
$contents '';
    var 
$modified 0;

    function 
FileContainer($file)
    {
        
$this->PEAR(); // Appel du constructeur de la classe parent
        
$fp fopen($file"r");
        if (!
is_resource($fp)) {
            return;
        }
        
$this->file $file;
        while (
$data fread($fp2048)) {
            
$this->contents .= $data;
        }
        
fclose($fp);
    }

    function 
append($str)
    {
        
$this->contents .= $str;
        
$this->modified++;
    }

    
// Le "destructeur" est nomm&eacute; comme le constructeur
    // mais avec un underscore devant.
    
function _FileContainer()
    {
        if (
$this->modified) {
            
$fp fopen($this->file"w");
            if (!
is_resource($fp)) {
                return;
            }
            
fwrite($fp$this->contents);
            
fclose($fp);
        }
    }
}

$fileobj =& new FileContainer("testfile");
$fileobj->append("Cela se trouvera &agrave; la fin du fichier\n");

// Lorsque la requ&ecirc;te sera termin&eacute;e et que PHP finira son &eacute;x&eacute;cution,
// le "destructeur" de $fileobj sera appel&eacute; et mettra &agrave; jour le fichier
// sur le disque.
?>

Les "destructeurs" PEAR utilisent les fonctions 'callback' (register_shutdown_function()) de fin d'éxécution de PHP, et dans PHP < 4.1, vous ne pouvez rien envoyer à la sortie standard lorsque PHP tourne dans un serveur Web. Ainsi tout ce qui est affiché dans le "destructeur" est perdu à moins que PHP soit utilisé en mode ligne de commande. Avec PHP 4.1 et supérieur, les sorties peuvent être générées par le destructeur.

Voir aussi l'avertissement au sujet de la façon d'instancier les objets si vous voulez utiliser le destructeur.

Les exemples suivants illustrent les différentes façons d'utiliser les mécanismes de gestion d'erreurs de PEAR.

Exemple de gestion d'erreur PEAR (1)

<?php
function mysockopen($host "localhost"$port 8090)
{
    
$fp fsockopen($host$port$errno$errstr);
    if (!
is_resource($fp)) {
        return new 
PEAR_Error($errstr$errno);
    }
    return 
$fp;
}

$sock mysockopen();
if (
PEAR::isError($sock)) {
    print 
"mysockopen error: ".$sock->getMessage()."<br />\n"
}
?>

Cet exemple montre une émulation de la fonction fsockopen() qui offre, comme valeur de retour, un objet PEAR contenant le message ou code d'erreur de retour de la fonction fsockopen() (s'il y a lieu) . Notez que PEAR::isError() est utilisé pour déterminer si le code de retour est un objet PEAR error.

Le mode d'opération de PEAR_Error dans cet exemple est simplement de retourner l'objet d'erreur et laisse à l'utilisateur (le programmeur) le travail de traitement. C'est le mode par défaut.

L'exemple suivant montre comment utiliser les modes d'erreur par défaut :

Exemple de gestion d'erreur PEAR (2)

<?php
class TCP_Socket extends PEAR
{
    var 
$sock;

    function 
TCP_Socket()
    {
        
$this->PEAR();
    }

    function 
connect($host$port)
    {
        
$sock fsockopen($host$port$errno$errstr);
        if (!
is_resource($sock)) {
            return 
$this->raiseError($errstr$errno);
        }
    }
}

$sock = new TCP_Socket;
$sock->setErrorHandling(PEAR_ERROR_DIE);
$sock->connect("localhost"8090);
echo 
"Encore active<br />\n";
?>

Ici nous fixons le mode par défaut à PEAR_ERROR_DIE, et puisque nous n'indiquons pas de mode d'erreur dans l'appel à raiseError (cela serait le troisième paramètre), raiseError utilise le mode par défaut et termine l'éxécution lorsque fsockopen génère une erreur.

Variables Globales Utilisées

La classe PEAR utilise quelques variables globales pour enregistrer les valeurs globales par défaut et une liste des objets utilisés par les "destructeurs". Toutes les variables globales associées à la classe PEAR ont un nom commençant par _PEAR_.

$_PEAR_default_error_mode

Si aucun mode par défaut n'est fixé dans un objet, ce mode est utilisé. Cela doit être une des valeurs suivantes : PEAR_ERROR_RETURN, PEAR_ERROR_PRINT, PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE or PEAR_ERROR_CALLBACK.

N'assignez pas une valeur à cette variable directement, utilisez la fonction PEAR::setErrorHandling() comme une méthode statique de la façon suivante :

<?php          
PEAR
::setErrorHandling(PEAR_ERROR_DIE);
?>

$_PEAR_default_error_options

Si le mode d'erreur est PEAR_ERROR_TRIGGER, alors il s'agit du niveau de l'erreur ( soit E_USER_NOTICE, E_USER_WARNING ou E_USER_ERROR).

N'assignez pas une valeur à cette variable directement, utilisez la fonction PEAR::setErrorHandling() comme une méthode statique de la façon suivante :

<?php
PEAR
::setErrorHandling(PEAR_ERROR_TRIGGERE_USER_ERROR);
?>

$_PEAR_default_error_callback

Si aucun paramètre options n'est utilisé lorsqu'une erreur survient et que le mode d'erreur est PEAR_ERROR_CALLBACK, la valeur de cette variable est utilisée comme le callback. Cela signifie que vous pouvez changer le mode d'erreur temporairement et retourner au mode callback sans avoir à re-spécifier la fonction de callback. Une chaîne de caractères représente une fonction, un tableau à deux éléments avec un objet à l'index 0 et une chaîne de caractère à l'index 1 représente une méthode.

Là encore, n'assignez pas une valeur à cette variable directement, utilisez la fonction PEAR::setErrorHandling() comme une méthode statique de la façon suivante :

<?php
PEAR
::setErrorHandling(PEAR_ERROR_CALLBACK"my_error_handler");
?>

Voici un exemple sur la façon de changer de mode et revenir au mode initial sans avoir à spécifier à nouveau la fonction de callback :

<?php
PEAR
::setErrorHandling(PEAR_ERROR_CALLBACK"my_function_handler");
do_some_stuff();
PEAR::setErrorHandling(PEAR_ERROR_DIE);
do_some_critical_stuff();
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK);
// ici nous r&eacute;utilisons de nouveau my_function_handler
?>

PEAR (Previous) Constantes prédéfinies (Next)
Last updated: Sun, 29 Aug 2010 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.