PHP met à notre disposition une constante très pratique : DIRECTORY_SEPARATOR. Hélas, c'est bien long à taper. Comme un bon programmeur est un programmeur fainéant, on a créé un alias vers cette constante : DS ; de cette façon :

define('DS', DIRECTORY_SEPARATOR);

On insiste sur le fait que cette constante n'est qu'un alias.

PHP propose cette constante car les séparateurs de dossiers diffèrent selon les systèmes sur lesquels on travaille.

Il faut s'imaginer une arborescence comme un arbre, où chaque branche donne lieu sur de nouvelles branches, à travers des nœuds, jusqu'à atteindre les feuilles. Comme le caractère symbolisant un nœud est différent selon le système, il est nécessaire d'utiliser cette constante, cela assure la portabilité du projet.

Ainsi, un chemin s'écrira de la façon suivante :

$chemin  = 'dossierA' . DS . 'dossierB' . DS . 'dossierC';
$fichier = $chemin . DS . 'monFichier.php';

De la même manière, il est nécessaire d'avoir une constante symbolisant les chemins ; caractère lui aussi différent selon les systèmes.

PHP propose la constante PATH_SEPARATOR. Pour les mêmes raisons que sa jumelle, on a défini un alias :

define('PS', PATH_SEPARATOR);

Cette constante est également à utiliser à chaque fois que l'on veut utiliser un séparateur de chemins.

Ainsi, si l'on reprend l'exemple de la section intitulée « Modifier les chemins d'inclusion » et que l'on veut y ajouter un autre chemin plus loin dans le script, la constante PS sera définie, alors :

set_include_path('./Autre_Chemin' . PS .
                 get_include_path());

Un fichier non vide contient généralement des lignes. Ces lignes ont un début et une fin. La fin d'une ligne peut être déduite en fonction de sa longueur, ou alors à partir d'une suite de symboles.

On a pour habitude de définir la fin de ligne à partir du symbole appelé CRLF. Le CRLF est un caractère spécial^[4]. Ce n'est pas un caractère ASCII, mais l'association de 2 caractères : 13 et 10, respectivement pour \r et \n. Le \r correspond au retour chariot^[5], et le \n correspond à la fin de la ligne.

Mais comme beaucoup de paramètres, celui-ci dépend du système sur lequel on travaille. En effet, sur Unix, on utilise plutôt LF, sous Mac OS, CR, et sous Windows, CRLF. D'où l'importance d'introduire une constante. Cette constante aurait très bien pu s'appeler EOL, on l'accorde, mais on a préféré être générique est l'appeler CRLF pour éviter les confusions avec EOF etc.

Il est possible de la rédéfinir en cas de besoin. Pour cela, il faut ouvrir le fichier Framework.php, et modifier sa valeur. Elle a été initialisée à \r\n :

define('CRLF', "\r\n");

