| New file |
|---|
| 0,0 → 1,488 |
|---|
| <?php |
| /** |
| * 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 |
| * 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> |
| * @copyright Copyright (c) 2010, Tela Botanica (accueil@tela-botanica.org) |
| * @license GPL v3 <http://www.gnu.org/licenses/gpl.txt> |
| * @license CECILL v2 <http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt> |
| * @since 0.3 |
| * @version $Id$ |
| * @link /doc/framework/ |
| */ |
| // 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 |
| * 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 |
| * 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'; |
| |
| /** 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). |
| * @var string */ |
| private static $debogageMode = ''; |
| |
| /** La méthode de la requête HTTP utilisée. |
| * @var string */ |
| private $methode = 'GET'; |
| |
| /** 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). |
| * @var array */ |
| private $requeteDonneesParsees = null; |
| |
| /** Version de l'API demandée. |
| * Ex. http://www.mondomaine.org/services/[apiVersion]/mon-service/ |
| * @var mixed Généralement deux nombres séparés par un point. Ex. : 1.0 |
| */ |
| private $apiVersion = null; |
| |
| /** 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 |
| */ |
| private static $config = array(); |
| |
| /** Codes HTTP. */ |
| private static $http10 = array( |
| 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', |
| self::HTTP_CODE_ACCES_NON_AUTORISE => 'Unauthorized', |
| self::HTTP_CODE_RESSOURCE_INTROUVABLE => 'Not Found', |
| self::HTTP_CODE_METHODE_NON_AUTORISE => 'Method Not Allowed', |
| self::HTTP_CODE_CONFLIT => 'Conflict', |
| 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'); |
| |
| /** |
| * Analyse les données envoyées au serveur, enregistre la méthode HTTP utilisée pour appeler le serveur et parse |
| * l'url appelée pour trouver le service demandé. |
| */ |
| public function __construct() { |
| Config::verifierPresenceParametres($this->parametres_obligatoires); |
| |
| self::$debogageActivation = Config::get('debogage'); |
| self::$debogageMode = Config::get('debogage_mode'); |
| |
| 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(); |
| Debug::printr($this); |
| // 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 { |
| $e = "La classe Serveur du TBFRamework nécessite, pour fonctionner, l'accès aux variables serveurs REQUEST_URI, REQUEST_METHOD et QUERY_STRING."; |
| trigger_error($e, E_USER_ERROR); |
| } |
| } |
| |
| private function initialiserMethode() { |
| if (isset($_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE']) && count(trim($_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE'])) > 0) { |
| $this->methode = trim($_SERVER['X_HTTP_METHOD_OVERRIDE']); |
| } else { |
| $this->methode = $_SERVER['REQUEST_METHOD']; |
| } |
| } |
| |
| private function initialiserRequeteDonnees() { |
| if (isset($_SERVER['CONTENT_LENGTH']) && $_SERVER['CONTENT_LENGTH'] > 0) { |
| $this->requeteDonnees = ''; |
| $httpContent = fopen('php://input', 'r'); |
| while ($data = fread($httpContent, 1024)) { |
| $this->requeteDonnees .= $data; |
| } |
| fclose($httpContent); |
| } |
| } |
| |
| private function decouperUrlChemin() { |
| if (strlen($_SERVER['QUERY_STRING']) == 0) { |
| $tailleURL = strlen($_SERVER['REQUEST_URI']); |
| } else { |
| $tailleURL = -(strlen($_SERVER['QUERY_STRING']) + 1); |
| } |
| $urlChaine = ''; |
| if (strpos($_SERVER['REQUEST_URI'], Config::get('serveur.baseURL')) !== false) { |
| $urlChaine = substr($_SERVER['REQUEST_URI'], strlen(Config::get('serveur.baseURL')), $tailleURL); |
| } else if (strpos($_SERVER['REQUEST_URI'], Config::get('serveur.baseAlternativeURL')) !== false) { |
| $urlChaine = substr($_SERVER['REQUEST_URI'], strlen(Config::get('serveur.baseAlternativeURL')), $tailleURL); |
| } |
| return explode('/', $urlChaine); |
| } |
| |
| private function initialiserApiVersion($apiVersion) { |
| if (isset($apiVersion) && !empty($apiVersion)) { |
| $this->apiVersion = $apiVersion; |
| self::$config['chemins']['api'] = Config::get('chemin_modules').$this->apiVersion.DS; |
| } else { |
| $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/"; |
| trigger_error($e, E_USER_ERROR); |
| } |
| } |
| |
| private function initialiserServiceNom($serviceNom) { |
| if (isset($serviceNom) && !empty($serviceNom)) { |
| $this->service = $this->traiterNomService($serviceNom); |
| } else { |
| $e = "Aucun service n'a été spécifié dans l'url qui doit avoir la forme suivante http://www.mondomaine.org/services/apiVersion/monService/"; |
| trigger_error($e, E_USER_ERROR); |
| } |
| } |
| |
| 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) { |
| // Ne pas utiliser empty() car valeur 0 acceptée |
| if ($ressource != '') { |
| $this->ressources[] = urldecode($ressource); |
| } |
| } |
| } |
| } |
| |
| 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 |
| if (isset($_GET) && count($_GET) > 0) { |
| foreach ($_GET as $cle => $valeur) { |
| $verifier = array('NULL', "\n", "\r", "\\", "'", '"', "\x00", "\x1a", ';'); |
| $_GET[$cle] = strip_tags(str_replace($verifier, '', $valeur)); |
| } |
| } |
| } |
| |
| /** |
| * 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. |
| * |
| *@param string le nom de la classe appelée. |
| *@return void le fichier contenant la classe doit être inclu par la fonction. |
| */ |
| public static function chargerClasse($classe) { |
| if (class_exists($classe)) { |
| return null; |
| } |
| |
| $chemins = array('', self::$config['chemins']['api']); |
| foreach ($chemins as $chemin) { |
| $chemin = $chemin.$classe.'.php'; |
| if (file_exists($chemin)) { |
| require_once $chemin; |
| } |
| } |
| } |
| |
| /** |
| * Execute la requête. |
| */ |
| function executer() { |
| switch ($this->methode) { |
| case 'GET': |
| $this->get(); |
| break; |
| case 'POST': |
| $this->post(); |
| break; |
| case 'DELETE': |
| $this->delete(); |
| break; |
| case 'PUT': |
| $this->put(); |
| break; |
| default : |
| $e = "La méthode HTTP '{$this->methode}' n'est pas prise en compte par ce serveur REST."; |
| trigger_error($e, E_USER_WARNING); |
| } |
| // Affichage des exceptions et erreurs générées par les services |
| $this->gererErreurs(); |
| } |
| |
| /** |
| * Execute a GET request. A GET request fetches a list of resource when no resource name is given, a list of element |
| * when a resource name is given, or a resource element when a resource and resource unique identifier are given. It does not change the |
| * database contents. |
| */ |
| private function get() { |
| if ($this->service != null) { |
| $Service = new $this->service(self::$config); |
| if (method_exists($Service, self::METHODE_GET)) { |
| $methodeGet = self::METHODE_GET; |
| $Service->$methodeGet($this->ressources, $this->parametres); |
| } else { |
| $e = "Le service '{$this->service}' ne contient pas la méthode '".self::METHODE_GET."' nécessaire ". |
| "lors de l'appel du service via la méthode HTTP GET."; |
| trigger_error($e, E_USER_ERROR); |
| } |
| } |
| } |
| |
| private function post() { |
| $paires = $this->parserDonneesRequete(); |
| |
| if (count($paires) != 0) { |
| if (isset($paires['action']) && $paires['action'] == 'DELETE') {// Altnative à l'utilisation de DELETE |
| $this->delete(); |
| } else if (count($this->ressources) == 0) {// Altnative à l'utilisation de PUT |
| $this->add(); |
| } else { |
| if ($this->service != null) { |
| $Service = new $this->service(self::$config); |
| if (method_exists($Service, self::METHODE_POST)) { |
| $methodePost = self::METHODE_POST; |
| if ($Service->$methodePost($this->ressources, $paires)) { |
| $this->envoyerEnteteStatutHttp(self::HTTP_CODE_CREATION_OK); |
| } |
| } else { |
| $e = "Le service '{$this->service}' ne contient pas la méthode '".self::METHODE_POST."' nécessaire ". |
| "lors de l'appel du service via la méthode HTTP POST."; |
| trigger_error($e, E_USER_ERROR); |
| } |
| } |
| } |
| } else { |
| $this->envoyerEnteteStatutHttp(self::HTTP_CODE_CONTENU_REQUIS); |
| } |
| } |
| |
| private function put() { |
| $paires = $this->parserDonneesRequete(); |
| |
| if (count($paires) != 0) { |
| if ($this->service != null) { |
| $Service = new $this->service(self::$config); |
| if (method_exists($Service, self::METHODE_PUT)) { |
| $methodePut = self::METHODE_PUT; |
| if ($Service->$methodePut($this->ressources, $paires)) { |
| $this->envoyerEnteteStatutHttp(self::HTTP_CODE_CREATION_OK); |
| } |
| } else { |
| $e = "Le service '{$this->service}' ne contient pas la méthode '".self::METHODE_PUT."' nécessaire ". |
| "lors de l'appel du service via la méthode HTTP PUT (ou équivalant)."; |
| trigger_error($e, E_USER_ERROR); |
| } |
| } |
| } else { |
| $this->envoyerEnteteStatutHttp(self::HTTP_CODE_CONTENU_REQUIS); |
| } |
| } |
| |
| private function delete() { |
| if (count($this->ressources) != 0) { |
| if ($this->service != null) { |
| $Service = new $this->service(self::$config); |
| if (method_exists($Service, self::METHODE_DELETE)) { |
| $methodeDelete = self::METHODE_DELETE; |
| if ($Service->$methodeDelete($this->ressources, $paires)) { |
| $this->envoyerEnteteStatutHttp(self::HTTP_CODE_SUPPRESSION_OK); |
| } else { |
| $this->envoyerEnteteStatutHttp(self::HTTP_CODE_RESSOURCE_INTROUVABLE); |
| } |
| } else { |
| $e = "Le service '{$this->service}' ne contient pas la méthode '".self::METHODE_DELETE."' nécessaire ". |
| "lors de l'appel du service via la méthode HTTP DELETE (ou équivalant)."; |
| trigger_error($e, E_USER_ERROR); |
| } |
| } |
| } else { |
| $this->envoyerEnteteStatutHttp(self::HTTP_CODE_MAUVAISE_REQUETE); |
| } |
| } |
| |
| /** |
| * 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() { |
| $donnees = array(); |
| if ($this->$requeteDonneesParsees != null) { |
| $donnees = $this->$requeteDonneesParsees; |
| } else if ($this->requeteDonnees != null) { |
| $paires = explode('&', $this->requeteDonnees); |
| foreach ($paires as $paire) { |
| list($cle, $valeur) = explode('=', $paire); |
| $cle = (isset($cle)) ? trim(urldecode($cle)) : ''; |
| $valeur = (isset($valeur)) ? trim(urldecode($valeur)) : ''; |
| $donnees[$cle] = $valeur; |
| } |
| $this->$requeteDonneesParsees = $donnees; |
| } |
| 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. |
| */ |
| public static function envoyerEnteteStatutHttp($code) { |
| if (isset(self::$http10[$code])) { |
| $txt = self::$http10[$code]; |
| header("HTTP/1.0 $code $txt", true); |
| } |
| } |
| |
| /** |
| * 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 |
| * 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 |
| * 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 |
| * 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 |
| * 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). |
| */ |
| public static function gererErreurs() { |
| if (self::$debogageActivation && GestionnaireException::getExceptionsNbre() > 0) { |
| $exceptionsTriees = GestionnaireException::getExceptionsTriees(); |
| reset($exceptionsTriees); |
| $debogageSeulement = true; |
| if (! (count($exceptionsTriees) == 1 && key($exceptionsTriees) == E_USER_NOTICE)) { |
| self::envoyerEnteteStatutHttp(self::HTTP_CODE_ERREUR); |
| $debogageSeulement = false; |
| } |
| |
| $exceptionsFormatees = array(); |
| foreach ($exceptionsTriees as $exceptions) { |
| foreach ($exceptions as $e) { |
| if ($debogageSeulement && self::$debogageMode == Debug::MODE_ENTETE_HTTP) { |
| $exceptionsFormatees[] = GestionnaireException::formaterExceptionTxt($e); |
| } else { |
| echo GestionnaireException::formaterExceptionXhtml($e); |
| } |
| } |
| } |
| |
| if ($debogageSeulement && self::$debogageMode == Debug::MODE_ENTETE_HTTP) { |
| header('X_REST_DEBOGAGE_MESSAGES: '.json_encode($exceptionsFormatees)); |
| } |
| } |
| } |
| } |
| ?> |