Dans cet article, nous aborderons la mise en place d’un service AMF en PHP avec la solution de Midnight Coders : Weborb PHP. Nous commencerons par créer un service rudimentaire pour aborder les méthode de service, les type de retour, les paramètres de méthodes, la portée des méthode, la gestion des erreurs et enfin, nous exploiterons l’héritage pour gérer plus « finement » l’organisation des services.

Installation

Rendez-vous sur le site de Midnight Coders et téléchargez la dernier version de Weborb PHP (J’utilise la 3.6). Vous devez disposer d’un compte pour le téléchargement(c gratuit )

l’installation est relativement simple, décompactez le zip dans votre dossier web, vous allez obtenir cette arborescence :

Les fichiers importants à retenir sont :

• /index.php : Vous donne accès à la console de Weborb pour tester vos services, si l’installation a bien fonctionné, elle est dès maintenant accessible
• /weborb.php : Il s’agit de la passerelle, nous reviendrons sur ce fichier un peu plus tard.
• /Services/ : L’endroit où vous allez passer beaucoup de temps, c’est là que sont rangés les services AMF.

Premier service AMF : SimpleService

Les services PHP se présentent toujours sous la forme d’un Classe PHP. Par convention, on nomme généralement le fichier avec le nom de la classe. Dans notre cas donc, nous allons créer un fichier SimpleService.php dans le dossier /Services qui contiendra une classe SimpleService.

1
2
3
4
5

<?php
  class SimpleService {
 
  }
?>

La classe se décompose ensuite en série de méthode qui remplirons chaque une un tâche spécifique, notre première méthode respectera la procédure de tout tutorial d’initiation en retournant une chaine « Bonjour Monde », nous appellerons la méthode « direBonjour ».

1
2
3
4
5
6
7
8
9
10

<?php
// Fichier /Services/SimpleService.php
class SimpleService {
 
	// retourn String("Bonjour monde")
	function direBonjour(){
		return "Bonjour monde";
	}
}
?>

Tester ces Services AMF : La console de Weborb

L’intérêt majeur d’utiliser Weborb PHP, c’est la console d’administration fournit, elle propose une serie d’exemple d’utilisation, et surtout une interface de gestion qui propose notamment :

• Management : Console de test des services
• CodeGen : Un générateur de code source en fonction du support (Ajax, Flex, Flash) et en fonction du framework (Cairgorm, Puremvc, api de base)

Pour accéder à la console, rendez vous à l’index.php de l’installation de Weborb via votre navigateur, vous devriez obtenir une vue qui ressemble à ça

Weborb PHP - Console introduction

Allez ensuite dans l’onglet Management > Services, dans le vollet de gauche, sont listès tous les services installés (Classes), vous pouvez afficher le détail des méthodes en cliquant sur le triangle gris à gauche du nom du service.

Aperçu des services dans Weborb PHP

Pour executer notre méthode, sélectionnez là puis cliquez simplement sur le bouton Invoke, vous devriez voir s’afficher « Bonjour monde » dans le volet de droite.

Quand vous modifiez un service, inutile de rafraichir la console Weborb via le bouton rafraichir du navigateur, un bouton refresh situé en bas du volet de gauche est prévu à cet effet

Les différents type de retour

Vous avez probablement remarqué que lors des test de méthode dans la console, le volet de gauche nous propose 3 colonnes, dans la première sont affichés les noms des résultats (Result), dans la seconde le type de données retournée (Dans l’exemple précédent « String ») et enfin dans la dernière colonne, la donnée retournée.

Nous allons donc voir maintenant quel type de retour propose Weborb.

Type Chaine

Premier type de retour, les type String, rien de particulier

Type numérique