On a parfois besoin de savoir où se trouve le framework. On met donc à disposition la constante FW_BASE qui vaut la valeur du dossier de la constante magique __FILE__. Cette constante retourne le chemin complet et le nom du fichier courant. On travaille avec une version 5 de PHP, __FILE__ retourne donc un chemin absolu (ce qui n'était pas le cas des versions inférieures à 4.0.2). On se débarasse du nom du fichier à l'aide de la fonction dirname :

define('FW_BASE', dirname(__FILE__));

Toutes les commandes du terminal, ou les fonctions de PHP ne sont pas accessibles selon le système sur lequel on travaille. Certains systèmes sont très différents des autres. Il est donc bon de savoir si on se trouve notamment sur Windows^[6]. C'est le but de la constante OS_WIN qui vaut true si le système opérateur est Windows, false sinon :

define('OS_WIN', !strncasecmp(PHP_OS, 'win', 3));

Ainsi, on aura quelque chose de similaire :

if(true === OS_WIN) {
 
    // Une action propre à Windows.
}
else {
 
    // L'équivalence pour tous les
    // autres systèmes.
}

Hoa_Framework propose une fonction pratique qui permet de ne pas se poser de questions quant à l'existence d'une constante.

On peut lire le manuel sur la forme des constantes pour mémoire. On se rappelle que la forme des constantes peut avoir pour expression régulière :

[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*

Quand on veut déclarer une constante, il suffit d'invoquer la fonction _define. La fonction teste si la constante est préalablement définie ; si oui, alors on retourne false, sinon on la définit avec un nom, une valeur et une insensibilité de casse. Elle a un comportement strictement identique à la fonction define de PHP lors de la définition (à une insensibilité de casse près).

Ainsi, toutes les constantes peuvent être déclarées de la façon suivante :

_define('BONJOUR', 'Bonjour tout le monde !');

Dans ce cas, l'appel de BONJOUR retournera la chaîne Bonjour tout le monde !, et l'appel de Bonjour ne retournera rien, mais soulèvera une erreur. En effet, l'insensibilité de casse est mise à faux par défaut, i.e. la casse est sensible, elle doit être identique. Si on veut que la casse soit insensible, alors il faut déclarer :

_define('BoNjOur', 'Re-bonjour tout le monde !', true);

Alors, appeller BONJOUR, Bonjour etc. retournera la chaîne Re-bonjour tout le monde !.

PHP propose quatre fonctions qui permettent d'inclure ou de réquisitionner un fichier.

require et include sont identiques à une gestion d'erreur près. En effet, require génère une erreur fatale contrairement à include qui ne génère qu'une alerte. Si une erreur intervient pendant le déroulement de l'application, require arrêtera son exécution, alors qu'include affichera seulement une erreur, et l'application continuera son exécution.

Ces mêmes fonctions existent suffixées de _once. Cela signifie que si un fichier a déjà été chargé, alors il ne le sera pas à nouveau. Cette fonctionnalité est très pratique, mais elle consomme de la mémoire. Hoa_Framework se propose donc de palier ce problème de mémoire en tenant lui-même un historique des inclusions.

Pour inclure ou réquisitionner un fichier, on travaille avec l'aide de la fonction import (qui utilise require, important pour le type d'alerte).

Plusieurs choses sont à noter. La plus importante est l'écriture des chemins. Dans la section intitulée « Paquetage », on voit comment écrire le nom d'un paquetage. L'importation de ce dernier se fait de façon tout à fait naturelle en remplaçant les traits de soulignement par des points, et en supprimant la racine Hoa. Ainsi Hoa_Controller_Dispatcher_Abstract devient le chemin Controller.Dispatcher.Abstract. Par exemple :

<?php
 
/**
 * Commentaires sur le paquetage
 */
 
/**
 * Hoa_Framework
 */
require_once 'Framework.php';
 
/**
 * Hoa_Controller_Dispatcher_Abstract
 */
import('Controller.Dispatcher.Abstract');
 
/**
 * Hoa_Autre_Paquetage
 */
import('Autre.Paquetage');

Ce comportement peut rappeler les importations de Java, mais la fonction import de Hoa apporte des petites choses supplémentaires.

Seulement pour information, la fonction import est en réalité un alias vers la méthode statique Hoa_Framework::import. On a créé cet alias, car il est plus rapide et agréable de n'écrire qu'import.

Il arrive qu'on ait besoin de tous les fichiers d'un paquetage. Si ce dernier comporte plus de 10 fichiers, ce sera long et pénible de tous les écrire. On utilise alors le caractère étoile pour dire : tous. Ainsi Filter.* va inclure Filter.Alpha, Filter.AlphaNumeric, Filter.Array, Filter.Blank, etc. Il ne faut pas en abuser ; il est préférable d'inclure strictement les paquetages dont nous avons besoin. En général, un paquetage règle ses dépendances seul, i.e. il importe les paquetages et fichiers dont il a besoin pour fonctionner. Néanmoins, cette fonctionnalité peut s'avérer pratique.

/**
 * On appelle tous les fichiers du paquetage "Paquetage".
 */
import('Paquetage.*');

On précise — même si c'est un intuitif — que l'étoile ne peut être que la dernière partie du chemin, sinon, cela n'aurait pas de sens.

Il y a aussi l'auto-complétion des chemins. Il arrive qu'un paquetage s'appelant A comporte une seule classe A, ou alors la classe d'entrée s'appelle A (en effet, les classes d'entrée des paquetages comportent le même nom que le paquetage). Il est donc lassant d'écrire UnLongNomPourUnPaquetage.UnLongNomPourUnPaquetage, on préférera écrire UnLongNomPourUnPaquetage.~. Le tilde signifie que le nom du fichier est le même que le nom du paquetage, par exemple : Translate.~, équivaut à Translate.Translate (soit Translate/Translate.php).

