Subversion Repositories Applications.framework

Rev

Rev 229 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
229 jpm 1 
<?php
2 
/**
232 jpm 3 
 * Classe principale gérant les services web de type (@link(REST, http://fr.wikipedia.org/wiki/Rest).
4 
 *
5 
 * Elle contient  :
6 
 *  - les constantes indiquant les différentes (@link(méthode HTTP, http://fr.wikipedia.org/wiki/Http) prises en compte.
7 
 *  - les @link(codes HTTP des réponses, http://fr.wikipedia.org/wiki/Liste_des_codes_HTTP)
8 
 *
9 
 * Ce serveur REST accepte 4 types de méthodes HTTP : GET, PUT, POST, DELETE.
10 
 * GET et POST ne pose généralement pas de problème pour les clients HTTP mais ce n'est pas forcément le cas pour PUT et DELETE.
11 
 * Vous pouvez donc pour réaliser :
12 
 *  - DELETE : utiliser la méthode POST avec action=DELETE dans le corps de la requête.
13 
 *  - PUT : utiliser la méthode POST avec une url ne contenant aucune indication de ressource.
14 
 * Une autre solution consiste à utiliser n'importe quelle méthode et à ajouter l'entête "X_HTTP_METHOD_OVERRIDE" avec pour
15 
 * valeur le nom de la méthode que vous souhaitez utiliser. Exemple d'entête : "X_HTTP_METHOD_OVERRIDE: PUT".
16 
 * Exemple : <code>curl -v -v -H "X_HTTP_METHOD_OVERRIDE: DELETE" "http://www.mondomaine.org/services/apiVersion/[mon-service]/"</code>
17 
 * Cela fonctionne avec Apache.
18 
 *
19 
 * Les classes des services web doivent avoir un nom au format ChatMot "MonService" et être appelée dans l'url par le même nom
20 
 * en minuscule où les mots sont séparés par des tirets "mon-service".
21 
 *
229 jpm 22 
 * Paramètres liés dans config.ini :
23 
 *  - serveur.baseURL
232 jpm 24 
 *
229 jpm 25 
 * Encodage en entrée : utf8
26 
 * Encodage en sortie : utf8
27 
 *
28 
 * @category	Php 5.2
232 jpm 29 
 * @package	Framework
229 jpm 30 
 * @author		Jean-Pascal MILCENT <jpm@tela-botanica.org>
232 jpm 31 
 * @copyright	Copyright (c) 2010, Tela Botanica (accueil@tela-botanica.org)
32 
 * @license	GPL v3 <http://www.gnu.org/licenses/gpl.txt>
33 
 * @license	CECILL v2 <http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt>
34 
 * @version	$Id$
35 
 * @link		/doc/framework/
229 jpm 36 
 */
