Tutoriel Raydium: Utiliser PHP

Ref: RaydiumTutoriels

TutorielPHP

Mise en place :

Utiliser la source complète du tutoriel TutorielUtiliserLaPhysique.

Problèmatique :

Développer une application 3D saine demande de la rigeur, sans compter que l'écriture (et donc le langage utilisé pour cette écriture) doit être la plus rapide possible. C'est une des raisons qui fait que Raydium est écrit en C.
Mais certaines parties de l'application sont délicates à réaliser sous ces contraintes, comme par exemple la logique du jeu ("gameplay"), qui nécessite de pouvoir tester beaucoup de choses différentes rapidement (sans recompilation ni relancement de l'application). Le développeur de l'application peut également souhaiter vouloir avoir accès rapidement à certaines informations de son application en plein fonctionnement, voire même changer son comportement au vol.
Dernier point, le langage C n'offre que très peu d'outils et de fonctionnalités avancées (ça n'est pas son rôle), contrairement à ce que proposent la plupart des langages scriptés.
Raydium offre donc la possibilité au développeur d'utiliser le langage PHP (version 5) au sein même des applications.

Raydium et PHP :

RayPHP permet :
- d'exporter des fonctions et des variables de l'application dans PHP
- de faire appel à un script PHP depuis une application Raydium
- d'écrire des morceaux "vivants" de l'application Raydium en PHP
- d'utiliser des fonctionnalités puissantes de PHP dans l'application Raydium (bases de données SQL, accès à des ressources réseau du type HTTP, FTP, services webs, utilisation d'XML, compression, ...)
- de coder en PHP dans la console ingame (touche ², sous la touche ESC).

Raydium utilise déjà en interne PHP pour différents usages (téléchargement automatique de données, par exemple, cf client R3S).

l'API RayPHP par l'exemple :

L'interface RayPHP supporte les types suivants :

Entiers
Flottants
Chaînes
Caractères signés

Les tableaux ne sont pas (encore) supportés.

Enregistrement de variables C dans PHP

Par défaut, l'isolation entre PHP et votre application C est totale : les scripts PHP ne peuvent modifier vos "variables C" et vice-versa. Pour permettre ce genre de manipulation ("enregistrement"), vous n'avez qu'une seule fonction à manipuler dans votre programme Raydium :

int raydium_register_variable(void *addr, int type, char *name);

Cette fonction vous demande 3 arguments : la variable que vous souhaitez enregister (son adresse, précisément), son type, et le nom sous laquelle vous souhaitez l'exporter dans PHP.
Le type est à choisir dans la liste suivante :

#define RAYDIUM_REGISTER_INT                    1
#define RAYDIUM_REGISTER_FLOAT                  2
#define RAYDIUM_REGISTER_STR                    3
#define RAYDIUM_REGISTER_SCHAR                  6
// valeurs constantes (interger et float)
#define RAYDIUM_REGISTER_ICONST                 4
#define RAYDIUM_REGISTER_FCONST                 5

Ces types sont en fait les correspondances des type C suivant : int, float, char * et signed char. Attention à ne pas utiliser d'autres types que ceux là.
Exemples :

int score;
float position_x;
char nom[128];
 
raydium_register_variable(&score, RAYDIUM_REGISTER_INT, "score");
raydium_register_variable(&position_x, RAYDIUM_REGISTER_FLOAT, "posx");
raydium_register_variable(nom, RAYDIUM_REGISTER_STR, "score");

(Essayez de ne pas mettre de & devant les variables de type char *)
Attention, RayPHP n'effectue aucune vérification sur la longueur des chaînes manipulées dans les scripts PHP, pensez à faire la vérification du coté de PHP s'il y'a un risque.
Notez que PHP travaille sur des copies de vos variables, ces dernière n'étant modifiées qu'a la fin du script PHP.

Il vous est possible de supprimer la dernière variable enregistrée, grâce à void raydium_register_variable_unregister_last(void).
Par exemple, pour annuler les enregistrements précédents, utilisez :

raydium_register_variable_unregister_last();
raydium_register_variable_unregister_last();
raydium_register_variable_unregister_last();

La complétion de commandes de la console ingame de Raydium est capable de proposer vos propres variables à l'utilisateur, sans manipulation particulière autre que l'utilisation de la touche "Tab".

Enregistrement de fonctions C dans PHP

Si vous souhaitez pouvoir faire appel à des "fonctions C" depuis vos scripts PHP, vous devrez appliquer le même principe qu'avec les variables : enregistrer vos fonctions. Cette opération est à peine plus complexe qu'avec les variables.
La princiaple différence est liée au fait qu'il faut passer par deux étapes distinctes : création du "wrapper", et l'enregistrement.

Wrapper PHP

PHP doit "enrober" votre fonction pour y placer du code avant et après son exécution. Raydium offre des macros qui automatisent une grande partie de cette étape.
Ces macros sont construites selon le profil suivant :
PHP_retour_arguments(fonction), ou retour est le type de retour de votre fonction, arguments la liste des types de ses arguments et fonction le nom de la fonction que vous souhaitez exporter.
Imaginez une fonction telle que :

int testphp(int a, int b)
{
 return a+b;
}

Si vous souhaitez exporter cette fonction, déclarez un wrapper de cette manière :

PHP_i_ii(testphp)

On retrouve bien le premier i (type du retour de la fonction) et ses deux arguments de type entier notés ii. Vous pouvez placer ce wrapper à n'importe quel endroit après la déclaration de votre fonction, même si en général, pour des raisons de lisibilité, on préfère écrire le tout comme ceci :

int testphp(int a, int b)
{
 return a+b;
} PHP_i_ii(testphp)

Notez qu'il n'est pas nécessaire d'ajouter un ; à la fin de la création du wrapper.

Les autres lettres disponibles sont v pour void, f pour float, s pour les char * (string).
Il existe un autre type plus complexe, svaria, destiné aux arguments variadiques précédés par une chaîne (notation style printf(char *, ...) pour les fonctions au nombre d'argument variable.

La liste des wrappers disponibles est visible dans le fichier raydium/php_wrappers.c des sources de Raydium.

Attention ! Lorsque vous faîtes appel à une fonction C qui doit écrire dans une chaine de caractères PHP, il est nécessaire de s'assurer avant l'appel que cette variable est assez "grande", sous peine de plantage immédiat :

$proxy = str_pad('', 256); // on "réserve" 256 caractères
raydium_parser_db_get("Generic-Proxy", $proxy, ""); // appel de la fonction C qui écrit dans $proxy

Enregistrement du wrapper

Une fois le wrapper créé, il ne reste plus qu'a enregistrer la fonction auprès de Raydium, avec une syntaxe simple :

raydium_register_function(C2PHP(testphp),"testphp");

Le premier argument est le nom de la fonction que vous souhaitez exporter, encadré par la macro C2PHP() (qui va traduire le nom de la fonction vers le nom du wrapper), et le second est le nom sous lequel vous souhaitez exporter la fonction dans PHP. Ces deux valeurs peuvent être différentes, dans le but de simplifier le nom de la fonction dans PHP, ou pour éviter un conflit avec une fonction déjà existante dans PHP (exemple : kill()).

Appel d'un script PHP depuis une application C

RayPHP offre une fonction simple destinée à exécuter ponctuellement un script PHP.
Exemple :

raydium_php_exec("playlist.php");

Si vous souhaitez échanger des informations entre votre application et le script, enregistrez des variables destinées à cet effet :

char newfile[256];
raydium_register_variable(newfile,RAYDIUM_REGISTER_STR,"music_file");
raydium_php_exec("playlist.php");
raydium_register_variable_unregister_last();
raydium_sound_load_music(newfile);

Dans cet exemple, le script playlist.php va devoir renseigner la variable $music_file avec le nom d'un fichier .ogg (en cherchant l'ensemble des fichiers de ce type dans un répertoire ou depuis une requête SQL, par exemple), ce qui va modifier la variable newfile dans l'application.

Exemple pour ce script PHP :

$dir=opendir("music/");
if($dir==false) die("Cannot find \"music/\" directory...");
 
unset($tbl);
while (($file = readdir($dir)) != false)
    if(substr($file,-4) == ".ogg")
        $tbl[]=$file;
  
$music_file="music/".$tbl[rand(0,count($tbl)-1)]; 
echo "Now playing $music_file ..."; // affichage dans la console de Raydium

Les échanges peuvent bien sûr se faire dans l'autre sens (le script PHP récupère une variable dont la valeur est définie dans l'application C avant l'appel du script) en suivant exactement le même principe.

Utiliser PHP dans la console

En affichant la console dans une application Raydium (touche '²' sous la touche Esc), vous disposez d'un accès direct à RayPHP. Toute instruction entrée dans cette console est interprétée par PHP.
Exemples :

echo testphp(2,2)
4
$test="Hello World !" ; echo $test
Hello World !
echo $test
raydium_sound_load_music("memak1.ogg")
echo $_ENV["HOSTNAME"]
Julien
system("ls")
phpinfo()
...

Notez que chaque "ligne" dispose de son propre interpréteur. Il est impossible de conserver une variable d'une ligne sur l'autre, par exemple.
Le ; en fin de ligne n'est pas obligatoire en cas d'instruction "simple".

Vous pouvez utiliser certains modificateurs en début d'instruction :

/ : commande non PHP (envoyée directement à l'application, voir raydium_console_gets_callback et/ou le code source du RaydiumModler, qui utilise ce méchanisme).
> : lancer le script PHP donné en argument (équivalent à "include("...")).
! : lancer le script (qui doit contenir une séquence de commande [PHP ou non]).

Notez que la console dispose d'une aide à la saisie ("complétion") accessible grâce à la touche "tabulation".

Et les autres modules PHP ?

Si vous souhaitez disposer d'autres fonctions de PHP5 que celles fournie de base par Raydium, il suffit d'activer ces extensions à la compilation de PHP (cf section "PHP" de InstallRaydium). Aucune autre manipulation n'est à effectuer au sein de Raydium.
Attentions aux dépendances créées par ce genre de manipulations.
La liste des fonctions et des extension est disponible sur le site de PHP à cette adresse http://www.php.net/manual/fr/funcref.php

Tutoriel 5: TutorielPhysiqueEtReseau