On a trouvé très pratique, par la suite, de grouper les commandes. C'est à dire qu'un groupe contient plusieurs commandes qui agissent dans un même but. On peut prendre pour exemple le groupe Controller qui contient des commandes d'aide à la création, suppression, déplacement (ou renommage) etc. de contrôleurs d'application (dans une logique MVC, voir Chapitre 12, Hoa_Controller).

L'avantage est que l'on peut voir un groupe comme un module. Ainsi, on peut déplacer ce groupe dans un autre environnement, et — si les conventions de nommages sont les mêmes — on pourra les utiliser.

Les groupes sont donc simplement des dossiers. Le groupe par défaut est Main, c'est à dire que si aucun groupe n'est précise dans la ligne de commande, ce sera ce groupe qui sera appelé. Bien entendu, il va de soit que ce groupe par défaut est paramétrable, tout comme le nom et la forme de tous les groupes.

Une commande est un script, elle va effectuer une action précise. Les commandes appartiennent à des groupes de commandes.

Une commande est un fichier PHP, et contient une classe. En effet, toutes les commandes sont des classes.

Chaque classe doit étendre la classe Hoa_Console_Commande_Abstract qui est le seul lien avec le framework. C'est à travers cette classe que l'on a accès à des raccourcis pour les outils. Si la commande n'étend pas cette classe, une exception Hoa_Console_Exception sera levée.

Comme en C, c'est la méthode main qui sera automatiquement appelée. Toutefois, cette méthode est d'arité nulle, c'est à dire qu'elle ne prend aucun argument.

Par défaut, le nom des fichiers qui contiennent les commandes est tout simplement le nom de la commande avec la première lettre en majuscule, et le nom de classe est le nom de la commande suivi par Command. Ainsi, la commande Hello, qui affiche « Hello World ! », et qui fait partie du groupe principal s'écrira de cette façon :

<?php
 
/**
 * Notre commande s'apelle Hello.
 * Son emplacement est : Command/Main/Hello.php
 * Et sa classe s'apelle HelloCommand.
 */
class HelloCommand extends Hoa_Console_Command_Abstract {
 
    /**
     * Seule méthode appelée.
     */
    public function main ( ) {
 
        /**
         * On affiche « Hello World ! » via la fonction
         * cout, que l'on verra plus tard.
         */
        cout('Hello World !');
    }
}

On a pour habitude de spécifier l'auteur de la commande, ainsi que son nom. Ces informations sont contenues dans les attributs de classe $author et $programName :

<?php
 
class HelloCommand extends Hoa_Console_Command_Abstract {
 
    /**
     * Nom de l'auteur.
     */
    protected $author      = 'Ivan Enderlin';
 
    /**
     * Nom du programme.
     */
    protected $programName = 'Hello';
 
 
 
    /**
     * Notre méthode principale.
     */
    public function main ( ) {
 
        cout('Hello World !');
    }
}

Ces informations sont optionnelles et ne sont donc pas critiques.

La classe Hoa_Console_Command_Abstract force l'implémentation de deux méthodes : main, mais également usage. La méthode usage est utile pour afficher l'aide de la commande utilisée. Elle est également d'arité nulle. Donc :

<?php
 
class HelloCommand extends Hoa_Console_Command_Abstract {
 
    /**
     * Nom de l'auteur.
     */
    protected $author      = 'Ivan Enderlin';
 
    /**
     * Nom du programme.
     */
    protected $programName = 'Hello';
 
 
 
    /**
     * Notre méthode principale.
     */
    public function main ( ) {
 
        cout('Hello World !');
    }
 
    /**
     * L'aide de notre commande.
     */
    public function usage ( ) {
 
        cout('Vraiment, c\'est si difficile ?');
    }
}

Notre commande est prête à l'utilisation.

Par défaut, la méthode main retourne HC_SUCCESS. Cette constante signifie que tout s'est bien passé, avec succès.

