services/REST/services.php

<?php
/**
 * Ce fichier permet de déclarer la classe Services, classe de base pour
 * toutes les ressources exposées à travers l'interface REST.
 *
 * @package openfoncier
 * @version SVN : $Id$
 */

/**
 * Cette classe instancie la classe utils pour établir une connexion à la base
 * de données et accéder aux méthodes principales de cette classe. Elle contient
 * également les méthodes permettant de vérifier l'intégrité REST des requêtes
 * reçues. On trouve la définition du comportement par défaut pour les méthodes
 * POST, PUT, GET, DELETE. Les méthodes de retour/réponse à la requête REST sont
 * aussi définies ici.
 */
class Services {

    /**
     * Constructeur
     *
     * Initialise les attributs de la classe.
     */
    public function __construct() {

        /**
         * Définition de la constante 'REST_REQUEST' qui est un marqueur
         * permettant d'indiquer que nous sommes dans le contexte d'une requête
         * REST. Par exemple, ce marqueur permet de ne pas afficher les erreurs
         * lors des traitements dans om_dbform.class.php.
         */
        if (!defined('REST_REQUEST')) {
            define('REST_REQUEST', true);
        }

        /**
         * @var mixed Cet attribut contient les données JSON reçues dans la
         * requête REST. C'est un tableau associatif. Il est utilisé lors de
         * la vérification de la validité du format de la requête REST (voir
         * la méthode requestValid).
         */
        $this->contents = array();

        /**
         * @var resource Cet attribut est l'intance du metier_manager qui permet
         * d'effectuer le traitement sur les données. L'instanciation est faite
         * dans une des classes enfants en fonctione de la ressource.
         */
        $this->metier_manager = null;

        /**
         * @var mixed Cet attribut est utilisé lors de la vérification de la
         * validité du format de la requête. Lorsque les données transmises
         * peuvent être différentes selon la requête alors il est nécessaire
         * d'avoir des groupes de validation. Chaque élément de mdtry_groups,
         * appelé un groupe, est traité comme un tableau. Toutes les chaines
         * trouvées dans un groupe doivent être présentes dans le tableau JSON
         * reçu. Cet attribut doit être rempli dans les classes dérivées.
         */
        $this->mdtry_grps = null;

    }

    /**
     * Destructeur
     *
     * Détruit les variables.
     */
    public function __destruct() {

        // Si un metiermanager est défini alors on le détruit
        if ($this->metier_manager) {
            unset($this->metier_manager);
        }

    }

    /**
     * Cette méthode vérifie si le format des données JSON reçues dans la
     * requête REST est valide.
     *
     * @param mixed $data Le tableau contenant les données reçues
     * @param mixed $optional Une liste des éléments pour lequel l'attribut
     * contents est autorisé à avoir une valeur vide
     * @return bool Renvoi true si le format des données est valide sinon false
     */
    protected function requestValid($data, $optional = null) {

        // Si le tableau est vide alors on retourne false
        if (count($data) == 0) {
            return false;
        }

        // Remplissage de l'attribut contents avec les données reçues
        foreach (array_keys($this->contents) as $elem) {
            if (isset($data[$elem])) {
                $this->contents[$elem] = $data[$elem];
            }
        }

        // Vérification que toutes les données nécessaires sont présentes à
        // moins qu'elle soit optionnelle
        foreach ($this->contents as $key => $value) {
            // Si la valeur est vide
            if (empty($value)) {
                // Si cette clé est optionnelle alors on passe à l'itération
                // suivante
                if ($optional && in_array($key, $optional)) {
                    continue;
                }
                // Si cette clé n'est pas optionnelle alors on retourne false
                return false;
            }
        }

        // On retourne true
        return true;

    }