37 
// TODO : gerer les retours : dans ce controleur : code retour et envoi ...
38 
class Serveur {
39 
 
40 
	/** Nom de la méthode appelée dans un service pour éxécuter une requête de type GET. */
232 jpm 41 
	const METHODE_GET = 'consulter';
229 jpm 42 
 
43 
	/** Nom de la méthode appelée dans un service pour éxécuter une requête de type POST. */
232 jpm 44 
	const METHODE_POST = 'modifier';
229 jpm 45 
 
46 
	/** Nom de la méthode appelée dans un service pour éxécuter une requête de type DELETE. */
232 jpm 47 
	const METHODE_DELETE = 'supprimer';
229 jpm 48 
 
49 
	/** Nom de la méthode appelée dans un service pour éxécuter une requête de type PUT. */
232 jpm 50 
	const METHODE_PUT = 'ajouter';
229 jpm 51 
 
232 jpm 52 
	/** Code HTTP 200 indiquant le succès de l'accès à un service web par la méthode GET.
53 
	 * L'utiliser lors d'une requète de type GET (consulter) pour indiquer le succès de l'opération.
54 
	 * Sera renvoyée par défaut par PHP. */
55 
	const HTTP_CODE_OK = '200';
229 jpm 56 
 
232 jpm 57 
	/** Code HTTP 201 indiquant que l'accès à un service web est un succès et que la ressource a été créée ou modifié.
58 
	 * L'utiliser lors d'une requète de type PUT (ajouter) ou POST (modifier) pour indiquer le succès de l'opération. */
59 
	const HTTP_CODE_CREATION_OK = '201';
60 
 
61 
	/** Code HTTP 204 indique que l'accès à un service web est un succès et qu'il n'y a pas de contenu à renvoyer.
62 
	 * L'utiliser lors d'une requète de type DELETE (supprimer) pour indiquer le succès de l'opération. */
63 
	const HTTP_CODE_SUPPRESSION_OK = '204';
64 
 
65 
	/** Code HTTP 400 indique que les paramètres envoyés au service contiennent des erreurs.
66 
	 * L'utiliser pour indiquer l'échec de l'accès au service. La réponse pourra contenir un message expliquant la source
67 
	 * de l'erreur. */
68 
	const HTTP_CODE_MAUVAISE_REQUETE = '400';
69 
 
70 
	/** Code HTTP 401 indiquant que l'accès à un service web est refusé car l'authentification (obligatoire) a échoué pour
71 
	 * accéder à la ressource. */
72 
	const HTTP_CODE_ACCES_NON_AUTORISE = '401';
73 
 
74 
	/** Code HTTP 404 indiquant que la ressource indiquée par l'url est introuvable. */
75 
	const HTTP_CODE_RESSOURCE_INTROUVABLE = '404';
76 
 
77 
	/** Code HTTP 405 indiquant soit :
78 
	 *  - que le service web ne possède pas d'accès la ressource correspondant à la méthode HTTP employée.
79 
	 *  - que la méthode HTTP enployée n'est pas en accord avec la ressource indiquée par l'url. */
80 
	const HTTP_CODE_METHODE_NON_AUTORISE = '405';
81 
 
82 
	/** Code d'erreur HTTP 409 indiquant qu'un conflit est survenu vis à vis de la ressource.
83 
	 * Par exemple, essayer de créer deux fois la même ressource ou bien tenter de modifier une ressource qui a été modifiée par
84 
	 * ailleurs. */
85 
	const HTTP_CODE_CONFLIT = '409';
86 
 
87 
	/** Code HTTP 411 indiquant que des paramètres passés dans le contenu de la requête sont nécessaires au service. */
88 
	const HTTP_CODE_CONTENU_REQUIS = '411';
89 
 
90 
	/** Code d'erreur HTTP 500 Internal Server Error.
91 
	 * L'utiliser quand le serveur ou un service soulève une erreur ou une exception. */
92 
	const HTTP_CODE_ERREUR = '500';
93 
 
94 
	/** Les paramètres de configuration dynamiques internes au serveur.
95 
	 * @var array */
96 
	private static $config = array();
97 
 
98 
	/** La méthode de la requête HTTP utilisée.
99 
	 * @var string */
229 jpm 100 
	private $methode = 'GET';
101 
 
232 jpm 102 
	/** Le contenu brut du corps de la requête HTTP (s'il y en a).
103 
	 * @var array */
104 
	private $requeteDonnees = null;
105 
 
106 
	/** Le contenu sous forme de tableau de paires clés-valeurs du corps de la requête HTTP (s'il y en a).
107 
	 * @var array */
108 
	private $requeteDonneesParsees = null;
229 jpm 109 
 
110 
	/** Version de l'API demandée.
232 jpm 111 
	 * Ex. http://www.mondomaine.org/services/[apiVersion]/mon-service/
112 
	 * @var mixed Généralement deux nombres séparés par un point. Ex. : 1.0
229 jpm 113 
	 */
114 
	private $apiVersion = null;
115 
 
116 
	/** Nom du service demandé.
232 jpm 117 
	 * Ex. http://www.mondomaine.org/services/apiVersion/[mon-service]/
118 
	 * @var string par défaut vaut null.
229 jpm 119 
	 */
232 jpm 120 
	private $service = null;
229 jpm 121 
 
232 jpm 122 
	/** Morceaux de l'url servant à préciser la ressource concerné pour le service demandé.
123 
	 * Ex. http://www.mondomaine.org/services/apiVersion/mon-service/[maRessource/maSousResource...]
124 
	 * @var array
229 jpm 125 
	 */
232 jpm 126 
	private $ressources = array();
229 jpm 127 
 
232 jpm 128 
	/** Partie de l'url situé après le '?' servant à paramétrer le service demandé.
129 
	 * Ex. http://www.mondomaine.org/services/apiVersion/mon-service?monParametre1=maValeur1&monParametre2=maValeur2
130 
	 * @var array
229 jpm 131 
	 */
132 
	private $parametres = array();
133 
 
134 
	/** Codes HTTP. */
135 
	private static $http10 = array(
232 jpm 136 
		self::HTTP_CODE_OK => 'OK',
137 
		self::HTTP_CODE_CREATION_OK => 'Created',
138 
		self::HTTP_CODE_SUPPRESSION_OK => 'No Content',
139 
		self::HTTP_CODE_MAUVAISE_REQUETE => 'Bad Request',
140 
		self::HTTP_CODE_ACCES_NON_AUTORISE => 'Unauthorized',
141 
		self::HTTP_CODE_RESSOURCE_INTROUVABLE => 'Not Found',
142 
		self::HTTP_CODE_METHODE_NON_AUTORISE => 'Method Not Allowed',
143 
		self::HTTP_CODE_CONFLIT => 'Conflict',
144 
		self::HTTP_CODE_CONTENU_REQUIS => 'Length Required',
145 
		self::HTTP_CODE_ERREUR => 'Internal Server Error'
229 jpm 146 
	);
147 
 
148 
	/**
149 
	 * Analyse les données envoyées au serveur, enregistre la méthode HTTP utilisée pour appeler le serveur et parse
150 
	 * l'url appelée pour trouver le service demandé.
151 
	 */
152 
	public function __construct() {
153 
		if (isset($_SERVER['REQUEST_URI']) && isset($_SERVER['REQUEST_METHOD']) && isset($_SERVER['QUERY_STRING'])) {
232 jpm 154 
			$this->initialiserMethode();
155 
			$this->initialiserRequeteDonnees();
229 jpm 156 
 
232 jpm 157 
			$urlParts = $this->decouperUrlChemin();
158 
			$this->initialiserApiVersion(array_shift($urlParts));
159 
			$this->initialiserServiceNom(array_shift($urlParts));
160 
			$this->initialiserRessource($urlParts);
229 jpm 161 
 
232 jpm 162 
			$this->initialiserParametres();
163 
			Debug::printr($this);
229 jpm 164 
			// Enregistrement en première position des autoload de la méthode gérant les classes des services
165 
			spl_autoload_register(array(get_class(), 'chargerClasse'));
166 
		} else {
167 
			$e = "La classe Serveur du TBFRamework nécessite, pour fonctionner, l'accès aux variables serveurs REQUEST_URI, REQUEST_METHOD et QUERY_STRING.";
168 
			trigger_error($e, E_USER_ERROR);
169 
		}
170 
	}
171 
 
232 jpm 172 
	private function initialiserMethode() {
173 
		if (isset($_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE']) && count(trim($_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE'])) > 0) {
174 
			$this->methode = trim($_SERVER['X_HTTP_METHOD_OVERRIDE']);
175 
		} else {
176 
			$this->methode = $_SERVER['REQUEST_METHOD'];
177 
		}