Si jamais une erreur est survenue, on peut retourner la constante HC_EXIT. Le support des autres constantes n'est pas encore totalement supporté, il vaut mieux ne pas les utiliser, et on ne les décrira pas ici.

Le préfixe HC signifie Hoa Console. Ces constantes seront définies si et seulement si elles n'existent pas déjà. Elles appartiennent à la classe d'entrée Hoa_Console.

Comme dans tout fichier d'amorçage, on commence par redéfinir les chemins d'inclusion. Ensuite, on va inclure le fichier principal du framework, à savoir Framework.php. Une fois ce fichier inclus, on va pouvoir importer le paquetage Hoa_Console :

<?php
 
set_include_path( ... );
 
require_once 'Framework.php';
 
/**
 * On importe Hoa_Console.
 */
import('Console.~');

On va commencer par récupérer l'instance de notre classe Hoa_Console pour ensuite lancer le dispatche. C'est à dire que l'on va récupérer la ligne de commande, l'analyser, et en fonction du résultat, appeler la commande et lui donner des arguments. On aurait alors :

/**
 * C'est parti …
 */
Hoa_Console::getInstance()->dispatch();

Si on utilise les paramètres par défaut, cela suffit pour démarrer notre interface graphique.

Notre fichier d'amorçage écrit, il faut maintenant l'exécuter. Plusieurs solutions s'offrent à nous :

Depuis PHP donc, on aurait quelques choses comme : $ php Bootstrap.php

Depuis un fichier .bat, on aurait quelque chose du genre :

@echo off
 
BREAK=ON
set PHP="php.exe"
set SCRIPT_DIR=%~dp0
set BOOTSTRAP=%SCRIPT_DIR%Bootstrap.php
 
"%PHP%" %BOOTSTRAP% %*

Et on le lancera de cette façon : > Bootstrap.bat

Enfin, depuis Unix, on aurait :

#!/usr/bin/env php
<?php
 
require_once dirname(__FILE__) . DIRECTORY_SEPARATOR . 'Bootstrap.php';

Et on l'exécuterait de cette façon : $ chmod +x Bootstrap $ ./Bootstrap

On laisse naturellement le choix à l'utilisateur de s'organiser comme bon lui semble. Il existe beaucoup de possibilités.

Appelons maintenant notre commande Hello : $ ./Bootstrap Hello

Si on veut préciser le groupe, il faut utiliser la syntaxe suivante : nom du groupe:nom de la commande. Par défaut, le groupe sera Main, et le nom de la commande sera Welcome. On rappelle que tout ceci reste paramétrable, tout comme le séparateur de groupe et de commande.

On précise aussi que la casse n'a pas d'importance. On peut appeler la commande (ou le groupe) Hello, hello, ou encore HeLlO, cela reviendra au même. Ainsi : $ ./Bootstrap main:hello

On va étudier les paramètres de l'environnement puis l'utilisation des options (arguments de la commande).

/**
 * On déclare nos paramètres.
 */
$parameters = array(
    // Nos paramètres.
);
 
Hoa_Console::getInstance($parameters)->dispatch();

On trouve deux paramètres du système de base. Ils désignent les valeurs par défaut du groupe et de la commande quand on utilise l'interface en ligne de commande.

Par défaut, si le groupe n'est pas précisé dans une ligne de commande, on utilisera la valeur de system.group.default, soit Main. Et pour la commande, on utilisera la valeur de system.command.default, soit Welcome.

Si on veut les modifier, on ferait :

/**
 * On redéfinit notre groupe et commande
 * utilisés par défaut.
 */
$parameters = array(
    'system.group.default'   => 'Maintenance',
    'system.command.default' => 'Cache'
);
 
/** 
 * Et on lance le système avec ces nouvelles
 * configurations.
 */
Hoa_Console::getInstance($parameters)->dispatch();

On a dit que — par défaut — les commandes se trouvent dans le dossier Command/. Cette valeur est donnée par le paramètre route.directory.

Si on veut placer les commandes dans un autre dossier, on aurait :