/**
 * On appelle le fichier "Paquetage" du paquetage "Paquetage".
 */
import('Paquetage.~');

Le tilde prend tout son sens uniquement pour la dernière partie du chemin. Si on place le tilde avant la dernière partie, il n'aura aucun effet à part produire une erreur. On l'utilise principalement pour faciliter l'appel aux classes d'entrée.

PHP propose une fonction utilisateur qui permet la gestion des exceptions. Hoa s'en sert pour rediriger toutes les exceptions non capturées vers Hoa_Exception::handler.

De ce fait, les exceptions non capturées seront toujours attrapées et — par défaut — affichées. On précise que c'est par défaut, car les exceptions sont transformées en messages, qui peuvent être retournés, affichés, être lancés avec la fonction trigger_error, ou être tués avec exit.

Chaque paquetage contient au moins une exception qui est étendue à l'exception mère Hoa_Exception. Par exemple, le nom de l'exception du paquetage Mail est Hoa_Mail_Exception.

On sait alors d'où vient l'exception, et on peut tracer son parcours. On peut également créer des exceptions personnalisées, les faire dévier etc. La gestion des exceptions est très libre et souple.

La construction des exceptions est un peu particulière dans Hoa, elle ajoute des petites fonctionnalités.

Une exception est constituée tout d'abord d'un message, qui est le premier argument. Ce message sera formaté, il peut donc contenir tous les caractères de formatage de texte. La liste des options de formatages se trouve sur la description de la fonction sprintf. Hoa n'utilise pas sprintf pour formater le texte, mais vsprintf, qui formate une chaîne à partir d'un tableau. Le tableau est passé en troisième argument de l'exception ; on y reviendra.

Le second argument est le code de l'exception, il est écrit arbitrairement. On a pris pour habitude d'incrémenter les exceptions à l'intérieur d'une classe, de cette manière, une exception est identifiée par son nom, et un code.

On revient sur le tableau contenant la liste des valeurs pour formater le message de l'exception. Si on passe une chaîne, elle sera transtypée en tableau, sinon on passe un tableau uni-dimensionnel. Le troisième paramètre est optionnel. Par exemple :

/**
 * On définit notre propre exception.
 */
class MonException extends Hoa_Exception { }
 
/**
 * On jette une exception toute simple.
 */
throw new MonException('Attention, une exception, ' .
                       'derrière vous !',
                       0);
 
/**
 * On jette une exception avec un message formaté simple.
 */
throw new MonException('%s le crabe.',
                       1,
                       'Billy');
 
/**
 * On jette une exception avec un message formaté.
 */
throw new MonException('La somme de 1 à %d donne %d, ' .
                       '%2$d étant un nombre d\'Armstrong, ' .
                       'et %1$d étant un nombre premier.',
                       2,
                       array(17, 153));
// Le message sera (sans les retours à la ligne) :
//   La somme de 1 à 17 donne 153,
//   153 étant un nombre d'Armstrong,
//   et 17 étant un nombre premier.
 
/**
 * On jette une exception courante.
 */
throw new MonException('Le fichier %s n\'existe pas.',
                       3,
                       $nomDuFichier);

Une fois une exception construite et lancée, on se doit de la capturer :

try {
 
    // Code qui jette une exception.
}
catch ( Hoa_Exception $e ) {
 
    // On l'a capturée.
}

Une fois l'exception capturée, on peut lui appliquer plusieurs méthodes pour obtenir différents renseignements.

try {
 
    // Code qui jette une exception.
}
catch ( Hoa_Exception $e ) {
 
    echo $e;
}

try {
 
    // Code qui jette une exception.
}
catch ( Hoa_Exception $e ) {
 
    // Le message sera affiché.
    $e->raiseError();
}

try {
 
    // Code qui jette une exception.
}
catch ( Hoa_Exception $e ) {
 
    // Fin d'exécution après l'affichage
    // du message.
    $e->raiseError(Hoa_Exception::ERROR_DIE);
}

try {
 
    // Code qui jette une exception.
}
catch ( Hoa_Exception $e ) {
 
    // Une erreur utilisateur de
    // type notice.
    $e->raiseError(Hoa_Exception::ERROR_TRIGGER,
                   E_USER_NOTICE);
}