    /**
     * Cette méthode permet de vérifier si les données transmises correspondent
     * à l'attendu. L'attendu est paramétré dans l'attribut 'mdtry_grps' par les
     * classes qui surcharge la classe Services. Si les données correspondent
     * alors on renvoi la clé du tableau vérifié sinon c'est la valeur NULL
     * qui est retournée.
     * 
     * @param mixed $data Le tableau contenant les données reçues via REST
     */
    protected function requestMdtrGroup(&$data) {

        // Si l'attribut est NULL alors on retourne NULL
        if (is_null($this->mdtry_grps)) {
            return NULL;
        }

        // On boucle sur chacun des groupes
        foreach ($this->mdtry_grps as $key => $group) {
            // On définit un marqueur pour le groupe
            $group_is_correct = NULL;
            // On boucle sur chacun des éléments du groupe
            foreach ($group as $elem) {
                // Si l'élément du groupe correspond
                if (isset($data[$elem]) && !empty($data[$elem])) {
                    // Si le marqueur est NULL alors on le marque à true
                    if (is_null($group_is_correct)) {
                        $group_is_correct = true;
                    }
                } else {
                    // Si l'élément ne correspond pas on passe au groupe suivant
                    $group_is_correct = false;
                    break;
                }
            }
            // Le groupe n'est pas correct alors on passe au groupe suivant
            if ($group_is_correct != true) {
                continue;
            }
            // Si le groupe est correct alors on retourne la clé du groupe
            return $key;
        }

        // Aucun groupe n'est correct alors on retourne NULL
        return NULL;

    }

    /**
     * Cette méthode permet de définir le traitement du POST sur une requête
     * REST. Elle doit être surchargée par la ressource si nécessaire. Le
     * comportement par défaut est de retourner une erreur 400.
     * 
     * @param mixed $request_data Les données JSON reçues (voir @uses)
     * 
     * @uses ./restler La librairie restler, lors de l'utilisation des méthodes
     * PUT et POST, la méthode qui reçoit les données entrantes DOIT contenir
     * un paramètre appellé request_data. En effet la librairie stocke la chaine
     * JSON reçue convertie en un tableau dans le paramètre request_data.
     */
    public function post($request_data) {
        return $this->sendHttpCode(400, "La méthode POST n'est pas disponible".
                                   " sur cette ressource.");
    }

    /**
     * Cette méthode permet de définir le traitement du GET sur une requête
     * REST. Elle doit être surchargée par la ressource si nécessaire. Le
     * comportement par défaut est de retourner une erreur 400.
     *
     * @param string $id L'identifiant de la ressource
     */
    public function get($id) {
        return $this->sendHttpCode(400, "La méthode GET n'est pas disponible".
                                   " sur cette ressource.");
    }

    /**
     * Cette méthode permet de définir le traitement du PUT sur une requête
     * REST. Elle doit être surchargée par la ressource si nécessaire. Le
     * comportement par défaut est de retourner une erreur 400.
     *
     * @param string $id L'identifiant de la ressource
     * @param mixed $request_data Les données JSON reçues (voir @uses)
     *
     * @uses ./restler La librairie restler, lors de l'utilisation des méthodes
     * PUT et POST, la méthode qui reçoit les données entrantes DOIT contenir
     * un paramètre appellé request_data. En effet la librairie stocke la chaine
     * JSON reçue convertie en un tableau dans le paramètre request_data.
     */
    public function put($id, $request_data) {
        return $this->sendHttpCode(400, "La méthode PUT n'est pas disponible".
                                   " sur cette ressource.");
    }

    /**
     * Cette méthode permet de définir le traitement du DELETE sur une requête
     * REST. Elle doit être surchargée par la ressource si nécessaire. Le
     * comportement par défaut est de retourner une erreur 400.
     *
     * @param string $id L'identifiant de la ressource
     */
    public function delete($id) {
        return $this->sendHttpCode(400, "La méthode DELETE n'est pas".
                                   " disponible sur cette ressource.");
    }

