Subversion Repositories Applications.framework

Compare Revisions

Ignore whitespace Rev 398 → Rev 399

/trunk/framework/RestServeur.php
2,32 → 2,32
// declare(encoding='UTF-8');
/**
* Classe principale gérant les services web de type (@link(REST, http://fr.wikipedia.org/wiki/Rest).
*
*
* Elle contient :
* - les constantes indiquant les différentes (@link(méthode HTTP, http://fr.wikipedia.org/wiki/Http) prises en compte.
* - les @link(codes HTTP des réponses, http://fr.wikipedia.org/wiki/Liste_des_codes_HTTP)
*
*
* Ce serveur REST accepte 4 types de méthodes HTTP : GET, PUT, POST, DELETE.
* 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.
* Vous pouvez donc pour réaliser :
* - DELETE : utiliser la méthode POST avec action=DELETE dans le corps de la requête.
* - PUT : utiliser la méthode POST avec une url ne contenant aucune indication de ressource.
* Une autre solution consiste à utiliser n'importe quelle méthode et à ajouter l'entête "X_HTTP_METHOD_OVERRIDE" avec pour
* Une autre solution consiste à utiliser n'importe quelle méthode et à ajouter l'entête "X_HTTP_METHOD_OVERRIDE" avec pour
* valeur le nom de la méthode que vous souhaitez utiliser. Exemple d'entête : "X_HTTP_METHOD_OVERRIDE: PUT".
* Exemple : <code>curl -v -v -H "X_HTTP_METHOD_OVERRIDE: DELETE" "http://www.mondomaine.org/services/apiVersion/[mon-service]/"</code>
* Cela fonctionne avec Apache.
*
*
* 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
* en minuscule où les mots sont séparés par des tirets "mon-service".
*
*
* Paramètres liés dans config.ini :
* - serveur.baseURL : morceau de l'url pour appeler le serveur relative au domaine. Exemple : pour http://www.tela-botanica.org/mon_serveur/
* mettre : "/mon_serveur/"
* - serveur.baseAlternativeURL : sur le même principe que ci-dessus permet d'affecter une deuxième url (pour gérer des raccourci via htaccess)
*
*
* Encodage en entrée : utf8
* Encodage en sortie : utf8
*
*
* @category Php 5.2
* @package Framework
* @author Jean-Pascal MILCENT <jpm@tela-botanica.org>
40,76 → 40,76
*/
// TODO : gerer les retours : dans ce controleur : code retour et envoi ...
class RestServeur {
 
/** Nom de la méthode appelée dans un service pour éxécuter une requête de type GET. */
const METHODE_GET = 'consulter';
 
/** Nom de la méthode appelée dans un service pour éxécuter une requête de type POST. */
const METHODE_POST = 'modifier';
 
/** Nom de la méthode appelée dans un service pour éxécuter une requête de type DELETE. */
const METHODE_DELETE = 'supprimer';
 
/** Nom de la méthode appelée dans un service pour éxécuter une requête de type PUT. */
const METHODE_PUT = 'ajouter';
 
/** Code HTTP 200 indiquant le succès de l'accès à un service web par la méthode GET.
* L'utiliser lors d'une requète de type GET (consulter) pour indiquer le succès de l'opération.
* Sera renvoyée par défaut par PHP. */
const HTTP_CODE_OK = '200';
 
/** 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é.
* L'utiliser lors d'une requète de type PUT (ajouter) ou POST (modifier) pour indiquer le succès de l'opération. */
const HTTP_CODE_CREATION_OK = '201';
 
/** 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.
* L'utiliser lors d'une requète de type DELETE (supprimer) pour indiquer le succès de l'opération. */
const HTTP_CODE_SUPPRESSION_OK = '204';
 
/** Code HTTP 400 indique que les paramètres envoyés au service contiennent des erreurs.
* L'utiliser pour indiquer l'échec de l'accès au service. La réponse pourra contenir un message expliquant la source
* L'utiliser pour indiquer l'échec de l'accès au service. La réponse pourra contenir un message expliquant la source
* de l'erreur. */
const HTTP_CODE_MAUVAISE_REQUETE = '400';
 
/** Code HTTP 401 indiquant que l'accès à un service web est refusé car l'authentification (obligatoire) a échoué pour
* accéder à la ressource. */
const HTTP_CODE_ACCES_NON_AUTORISE = '401';
 
/** Code HTTP 404 indiquant que la ressource indiquée par l'url est introuvable. */
const HTTP_CODE_RESSOURCE_INTROUVABLE = '404';
 
/** Code HTTP 405 indiquant soit :
* - que le service web ne possède pas d'accès la ressource correspondant à la méthode HTTP employée.
* - que la méthode HTTP enployée n'est pas en accord avec la ressource indiquée par l'url. */
const HTTP_CODE_METHODE_NON_AUTORISE = '405';
 
/** Code d'erreur HTTP 409 indiquant qu'un conflit est survenu vis à vis de la ressource.
* 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
* 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
* ailleurs. */
const HTTP_CODE_CONFLIT = '409';
 
/** Code HTTP 411 indiquant que des paramètres passés dans le contenu de la requête sont nécessaires au service. */
const HTTP_CODE_CONTENU_REQUIS = '411';
 
/** Code d'erreur HTTP 500 Internal Server Error.
* L'utiliser quand le serveur ou un service soulève une erreur ou une exception. */
const HTTP_CODE_ERREUR = '500';
 
/** Motif de l'epression régulière vérfiant la version de l'API. */
const MOTIF_API_VERSION = '/^[0-9]+(?:[.][0-9]+)*$/';
 
/** Motif de l'epression régulière vérfiant le nom du service. */
const MOTIF_SERVICE_NOM = '/^[a-z0-9]+(?:[-][a-z0-9]+)*$/';
/** Mettre à true pour activer l'affichage des messages d'erreurs et de débogage.
 
/** Mettre à true pour activer l'affichage des messages d'erreurs et de débogage.
* @var boolean */
private static $debogageActivation = false;
/** Indiquer le mode de débogage à utiliser (@see Debug).
 
/** Indiquer le mode de débogage à utiliser (@see Debug).
* @var string */
private static $debogageMode = '';
/** La méthode de la requête HTTP utilisée.
 
/** La méthode de la requête HTTP utilisée.
* @var string */
private $methode = 'GET';
 
116,8 → 116,8
/** Le contenu brut du corps de la requête HTTP (s'il y en a).
* @var array */
private $requeteDonnees = null;
/** Le contenu sous forme de tableau de paires clés-valeurs du corps de la requête HTTP (s'il y en a).
 
/** Le contenu sous forme de tableau de paires clés-valeurs du corps de la requête HTTP (s'il y en a).
* @var array */
private $requeteDonneesParsees = null;
 
127,24 → 127,24
*/
private $apiVersion = null;
 
/** Nom du service demandé.
/** Nom du service demandé.
* Ex. http://www.mondomaine.org/services/apiVersion/[mon-service]/
* @var string par défaut vaut null.
*/
private $service = null;
 
/** Morceaux de l'url servant à préciser la ressource concerné pour le service demandé.
* Ex. http://www.mondomaine.org/services/apiVersion/mon-service/[maRessource/maSousResource...]
* @var array
*/
private $ressources = array();
 
/** Partie de l'url situé après le '?' servant à paramétrer le service demandé.
* Ex. http://www.mondomaine.org/services/apiVersion/mon-service?monParametre1=maValeur1&monParametre2=maValeur2
* @var array
*/
private $parametres = array();
 
/** Tableau contenant les paramètres de configuration du serveur.
* @var array
*/
154,10 → 154,10
* @var array
* */
private static $messages = array();
 
/** Codes HTTP. */
private static $http10 = array(
self::HTTP_CODE_OK => 'OK',
self::HTTP_CODE_OK => 'OK',
self::HTTP_CODE_CREATION_OK => 'Created',
self::HTTP_CODE_SUPPRESSION_OK => 'No Content',
self::HTTP_CODE_MAUVAISE_REQUETE => 'Bad Request',
168,7 → 168,7
self::HTTP_CODE_CONTENU_REQUIS => 'Length Required',
self::HTTP_CODE_ERREUR => 'Internal Server Error'
);
 
/** Tableau des noms des paramètres à définir dans le fichier de config car obligatoirement nécessaire à cette classe.*/
private $parametres_obligatoires = array('debogage', 'debogage_mode', 'serveur.baseURL', 'chemin_modules');
 
178,7 → 178,7
*/
public function __construct() {
Config::verifierPresenceParametres($this->parametres_obligatoires);
 
self::$debogageActivation = Config::get('debogage');
self::$debogageMode = Config::get('debogage_mode');
 
185,15 → 185,15
if (isset($_SERVER['REQUEST_URI']) && isset($_SERVER['REQUEST_METHOD']) && isset($_SERVER['QUERY_STRING'])) {
$this->initialiserMethode();
$this->initialiserRequeteDonnees();
 
$urlParts = $this->decouperUrlChemin();
 
$this->initialiserApiVersion(array_shift($urlParts));
$this->initialiserServiceNom(array_shift($urlParts));
$this->initialiserRessource($urlParts);
 
$this->initialiserParametres();
// Enregistrement en première position des autoload de la méthode gérant les classes des services
// Enregistrement en première position des autoload de la méthode gérant les classes des services
spl_autoload_register(array(get_class(), 'chargerClasse'));
} else {
self::envoyerEnteteStatutHttp(self::HTTP_CODE_ERREUR);
201,7 → 201,7
self::ajouterMessage($e);
}
}
 
private function initialiserMethode() {
if (isset($_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE']) && count(trim($_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE'])) > 0) {
$this->methode = trim($_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE']);
209,7 → 209,7
$this->methode = $_SERVER['REQUEST_METHOD'];
}
}
 
