Interface en ligne de commande

---

1Présentation

Il est souvent utile d'écrire des scripts destinés à être exécutés en ligne de commande. C'est quelque chose de très facile à faire en PHP pur, mais vous devez alors initialiser manuellement le log, les sources de données, l'autoloader, l'injection de dépendances…

Temma propose donc la fonctionnalité Comma (COMmand-line MAnager), qui effectue toutes les initialisations nécessaires, avant d'exécuter le code demandé.

L'exécution d'un script se fait en appelant le programme bin/comma, en lui passant en paramètre le nom de l'objet et de la méthode à exécuter, ainsi que les éventuels paramètres supplémentaires attendus par cette méthode.
Le code qui s'exécute peut soit être complètement autonome (et faire son travail à partir des options qui lui auront été fournies), soit entrer dans une communication interactive avec l'utilisateur.

Quelques exemples imaginaires :

Par défaut, les commandes exécutables sont enregistrées dans le répertoire cli/ du projet. Il est toutefois possible de les placer où vous le souhaitez dans les chemins d'inclusion, éventuellement en utilisant un namespace.

Dans le cas de l'utilisation d'un namespace, il faut mettre le nom de l'objet entre guillemets ou entre apostrophes.
Par exemple :

---

2Documentation

En tapant bin/comma ou bin/comma help, vous pouvez voir la documentation générale de Comma :

En tapant bin/comma help suivi du nom d'un contrôleur, vous pourrez voir la liste des actions de ce contrôleur, avec la documentation associée :

Si vous ajoutez le nom d'une action, vous ne verrez que la documentation de celle-ci :

---

3Contrôleurs

Les objets exécutés par Comma sont des contrôleurs identiques à ceux utilisés par Temma en réponse aux requêtes HTTP, à ceci près qu'ils doivent être enregistrés dans le répertoire cli/ (et non pas controllers/).

Il y a de nombreuses similitudes :

• Les actions peuvent prendre un nombre variable de paramètres, avec éventuellement des paramètres optionnels (possédant une valeur par défaut).
• Les méthodes d'initialisation __wakeup() et de finalisation __sleep() sont exécutées respectivement avant et après l'exécution de l'action.
• Si aucun nom de méthode n'est fourni en ligne de commande, c'est l'action racine __invoke() qui est appelée. Cette action ne peut pas prendre de paramètres.
• Si une action par défaut __call() est définie dans le contrôleur, elle sera exécutée pour toutes les actions demandées qui n'ont pas de méthode équivalente.
• Si une action proxy __proxy() est définie dans le contrôleur, elle sera toujours exécutée, quelle que soit l'action appelée.
• Les attributs positionnés sur les contrôleurs et les actions sont exécutés (pour autant qu'ils puissent fonctionner dans un environnement en ligne de commande, et non un environnement web).
• Le fichier de configuration etc/temma.php est lu et son contenu est disponible via l'objet $this->_config.
• Le composant d'injection de dépendances est généré, et est disponible de la même manière (en écrivant $this->_loader).
• Les sources de données sont générées et sont disponibles soit par écriture directe (par exemple $this->db), soit en passant par le composant d'injection de dépendance (par exemple $this->_loader->dataSources->db ou $this->_loader->dataSources['db-read']).
• Il est possible d'utiliser des DAO.

Mais il y a aussi plusieurs différences :

• Il n'y a pas de système de routage, même simplifié (il n'est pas possible d'appeler un contrôleur par un autre nom que le sien).
• Il n'y a pas d'exécution de plugins.
• Il n'y a pas de vue.
• L'objet $this->_request ne contient que les paramètres fournis sur la ligne de commande.

---

4Paramètres

Les paramètres attendus par les actions sont passés en ligne de commande en leur ajoutant le préfixe --, en leur ajoutant ensuite le signe égal (=) suivi de la valeur associée.

Si la valeur contient des espaces, il est possible de la placer entre guillemets (") ou entre apostrophes (').

Si un paramètre est passé sans valeur, il sera considéré comme un booléen de valeur true.

---

5Exemple

Prenons l'exemple d'un script servant à ajouter un utilisateur en base de données.

Ce script pourrait être appelé de la manière suivante :

On pourrait imaginer un paramètre optionnel, pour dire que l'utilisateur est une administrateur :

Concrètement, Comma va instancier l'objet User, puis appeler sa méthode add() en lui passant les paramètres.

L'objet User doit être stocké dans un fichier nommé User.php, placé dans le répertoire cli/ du projet.
Cet objet doit hériter de l'objet \Temma\Web\Controller.

Le code de cet objet pourrait être :

class User extends \Temma\Web\Controller {
    /** Création de la DAO de connexion à la base de données. */
    protected $_temmaAutoDao = true;

    /**
     * Ajout d'utilisateur.
     * @param  string  $name   Nom de l'utilisateur.
     * @param  string  $email  Adresse mail de l'utilisateur.
     * @param  bool    $admin  (optionnel) Droit administrateur. Faux par défaut.
     */
    public function add(string $name, string $email, bool $admin=false) {
        // ajout de l'utilisateur en base de données
        $id = $this->dao->create([
            'name'  => $name,
            'email' => $email,
            'roles' => $admin ? 'admin' : '',
        ]);
        // message
        print("Utilisateur créé avec l'identfiant '$id'.\n");
    }
}

---

6Configuration

Par défaut, les scripts en ligne de commande chargent la configuration présente dans le fichier etc/temma.php. Il est possible de fournir le chemin vers un autre fichier en utilisant le paramètre conf.

Ce paramètre doit être placé avant le nom du contrôleur.

Par exemple :

Attention, fournir un fichier placé en-dehors de l'arborescence du projet est possible, mais cela ne changera pas les chemins utilisés vers les différents répertoires. Par exemple, le plugin Language continuera à chercher ses fichier dans etc/lang/.

---

7Chemins d'inclusion

Les scripts exécutés avec Comma se voient ajouté à leurs chemins d'inclusion le répertoire lib/ du projet. Il est possible d'ajouter des chemins supplémentaires avec le paramètre inc.

Comme pour le paramètre conf, ce paramètre doit être placé avant le nom du contrôleur.

Par exemple :

---

8Log

Par défaut, les scripts en ligne de commande écrivent leur log sur la sortie d'erreur.

Si le fichier etc/temma.php le prévoit, les logs pourront aussi être écrits sur le fichier log/temma.log.

Pour désactiver l'écriture sur la sortie d'erreur, il faut utiliser le paramètre nostderr.

Comme pour les paramètres conf et inc, ce paramètre doit être placé avant le nom du contrôleur.

Exemple :

---

9Interface

L'interface utilisateur est complètement différente de celle des contrôleurs web. Les scripts en ligne de commande interagissent en écrivant sur leur sortie standard, et récupèrent ce que saisit l'utilisateur en lisant sur leur entrée standard.

Temma fournit deux helpers qui sont utiles dans ces conditions :

• \Temma\Utils\Ansi : fournit des méthodes permettant d'améliorer l'affichage des informations écrite par votre code.
• \Temma\Utils\Term : offre des fonctionnalités pour interagir plus facilement avec le terminal.