    /**
     * Cette méthode envoi une réponse en fonction du résultat du traitement
     * de la requête.
     *
     * @param string $result Le résultat du traitement
     * @param string $msg Le message additionnel à envoyer
     *
     * @todo XXX Vérifier la logique de traitement de cette méthode
     */
    protected function sendReply($result, $msg) {

        // Si le résultat de la requête n'est pas correct
        if ($result != 'OK') {

            // Si il y a eut un problème avec les données, alors on retourne un
            // code 400  et le message additionnel
            if ($result == 'BAD_DATA') {
                return $this->sendHttpCode(400, $msg);
            }

            // Si il y a eut un problème dans le traitement, alors on retourne
            // un code 500 avec le message additionnel
            return $this->sendHttpCode(500, $msg);

        }

        // Si le résultat de la requête est correct, alors on retourne un code
        // 200 et le message additionnel
        return $this->sendHttpCode(200, $msg);

    }

    /**
     * Cette méthode permet de retourner la réponse à la requête REST.
     *
     * @param int|string $http_code Le code HTTP à envoyer
     * @param string $message Le message additionnel à envoyer
     * @return mixed En-tête HTTP et tableau résultat de la requête REST
     *
     * @todo Modifier le tableau de retour pour qu'il ressemble au tableau
     * de retour d'erreur fourni par restler lors d'un 404 par exemple
     */
    protected function sendHttpCode($http_code, $message = '') {

        // Définition du protocole HTTP
        $http_protocol = "HTTP/1.0"; 
        if (isset($_SERVER['SERVER_PROTOCOL'])
            && stripos($_SERVER['SERVER_PROTOCOL'],"HTTP") >= 0) {
            $http_protocol = $_SERVER['SERVER_PROTOCOL'];
        }

        // Définition des codes HTTP
        $http = array(
            200 => '200 OK',
            201 => '201 Created',
            204 => '204 No Content',
            400 => '400 Bad Request',
            401 => '401 Unauthorized',
            403 => '403 Forbidden',
            404 => '404 Not Found',
            409 => '409 Conflict',
            500 => '500 Internal Server Error',
        );

        // Gestion du paramètre $http_code - les types int et string peuvent
        // être reçus
        if (!is_numeric($http_code)) {
            $http_code = intval($http_code);
        }

        // Envoi de l'en-tête HTTP
        header($http_protocol." ".$http[$http_code]);

        // Retour du tableau résultat
        return array(
            'http_code' => $http_code,
            'http_code_message' => $http[$http_code],
            'message' => $message,
        );

    }

}