178 
	}
179 
 
180 
	private function initialiserRequeteDonnees() {
181 
		if (isset($_SERVER['CONTENT_LENGTH']) && $_SERVER['CONTENT_LENGTH'] > 0) {
182 
			$this->requeteDonnees = '';
183 
			$httpContent = fopen('php://input', 'r');
184 
			while ($data = fread($httpContent, 1024)) {
185 
				$this->requeteDonnees .= $data;
186 
			}
187 
			fclose($httpContent);
188 
		}
189 
	}
190 
 
191 
	private function decouperUrlChemin() {
192 
		if (strlen($_SERVER['QUERY_STRING']) == 0) {
193 
			$tailleURL = strlen($_SERVER['REQUEST_URI']);
194 
		} else {
195 
			$tailleURL = -(strlen($_SERVER['QUERY_STRING']) + 1);
196 
		}
197 
		$urlChaine = substr($_SERVER['REQUEST_URI'], strlen(Config::get('serveur.baseURL')), $tailleURL);
198 
		return explode('/', $urlChaine);
199 
	}
200 
 
201 
	private function initialiserApiVersion($apiVersion) {
202 
		if (isset($apiVersion) && !empty($apiVersion)) {
203 
			$this->apiVersion = $apiVersion;
204 
			self::$config['chemins']['api'] = Config::get('chemin_modules').$this->apiVersion.DS;
205 
		} else {
206 
			$e = "Aucune version d'API n'a été spécifié dans l'url qui doit avoir la forme suivante http://www.mondomaine.org/services/apiVersion/monService/";
207 
			trigger_error($e, E_USER_ERROR);
208 
		}
209 
	}