Tous les types « numérique » retournés par Weborb sont retourné en type Number, ajoutez ces méthodes à notre SimpleService pour voir ça en action :

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

	// retourne Number(3.14)
	function retournFloat(){
		return (float)3.14;
	}
 
	// retourne Number(5)
	function retourneInt(){
		return (int)5;
	}
 
	// retourne Number(NaN)
	function retourneNaN(){
		return NAN;
	}
 
	// ATTENTION : retourne Number(0) !!!
	function retourneNaNAttention(){
		return floatval("n'est pas un nombre");
	}

Rien de particulier ormis le retour à 0 de la dernière méthode (dû à PHP) qui peut engendrer des effets de bord, si vous avez besoin d’un retour type Nan prévoyez un test côté serveur.

30
31
32
33
34

	// retourne Number(NaN)
	function retourneNaNOK(){
		$nan = "not a number";
		return (is_numeric($nan))?floatval($nan):NAN;
	}

Type Boolean

Le type le plus simple, retourne simplement un Boolean

36
37
38
39
40
41
42
43
44

	// retourne TRUE
	function retourneBoolTrue(){
		return TRUE;
	}
 
	// retourne FALSE
	function retourneBoolFalse(){
		return FALSE;
	}

Type Date

Pour l’échange de date, vous devez utiliser la classe DateTime de PHP.

46
47
48
49

	// retourne Date
	function retourneDate(){
		return new DateTime();
	}

Type Array

Le « type » array de php est également supporté et retourne des Array, mais uniquement si vos array PHP utilisent une indexation NUMERIQUE. Dans le cas contraire vous recevrez un type Object (que nous verrons dans la partie suivante)

51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

	// retourne Array
	function retourneArray(){
		return array("Chaine",3.14,"Autre Chaine",493);
	}
 
	// retourne Array : Dans ce cas de figure, 
	// le tableau est réindexé de 0 à 3
	function retourneArrayIndexSpe(){
		return array(
			2=>"Chaine",
			3=>3.14,
			7=>"Autre Chaine",
			1=>493
		);
	}

Vous obtenez ce type d’affichage dans le console.

Aperçu des retours type Array dans la console Weborb PHP

Si vous avez la version « Debug » du player Flash, il peut arriver qu’une erreur d’execution survienne quand vous selectionnez le Result dans le volet de résultat, ca n’a rien de bloquant.

Type Object

Enfin, c’est (pour le moment) de dernier type que nous verrons, le type Object. Coté php c’est assez simple, ca correspond aux array ayant une indexation non-numérique

67
68
69
70
71
72
73
74
75
76

	// retourne Object
	function retournObject(){
		return array(
			"id"=>1,
			"nom"=>"Bouvry",
			"prenom"=>"Stéphane",
			"age"=>30,
			"activites"=>array("Infographie","Développement")
		);
	}

Comme vous pouvez le constater, le type global est Object, ensuite on trouve les noms de propriétés avec les types correspondant.

Aperçu des retours de type Object

Nous y reviendrons dans la partie consacrés aux ValueObject, mais les Instances de classe « perso » se présentent sous la forme d’Object, même si le type est conservé

Conclusion sur les types

Au final, les types de retour disponibles sont certes limités, mais cette limite est principalement la conséquence des « liberté de typage » intrinsèque à PHP, si vous êtes exigeants à ce niveau, une batterie de test sera essentielle pour bâtir une application serveur stable. Après rien ne vous empêche de vous tourner vers une application basé sur java (blazeds par exemple), beaucoup plus fin à ce niveau.

Enfin, sachez que vous pouvez également utiliser vos propres type entre Flex et PHP, ce type de donnée sont généralement qualifiés de ValueObject et sera le sujet d’un prochain article

Paramètres de méthodes

Maintenant que nous savons ce que peut nous envoyer PHP, nous allons maintenant voir l’opération inverse, à savoir envoyer des données à PHP.

En raison du faible (pénible) typage de PHP, nous allons voir ensemble que la transmission de données est simple dans le principe, mais peut devenir un véritable casse-tête pour l’applicatif serveur, car PHP gobe tout et parfois n’importe comment. Pour tester l’envoi de données, nous allons créer une application Flex donc la fonction sera d’appeler les méthodes de notre service afin de voir comment transitent les données entre Flex et Weborb.