private function initialiserRequeteDonnees() {
if (isset($_SERVER['CONTENT_LENGTH']) && $_SERVER['CONTENT_LENGTH'] > 0) {
$this->requeteDonnees = '';
220,7 → 220,7
fclose($httpContent);
}
}
 
private function decouperUrlChemin() {
if (isset($_SERVER['REDIRECT_URL']) && $_SERVER['REDIRECT_URL'] != '') {
if (isset($_SERVER['REDIRECT_QUERY_STRING']) && !empty($_SERVER['REDIRECT_QUERY_STRING'])) {
231,13 → 231,13
} else {
$url = $_SERVER['REQUEST_URI'];
}
 
if (strlen($_SERVER['QUERY_STRING']) == 0) {
$tailleURL = strlen($url);
} else {
$tailleURL = -(strlen($_SERVER['QUERY_STRING']) + 1);
}
 
$urlChaine = '';
if (strpos($url, Config::get('serveur.baseURL')) !== false) {
$urlChaine = substr($url, strlen(Config::get('serveur.baseURL')), $tailleURL);
246,7 → 246,7
}
return explode('/', $urlChaine);
}
 
private function initialiserApiVersion($apiVersion) {
if ($this->verifierApiVersion($apiVersion)) {
$this->apiVersion = $apiVersion;
260,7 → 260,7
self::cloreAccesServeur();
}
}
 
private function verifierApiVersion($apiVersion) {
$apiOk = false;
if (isset($apiVersion) && !empty($apiVersion) && preg_match(self::MOTIF_API_VERSION, $apiVersion)) {
268,7 → 268,7
}
return $apiOk;
}
 
private function initialiserServiceNom($serviceNom) {
if ($this->verifierServiceNom($serviceNom)) {
$this->service = $this->traiterNomService($serviceNom);
281,7 → 281,7
self::cloreAccesServeur();
}
}
 
private function verifierServiceNom($serviceNom) {
$serviceNomOk = false;
if (isset($serviceNom) && !empty($serviceNom) && preg_match(self::MOTIF_SERVICE_NOM, $serviceNom)) {
289,11 → 289,11
}
return $serviceNomOk;
}
 
private function traiterNomService($serviceNom) {
return str_replace(' ', '', ucwords(str_replace('-', ' ', strtolower($serviceNom))));
}
 
private function initialiserRessource($urlParts) {
if (is_array($urlParts) && count($urlParts) > 0) {
foreach ($urlParts as $ressource) {
304,14 → 304,14
}
}
}
 
private function initialiserParametres() {
$this->nettoyerGet();
$this->parametres = $_GET;
}
 
private function nettoyerGet() {
// Pas besoin d'utiliser urldecode car déjà fait par php pour les clés et valeur de $_GET
// Pas besoin d'utiliser urldecode car déjà fait par php pour les clés et valeur de $_GET
if (isset($_GET) && count($_GET) > 0) {
foreach ($_GET as $cle => $valeur) {
$verifier = array('NULL', "\n", "\r", "\\", "'", '"', "\x00", "\x1a", ';');
319,7 → 319,7
}
}
}
 
/**
* La méthode __autoload() charge dynamiquement les classes trouvées dans le code.
* Cette fonction est appelée par php5 quand il trouve une instanciation de classe dans le code.
340,7 → 340,7
$classeTrouvee = true;
}
}
if ($classeTrouvee === false) {
if ($classeTrouvee === false && phpversion() >= 5.3) {
self::envoyerEnteteStatutHttp(self::HTTP_CODE_RESSOURCE_INTROUVABLE);
$e = "La classe '$classe' du service n'a pas été trouvée par le serveur.\n".
"Cela peut signifier que le nom du service saisi comporte une erreur.";
348,7 → 348,7
self::cloreAccesServeur();
}
}
 
/**
* Execute la requête.
*/
422,7 → 422,7
self::ajouterMessage($e);
}
}
}
}
} else {
$this->envoyerEnteteStatutHttp(self::HTTP_CODE_CONTENU_REQUIS);
$e = "Le service '{$this->service}' requiert de fournir le contenu à modifier dans le corps ".
485,12 → 485,12
self::ajouterMessage($e);
}
}
 