210 
 
211 
	private function initialiserServiceNom($serviceNom) {
212 
		if (isset($serviceNom) && !empty($serviceNom)) {
213 
			$this->service = $this->traiterNomService($serviceNom);
214 
		} else {
215 
			$e = "Aucun service n'a été spécifié dans l'url qui doit avoir la forme suivante http://www.mondomaine.org/services/apiVersion/monService/";
216 
			trigger_error($e, E_USER_ERROR);
217 
		}
218 
	}
219 
 
229 jpm 220 
	private function traiterNomService($serviceNom) {
221 
		return str_replace(' ', '', ucwords(str_replace('-', ' ', strtolower($serviceNom))));
222 
	}
223 
 
232 jpm 224 
	private function initialiserRessource($urlParts) {
225 
		if (is_array($urlParts) && count($urlParts) > 0) {
226 
			foreach ($urlParts as $ressource) {
227 
				// Ne pas utiliser empty() car valeur 0 acceptée
228 
				if ($ressource != '') {
229 
					$this->ressources[] = urldecode($ressource);
230 
				}
231 
			}
232 
		}
233 
	}
234 
 
235 
	private function initialiserParametres() {
236 
		$this->nettoyerGet();
237 
		$this->parametres = $_GET;
238 
	}
239 
 
229 jpm 240 
	private function nettoyerGet() {
232 jpm 241 
		// Pas besoin d'utiliser urldecode car déjà fait par php pour les clés et valeur de $_GET
229 jpm 242 
		if (isset($_GET) && count($_GET) > 0) {
243 
			foreach ($_GET as $cle => $valeur) {
244 
				$verifier = array('NULL', "\n", "\r", "\\", "'", '"', "\x00", "\x1a", ';');
245 
				$_GET[$cle] = strip_tags(str_replace($verifier, '', $valeur));
246 
			}
247 
		}
248 
	}
249 
 
250 
	/**
251 
	* La méthode __autoload() charge dynamiquement les classes trouvées dans le code.
252 
	* Cette fonction est appelée par php5 quand il trouve une instanciation de classe dans le code.
253 
	*
254 
	*@param string le nom de la classe appelée.
255 
	*@return void le fichier contenant la classe doit être inclu par la fonction.
256 
	*/
257 
	public static function chargerClasse($classe) {
258 
		if (class_exists($classe)) {
259 
			return null;
260 
		}
261 
 
262 
		$chemins = array('', self::$config['chemins']['api']);
263 
		foreach ($chemins as $chemin) {
264 
			$chemin = $chemin.$classe.'.php';
265 
			if (file_exists($chemin)) {
266 
				require_once $chemin;
267 
			}
268 
		}
269 
	}
270 
 
271 
	/**
272 
	 * Execute la requête.
273 
	 */