Pour cette partie, nous allons travailler sur un nouveau service , commencez par créer un fichier EnvoisDeDonnees.php dans le dossier service, puis nous allons créer une série de méthodes rudimentaire dont la tâche sera de retourner les données reçues en paramètre.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

<?php 
// Services/EnvoisDeDonnees.php
class EnvoisDeDonnees {
	function envoyerChaine( $chaine ){
		return $chaine;
	}
 
	function envoyerNombre( $nombre ){
		return $nombre;
	}
 
	function envoyerBooleen( $booleen ){
		return $booleen;
	}
 
	function envoyerDate( $date ){
		return $date;
	}
 
	function envoyerXML( $xml ){
		return $xml;
	}
 
	function envoyerArray( $array ){
		return $array;
	}
 
	function envoyerObjet( $objet ){
		return $objet;
	}
}
?>

Voyons la partie Flex, nous allons gérer une application simple qui va envoyer des données typées à notre méthode et voir ce que l’on reçois en retour. Copiez le code ci-dessous, je vous laisse le soin d’analyser le code pour comprendre le fonctionnement des RemoteObject.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
 
	<mx:Script>
		<![CDATA[
			import mx.rpc.events.InvokeEvent;
			import mx.collections.ArrayCollection;
			import flash.utils.describeType;
			import mx.rpc.events.FaultEvent;
			import mx.rpc.events.ResultEvent;	 
 
			// Stoque le détail du retour serveur
			[Bindable] public var retour:String;
 
			// Capte le retour du serveur
			private function getResult( result:ResultEvent ) :void {
				retour += "RESULT >>> " +result.result +"\n\n";
				retour += describeType(result.result);
			}
 
			// Capte les erreur
			private function getFault( fault:FaultEvent ) :void {
				retour += "ERREUR : " +fault.fault.faultString;
			}
 
			// Capte l'appel
			private function getInvoke( invoke:InvokeEvent ):void{
				retour = "INVOKE : " + invoke.message +"\n\n";
			}
 
			// Pour gérer l'Array
			[Bindable] public var arrayContent:Array = [
				"Stéphane",
				"Bouvry",
				1.86,
				true
			];
 
			[Bindable] public var objectContent:Object = {
				prenom:"Stéphane",
				nom:"Bouvry",
				taille:1.86,
				online:true
			};
 
		]]>
	</mx:Script>
 
	<mx:RemoteObject id="service"
		fault="getFault(event)"
		result="getResult(event)"
		invoke="getInvoke(event)"
		endpoint="http://exemples.jacksay.com/serviceAMF/weborb.php"
		destination="EnvoisDeDonnees"
	>
	</mx:RemoteObject>
 
	<mx:HBox width="100%" height="100%">
 
	<mx:VBox>
		<mx:HBox>
			<mx:Label text="String : " />
			<mx:TextInput id="champString" text="Valeur envoyée" />
			<mx:Button click="service.envoyerChaine(champString.text)" label="Envoyer"/>
		</mx:HBox>
 
		<mx:HBox>
			<mx:Label text="Number : " />
			<mx:TextInput id="champNumber" text="49.3" />
			<mx:Button click="service.envoyerNombre(Number(champNumber.text))" label="Envoyer" />
		</mx:HBox>
 
		<mx:HBox>
			<mx:Label text="Boolean : " />
			<mx:CheckBox id="champBoolean" selected="true" />
			<mx:Button click="service.envoyerBooleen(champBoolean.selected)" label="Envoyer" />
		</mx:HBox>
 
		<mx:HBox>
			<mx:Label text="Date : " />
			<mx:DateField id="champDate" selectedDate="{new Date()}" yearNavigationEnabled="true" />
			<mx:Button click="service.envoyerDate(champDate.selectedDate)" label="Envoyer" />
		</mx:HBox>
 
		<mx:HBox>
			<mx:Label text="Array : " />
			<mx:Button click="service.envoyerArray(arrayContent)" label="Envoyer" />
		</mx:HBox>
 
		<mx:HBox>
			<mx:Label text="Object : " />
			<mx:Button click="service.envoyerObjet(objectContent)" label="Envoyer" />
		</mx:HBox>
 
		<mx:HBox>
			<mx:Label text="XML : " />
			<mx:Button click="service.envoyerXML(describeType('donnèes'))" label="Envoyer" />
		</mx:HBox>
 
		<mx:Label fontWeight="bold" text="Appel d'un fonction qui n'existe pas" />
		<mx:Label text="Dans ce cas, le fault s'execute indiquant que la fonction n'existe pas" />
		<mx:HBox>
			<mx:Label text="Erreur (fonction n'existe pas) : " />
			<mx:Button click="service.nexistepas()" label="Envoyer" />
		</mx:HBox>
 
		<mx:Label fontWeight="bold" text="Trop de Paramètres" />
		<mx:Label text="Danger : PHP s'en fout, il ne garde que le premier, enjoy :P"/>
		<mx:HBox>
			<mx:Label text="Erreur (Trop de paramètre) : " />
			<mx:Button click="service.envoyerDonnees('arg1','arg2')" label="Envoyer" />
		</mx:HBox>
 
 
		<mx:Label fontWeight="bold" text="Paramètres envoyés Moisi" />
		<mx:Label text="Dans ce cas attention, le service reste silencieux..."/>
		<mx:HBox>
			<mx:Label text="Erreur (Type non supporté) : " />
			<mx:Button click="service.envoyerDonnees(Application.application)" label="Envoyer" />
		</mx:HBox>
 
 
	</mx:VBox>
 
	<mx:VBox width="100%">
		<mx:Label text="RETOUR : " fontWeight="bold"/>
		<mx:Text text="{retour}" />
	</mx:VBox>	
	</mx:HBox>
