Fonctions d'émulation pour bac à sable


AVANT PROPOS

Cela va paraître fastidieux, mais beaucoup moins que de déboguer à l'éveugle: si vous prenez le temps de préparer le code d'émulation spécifique à votre script, vous considérerez le bac à sable comme un outil de débogage, il suffira de copier le script tel quel pour le tester ! chaque petit changement, chaque test de variable que vous pouvez insérer à la volée dans le code sera simplifié. Les autres alternatives sont pires
NB: tout n'est pas émulé, dans ce cas, il faudra modifier quand même le code sur les fonctions non émulées pour les remplacer par une valeur, ou les mettre en commentaire afin de ne pas provoquer d'erreur lors de l'éxécution dans le bac à sable.
C'est pour cette raison que certaines fonctions émulées seront prévues pour juste éviter ce genre d'erreur, ceci sera précisé quand elles seront documentées (un exemple : setValue qui change la valeur d'un périphérique ne peut pas être testée hors utilisation réelle, sa fonction d'évaluation ne fait donc rien à part éviter les messages d'erreur, par contre il peut indiquer dans le résultat - dans le Bac à Sable - que la commande a été comprise)


Les fonctions suivantes doivent être, si elles sont utilisées dans votre script, copiées / collées dans un fichier php qui commence par le tag php <?php (utilisez Notepad++), complétées par les noms des variables et valeurs éventuelles, puis se terminer par un grand trait sous forme de commentaire, exemple

<?php
// ====================== fonctions d'émulation =========================

fonction1
fonction2
.../...

// ====================== votre script dessous ==========================

Après avoir ouvert le Bac à Sable; Vous collerez le contenu de ce fichier, spécifique à votre script.
Vous collerez ensuite votre script évidemment sans le <?php de début et vous remplacerez les fonctions non émulées par leur valeur !

Application Pratique (comment contruire le fichier d'émulation)

Collez dans votre bac à sable les lignes ci dessus, en supprimant bien entendu fonction1, fonction2, .../...
puis dessous, insérez/commencez votre script SANS le tag html <?php qui figure déjà en début de code.
Mettez ensuite de côté le fichier d'émulation: il ne correspond qu'à un seul script en particulier, notamment par les variables et les valeurs qu'il contient.

astuce

Au lieu de rechercher les fonctions spécifiques, il est souvent plus simple de simplement exécutez le code: tant qu'il reste des fonctions Eedomus non émulées, vous aurez un message FATAL ERROR pour "fonction non définie", vous copiez/collez alors la fonction d'émulation correspondante dans la partie émulation puis la complétez par les variables et valeurs requises. Refaite l'opération jusqu'à obtention d'un résultat correct.
NB: lors d'un debogage, pour connaître une valeur de variable, faites un echo et encadrez la de manière explicites pour indiquer que cette indication ne fera PAS partie du XML généré, un peu comme dans l'instruction émulée setValue

fonction non émulée

Si une fonction n'est pas encore émulée, il faudra, dans le code, la remplacer par sa valeur, vous prendrez soin de repérer le changement en l'encadrant avec des commentaires, si vous avez toutes les fonctions émulées, il suffira de copier/coller tel quel le script pour test

fichier exemple

Voir ICI un exemple d'un fichier d'émulation, pour le script Mobile Alerts, vous aurez dans ce fichier la partie émulation, complétée avec des variables et des exemples de leurs valeurs, il n'y manque que le code source HTML et le code du script (explications dans le fichier)

Fonctions émulées

 GetArg   httpQuery   saveVariable   deleteVariable   loadVariable   setValue   getValue   getRooms
(d'autres fonctions seront rajoutées)

GetArg

Les appels

essentiellement les VAR renseignés dans la fenêtre de configuration de votre périphérique, appelés dans l'URL de type:
http://localhost/script/?exec=plugin.php&var1=[VAR1]&var2=[VAR2]&var3=[VAR3]
les noms de variable étant indiqués ici comme var1, var2 et var3, il faudra donc remplacer ces variables et les valeurs correspondantes de la fonction décrite ci-dessous par VOS variables et VOS valeurs.
A ces 3 VAR est ajouté la variable eedomus_controller_module_id qui permet de récupérer l'ID du périphérique appelant, si vous l'utilisez, indiquez le dans la ligne correspondante, ici on a donné comme exemple 1234567
=> Les variables non nécessaires peuvent être laissées telles quelles, ou la ligne correspondante supprimée.

Le code

function getArg($var) {
if ($var=="var1") { $return = "valeur1";}
if ($var=="var2") { $return = "valeur2";}
if ($var=="var3") { $return = "valeur3";}
if ($var=="eedomus_controller_module_id") { $return = 1234567;}
return $return;
}

httpQuery

Emulation simplifiée (on ne contrôle pas l'URL) : on va se contenter d'un seul appel dans le code, pour un seul retour qui contiendra le code source de l'URL appelé, il faudra donc récupérer directement ce code source en allant ouvrir l'URL dans votre navigateur, puis menu bouton droit pour afficher le code source, sélectionner tout (Ctrl A), copier (Ctrl C) puis collez le (Ctrl V) à l'endroit indiqué.

Le code

function httpQuery($url) {
// coller dans l'espace libre ci dessous le code source de la page HTML appellée
$return=<<<'pageHTML'



pageHTML;
return $return;
}

saveVariable, deleteVariable, loadVariable

Ces trois instructions sauvegardent, suppriment ou chargent le contenu d'une variable.
On part sur le principe que les noms de variables enregistrées sont les mêmes (sans le signe $):
$ma_variable (dans le code) 'ma_variable' (enregistrée)

saveVariable

on remplace dans le code, le nom de la (des) variable(s) utilisées (3 fois par variable)
function saveVariable($variable_name, $variable_content) {
if ($variable_name=="ma_variable1") { global $ma_variable1; $ma_variable1 = $variable_content;}
if ($variable_name=="ma_variable2") { global $ma_variable2; $ma_variable2 = $variable_content;}
}

deleteVariable

on remplace dans le code, le nom de la (des) variable(s) utilisées (3 fois par variable)
function deleteVariable($variable_name) {
if ($variable_name=="ma_variable1") { global $ma_variable1; $ma_variable1 = NULL;}
if ($variable_name=="ma_variable2") { global $ma_variable2; $ma_variable2 = NULL;}
}

loadVariable

ATTENTION Si une variable, dans le code, est appelée par un loadVariable avant un saveVariable la concernant, elle doit être auparavant initialisée, sinon, le code retournera NULL
En fait, il n'y a pas d'enregistrement réel, chaque exécution de code "remet les compteurs à zero", pour simuler cet 'enregistrement', on prendra donc soin d'initialiser cette variable, on peut le faire juste avant la fonction loadVariable, par exemple si la variable devait contenir l'heure d'il ya 20 minutes, juste avant la fonction, on indiquera :
$ma_variable = time() - 20*60;

on remplace dans le code, le nom de la (des) variable(s) utilisées (3 fois par variable), en ayant donc pris soins, avant, d'initialiser la(les) variable(s) si nécessaire.

Le code

// si nécessaire
$ma_variable1 = valeur1;
$ma_variable2 = valeur2;
//
function loadVariable($variable_name) {
if ($variable_name=="ma_variable1") { global $ma_variable1; $return = $ma_variable1;}
if ($variable_name=="ma_variable2") { global $ma_variable2; $return = $ma_variable2;}
return $return;
}

setValue

Fonction qui affiche pour contrôle la valeur qui serait envoyée au périphérique (ID), cet affichage n'apparait bien entendu pas dans l'éxécution réelle du code qui modifiera la valeur du périphérique d'ID correspondant.
function setValue($ID, $value) {
echo "\n=====contrôle débogage======\n"; // retour ligne et double trait pour repérer le contrôle débogage
echo "Contrôle Débogage, ";
echo "le périphérique ID " . $ID;
echo " recevra la valeur: " . $value;
echo "\n====/contrôle débogage======\n"; // retour ligne et double trait pour repérer la fin de contrôle débogage
}

getValue

Emulation simplifiée (on ne contrôle pas l'ID) : on va se contenter d'un seul appel dans le code, pour un seul retour qui contiendra le tableau des valeurs d'un périphérique, comme ici, seul le code exécuté sur Eedomus pourra le renvoyer, il faudra donc construire le tableau comme indiqué ci-après.

Le code

function getValue($ID,$value_text) {
$tableau = array(
    "full_name" => "",
    "value" => "",
    "value_type" => "",
    "change" => "",
    "pending_action" => "",
    "unit" => "",
    "icon" => ""
);
if ($value_text) {$texte = array(
    "value_text" => ""
);
$tableau = array_merge ($tableau, $texte);
}
$return = $tableau;
return $return;
}

Construire le tableau

Ne complétez que les valeurs => "" utiles du périphérique testé, laisser tel quel pour les valeurs que vous ne récupérerez pas dans le code,
ci-dessous, vous avez des valeurs en exemple et les explications

"full_name"=> "nom du périphérique", // full_name: la pièce est indiquée
"value"=> "15.4", // valeur texte, nombre
"value_type"=> "float", // type : float, string, list
"change"=> "2018-03-01 19:57:03", // date de la mesure AAAA-MM-JJ HH:MM:SS
"pending_action"=> "", // non documenté (valeur en attente ?)
"unit"=> "°C", // Unité
"icon"=> "/img/mdm/01/windspeed.png", // url relatif de l'icône
"value_text" => "ON" // (si $value_text est à true) description de la valeur du périphérique

Modification du code pour plusieurs ID

On va dupliquer le code de construction du tableau avec un conditionnel sur l'ID :
function getValue($ID,$value_text) {

// 1er ID
if ($ID == "ID1"){
$tableau = array(
    "full_name" => "",
    "value" => "",
    "value_type" => "",
    "change" => "",
    "pending_action" => "",
    "unit" => "",
    "icon" => ""
);
if ($value_text) {$texte = array(
    "value_text" => ""
);
$tableau = array_merge ($tableau, $texte);
}
}
// suivants
elseif ($ID == "ID2"){
$tableau = array(
    "full_name" => "",
    "value" => "",
    "value_type" => "",
    "change" => "",
    "pending_action" => "",
    "unit" => "",
    "icon" => ""
);
if ($value_text) {$texte = array(
    "value_text" => ""
);
$tableau = array_merge ($tableau, $texte);
}
}

$return = $tableau;
return $return;
}
NB : il faut dans ce cas renseigner les ID ! (par exemple, ceux renseignés en GetArg)

getRooms

Emulation simplifiée (on ne contrôle pas l'ID) : on va se contenter d'un seul appel dans le code, pour un seul retour qui contiendra un tableau avec la pièce d'un périphérique, comme ici, seul le code exécuté sur Eedomus pourra le renvoyer, il faudra donc construire le tableau en indiquant la pièce à récupérer dans le code. ATTENTION le tableau ici n'est prévu que pour deux pièces.
function getRooms($ID) {
$return = array([
    "room_id" => "",
    "room_name" => "",
    "img" => ""
],[
    "room_id" => "",
    "room_name" => "",
    "img" => ""
]);
return $return;
}