274 
	function executer() {
275 
		switch ($this->methode) {
276 
			case 'GET':
277 
				$this->get();
278 
				break;
279 
			case 'POST':
280 
				$this->post();
281 
				break;
282 
			case 'DELETE':
283 
				$this->delete();
284 
				break;
285 
			case 'PUT':
232 jpm 286 
				$this->put();
229 jpm 287 
				break;
232 jpm 288 
			default :
289 
				$e = "La méthode HTTP '{$this->methode}' n'est pas prise en compte par ce serveur REST.";
290 
				trigger_error($e, E_USER_WARNING);
229 jpm 291 
		}
292 
		// 	Affichage des exceptions et erreurs générées par les services
232 jpm 293 
		$this->gererErreurs();
229 jpm 294 
	}
295 
 
296 
	/**
297 
	 * Execute a GET request. A GET request fetches a list of resource when no resource name is given, a list of element
298 
	 * when a resource name is given, or a resource element when a resource and resource unique identifier are given. It does not change the
299 
	 * database contents.
300 
	 */
301 
	private function get() {
232 jpm 302 
		if ($this->service != null) {
303 
			$Service = new $this->service(self::$config);
304 
			if (method_exists($Service, self::METHODE_GET)) {
305 
				$methodeGet = self::METHODE_GET;
306 
				$Service->$methodeGet($this->ressources, $this->parametres);
307 
			} else {
308 
				$e = "Le service '{$this->service}' ne contient pas la méthode '".self::METHODE_GET."' nécessaire ".
309 
					"lors de l'appel du service via la méthode HTTP GET.";
310 
				trigger_error($e, E_USER_ERROR);
311 
			}
229 jpm 312 
		}
313 
	}
314 
 
315 
	private function post() {
232 jpm 316 
		$paires = $this->parserDonneesRequete();
229 jpm 317 
 
232 jpm 318 
		if (count($paires) != 0) {
319 
			if (isset($paires['action']) && $paires['action'] == 'DELETE') {// Altnative à l'utilisation de DELETE
229 jpm 320 
				$this->delete();
232 jpm 321 
			} else if (count($this->ressources) == 0) {// Altnative à l'utilisation de PUT
322 
				$this->add();
323 
			} else {
324 
				if ($this->service != null) {
325 
					$Service = new $this->service(self::$config);
326 
					if (method_exists($Service, self::METHODE_POST)) {
327 
						$methodePost = self::METHODE_POST;
328 
						if ($Service->$methodePost($this->ressources, $paires)) {
329 
							$this->envoyerEnteteStatutHttp(self::HTTP_CODE_CREATION_OK);
229 jpm 330 
						}
232 jpm 331 
					} else {
332 
						$e = "Le service '{$this->service}' ne contient pas la méthode '".self::METHODE_POST."' nécessaire ".
333 
							"lors de l'appel du service via la méthode HTTP POST.";
334 
						trigger_error($e, E_USER_ERROR);
229 jpm 335 
					}
336 
				}
232 jpm 337 
			}
338 
		} else {
339 
			$this->envoyerEnteteStatutHttp(self::HTTP_CODE_CONTENU_REQUIS);
229 jpm 340 
		}
341 
	}
342 
 
232 jpm 343 
	private function put() {
344 
		$paires = $this->parserDonneesRequete();
345 
 
346 
		if (count($paires) != 0) {
347 
			if ($this->service != null) {
348 
				$Service = new $this->service(self::$config);
349 
				if (method_exists($Service, self::METHODE_PUT)) {
350 
					$methodePut = self::METHODE_PUT;
351 
					if ($Service->$methodePut($this->ressources, $paires)) {
352 
						$this->envoyerEnteteStatutHttp(self::HTTP_CODE_CREATION_OK);
353 
					}
354 
				} else {
355 
					$e = "Le service '{$this->service}' ne contient pas la méthode '".self::METHODE_PUT."' nécessaire ".
356 
						"lors de l'appel du service via la méthode HTTP PUT (ou équivalant).";
357 
					trigger_error($e, E_USER_ERROR);
229 jpm 358 
				}
359 
			}
232 jpm 360 
		} else {
361 
			$this->envoyerEnteteStatutHttp(self::HTTP_CODE_CONTENU_REQUIS);
229 jpm 362 
		}
363 
	}
364 
 