/**
 * Nos commandes sont placées dans le dossier UBin/
 */
$parameters = array(
    'route.directory' => 'UBin/'
);
 
/** 
 * Et on lance le système avec cette nouvelle
 * configuration.
 */
Hoa_Console::getInstance($parameters)->dispatch();

Il existe un autre paramètre mais qui est nettement plus sensible. On déconseille de le modifier, sauf avec beaucoup de précautions. Il s'agit du paramètre route.grpcmd.separator qui désigne le caractère (ou chaîne) qui sépare le groupe de la commande dans une ligne de commande. Par défaut, on utilise :.

On comprend que si l'on utilise un paramètre comme l'espace, l'analyse de la ligne de commande risque de ne pas très bien fonctionner ; pareil pour un séparateur vide. Aucune vérification n'est faite, attention donc.

Les motifs de paramètre sont bien connus dans Hoa. On lira la section intitulée « Utiliser les motifs d'architecture » comme référence.

On trouve quatre motifs :

Il n'existe qu'un seul paramètre de ligne de commande. Ce paramètre est cli.longonly et est utile à l'interprétation des options courtes dans une ligne de commande.

Par défaut, il vaut false, c'est à dire que -abc sera interprété comme -a -b -c.

Si on veut seulement utiliser les options longues, on ferait :

/**
 * On force l'évaluation de toutes les options
 * comme étant des options longues.
 */
$parameters = array(
    'cli.longonly' => true
);
 
/** 
 * Et on lance le système avec cette nouvelle
 * configuration.
 */
Hoa_Console::getInstance($parameters)->dispatch();

Le paramètre interface.style.directory décrit le dossier qui contient les classes de style utilisées par la méthode importStyle. Par défaut, il vaut Style/.

Les commandes utilisateurs sont les commandes du système de l'utilisateur à appeler quand on souhaite effectuer une action spéciale.

Par exemple, si on veut lancer le navigateur, on appelera la commande représentée par le paramètre command.broswer. Par défaut, il faut open qui est une commande disponible sur Mac OS X, apparue sous NextStep, et qui permet d'ouvrir à peu prêt tout et n'importe quoi, dont les URL dans le navigateur par défaut.

On trouve également le paramètre command.php qui représente la commande php.

On donne le vocabulaire utilisé dans le sous-paquetage Hoa_Console_Core_Cli_Parser et utilisé partout dans ce document ou dans notre environnement en ligne de commande. Ce vocabulaire est nécessaire à la bonne compréhension des informations manipulées.

On y détaille aussi la syntaxe comprise et utilisée.

Voici le vocabulaire accompagné d'explications.

On conseille vivement de lire la documentation API de la méthode parse de la classe Hoa_Console_Core_Cli_Parser pour plus d'informations.

On se place dans notre commande Hello. On va supposer qu'elle a trois arguments :

On utilise alors l'attribut de classe $options qui est un tableau de tableau. Chaque sous-tableau représente un argument et à cette forme :

array(
    'option longue',
    'type d\'argument',
    'option courte'
);

L'option longue est une simple chaîne de caractère, et l'option courte un simple caractère. Le type d'argument est représenté par trois constantes :

Ainsi, on aurait :

class HelloCommand extends Hoa_Console_Command_Abstract {
 
    /**
     * Nos options.
     */
    protected $options = array(
        array('name',     parent::REQUIRED_ARGUMENT, 'n'),
        array('question', parent::NO_ARGUMENT,       'q'),
        array('help',     parent::NO_ARGUMENT,       'h'),
        array('help',     parent::NO_ARGUMENT,       '?'),
    );
 
    // …
}

class HelloCommand extends Hoa_Console_Command_Abstract {
 
    /**
     * Nos options.
     */
    protected $options = array(
        array('name',     parent::REQUIRED_ARGUMENT, 'n'),
        array('question', parent::NO_ARGUMENT,       'q'),
        array('help',     parent::NO_ARGUMENT,       'h'),
        array('help',     parent::NO_ARGUMENT,       '?'),
    );
 
 
 
