diff --git a/doc/src/contrib/addons/cli-commands.md b/doc/src/contrib/addons/cli-commands.md index 5d7879f0..31b23911 100644 --- a/doc/src/contrib/addons/cli-commands.md +++ b/doc/src/contrib/addons/cli-commands.md @@ -1,5 +1,7 @@ # Les commandes *CLI* personnalisées +## Introduction + Les [LSaddons](../../conf/index.md#configuration-des-lsaddons) peuvent fournir des commandes *CLI* personnalisées qui seront accessibles via la commande `ldapsaisie` fournie avec l'application. Cela peut, par exemple, vous permettre de rendre accessible en ligne de commandes une procédure @@ -8,81 +10,152 @@ exécutant cette procédure régulièrement. Pour mettre en place une telle commande *CLI* personnalisée, il est nécessaire de : -- Déclarer cette vue dans la fonction `LSaddon_[addon]_support` de l'addon à l'aide de la méthode - `LScli :: add_command()` ; +- Déclarer cette commande *CLI* personnalisée dans la fonction `LSaddon_[addon]_support` de l'addon + à l'aide de la méthode `LScli::add_command()` ; - Déclarer la fonction implémentant cette commande *CLI* personnalisée. Cette fonction acceptera, en tant qu'unique paramètre, un tableau des arguments reçus lors de l'exécution de la commande et - retournera `True` ou `False` en cas de succès/d'erreur d'exécution de la commande. Cette valeur de - retour influencera le code retourné par la commande : `0` en cas de succès, `1` en cas d'erreur. + retournera `True` ou `False` en cas de succès/d'erreur d'exécution de la commande. Cette valeur + de retour influencera le code retourné par la commande : `0` en cas de succès, `1` en cas + d'erreur. - Bien que cela ne soit pas obligatoire, il sera également possible de déclarer une fonction - permettant l'autocomplétion des arguments acceptés par la commande. + permettant l'autocomplétion des arguments acceptés par la commande. Pour plus d'informations à ce + propos, reportez-vous à la [section dédiée](#auto-completion). - Cette méthode recevra en paramètre : +## Outils à votre disposition - - `$command_args` +Pour vous aider dans l'écriture de vos méthodes *CLI*, la classe `LScli` offre des méthodes +pour les tâches les plus courantes : - Un tableau des arguments déjà reçus par la commande. +- `LScli::usage($error, ...$extra_args)` - - `$comp_word_num` + Affichage du message d'aide de votre commande avant arrêt. Un message d'erreur peut également + être spécifié avec d'éventuels arguments supplémentaires pour le composer (via `sprintf()`). Si un + message d'erreur est fourni, le code de retour de la commande sera `1` et à défaut, `0`. - Un entier indiquant le rang de l'argument que l'autocomplétion tente de compléter. Il peut - s'agir du rang d'un paramètre déjà fourni et présent dans le tableau `$command_args` ou bien - d'un rang supérieur aux nombres d'arguments déjà fournis à la commande et dans ce cas il s'agira - d'autocompléter tous potentiels autre argument que pourrait accepter cette commande. +- `LScli::need_ldap_con()` - - `$comp_word` + Permet d'établir la connexion à l'annuaire LDAP (si ce n'est pas déjà fait). - Une chaîne de caractères correspondant à ce qu'a déjà saisi l'utilisateur de l'argument que l'on - tente d'autocompléter. Cette chaîne de caractères peut être vide ou non, en fonction de s'il - s'agit d'un nouvel argument à autocompléter ou non. +- `LScli::run_external_command($command, $data_stdin=null, $escape_command_args=true, $cwd=null)` : - - `$opts` + Permet d'exécuter une commande externe et de récupérer un tableau contenant le code de + retour de la commande exécutée, le contenu affiché sur la sortie standard et le contenu + affiché sur la sortie d'erreur. - Un tableau des potentiels arguments globaux acceptés par *LScli* dans le contexte actuel (par - exemple, `-d` ou `--debug` pour l'activation du mode debug). La réponse de cette fonction devra - inclure ces potentiels arguments si le contexte d'autocomplétion si prête (nouvel argument par - exemple). + La commande à exécuter peut être passée sous la forme d'une chaîne de caractères ou d'un + tableau de chaînes de caractères correspondant à la commande et ses arguments. Par défaut, + les caractères spéciaux contenus dans les paramètres passés à la commande seront + "échappés", mais il est possible de désactiver cela via le paramètre `$escape_command_args`. - Pour finir, cette fonction devra retourner un tableau des potentielles valeurs que pourrait - prendre l'argument autocomplété. Si une unique proposition est faite à l'utilisateur, celle-ci - sera automatiquement proposée à l'utilisateur et à défaut, la liste des valeurs possibles lui - seront affichées. + Il est possible de fournir des données à passer à la commande via son entrée standard via + le paramètre `$data_stdin`. - !!! note + Enfin, il est possible de spécifier l'emplacement du dossier courant d'exécution de la + commande via le paramètre `$cwd`. - Pour vous aider dans l'écrire d'une telle méthode d'autocomplétion, des méthodes statiques - sont fournies par la classe `LScli` pour les autocomplétions les plus courantes : +- `LScli::confirm($question=null)` - - `LScli :: autocomplete_class_name()` : Autocomplétion du nom d'une classe PHP. + Permet de demander à l'utilisateur de confirmer quelque chose. La question à poser peut être + passée en paramètre et cette méthode retournera `true` ou `false` en fonction du choix de + l'utilisateur. - - `LScli :: autocomplete_addon_name()` : Autocomplétion du nom d'un - [LSaddon](../../conf/index.md#configuration-des-lsaddons). +- `LScli::parse_arg_value($value, $custom_values=null)` - - `LScli :: autocomplete_int()` : Autocomplétion d'un nombre entier. + Permet d'interpréter la valeur d'un argument fourni par l'utilisateur. Celui-ci pourra spécifier + le type de l'argument en préfixant l'argument de son type entre crochets (exemple : `[bool]1`, + types supportés : `string`, `str`, `bool`, `boolean`, `int`, `integer`, `float`, `array`) et à + défaut, la valeur sera analysée comme une valeur JSON permettant de passer des paramètres + complexes à vos méthodes (un tableau associatif arborescent par exemple). - - `LScli :: autocomplete_LSobject_types()` : Autocomplétion du nom d'un type - d'[LSobject](../../conf/index.md#configuration-lsobject). + Des valeurs particulières seront également analysées de manières prédéfinies si elles ne + sont pas préfixées d'un type particulier. C'est le cas par défaut des chaînes de + caractères `true` et `false` qui seront comprises comme des booléens et `null` qui sera + compris comme la valeur `NULL` au sens PHP. - - `LScli :: autocomplete_LSobject_dn()` : Autocomplétion du DN d'un type précis - d'[LSobject](../../conf/index.md#configuration-lsobject) de l'annuaire. + Vous pouvez également spécifier vos propres valeurs particulières via l'argument + `$custom_values` sous la forme d'un tableau associatif dont les clés sont les valeurs + particulières fournies par l'utilisateur et la valeur correspondante, la valeur au sens + _PHP_. - - `LScli :: autocomplete_LSobject_attr_name()` : Autocomplétion du nom d'un attribut précis - pour un type d'[LSobject](../../conf/index.md#configuration-lsobject) de l'annuaire. + __Important :__ l'analyse des valeurs particulières sera faite en mettant + __en minuscule__ la valeur fournie par l'utilisateur. Il est donc important que vos + valeurs particulières spécifiées via l'argument `$custom_values` soient toutes en + minuscule. - - `LScli :: autocomplete_LSobject_ioFormat()` : Autocomplétion du nom d'un - [ioFormat](../../conf/LSobject/ioFormat.md#ioformat) pour un type - d'[LSobject](../../conf/index.md#configuration-lsobject) de l'annuaire. +## Auto-complétion - - `LScli :: autocomplete_LSform_name()` : Autocomplétion du nom d'un formulaire de - l'application. +Lors de la déclaration de votre commande CLI personnalisée à l'aide de la méthode +`LScli::add_command()`, vous avez la possibilité de spécifier une fonction permettant +l'autocomplétion des arguments acceptés par celle-ci. - Par ailleurs, la méthode `LScli :: autocomplete_opts()` vous facilitera la construction de la - liste des valeurs d'autocomplétion de l'argument courant en fonction de ce qui a déjà été - saisi par l'utilisateur (paramètre `$comp_word`). Cette méthode s'occupera en l'occurrence de - filtrer parmi toutes les valeurs contextuelles possibles, celles qui correspondent au préfixe - fourni par l'utilisateur. +Cette fonction recevra en paramètre : + +- `$command_args` + + Un tableau des arguments déjà reçus par la commande. + +- `$comp_word_num` + + Un entier indiquant le rang de l'argument que l'autocomplétion tente de compléter. Il peut + s'agir du rang d'un paramètre déjà fourni et présent dans le tableau `$command_args` ou bien + d'un rang supérieur aux nombres d'arguments déjà fournis à la commande et dans ce cas il s'agira + d'autocompléter tous potentiels autres arguments que pourrait accepter cette commande. + +- `$comp_word` + + Une chaîne de caractères correspondant à ce qu'a déjà saisi l'utilisateur de l'argument que l'on + tente d'autocompléter. Cette chaîne de caractères peut être vide ou non, en fonction de s'il + s'agit d'un nouvel argument à autocompléter ou non. + +- `$opts` + + Un tableau des potentiels arguments globaux acceptés par *LScli* dans le contexte actuel (par + exemple, `-d` ou `--debug` pour l'activation du mode debug). La réponse de cette fonction devra + inclure ces potentiels arguments si le contexte d'autocomplétion s'y prête (nouvel argument par + exemple). + +Pour finir, cette fonction devra retourner un tableau des potentielles valeurs que pourrait +prendre l'argument autocomplété. Si une unique proposition est faite à l'utilisateur, celle-ci +sera automatiquement proposée à l'utilisateur et à défaut, la liste des valeurs possibles lui +seront affichées. + +!!! note + + Pour vous aider dans l'écriture d'une telle méthode d'autocomplétion, des méthodes statiques + sont fournies par la classe `LScli` pour les autocomplétions les plus courantes : + + - `LScli::autocomplete_class_name()` : Autocomplétion du nom d'une classe PHP. + + - `LScli::autocomplete_addon_name()` : Autocomplétion du nom d'un + [LSaddon](../../conf/index.md#configuration-des-lsaddons). + + - `LScli::autocomplete_int()` : Autocomplétion d'un nombre entier. + + - `LScli::autocomplete_LSobject_types()` : Autocomplétion du nom d'un type + d'[LSobject](../../conf/index.md#configuration-lsobject). + + - `LScli::autocomplete_LSobject_dn()` : Autocomplétion du DN d'un type précis + d'[LSobject](../../conf/index.md#configuration-lsobject) de l'annuaire. + + - `LScli::autocomplete_LSobject_attr_name()` : Autocomplétion du nom d'un attribut précis + pour un type d'[LSobject](../../conf/index.md#configuration-lsobject) de l'annuaire. + + - `LScli::autocomplete_LSobject_ioFormat()` : Autocomplétion du nom d'un + [ioFormat](../../conf/LSobject/ioFormat.md#ioformat) pour un type + d'[LSobject](../../conf/index.md#configuration-lsobject) de l'annuaire. + + - `LScli::autocomplete_LSform_name()` : Autocomplétion du nom d'un formulaire de + l'application. + + Par ailleurs, la méthode `LScli::autocomplete_opts()` vous facilitera la construction de la + liste des valeurs d'autocomplétion de l'argument courant en fonction de ce qui a déjà été + saisi par l'utilisateur (paramètre `$comp_word`). Cette méthode s'occupera en l'occurrence de + filtrer parmi toutes les valeurs contextuelles possibles, celles qui correspondent au préfixe + fourni par l'utilisateur. + +## Exemple d'implémentation Pour implémenter une telle commande *CLI* personnalisée, vous pouvez vous inspirer de l'exemple fourni ci-dessous ou encore des commandes *CLI* fournies par les autres @@ -90,30 +163,38 @@ fourni ci-dessous ou encore des commandes *CLI* fournies par les autres **Structure du fichier includes/addons/LSaddons.[addon name].php :** -``` +```php loadData($dn)) { - self :: log_fatal("Fail to load object $dn data from LDAP"); + self::log_fatal("Fail to load object $dn data from LDAP"); return false; } @@ -188,7 +269,9 @@ function cli_my_custom_cli_cmd($command_args) { * * @return array List of available options for the word to autocomplete **/ -public static function cli_my_custom_cli_cmd_autocompleter($command_args, $comp_word_num, $comp_word, $opts) { +public static function cli_my_custom_cli_cmd_autocompleter( + $command_args, $comp_word_num, $comp_word, $opts +) { $opts = array_merge($opts, array ('-f', '--force')); // Handle positional args @@ -202,33 +285,40 @@ public static function cli_my_custom_cli_cmd_autocompleter($command_args, $comp_ if (is_null($objType)) { // Defined it $objType = $command_args[$i]; - LScli :: unquote_word($objType); + LScli::unquote_word($objType); $objType_arg_num = $i; // Check object type exists - $objTypes = LScli :: autocomplete_LSobject_types($objType); + $objTypes = LScli::autocomplete_LSobject_types($objType); // Load it if exist and not trying to complete it if (in_array($objType, $objTypes) && $i != $comp_word_num) { - LSsession :: loadLSobject($objType, false); + LSsession::loadLSobject($objType, false); } } elseif (is_null($dn)) { $dn = $command_args[$i]; - LScli :: unquote_word($dn); + LScli::unquote_word($dn); $dn_arg_num = $i; } } } - // If objType not already choiced (or currently autocomplete), add LSobject types to available options + // If objType not already chosen (or currently autocomplete), + // add LSobject types to available options if (!$objType || $objType_arg_num == $comp_word_num) - $opts = array_merge($opts, LScli :: autocomplete_LSobject_types($comp_word)); + $opts = array_merge( + $opts, + LScli::autocomplete_LSobject_types($comp_word) + ); - // If dn not alreay choiced (or currently autocomplete), try autocomplete it + // If dn not already chosen (or currently autocomplete), try autocomplete it elseif (!$dn || $dn_arg_num == $comp_word_num) - $opts = array_merge($opts, LScli :: autocomplete_LSobject_dn($objType, $comp_word)); + $opts = array_merge( + $opts, + LScli::autocomplete_LSobject_dn($objType, $comp_word) + ); - return LScli :: autocomplete_opts($opts, $comp_word); + return LScli::autocomplete_opts($opts, $comp_word); } ```