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.
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 :
<?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($fp, 2048)) {
$this->contents .= $data;
}
fclose($fp);
}
function append($str)
{
$this->contents .= $str;
$this->modified++;
}
// Le "destructeur" est nommé 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 à la fin du fichier\n");
// Lorsque la requête sera terminée et que PHP finira son éxécution,
// le "destructeur" de $fileobj sera appelé et mettra à jour le fichier
// sur le disque.
?>
Note :
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.
<?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 :
<?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 :
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 :
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éutilisons de nouveau my_function_handler
?>