    /**
     * Notre commande principale.
     */
    public function main ( ) {
 
        /**
         * On définit nos paramètres par défaut.
         */
        $name = 'World';
        $mark = '!';
 
        /**
         * On lit toutes les options, soit n, q, h et ?.
         * $c représente l'option lue, et $v la valeur de l'option.
         */
        while(false !== $c = parent::getOption($v)) {
 
            switch($c) {
 
                /**
                 * Si l'option est lue, on assigne la valeur.
                 */
                case 'n':
                    $name = $v;
                  break;
 
                /**
                 * Si l'option est lue, on modifie la valeur.
                 */
                case 'q':
                    if(true === $v)
                        $mark = '?';
                  break;
 
                /**
                 * Si l'option h ou ? est lue.
                 * On utilise un retour, donc si l'option
                 * h ou ? est utilisée avec des autres,
                 * on aura l'aide et rien d'autres.
                 */
                case 'h':
                case '?':
                    return $this->usage();
                  break;
            }
        }
 
        cout('Hello ' . $name . ' ' . $mark);
    }
 
    public function usage ( ) {
 
        cout('Ceci est l\'aide !');
 
        return HC_SUCCESS;
    }
}

class HelloCommand extends Hoa_Console_Command_Abstract {
 
    // …
 
    public function main ( ) {
 
        // …
 
        $names = array('World');
 
        while(false !== $c = parent::getOption($v)) {
 
            switch($c) {
 
                /**
                 * Imaginons que nous ayons plusieurs noms.
                 */
                case 'n':
                    $names = parent::parseSpecialValues($v);
                  break;
 
                // …
            }
        }
 
        cout('Hello ' . implode(' and ', $names) . ' ' . $mark);
    }
 
    // …
}

On peut utiliser des mots-clés dans les options spéciales. Pour ça, on utilise le second paramètre de la méthode parseSpecialValues qui est un tableau.

Par exemple, si on veut utiliser le mot-clé ME pour dire Hywan, on aurait :

class HelloCommand extends Hoa_Console_Command_Abstract {
 
    // …
 
    public function main ( ) {
 
        // …
 
        $names = array('World');
 
        while(false !== $c = parent::getOption($v)) {
 
            switch($c) {
 
                /**
                 * Imaginons que nous ayons plusieurs noms.
                 */
                case 'n':
                    $names = parent::parseSpecialValues(
                        $v,
                        array('ME' => 'Hywan')
                    );
                  break;
 
                // …
            }
        }
 
        cout('Hello ' . implode(' and ', $names) . ' ' . $mark);
    }
 
    // …
}

Si on veut utiliser notre mot-clé, on ferait : $ ./Bootstrap hello -n Titi,ME,Toto cela affichera : Hello Titi and Hywan and Toto !.

L'avantage des mots-clés est qu'on peut s'en servir comme raccourci. Par exemple, les mots-clés HEAD, PREV etc. sont très utiles.

Une dernière chose que fait la méthode parseSpecialValues est la gestion des intervalles. Les intervalles sont séparés par le symbole deux-points. Si on donne 1:7, on récupèrera un tableau rempli de 1 à 7. L'ordre n'a pas d'importance, les entiers seront triés selon l'ordre naturel, ce qui implique de n'utiliser que des entiers.

Donc si on entre : $ ./Bootstrap hello -n 1:3 on affichera : Hello 1 and 2 and 3 !

On peut bien sûr mélanger les mots-clés dans les intervalles etc.

Il existe la méthode getInputs qui retourne un tableau contenant toutes les entrées :

class HelloCommand extends Hoa_Console_Command_Abstract {
 
    public function main ( ) {
 
        $inputs = parent::getInputs();
 
        cout('Nombre d\'entrées : ' . count($inputs));
 
        foreach($inputs as $i => $input)
            cout('Entrée numéro ' . $i .
                 ' a pour valeur ' . $input . '.');
    }
 
