Manuel de référence

# Classe ApiUsage

La classe ApiUsage gère la définition et la validation des paramètres lors de l'appel et l'exécution de scripts CLI.
Elle permet de spécifier et contrôler la présence de paramètres requis ou optionnels, et de retourner un texte d'aide précisant les paramètres requis lorsque la validation échoue.

# Constructeur

new ApiUsage();

# Exemple

use Anakeen\Script;

$usage = new ApiUsage();
$docId = $usage->addRequiredParameter("id", "Smart Element id");
$usage->verify();

doSomethingWith($docId);

$ ./ank.php --script=test
Erreur : {CORE0001} argument 'id' expected


Usage :
        --id=<Smart Element id>
   Options:
        --userid=<user system id or login name to execute function - default is (admin)>, default is '1'
        --help (Show usage)

# Méthodes de la classe ApiUsage

# addEmptyParameter

    bool addEmptyParameter(string $argName, string $argDefinition = "")

Cette méthode ajoute un paramètre qui ne prend pas de valeur (autrement nommé flag). Elle retourne true si le paramètre est appliqué, false sinon.

# Liste des paramètres

argName (string)

Le nom du paramètre

argDefinition (string)

Un texte (simple ligne) de description du paramètre

# Exemple

use Anakeen\Script;

$usage = new ApiUsage();
$debug = $usage->addEmptyParameter("debug", "Turn on debug message");
$usage->verify();

$debug = $debug === false ? false : true;

if ($debug) {
  printf("Debug mode ON\n");
} else {
  printf("Debug mode OFF\n");
}

# addHiddenParameter

    string addHiddenParameter(string $argName, string $argDefinition = "")

Cette méthode ajoute un paramètre sans que celui-ci ne soit visible dans le texte d'usage. Un paramètre hidden n'est pas requis, et il est traité comme un paramètre optionnel (ApiUsage::addOptionalParameter). Cette méthode retourne la valeur du paramètre ou null si le paramètre n'est pas présent.

# Liste des paramètres

argName (string)

Le nom du paramètre

argDefinition

Un texte (simple ligne) de description du paramètre.

# Exemple

use Anakeen\Script;

$usage = new ApiUsage();
$hidden = $usage->addHiddenParameter("hidden", "Hidden option");
$usage->verify();

printf("hidden = '%s'\n", $hidden);

# addRequiredParameter

    string addRequiredParameter(string $argName, string $argDefinition = "", string[]|callable $restriction = null)

Cette méthode ajoute un paramètre obligatoire.
Elle retourne la valeur du paramètre. Si la valeur n'est pas conforme à la restriction spécifiée au moyen du paramètre restriction, alors la validation est mise en erreur.

# Liste des paramètres

argName (string)

Le nom du paramètre

argDefinition

Un texte (simple ligne) de description du paramètre

restriction (string[] | callable)

Liste des valeurs possibles pour le paramètre ou un [callable][callable_information] vérifiant une contrainte à appliquer à la valeur du paramètre.
Si la restriction est un array, alors la valeur passée doit obligatoirement être scalaire, et sa valeur doit être parmi les valeurs du tableau.
Pour une autre restriction, se reporter à la description du [callable de restriction][callable_information].

# Le callable de restriction

Le paramètre de restriction peut être un callable. Il permet de vérifier une contrainte que l'on souhaite appliquer aux valeurs passées en argument du paramètre.

    string function(string|string[] $values, string $argName, ApiUsage $apiusage)