/**
* Parse les données contenu dans le corps de la requête HTTP (= POST) en :
* - décodant les clés et valeurs.
* - supprimant les espaces en début et fin des clés et des valeurs.
*
*
* @return array Tableau de paires clé et valeur.
*/
private function parserDonneesRequete() {
509,11 → 509,11
}
return $donnees;
}
 
/**
* Envoyer un entête HTTP (version 1.0) de statut.
* Il remplacera systématiquement tout entête HTTP de statut précédement envoyé.
* @param int $code entier indiquant le code du statut de l'entête HTTP à envoyer.
* @param int $code entier indiquant le code du statut de l'entête HTTP à envoyer.
*/
public static function envoyerEnteteStatutHttp($code) {
if (isset(self::$http10[$code])) {
521,7 → 521,7
header("HTTP/1.0 $code $txt", true);
}
}
 
/**
* Termine l'accès au serveur après envoir envoyer les messages.
*/
528,27 → 528,27
private static function cloreAccesServeur($retour = '') {
// Gestion des exceptions et erreurs générées par les services
$retour .= self::gererErreurs();
 
// Envoie des messages d'erreur et d'avertissement du serveur
$retour .= self::envoyerMessages();
 
// Envoie sur la sortie standard le contenu de la réponse HTTP
print $retour;
 
// Nous terminons le script
exit(0);
}
 