    // …
}

Si on utilise la commande suivante : $ ./Bootstrap hello a b on aura à l'affichage :

Nombre d'entrées : 2
Entrée numéro 0 a pour valeur a
Entrée numéro 1 a pour valeur b

Il existe une autre méthode qui liste les entrées. Cette méthode s'appelle listInputs et prend 26 arguments, soit la longueur de l'alphabet latin. Chaque argument est passé en référence, voyons plutôt :

class HelloCommand extends Hoa_Console_Command_Abstract {
 
    public function main ( ) {
 
        parent::listInputs($source, $destination);
 
        cout('La source est : ' . $source . '.');
        cout('La destination est : ' . $destination . '.');
    }
 
    // …
}

Si la variable n'existe pas, i.e. si l'entrée n'existe pas, alors la variable aura pour valeur null.

import('Console.Core.Io');
 
/**
 * On demande à l'utilisateur d'entrer une
 * valeur.
 */
Hoa_Console_Core_Io::cin('Une valeur s\'il vous plaît : ');

Hoa_Console_Core_Io::cin( … );

cin('Une valeur s\'il vous plaît : ');

Par défaut, les entrées sont de type TYPE_NORMAL. Mais on peut modifier le comportement des entrées pour interpréter le résultat comme une question, c'est à dire où la réponse est oui ou non.

Pour cela, on utilise la constante TYPE_YES_NO. Toutes ces constantes sont des constantes de la classe Hoa_Console_Core_Io.

Ainsi, on aurait :

cin('Aimez-vous Hoa ?', Hoa_Console_Core_Io::TYPE_YES_NO);

