13.3.4 ApiUsage::addRequiredParameter()

13.3.4.1 Description

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

La présence du paramètre est vérifiée et sa valeur retournée.

13.3.4.1.1 Avertissements

Aucun.

13.3.4.2 Liste des paramètres

(string) argName

Le nom du paramètre.

(string) argDefinition

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

(string[]|callable) restriction

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

13.3.4.2.1 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:

(string|string[]) values

La ou les valeurs du paramètre

(string) argName

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.

13.3.4.3 Valeur de retour

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.

13.3.4.4 Erreurs / Exceptions

Aucune.

13.3.4.5 Historique

• Remplace la méthode addNeeded() qui est dépréciée depuis la version 3.2.5.

13.3.4.6 Exemples

13.3.4.6.1 Restriction par un array

<?php
 
$usage = new ApiUsage();
$docid = $usage->addRequiredParameter("docid", "Document id");
$format = $usage->addRequiredParameter("format", "Paper format", array("a4", "a3"));
$usage->verify();
 
printf("docid = '%s'\n", $docid);
printf("format = '%s'\n", $format);

Omission d'un paramètre obligatoire :

$ ./wsh.php --api=test
Erreur : {CORE0001} argument 'docid' expected
 
 
Usage :
        --docid=<Document 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)

Passage d'une valeur ne respectant pas la restriction :

$ ./wsh.php --api=test --docid=1234 --format=foo
Erreur : {CORE0001} argument 'format' must be one of these values : a4, a3
 
 
Usage :
        --docid=<Document 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 :

$ ./wsh.php --api=test --docid=1234 --format=a4
docid = '1234'
format = 'a4'

13.3.4.6.2 Restriction par un callable

<?php
 
$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 is not positive : [%s]", $values);
        }
        return "";
    }
);
$usage->verify();
 
printf("number = '%s'\n", $numberpositive);

Omission d'un paramètre obligatoire :

$ ./wsh.php --api=test
Erreur : {CORE0001} argument 'number' expected
 
 
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)

Passage d'une valeur ne respectant pas la restriction :

 $ ./wsh.php --api=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 :

$ ./wsh.php --api=test --number=12
number = '12'
 

13.3.4.7 Notes

Aucune.

13.3.4.8 Voir aussi

• apiUsage::verify()