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	<?php
2	/**
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	*
6	* @package openfoncier
7	* @version SVN : $Id$
8	*/
9
10	/**
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	class Services {
19
20	/**
21	* Constructeur
22	*
23	* Initialise les attributs de la classe.
24	*/
25	public function __construct() {
26
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	*/
33	if (!defined('REST_REQUEST')) {
34	define('REST_REQUEST', true);
35	}
36
37	/**
38	* @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	*/
43	$this->contents = array();
44
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	*/
50	$this->metier_manager = null;
51
52	/**
53	* @var mixed Cet attribut est utilisé lors de la vérification de la
54	* 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	* 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	*/
61	$this->mdtry_grps = null;
62
63	}
64
65	/**
66	* Destructeur
67	*
68	* Détruit les variables.
69	*/
70	public function __destruct() {
71
72	// Si un metiermanager est défini alors on le détruit
73	if ($this->metier_manager) {
74	unset($this->metier_manager);
75	}
76
77	}
78
79	/**
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	*/
88	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	foreach ($this->contents as $key => $value) {
105	// Si la valeur est vide
106	if (empty($value)) {
107	// Si cette clé est optionnelle alors on passe à l'itération
108	// suivante
109	if ($optional && in_array($key, $optional)) {
110	continue;
111	}
112	// Si cette clé n'est pas optionnelle alors on retourne false
113	return false;
114	}
115	}
116
117	// On retourne true
118	return true;
119
120	}
121
122	/**
123	* 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	*
129	* @param mixed $data Le tableau contenant les données reçues via REST
130	*/
131	protected function requestMdtrGroup(&$data) {
132
133	// Si l'attribut est NULL alors on retourne NULL
134	if (is_null($this->mdtry_grps)) {
135	return NULL;
136	}
137
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	if (isset($data[$elem]) && !empty($data[$elem])) {
146	// Si le marqueur est NULL alors on le marque à true
147	if (is_null($group_is_correct)) {
148	$group_is_correct = true;
149	}
150	} else {
151	// Si l'élément ne correspond pas on passe au groupe suivant
152	$group_is_correct = false;
153	break;
154	}
155	}
156	// 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	}
163
164	// Aucun groupe n'est correct alors on retourne NULL
165	return NULL;
166
167	}
168
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	*/
181	public function post($request_data) {
182	return $this->sendHttpCode(400, "La méthode POST n'est pas disponible".
183	" sur cette ressource.");
184	}
185
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	*/
193	public function get($id) {
194	return $this->sendHttpCode(400, "La méthode GET n'est pas disponible".
195	" sur cette ressource.");
196	}
197
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	* @param string $id L'identifiant de la ressource
204	* @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	*/
211	public function put($id, $request_data) {
212	return $this->sendHttpCode(400, "La méthode PUT n'est pas disponible".
213	" sur cette ressource.");
214	}
215
216	/**
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	*/
223	public function delete($id) {
224	return $this->sendHttpCode(400, "La méthode DELETE n'est pas".
225	" disponible sur cette ressource.");
226	}
227
228	/**
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	* @param string $msg Le message additionnel à envoyer
234	*
235	* @todo XXX Vérifier la logique de traitement de cette méthode
236	*/
237	protected function sendReply($result, $msg) {
238
239	// Si le résultat de la requête n'est pas correct
240	if ($result != 'OK') {
241
242	// Si il y a eut un problème avec les données, alors on retourne un
243	// code 400 et le message additionnel
244	if ($result == 'BAD_DATA') {
245	return $this->sendHttpCode(400, $msg);
246	}
247
248	// Si il y a eut un problème dans le traitement, alors on retourne
249	// un code 500 avec le message additionnel
250	return $this->sendHttpCode(500, $msg);
251
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	return $this->sendHttpCode(200, $msg);
257
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	* @todo Modifier le tableau de retour pour qu'il ressemble au tableau
268	* de retour d'erreur fourni par restler lors d'un 404 par exemple
269	*/
270	protected function sendHttpCode($http_code, $message = '') {
271
272	// Définition du protocole HTTP
273	$http_protocol = "HTTP/1.0";
274	if (isset($_SERVER['SERVER_PROTOCOL'])
275	&& stripos($_SERVER['SERVER_PROTOCOL'],"HTTP") >= 0) {
276	$http_protocol = $_SERVER['SERVER_PROTOCOL'];
277	}
278
279	// Définition des codes HTTP
280	$http = array(
281	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	);
291
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	}
297
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	}
309
310	}
311
312	?>