?>
1	mlimic	515	<?php
2	fmichon	715	/**
3			* Ce fichier permet de déclarer la classe Services, classe de base pour
4			* toutes les ressources exposées à travers l'interface REST.
5	mlimic	516	*
6	fmichon	715	* @package openfoncier
7			* @version SVN : $Id$
8	mlimic	516	*/
9
10	fmichon	715	/**
11			* Cette classe instancie la classe utils pour établir une connexion à la base
12			* de données et accéder aux méthodes principales de cette classe. Elle contient
13			* également les méthodes permettant de vérifier l'intégrité REST des requêtes
14			* reçues. On trouve la définition du comportement par défaut pour les méthodes
15			* POST, PUT, GET, DELETE. Les méthodes de retour/réponse à la requête REST sont
16			* aussi définies ici.
17			*/
18	fmichon	704	class Services {
19	fmichon	715
20			/**
21			* Constructeur
22	fmichon	704	*
23	fmichon	715	* Initialise les attributs de la classe.
24	fmichon	704	*/
25	fmichon	775	public function __construct() {
26	fmichon	715
27			/**
28			* Définition de la constante 'REST_REQUEST' qui est un marqueur
29			* permettant d'indiquer que nous sommes dans le contexte d'une requête
30			* REST. Par exemple, ce marqueur permet de ne pas afficher les erreurs
31			* lors des traitements dans om_dbform.class.php.
32	fmichon	704	*/
33			if (!defined('REST_REQUEST')) {
34			define('REST_REQUEST', true);
35	mlimic	515	}
36	fmichon	715
37			/**
38	fmichon	772	* @var mixed Cet attribut contient les données JSON reçues dans la
39			* requête REST. C'est un tableau associatif. Il est utilisé lors de
40			* la vérification de la validité du format de la requête REST (voir
41			* la méthode requestValid).
42	fmichon	704	*/
43			$this->contents = array();
44	fmichon	715
45			/**
46			* @var resource Cet attribut est l'intance du metier_manager qui permet
47			* d'effectuer le traitement sur les données. L'instanciation est faite
48			* dans une des classes enfants en fonctione de la ressource.
49	fmichon	704	*/
50			$this->metier_manager = null;
51	fmichon	715
52			/**
53	fmichon	772	* @var mixed Cet attribut est utilisé lors de la vérification de la
54	fmichon	773	* validité du format de la requête. Lorsque les données transmises
55			* peuvent être différentes selon la requête alors il est nécessaire
56			* d'avoir des groupes de validation. Chaque élément de mdtry_groups,
57	fmichon	772	* appelé un groupe, est traité comme un tableau. Toutes les chaines
58			* trouvées dans un groupe doivent être présentes dans le tableau JSON
59			* reçu. Cet attribut doit être rempli dans les classes dérivées.
60	fmichon	704	*/
61			$this->mdtry_grps = null;
62	fmichon	715
63	fmichon	704	}
64	fmichon	715
65			/**
66			* Destructeur
67	fmichon	704	*
68	fmichon	715	* Détruit les variables.
69	fmichon	704	*/
70	fmichon	775	public function __destruct() {
71	fmichon	715
72			// Si un metiermanager est défini alors on le détruit
73	fmichon	704	if ($this->metier_manager) {
74			unset($this->metier_manager);
75	mlimic	515	}
76	fmichon	715
77	fmichon	704	}
78	mlimic	515
79	fmichon	715	/**
80			* Cette méthode vérifie si le format des données JSON reçues dans la
81			* requête REST est valide.
82			*
83			* @param mixed $data Le tableau contenant les données reçues
84			* @param mixed $optional Une liste des éléments pour lequel l'attribut
85			* contents est autorisé à avoir une valeur vide
86			* @return bool Renvoi true si le format des données est valide sinon false
87	fmichon	704	*/
88	fmichon	715	protected function requestValid($data, $optional = null) {
89
90			// Si le tableau est vide alors on retourne false
91			if (count($data) == 0) {
92			return false;
93			}
94
95			// Remplissage de l'attribut contents avec les données reçues
96			foreach (array_keys($this->contents) as $elem) {
97			if (isset($data[$elem])) {
98			$this->contents[$elem] = $data[$elem];
99			}
100			}
101
102			// Vérification que toutes les données nécessaires sont présentes à
103			// moins qu'elle soit optionnelle
104	fmichon	704	foreach ($this->contents as $key => $value) {
105	fmichon	715	// Si la valeur est vide
106	fmichon	704	if (empty($value)) {
107	fmichon	715	// Si cette clé est optionnelle alors on passe à l'itération
108			// suivante
109	fmichon	704	if ($optional && in_array($key, $optional)) {
110			continue;
111			}
112	fmichon	715	// Si cette clé n'est pas optionnelle alors on retourne false
113	fmichon	704	return false;
114			}
115			}
116	fmichon	715
117			// On retourne true
118	fmichon	704	return true;
119	mlimic	515
120	fmichon	704	}
121	mlimic	518
122	fmichon	715	/**
123	fmichon	773	* Cette méthode permet de vérifier si les données transmises correspondent
124			* à l'attendu. L'attendu est paramétré dans l'attribut 'mdtry_grps' par les
125			* classes qui surcharge la classe Services. Si les données correspondent
126			* alors on renvoi la clé du tableau vérifié sinon c'est la valeur NULL
127			* qui est retournée.
128	fmichon	715	*
129	fmichon	773	* @param mixed $data Le tableau contenant les données reçues via REST
130	fmichon	704	*/
131			protected function requestMdtrGroup(&$data) {
132	fmichon	772
133			// Si l'attribut est NULL alors on retourne NULL
134			if (is_null($this->mdtry_grps)) {
135			return NULL;
136	mlimic	515	}
137	fmichon	772
138			// On boucle sur chacun des groupes
139			foreach ($this->mdtry_grps as $key => $group) {
140			// On définit un marqueur pour le groupe
141			$group_is_correct = NULL;
142			// On boucle sur chacun des éléments du groupe
143			foreach ($group as $elem) {
144			// Si l'élément du groupe correspond
145	fmichon	704	if (isset($data[$elem]) && !empty($data[$elem])) {
146	fmichon	772	// Si le marqueur est NULL alors on le marque à true
147			if (is_null($group_is_correct)) {
148			$group_is_correct = true;
149	fmichon	704	}
150	fmichon	772	} else {
151			// Si l'élément ne correspond pas on passe au groupe suivant
152			$group_is_correct = false;
153			break;
154	fmichon	704	}
155			}
156	fmichon	772	// Le groupe n'est pas correct alors on passe au groupe suivant
157			if ($group_is_correct != true) {
158			continue;
159			}
160			// Si le groupe est correct alors on retourne la clé du groupe
161			return $key;
162	fmichon	704	}
163	fmichon	772
164			// Aucun groupe n'est correct alors on retourne NULL
165			return NULL;
166
167	fmichon	704	}
168	fmichon	715
169			/**
170			* Cette méthode permet de définir le traitement du POST sur une requête
171			* REST. Elle doit être surchargée par la ressource si nécessaire. Le
172			* comportement par défaut est de retourner une erreur 400.
173			*
174			* @param mixed $request_data Les données JSON reçues (voir @uses)
175			*
176			* @uses ./restler La librairie restler, lors de l'utilisation des méthodes
177			* PUT et POST, la méthode qui reçoit les données entrantes DOIT contenir
178			* un paramètre appellé request_data. En effet la librairie stocke la chaine
179			* JSON reçue convertie en un tableau dans le paramètre request_data.
180	fmichon	704	*/
181	fmichon	715	public function post($request_data) {
182	fmichon	774	return $this->sendHttpCode(400, "La méthode POST n'est pas disponible".
183			" sur cette ressource.");
184	fmichon	704	}
185	fmichon	715
186			/**
187			* Cette méthode permet de définir le traitement du GET sur une requête
188			* REST. Elle doit être surchargée par la ressource si nécessaire. Le
189			* comportement par défaut est de retourner une erreur 400.
190			*
191			* @param string $id L'identifiant de la ressource
192	fmichon	704	*/
193	fmichon	715	public function get($id) {
194	fmichon	774	return $this->sendHttpCode(400, "La méthode GET n'est pas disponible".
195			" sur cette ressource.");
196	fmichon	704	}
197	fmichon	715
198			/**
199			* Cette méthode permet de définir le traitement du PUT sur une requête
200			* REST. Elle doit être surchargée par la ressource si nécessaire. Le
201			* comportement par défaut est de retourner une erreur 400.
202			*
203	fmichon	874	* @param string $id L'identifiant de la ressource
204	fmichon	715	* @param mixed $request_data Les données JSON reçues (voir @uses)
205			*
206			* @uses ./restler La librairie restler, lors de l'utilisation des méthodes
207			* PUT et POST, la méthode qui reçoit les données entrantes DOIT contenir
208			* un paramètre appellé request_data. En effet la librairie stocke la chaine
209			* JSON reçue convertie en un tableau dans le paramètre request_data.
210	fmichon	704	*/
211	mlimic	797	public function put($id, $request_data) {
212	fmichon	774	return $this->sendHttpCode(400, "La méthode PUT n'est pas disponible".
213			" sur cette ressource.");
214	fmichon	704	}
215	mlimic	518
216	fmichon	715	/**
217			* Cette méthode permet de définir le traitement du DELETE sur une requête
218			* REST. Elle doit être surchargée par la ressource si nécessaire. Le
219			* comportement par défaut est de retourner une erreur 400.
220			*
221			* @param string $id L'identifiant de la ressource
222	fmichon	704	*/
223	fmichon	715	public function delete($id) {
224	fmichon	774	return $this->sendHttpCode(400, "La méthode DELETE n'est pas".
225			" disponible sur cette ressource.");
226	fmichon	704	}
227	mlimic	518
228	fmichon	715	/**
229			* Cette méthode envoi une réponse en fonction du résultat du traitement
230			* de la requête.
231			*
232			* @param string $result Le résultat du traitement
233	fmichon	729	* @param string $msg Le message additionnel à envoyer
234	fmichon	715	*
235			* @todo XXX Vérifier la logique de traitement de cette méthode
236	fmichon	704	*/
237	mlimic	728	protected function sendReply($result, $msg) {
238	mlimic	515
239	fmichon	715	// Si le résultat de la requête n'est pas correct
240			if ($result != 'OK') {
241	fmichon	704
242	fmichon	715	// Si il y a eut un problème avec les données, alors on retourne un
243	fmichon	729	// code 400 et le message additionnel
244	mlimic	728	if ($result == 'BAD_DATA') {
245			return $this->sendHttpCode(400, $msg);
246	fmichon	715	}
247	fmichon	704
248	fmichon	715	// Si il y a eut un problème dans le traitement, alors on retourne
249			// un code 500 avec le message additionnel
250	mlimic	728	return $this->sendHttpCode(500, $msg);
251	fmichon	715
252			}
253
254			// Si le résultat de la requête est correct, alors on retourne un code
255			// 200 et le message additionnel
256	mlimic	728	return $this->sendHttpCode(200, $msg);
257	fmichon	715
258			}
259
260			/**
261			* Cette méthode permet de retourner la réponse à la requête REST.
262			*
263			* @param int\|string $http_code Le code HTTP à envoyer
264			* @param string $message Le message additionnel à envoyer
265			* @return mixed En-tête HTTP et tableau résultat de la requête REST
266			*
267	fmichon	773	* @todo Modifier le tableau de retour pour qu'il ressemble au tableau
268	fmichon	715	* de retour d'erreur fourni par restler lors d'un 404 par exemple
269	fmichon	704	*/
270	fmichon	715	protected function sendHttpCode($http_code, $message = '') {
271
272			// Définition du protocole HTTP
273	fmichon	704	$http_protocol = "HTTP/1.0";
274	fmichon	715	if (isset($_SERVER['SERVER_PROTOCOL'])
275			&& stripos($_SERVER['SERVER_PROTOCOL'],"HTTP") >= 0) {
276			$http_protocol = $_SERVER['SERVER_PROTOCOL'];
277	fmichon	704	}
278	fmichon	715
279			// Définition des codes HTTP
280	fmichon	704	$http = array(
281	fmichon	715	200 => '200 OK',
282			201 => '201 Created',
283			204 => '204 No Content',
284			400 => '400 Bad Request',
285			401 => '401 Unauthorized',
286			403 => '403 Forbidden',
287			404 => '404 Not Found',
288			409 => '409 Conflict',
289			500 => '500 Internal Server Error',
290	fmichon	704	);
291	fmichon	715
292			// Gestion du paramètre $http_code - les types int et string peuvent
293			// être reçus
294			if (!is_numeric($http_code)) {
295			$http_code = intval($http_code);
296	fmichon	704	}
297	fmichon	715
298			// Envoi de l'en-tête HTTP
299			header($http_protocol." ".$http[$http_code]);
300
301			// Retour du tableau résultat
302			return array(
303			'http_code' => $http_code,
304			'http_code_message' => $http[$http_code],
305			'message' => $message,
306			);
307
308	mlimic	515	}
309
310	fmichon	704	}
311
312	mlimic	515	?>