</mx:Application>

Voici un récapitulatif pour l’échange de type :

• String : Reçu comme une chaine de caractères
• Number (et autre type numérique) : Reçu comme un nombre
• Boolean : Reçu comme un Booléen
• Date : Reçu comme une date, le retour dans Flex est souvent taggé Object, mais c’est bien une Date
• Array : Reçu comme un array (indexation numérique)
• Object : Reçu comme un array (indexation non-numérique)
• XML : Reçu comme une chaine

Noter que PHP étant très « souple » (ce qui est un réel inconvénient), rien ne vous empêche d’envoyer une chaîne là ou côté PHP vous attendez un nombre, car malheureusement, vous ne pouvez pas gérer de typage fort en php, pour éviter d’éventuels problèmes, vous pouvez prévoir une batterie de test pour déterminer si les données reçues sont conformes à ce que vous attendez, cela représente un tâche énorme et laborieuse qui s’avérera indispensable si vos services sous dit « Ouvert ».

Si vous tentez de reproduire la partie serveur chez vous, vous allez rencontrer une alerte de sécurité, la fameuse erreur Sandbox, elle vous parle notamment du célébre fichier crossdomain.xml. Ce fichier est bien connu des personnes qui ont déjà mis en place des services distants, je ne vais pas en parler dans cet article, mais dans le cadre de vos tests, placer simplement un fichier « crossdomain.xml » à la racine de votre serveur web content ce script :

1
2
3
4

<?xml version="1.0"?>
<cross-domain-policy>
        <allow-access-from domain="*"/>
</cross-domain-policy>

Dans un contexte de prodution, il vous suffira de remplacer l’étoile par le nom du domaine où est situé votre application

Gérer la portée des méthodes

Weborb PHP prend en charge l’accès des méthodes, à savoir les tags private, public et protected.