232 jpm 365 
	private function delete() {
366 
		if (count($this->ressources) != 0) {
367 
			if ($this->service != null) {
368 
				$Service = new $this->service(self::$config);
369 
				if (method_exists($Service, self::METHODE_DELETE)) {
370 
					$methodeDelete = self::METHODE_DELETE;
371 
					if ($Service->$methodeDelete($this->ressources, $paires)) {
372 
						$this->envoyerEnteteStatutHttp(self::HTTP_CODE_SUPPRESSION_OK);
373 
					} else {
374 
						$this->envoyerEnteteStatutHttp(self::HTTP_CODE_RESSOURCE_INTROUVABLE);
229 jpm 375 
					}
232 jpm 376 
				} else {
377 
					$e = "Le service '{$this->service}' ne contient pas la méthode '".self::METHODE_DELETE."' nécessaire ".
378 
						"lors de l'appel du service via la méthode HTTP DELETE (ou équivalant).";
379 
					trigger_error($e, E_USER_ERROR);
229 jpm 380 
				}
381 
			}
382 
		} else {
232 jpm 383 
			$this->envoyerEnteteStatutHttp(self::HTTP_CODE_MAUVAISE_REQUETE);
229 jpm 384 
		}
385 
	}
232 jpm 386 
 
229 jpm 387 
	/**
232 jpm 388 
	 * Parse les données contenu dans le corps de la requête HTTP (= POST) en :
389 
	 *  - décodant les clés et valeurs.
390 
	 *  - supprimant les espaces en début et fin des clés et des valeurs.
391 
	 *
392 
	 * @return array Tableau de paires clé et valeur.
229 jpm 393 
	 */
394 
	private function parserDonneesRequete() {
232 jpm 395 
		$donnees = array();
396 
		if ($this->$requeteDonneesParsees != null) {
397 
			$donnees = $this->$requeteDonneesParsees;
398 
		} else if ($this->requeteDonnees != null) {
399 
			$paires = explode('&', $this->requeteDonnees);
400 
			foreach ($paires as $paire) {
401 
				list($cle, $valeur) = explode('=', $paire);
402 
				$cle = (isset($cle)) ? trim(urldecode($cle)) : '';
403 
				$valeur = (isset($valeur)) ? trim(urldecode($valeur)) : '';
404 
				$donnees[$cle] = $valeur;
229 jpm 405 
			}
232 jpm 406 
			$this->$requeteDonneesParsees = $donnees;
229 jpm 407 
		}
232 jpm 408 
		return $donnees;
229 jpm 409 
	}
410 
 
411 
	/**
232 jpm 412 
	 * Envoyer un entête HTTP (version 1.0) de statut.
413 
	 * Il remplacera systématiquement tout entête HTTP de statut précédement envoyé.
414 
	 * @param int $code entier indiquant le code du statut de l'entête HTTP à envoyer.
229 jpm 415 
	 */
232 jpm 416 
	public static function envoyerEnteteStatutHttp($code) {
229 jpm 417 
		if (isset(self::$http10[$code])) {
232 jpm 418 
			$txt = self::$http10[$code];
419 
			header("HTTP/1.0 $code $txt", true);
229 jpm 420 
		}
421 
	}
232 jpm 422 
 
423 
	/**
424 
	 * Si des exceptions ou des erreurs sont soulevées par le serveur ou les services, elles sont gérées par cette méthode.
425 
	 */
426 
	public static function gererErreurs() {
427 
		if (Config::get('fw_debogage') && GestionnaireException::getExceptionsNbre() > 0) {
428 
			$exceptionsTriees = GestionnaireException::getExceptionsTriees();
429 
			reset($exceptionsTriees);
430 
			if (! (count($exceptionsTriees) == 1 && key($exceptionsTriees) == E_USER_NOTICE)) {
431 
				self::envoyerEnteteStatutHttp(self::HTTP_CODE_ERREUR);
432 
			}
433 
			foreach ($exceptionsTriees as $exceptions) {
434 
				foreach ($exceptions as $e) {
435 
					echo GestionnaireException::formaterExceptionXhtml($e);
436 
				}
437 
			}
438 
		}
439 
	}
229 jpm 440 
}
441 
?>