Ce callable reçoit trois arguments:

  • values (string|string[])

    La ou les valeurs du paramètre

  • argName (string)

    Le nom du paramètre

  • apiusage (ApiUsage)

    L'objet courant de type ApiUsage contenant les informations des autres paramètres.
    Il est déclenché lors de l'appel à ApiUsage::verify() et doit retourner :

    • une chaîne vide si la valeur est valide,
    • un message d'erreur si la valeur n'est pas valide,
    • une chaîne d'usage si la valeur est la constante ApiUsage::GET_USAGE. Les callables suivants sont disponibles pour les cas standard:
    • ApiUsage::isScalar : vérifie que la valeur est scalaire (c'est la restriction appliquée par défaut),
    • ApiUsage::isArray : vérifie que la valeur est multiple.

# Exemple

use Anakeen\Script;

$usage = new ApiUsage();
$docid = $usage->addRequiredParameter("docid", "Smart Element id");
$format = $usage->addRequiredParameter("format", "Paper format", array("a4", "a3"));
$usage->verify();

printf("docid = '%s'\n", $docid);
printf("format = '%s'\n", $format);
  • Passage d'une valeur ne respectant pas la restriction
$ ./ank.php --script=test --docid=1234 --format=foo
Erreur : {CORE0001} argument 'format' must be one of these values : a4, a3


Usage :
        --docid=<Smart Element id>
        --format=<Paper format> [a4|a3]
   Options:
        --userid=<user system id or login name to execute function - default is (admin)>, default is '1'
        --help (Show usage)
  • Appel valide
$ ./ank.php --script=test --docid=1234 --format=a4
docid = '1234'
format = 'a4'
  • Restriction par un callable
use Anakeen\Script;

    $usage = new ApiUsage();
    $numberpositive = $usage->addRequiredParameter(
        "number",
        "A number",
        function($values, $argname, $apiusage){
            if (ApiUsage::GET_USAGE === $values) {
                return "A positive number";
            }
            if (is_array($values)) {
                $invalidValues = array_filter($values, function($var) {return($var < 0);});
                if (count($invalidValues) > 0 ) {
                    return sprintf("Following values are not positive: [%s]", implode("],[", $invalidValues));
                }
            } elseif ($values < 0) {
                return sprintf("Following value are not positive : [%s]", $values);
            }
            return "";
        }
    };
    $usage->verify();

    printf("number = '%s'\n", $numberpositive);
  • Passage d'une valeur ne respectant pas la restriction :
$ ./ank.php --script=test --number=-12
Erreur : {CORE0001} Error checking argument number type: Following value is not positive : [-12]


Usage :
      --number=<A number>A positive number
 Options:
      --userid=<user system id or login name to execute function - default is (admin)>, default is '1'
      --help (Show usage)
  • Appel valide
$ ./ank.php --script=test --number=12
number = '12'

# addOptionalParameter

    string addOptionalParameter( string $argName,
                                 string $argDefinition,
                                 string[]|callable $restriction = null,
                                 string $default = null)

Cette méthode ajoute un paramètre optionnel. Elle retourne trois valeurs possibles:

  • si le paramètre est présent, alors la valeur du paramètre est retournée,
  • si le paramètre n'est pas présent et qu'une valeur par défaut est fournie, alors c'est la valeur par défaut qui est retournée, sinon null est retourné,
  • si la valeur n'est pas conforme à la restriction spécifiée au moyen du paramètre restriction, alors la validation est mise en erreur.

# Liste des paramètres

argName (string)

Le nom du paramètre

argDefinition (string)

Un texte (simple ligne) de description du paramètre

restriction (string[]|callable)

Liste des valeurs possibles pour le paramètre ou un callable vérifiant une contrainte à appliquer à la valeur du paramètre.
Si la restriction est un array, alors la valeur passée doit obligatoirement être scalaire, et sa valeur doit être parmi les valeurs du tableau.
Pour une autre restriction, se reporter à la description du callable de restriction.

default (string)

Valeur retournée par défaut si le paramètre n'est pas présent.

# Exemple

  • Définition du paramètre format
use Anakeen\Script;

$usage = new ApiUsage();
$format = $usage->addOptionalParameter("format", "Paper format", array("a4", "a3"), "a4");
$usage->verify();
printf("format = '%s'\n", $format);
  • Chaîne d'usage générée
$ ./ank.php --script=test --help

Usage :
   Options:
        --userid=<user system id or login name to execute function - default is (admin)>, default is '1'
        --format=<Paper format> [a3|a4], default is 'a4'
        --help (Show usage)
  • Valeur par défaut
$ ./ank.php --script=test
format = 'a4'
  • Passage de la valeur
$ ./ank.php --script=test --format=a3
format = 'a3'

# setDefinitionText

    void setDefinitionText(string $text)

Cette méthode ajoute un texte de description du script d'API dans le message d'usage.

# Liste des paramètres

text (string)

Le texte (simple ligne) de description du script

# Exemple

use Anakeen\Script;

$usage = new ApiUsage();
$usage->setDefinitionText("Script de test de la classe ApiUsage");
$usage->verify();

$ ./ank.php --script=test --help
Script de test de la classe ApiUsage
Usage :
   Options:
        --userid=<user system id or login name to execute function - default is (admin)>, default is '1'
        --help (Show usage)

# setStrictMode

    void setStrictMode( bool $strict = true)

Cette méthode active ou désactive le mode de validation strict des paramètres. Lorsque le mode de validation strict est activé, la présence d'arguments non enregistrés auprès de l'instance d'ApiUsage en cours met en échec la validation des paramètres.
Par défaut, le mode de validation strict est actif.

# Liste des paramètres

strict (bool)

Active (true) ou désactive (false) le mode de validation strict.

# Exemple

use Anakeen\Script;

$usage = new ApiUsage();
$usage->setStrictMode(false);

$ ./ank.php --script=test --foo=bar

Aucune erreur n'est remontée concernant le paramètre foo inconnu.

# verify

    void verify( bool $useException = false)

Cette méthode lance la validation des paramètres précédemment définis. Elle génère une erreur si les paramètres ne sont pas conformes.

# Liste des paramètres

useException (bool)

Active (true) ou désactive (false) la remontée d'erreur par exception lors de l'échec de la validation des paramètres.

# Exemple

use Anakeen\Script;

$usage = new ApiUsage();
try {
  $usage->verify(true);
} catch (Anakeen\Script\Exception $e) {
  printf("Bad parameters!\n");
}
printf("Done.");

$ ./ank.php --script=test --foo=bar
Bad parameters!
Done.

# isScalar

    string isScalar($argVal, $argName)

Cette méthode vérifie qu'une valeur est scalaire.
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

argVal (string)

valeur du paramètre à vérifier

argName (string)

Nom du paramètre

# isArray

    string isArray($argVal)

Cette méthode vérifie si le paramètre est un tableau.
Elle retourne une chaîne vide s'il n'y a pas d'erreur, ou une chaîne non-vide contenant le message d'erreur dans le cas contraire.

# Liste des paramètres

argVal (string)

valeur du paramètre à vérifier

# setDefinitionText

    void setDefinitionText($text)

Cette méthode ajoute une description au script.

# Liste des paramètres

text (string)

description (simple ligne) à ajouter au script

# getUsage

    string getUsage()

Cette méthode retourne les informations relatives à un script telles que :

  • une description,
  • les paramètres obligatoires du script,
  • les paramètres optionnels du script.

← Classe Dir →