• private : Mode le plus restrictif, l’accès à la méthode n’est autorisé qu’au sein de la classe.
• protected : L’accès à la méthode n’est autorisé qu’au sein de la classe et des classes qui héritent de cette classe.
• public : Accès libre à la méthode, notez que quand vous ne donnez pas d’indication de portée, l’accès est publique.

Vous pouvez copier le code qui suit pour vérifier le comportement de Weborb

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?php
// AccesService.php
class AccesService {
 
	// Executé normalement
	public function accesPublic(){
		return "Accès public";
	}
 
	// Affiche un dialogue d'erreur
	protected function accesProtected(){
		return "Accès protected";
	}
 
	// Affiche un dialogue d'erreur
	private function accesPrivate(){
		return "Accès private";
	}
}
?>

Remontée des erreurs

Weborb (et AMF de manière général) permet de gérer la remontée d’erreur vers Flex relativement proprement. Dans l’exemple précédent, nous avons vu que les erreurs de portée, étaient matérialisées dans weborb sous la forme d’un modal affichant l’erreur. Ce modal affiche en fait un FaultEvent, vous avons déjà capé ce genre d’erreur dans la première partie avec l’exemple d’un appel de méthode non référencée.

Vous pouvez également produire ce genre d’erreur dans vos services lors d’erreurs bloquantes qui surviennent durant l’exécution de vos services.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?php
// ThrowExemple.php
class ThrowExemple {
 
	/**
	 * Si la connection réussie, emet
	 * un ResultEvent contenant un Booléen,
	 * sinon emet un FaultEvent
	 *
	 * @return boolean
	 */
	public function connection(){
		if(mysql_connect("localhost","user","pass")){
			return true;
		} else {
			throw new Exception(mysql_error());
		}
	}
}
?>

Organisation des services

Si vous avez suivis ce tutoriel depuis le début, vous devriez avoir dans votre dossier services un nombre de fichier grandissant. C’est pourquoi je consacrerez un point sur l’arborescence des services dans Weborb. Ensuite nous parlerons de la grande oublié : la fonction constructeur, et nous terminerons sur l’utilisation de l’héritage

Rangez !

NdlA : Le titre de cette partie devrez faire doucement rire les gens qui me connaissent, mais pour les autres je le répète, il faut ranger (comme disait Walker).

Par exemple, ranger chaque service dans un dossier, cela peut simplifier les switch de version de service, c’est dans ce but que Weborb propose un fichier de configuration des services, ce fichier va indiquer quel service est situé à quel endroit, voyons cela.

Créez un dossier Ranger dans le dossier services de l’installation de Weborb, puis créez une simple classe de test dans la dossier fraichement créé.

1
2
3
4
5
6
7
8

<?php 
// services/Ranger/RangerCBien.php
class RangerCBien {
	function essais(){
		return "Bien rangé";
	}
}
?>

Dans le configuration de Weborb : /Weborb/WEB-INF/flex/remoting-config.xml, nous allons créer un nouveau point d’entrée à la fin du fichier (entre les balises service)

<?xml version="1.0" encoding="UTF-8"?>
<service id="remoting-service" class="flex.messaging.services.RemotingService" messageTypes="flex.messaging.messages.RemotingMessage">
 
    <adapters>
        <adapter-definition id="php-object" default="true"/>
    </adapters>
 
    <default-channels>
        <channel ref="my-amf"/>
        <channel ref="my-rtmp"/>
        <channel ref="my-amf-absolute"/>
    </default-channels>
 
     <!-- (...) Services déclaré par defaut par weborb -->
 
    <!-- Nouveau point d'entrée -->
    <destination id="Rangez">
        <properties>
            <source>Ranger.RangerCBien</source>
        </properties>
    </destination>
 
</service>

J’ai volontairement choisi un nom de service différent que le nom de la classe, l’id présent dans le fichier de configuration correspond à la propriété destination dans flex :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" initialize="init()">
	<mx:Script>
		<![CDATA[
			private function init() :void {
				service.essais();
			}
		]]>
	</mx:Script>
	<mx:RemoteObject id="service"
		endpoint="http://exemples.jacksay.com/serviceAMF/weborb.php"
		destination="Rangez"
		result="trace(event)"
		fault="trace(event)"
	/>
