Chapitre 11 Dynacase en ligne de commande

L'exécution de programmes permettant de gérer les documents et le paramétrage en général peut être fait en ligne de commande. Le point d'entrée de la ligne de commande dans Dynacase est le script wsh.php.

11.1 wsh.php

Ce script permet de :

• lancer des scripts,
• exécuter des actions.

Son aide est disponible au moyen de l'option --help :

./wsh.php --help
usage   wsh.php --app=APPLICATION --action=ACTION [--ARG=VAL] ...:  execute an action
        wsh.php --api=API [--ARG=VAL] ....   :  execute an api function
        wsh.php --listapi                     : view api list

Note :

• Le script wsh.php doit être exécuté, en ligne de commande, sous le même compte utilisateur que celui du serveur Apache (afin que les fichiers produits soient accessibles par Dynacase en mode Web) et ne doit en aucun cas être lancé sous le compte utilisateurroot.

11.1.1 Utilisateur effectuant l'opération

Par défaut, les opérations sont lancées sous l'identité Dynacase de l'utilisateur Master Default (administrateur principal - compte admin). Il est possible de changer cette identité au moyen de l'option --userid, qui prend comme paramètre le login d'un utilisateur Dynacase, ou son identifiant système Dynacase.

11.1.2 Passage d'arguments

11.1.2.1 Arguments simples

Il est possible de passer des arguments nommés en rajoutant des options avec la notation --argumentName=argumentValue. Le nom de l'argument correspond au nom de l'option. Ainsi, --foo=bar assignera la valeur "bar" à l'argument foo.

Attention : les arguments ne sont pas typés : ils sont systématiquement envoyés au format texte. Aussi, lors de l'utilisation du paramètre --foo=true, le script appelé recevra l'argument "true" (string) et non pas le booléen true.

11.1.2.2 Arguments multivalués

Si la valeur de l'argument comporte des espaces les double-quotes "ou les quotes ' peuvent être utilisées.

./wsh.php --api=my_test --my_number=3 --my_text="l'argument texte"

Le passage d'arguments multivalués se fait au moyen de la notation --argumentName=argumentValue répétée autant de fois que nécessaire. Ainsi, --my_numbers[]=2 --my_numbers[]=4 assignera la valeur array("2","4") à l'argument my_numbers.

Pour la récupération des arguments, se référer à la documentation de la classe ApiUsage.

11.1.2.3 Arguments booléens

Enfin, il est possible de passer des arguments booléens avec la notation --argumentName (sans valaur). Ainsi, --foo assignera la valeur true à l'argument foo.

11.2 Gestion des erreurs wsh

Lorsqu'un shell non interactif¹ sort en erreur, un mail contenant le détail de l'erreur peut être envoyé.

Ce mail est envoyé uniquement si le paramètre CORE_WSH_MAILTO est non vide.

11.3 Exécuter des scripts avec wsh

Exemple d'appel :

./wsh.php --api=cleanContext

Cela appellera le script /API/cleanContext.php.

La liste des scripts disponibles est obtenu au moyen de la commande listapi :

./wsh.php --listapi
application list :
    - AppSwitcherSetCoreStartApp
    - DocRelInit
    - […]
    - vault_init
    - wdoc_graphviz

Afin de connaître l'usage d'un script, il est possible d'utiliser l'option --help :

./wsh.php --api=cleanContext --help
Clean base
Usage :
    Options:
        --userid=<user system id or login name to execute function - default is (admin)>, default is '1'
        --real=<real (yes or no)>
        --help (Show usage)

11.4 Exécuter des actions avec wsh

Il est possible au moyen de wsh de lancer n'importe quelle action de n'importe quelle application.

Exemple d'appel :

./wsh.php --app=MY_APP --action=MY_ACTION

Les arguments spécifiques de l'action doivent être indiqués au moyen de la syntaxe idoine

Le résultat de l'action est retournée sur la sortie standard.

Exemple d'exécution de l'action FDL_FAMILYSCHEMA de l'application FDL :

./wsh.php --app=FDL --action=FDL_FAMILYSCHEMA --id=DIR > dir.xsd

Toute action ou tout script exécuté avec wsh n'utilise pas les sessions. Les sessions, étant utilisées pour une connexion avec le client web, n'ont pas lieu d'être utilisées.

11.5 Retour d'erreur

Le script retourne un exit status indiquant si une erreur s'est produite. Lorsqu'une erreur se produit, son message est retourné sur la sortie standard (stdout), et non sur la sortie d'erreur (stderr).

Codes retournés :

• 0 : Pas d'erreur
• 1 : Déclenchement d'une exception, appel à Action::exitError(), ou action inconnue
• 2 : Utilisateur inconnu ou non actif (option --userid)
• 4 : Le script indiqué par --api est introuvable.

Exemple :

$ ./wsh.php --api=pastrouve
fichier API API/pastrouve.php non trouvé
$ echo $?
4

3.2.17 Si le code retourné est 1, le message d'erreur est affiché avec la fonction error_log(). Par défaut, l'affichage est effectué sur la sortie stderr. Ce message est accompagné de la callstack qui est à l'origine de l'erreur.

Exemple :

$ ./wsh.php --api=refreshDocuments --famid=389
    17208> Dynacase got an uncaught exception 'Dcp\Core\Exception' with message '{CORE0001} family 389 not exists' in file /var/www/tmp32/WHAT/Class.Action.php at line 651:
    17208> #0 /var/www/tmp32/API/refreshDocuments.php(74): Action->exitError('family 389 not ...')
    17208> #1 /var/www/tmp32/wsh.php(133): include('/var/www/tmp32/...')
    17208> #2 {main}
    17208> End Of Exception.
$ echo $?
1

Si le code est 2 ou 4, le message d'erreur est affiché sur la sortie standard (stdout).

11.6 Écrire un script CLI

Les scripts exécutables avec wsh doivent être des fichiers php présents dans le sous-répertoire ./API du contexte d'installation. Ces fichiers doivent porter l'extension php (le basename du fichier détermine le nom de l'api).

Lors du lancement d'un script, la variable $action est initialisée avec un objet de la classe Action. L'autoloader est initialisé, et l'intégralité des fonctions et méthodes de Dynacase peuvent être utilisées sans contrainte spécifique.