/**
* Si des exceptions ou des erreurs sont soulevées par le serveur ou les services, elles sont gérées par cette méthode.
* Si nous avec des erreurs d'un type différent d'E_USER_NOTICE (réservé au débogage), elle sont renvoyées sur la sortie
* Si nous avec des erreurs d'un type différent d'E_USER_NOTICE (réservé au débogage), elle sont renvoyées sur la sortie
* standard (via echo).
* Si seulement des erreurs de type E_USER_NOTICE, sont présentes, elle sont envoyées en fonction du contenu du paramètre de
* Si seulement des erreurs de type E_USER_NOTICE, sont présentes, elle sont envoyées en fonction du contenu du paramètre de
* config "debogage_mode" :
* - Debug::MODE_ECHO : les messages sont affichés en utilisant echo au moment où ils sont déclenchés dans le code.
* - Debug::MODE_NOTICE : les message sont stockés par le gestionnaire d'exception sous forme d'erreur de type
* - Debug::MODE_ECHO : les messages sont affichés en utilisant echo au moment où ils sont déclenchés dans le code.
* - Debug::MODE_NOTICE : les message sont stockés par le gestionnaire d'exception sous forme d'erreur de type
* E_USER_NOTICE et sont renvoyés sur la sortie standard à la fin de l'execution du programme (via echo).
* - Debug::MODE_ENTETE_HTTP : les message sont stockés par le gestionnaire d'exception sous forme d'erreur de type
* - Debug::MODE_ENTETE_HTTP : les message sont stockés par le gestionnaire d'exception sous forme d'erreur de type
* E_USER_NOTICE et sont renvoyés dans un entête HTTP (X_REST_DEBOGAGE_MESSAGES) à la fin de l'execution du programme.
* - Autre valeur : les messages sont formatés puis retournés par la fonction de débogage (à vous de les afficher).
*/
555,7 → 555,7
public static function gererErreurs() {
$retour = '';
if (self::$debogageActivation && GestionnaireException::getExceptionsNbre() > 0) {
 
$exceptionsTriees = GestionnaireException::getExceptionsTriees();
reset($exceptionsTriees);
$debogageSeulement = true;
563,7 → 563,7
self::envoyerEnteteStatutHttp(self::HTTP_CODE_ERREUR);
$debogageSeulement = false;
}
 
$exceptionsFormatees = array();
foreach ($exceptionsTriees as $exceptions) {
foreach ($exceptions as $e) {
574,7 → 574,7
}
}
}
 
if ($debogageSeulement && self::$debogageMode == Debug::MODE_ENTETE_HTTP) {
header('X_REST_DEBOGAGE_MESSAGES: '.json_encode($exceptionsFormatees));
}
581,12 → 581,12
}
return $retour;
}
 
 
/**
* Permet d'ajouter un message d'erreur ou d'avertissement qui sera envoyé au client.
* Le message doit être au format texte et en UTF-8.
* @param string $message le message à envoyer.
* @param string $message le message à envoyer.
*/
public static function ajouterMessage($message) {
if (isset($message) && !empty($message)) {
593,7 → 593,7
self::$messages[] = $message;
}
}
 
/**
* Envoie au client les éventuels messages d'erreur et d'avertissement du Serveur.
* Le format d'envoie est text/plain encodé en UTF-8.