</mx:Application>

C’est aussi simple que ca, pour basculer d’un service à l’autre, il vous suffit ensuite de modifier le fichier de configuration, vous n’avez rien a changer coté client

Rien ne vous empêche de supprimer les services déclaré par weborb, cela aura pour conséquence de faire planter la console (mais vos service déclarés seront toujours opérationnel)

Le constructeur

Dans les exemples précédents, je me suis appliqué à créer des services (des Classes PHP) qui ne disposaient pas de méthode constructeur (__construct). C’est volontaire car son fonctionnement est relativement spécifique. Créons un nouveau service :

1
2
3
4
5
6
7
8
9
10
11
12

<?php 
// fichier /Services/ExempleConstructeur.php
class ExempleConstructeur {
	function __construct(){
		return "appel du constructeur";
	}
 
	function methodeService(){
		return "méthode service";
	}
}
?>

En testant ce service dans la console de Weborb, vous pouvez constater que le fonctionnement du constructeur se comporte exactement comme une méthode traditionnelle. A première vu oui, mais nous allons voir ce qui se passe plus précisement dans l’exemple suivant, modifier le service de cette façon :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php 
// fichier /Services/ExempleConstructeur.php
class ExempleConstructeur {
 
	private $donnees = "Valeur par defaut";
 
	function __construct(){
		$this->donnees = "Passage par le constructeur constaté";
	}
 
	function methodeService(){
		return $this->donnees;
	}
}
?>

En testant votre méthode methodeService(), vous pouvez constater que le constructeur a bien été appelé AVANT l’exécution de la méthode !

Il est courant d’établir la connection au serveur de base de donnée dans le constructeur pour cette raison.

Héritage

Cela nous emmène tout naturellement à l’héritage qui va vous permettre de mieux organisez vos services en centralisant le code commun à tous vos services dans la classe parente.

Dans l’exemple si dessous, la classe parent définit des méthodes d’accès à une base de donnée et établis la connexion dans le constructeur, la classe enfant est par conséquent allégée et ne regroupera que les méthodes orientées métier, les accès à la base se feront via les méthodes héritées du parent. Si vous êtes parano, n’hesitez pas à sécurisé la classe parente en la taggant « abstract » et en définissant ces méthodes « protected »

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<?php 
// fichier /Service/ServiceParent.php
abstract class ServiceParent {
 
	protected $statusDB = "Disconnected";
 
	function __construct(){
		$this->connectionDB();
	}
 
	protected function connectionDB(){
		$this->statusDB = "Connected";
	}
 
	protected function envoyerRequete($requete){
		if( $result = mysql_query($requete) ){
			return $result;
		} else {
			throw new Exception("Erreur de requète");
		}
	}
}
?>

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php 
// fichier /Service/ServiceEnfant.php
require_once 'ServiceParent.php';
class ServiceEnfant extends ServiceParent {
	public function enregistrementDonnees(){
		try {
			return $this->envoyerRequete("REQUETE");
		} catch ( Exception $e ){
			throw new Exception("Impossible d'enregister la données. ".$e->getMessage());
		}
	}
}
?>

Ce système est d’expérience une bonne pratique, notamment pour le travail en équipe, en effet il est préférable de disposer de plusieurs petites classes que d’une seule blindée de méthodes, lors de l’identification d’un bug votre travaille sera facilité car pour rappel, une erreur de code dans une méthode fait planter la classe ENTIERE.

Ensuite l’organisation des classes enfants est libre et rien ne vous empêche de hiérarchiser des classes sur plusieurs niveaux.

Concusion

Voilà, vous disposez maintenant des bases nécessaires pour réaliser des services en PHP, à vos claviers

Retrouvez la suite de ce tutoriaux : Weborb PHP : Les values Objects