Pré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 :

Commandes proposés par Temma

Temma fournit plusieurs commandes, dont la documentation est accessible dans la section "Helpers" :

• Cache : Pour vider le cache.
• User : Pour gérer les utilisateurs (compatible avec le contrôleur/plugin Auth, l'attribut Auth et le plugin Api).

Documentation

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 :

Exemple

Par exemple, vous pourriez créer 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. */
    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");
    }
}

Contrôleurs

Comme vous pouvez le voir dans l'exemple ci-dessus, 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.json 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']).
• 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.

Configuration

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

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/.

Interface

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.