Toute réponse qui vaut : y, ye ou yes sont considérées comme répondant positivement (c'est à dire oui), donc renvoyant true. Toutes les autres réponses seront considérées comme fausses, donc elles vaudront false.

Un autre type d'entrée est le type donné par la constante TYPE_PASSWORD. Ce type d'entrée permet de cacher le mot de passe tapé par l'utilisateur.

En réalité, cette fonctionnalité ne marche que sous les terminaux TTY. Ce sera amélioré à l'avenir pour être standard. On utilise un hack qui sera bientôt corrigé. Il n'est que temporaire.

Ainsi, on aurait :

cin('Entrez votre mot de passe : ', Hoa_Console_Core_Io::TYPE_PASSWORD);

Hoa_Console_Core_Io::cout('Ceci est une sortie');

cout('Ceci est toujours une sortie');

Par défaut, on ajoute un saut de ligne à la fin, c'est à dire le caractère \n. Les constantes NEW_LINE (par défaut) et NO_NEW_LINE contrôle ce comportement. Ainsi, si on ne veut pas ajouter de saut de ligne à la fin, on aurait :

cout('Hop, sans saut de ligne !', Hoa_Console_Core_Io::NO_NEW_LINE);

Par défaut, on effectue une césure sur les sorties. C'est à dire que si la sortie a une taille supérieure à la largeur du terminal, elle sera tronquer pour rentrer dans la largeur.

Les constantes WORDWRAP (par défaut) et NO_WORDWRAP.

Ainsi :

cout('Et une très très très … très longue sortie.',
     Hoa_Console_Core_Io::NEW_LINE,
     Hoa_Console_Core_Io::NO_WORDWRAP);

Une animation s'écrit à l'aide de quatre méthodes :

Pour écrire une animation, il faut étendre la classe Hoa_Console_Interface_Animation. C'est une classe abstraite où les méthodes animation* sont abstraites.

Concrètement, une animation est découpée en image (en frame avec le terme anglais). On a donc un nombre d'images maximum et on va afficher toutes les images une par une. Au final, chaque image sera calculée et affichée à la volée. Bien sûr, on parle d'image, mais il est question de texte, car on est dans un terminal.

Pour détailler les méthodes, la méthode animationFrameMax a une arité nulle et retourne un entier ; la méthode animationFrame prend un entier représentant le numéro de l'image précédente, et retourne un entier représentant le numéro de l'image courante ; et enfin la méthode animationRender prend deux arguments : le numéro de l'image courante à dessiner, et le nombre maximum d'images. Le tout est utilisé par la méthode render.

On va donner un exemple concret d'une barre de progressions :

/**
 * On importe le paquetage
 */
import('Console.Interface.Animation');
 
class ProgressBar extends Hoa_Console_Interface_Animation {
 
    /**
     * On donne le nombre maximum d'image, soit
     * le nombre maximum d'étapes dans notre barre.
     * Ici, notre barre a cinq étapes.
     */
    protected function animationFrameMax ( ) {
 
        return 5;
    }
 
    /**
     * On donne l'étape courante de la barre.
     * On va faire les étapes une par une.
     */
    protected function animationFrame ( $i ) {
 
        return $i + 1;
    }
 
    /**
     * On dessine notre barre.
     */
    protected function animationRender ( $i, $max ) {
 
        /**
         * On attend 1 seconde entre chaque animation.
         */
        sleep(1);
 
        return 'Barre : [' .
               str_pad(str_repeat('#', $i), $max) .
               ']';
    }
}

Et pour lancer l'animation :

$bar = new ProgressBar();
$bar->render();

On concède que c'est très trivial, mais on peut imaginer que animationFrame puise ses données autre part.

Imaginons un barre qui représente l'avancement de plusieurs tâches. On a une méthode qui va faire avancer le compteur de tâche, et la méthode animationFrame n'aura qu'à retourner la valeur de ce compteur.

On aurait alors :

class Task extends Hoa_Console_Interface_Animation {
 
    /**
     * Notre numéro de tâche courante.
     */
    protected $taskI   = 0;
 
    /**
     * Nos tâches associées à l'avancement.
     */
    protected $taskMod = array(
        0 => 2,
        1 => 5,
        2 => 8,
        3 => 17,
        4 => 20
    );
 
 
 
    /**
     * On démarre nos tâches.
     */
    public function __construct ( ) {
 
        parent::render();
    }
 
    /**
     * On effectue une tâche.
     */
    public function makeTask ( ) {
 
        switch($this->taskI) {
 
            case 1:
                sleep(1.8);
              break;
 
            case 2:
                sleep(1.6);
              break;
 
            case 3:
                sleep(1.5);
              break;
 
            case 4:
                sleep(.3);
              break;
        }
 
        $this->taskI++;
    }
 
    /**
     * Nos méthodes d'animations bien connues.
     */
 
    protected function animationFrameMax ( ) {
 
        return 4;
    }
 
    protected function animationFrame ( $i ) {
 
        /**
         * On effectue une tâche.
         */
        return $this->makeTask();
    }
 
    protected function animationRender ( $i, $max ) {
 
        return 'Tâche ' . $i . '/' . $max . ' : [' .
               str_pad(str_repeat('#', $this->taskMod[$i]), 20) .
               ']';
    }
}

Et on lance nos tâches :

$task = new Task();

On a simplifié — encore une fois — à l'extrême pour une plus grande clarté du code, mais on voit comment imbriquer les animations dans une classe.

On peut aussi avoir simplement une classe ProgressBar qui est utilisée dans une classe Task, il suffit d'user de stratégie.

Les animations ont besoin parfois d'être paramétrer pour une plus grande souplesse. C'est pourquoi on a fait un système de gestion de paramètres, tout simple, dans la classe Hoa_Console_Interface_Animation.

Pour faire fonctionner le système de paramètre, on a besoin de :

Pour initialiser des paramètres, on peut redéfinir directement l'attribut de classe $parameters ou appeler le constructeur ou setParameters en passant un tableau de paramètre.

Comme toutes ces méthodes sont présentes dans la classe Hoa_Console_Interface_Animation, on les retrouve par héritage dans notre classe ProgressBar de l'exemple précédent.

L'utilisation est triviale.

On commence par lister tous les styles disponibles :