source: spip-zone/_plugins_/taxonomie/trunk/services/iucn/iucn_api.php @ 113783

Last change on this file since 113783 was 113783, checked in by root, 4 months ago

Mise au point des services de Taxonomie avec l'API des caches de Cache Factory.
A voir aussi comment gérer les get unitaires avec la sérialisation.
On change l'ordre des composants en mettant le tsn est premier pour un meilleur classement.

  • Property svn:eol-style set to native
File size: 10.3 KB
Line 
1<?php
2/**
3 * Ce fichier contient l'ensemble des constantes et fonctions implémentant le service web de IUCN Red List.
4 *
5 * @package SPIP\TAXONOMIE\SERVICES\IUCN
6 * @todo    phpdoc : exemples
7 */
8if (!defined('_ECRIRE_INC_VERSION')) {
9        return;
10}
11
12if (!defined('_TAXONOMIE_IUCN_ENDPOINT_BASE_URL')) {
13        /**
14         * Préfixe des URL du service web de WIKIPEDIA.
15         */
16        define('_TAXONOMIE_IUCN_ENDPOINT_BASE_URL', 'http://apiv3.iucnredlist.org/api/v3/');
17}
18
19if (!defined('_TAXONOMIE_IUCN_TAXON_BASE_URL')) {
20        /**
21         * URL de base d'une page d'un taxon sur le site de la red list IUCN.
22         * Cette URL est fournie dans les credits.
23         */
24        define('_TAXONOMIE_IUCN_TAXON_BASE_URL', 'http://apiv3.iucnredlist.org/api/v3/website/');
25}
26
27if (!defined('_TAXONOMIE_ITIS_SITE_URL')) {
28        /**
29         * URL de la page d'accueil du site ITIS.
30         * Cette URL est fournie dans les credits.
31         */
32        define('_TAXONOMIE_ITIS_SITE_URL', 'http://www.iucnredlist.org/');
33}
34
35if (!defined('_TAXONOMIE_IUCN_CACHE_TIMEOUT')) {
36        /**
37         * Période de renouvellement du cache de Wikipedia (6 mois)
38         */
39        define('_TAXONOMIE_IUCN_CACHE_TIMEOUT', 86400 * 30 * 6);
40}
41
42$GLOBALS['iucn_categorie'] = array(
43        /**
44         * Configuration des catégories IUCN.
45         */
46        // Extinct
47        'EX'    => array('item' => 'extinct', 'versions' => array('3.1', '2.3')),
48        // Extinct in the Wild
49        'EW'    => array('item' => 'extinct_in_the_wild', 'versions' => array('3.1', '2.3')),
50        // Critically Endangered
51        'CR'    => array('item' => 'critically_endangered', 'versions' => array('3.1', '2.3')),
52        // Critically Endangered (possibly extinct) - BirdLife
53        'PE'    => array('item' => 'possibly_extinct', 'versions' => array()),
54        // Endangered
55        'EN'    => array('item' => 'endangered', 'versions' => array('3.1', '2.3')),
56        'E'     => array('item' => 'endangered', 'versions' => array()),
57        // Vulnerable
58        'VU'    => array('item' => 'vulnerable', 'versions' => array('3.1', '2.3')),
59        'V'     => array('item' => 'vulnerable', 'versions' => array()),
60        // Threatened
61        'T' => array('item' => 'threatened', 'versions' => array()),
62        // Lower Risk (conservation dependent)
63        'LR/cd' => array('item' => 'lower_risk_conservation_dependent', 'versions' => array('2.3')),
64        // Near Threatened
65        'NT'    => array('item' => 'near_threatened', 'versions' => array('3.1')),
66        // Lower Risk (near threatened)
67        'LR/nt' => array('item' => 'lower_risk_near_threatened', 'versions' => array('2.3')),
68        // Least Concern
69        'LC'    => array('item' => 'least_concern', 'versions' => array('3.1')),
70        // Lower Risk (least concern)
71        'LR/lc' => array('item' => 'lower_risk_least_concern', 'versions' => array('2.3')),
72        // Data Deficient
73        'DD'    => array('item' => 'data_deficient', 'versions' => array('3.1', '2.3')),
74        // Not Evaluated
75        'NE'    => array('item' => 'not_evaluated', 'versions' => array('3.1', '2.3')),
76        // Not Recognized - BirdLife
77        'NR'    => array('item' => 'not_recognized', 'versions' => array()),
78);
79
80$GLOBALS['iucn_language'] = array(
81        /**
82         * Configuration de la correspondance entre langue IUCN et code de langue SPIP.
83         * La langue du service est l'index, le code SPIP est la valeur.
84         */
85        'fre' => 'fr',
86        'eng' => 'en',
87        'spa' => 'es'
88);
89
90$GLOBALS['iucn_webservice'] = array(
91        /**
92         * Variable globale de configuration de l'api des actions du service web IUCN Red List
93         */
94        'species'     => array(
95                'assessment'   => array(
96                        'list'     => 'result',
97                        'index'    => array(
98                                'nom_scientifique' => 'scientific_name',
99                                'code'             => 'category',
100                                'critere'          => 'criteria',
101                                'annee'            => 'published_year'
102                        ),
103                ),
104                'common_name' => array(
105                        'list'     => 'result',
106                        'index'    => array(
107                                'nom_commun' => 'taxonname',
108                                'langage'    => 'language'
109                        ),
110                ),
111                'history' => array(
112                        'list'     => 'result',
113                        'index'    => array(
114                                'annee'     => 'year',
115                                'categorie' => 'category',
116                                'code'      => 'code'
117                        ),
118                )
119        )
120);
121
122
123// -----------------------------------------------------------------------
124// ------------ API du web service IUCN - Actions principales ------------
125// -----------------------------------------------------------------------
126
127
128/**
129 * Renvoie l'ensemble des informations sur un taxon désigné par son identifiant unique TSN.
130 *
131 * @api
132 * @uses cache_taxonomie_existe()
133 * @uses itis_build_url()
134 * @uses inc_taxonomie_requeter_dist()
135 * @uses cache_taxonomie_ecrire()
136 *
137 * @param array  $search
138 *        Tableau contenant le taxon à cherché sous une forme textuelle et numérique:
139 *        - `name` : chaine de recherche qui est en généralement le nom scientifique du taxon.
140 *        - `tsn`  : identifiant ITIS du taxon, le TSN. Etant donné que ce service s'utilise toujours sur un taxon
141 *                   existant le TSN existe toujours. Il sert à créer le fichier cache.
142 *
143 * @return array
144 *        Si le taxon est trouvé, le tableau renvoyé possède les index associatifs suivants:
145 *        - `nom_scientifique`  : le nom scientifique complet du taxon tel qu'il doit être affiché (avec capitales).
146 *        - `rang`              : le nom anglais du rang taxonomique du taxon
147 *        - `regne`             : le nom scientifique du règne du taxon en minuscules
148 */
149function iucn_get_assessment($search) {
150
151        $assessment = array();
152
153        if (!empty($search['scientific_name'] and !empty($search['tsn']))) {
154                // Construction des options permettant de nommer le fichier cache.
155                include_spip('inc/cache');
156                $cache = array(
157                        'service'  => 'iucn',
158                        'action'   => 'assessment',
159                        'tsn'      => $search['tsn']
160                );
161
162                if ((!$file_cache = cache_existe('taxonomie', $cache))
163                or !filemtime($file_cache)
164                or (time() - filemtime($file_cache) > _TAXONOMIE_IUCN_CACHE_TIMEOUT)
165                        or (defined('_TAXONOMIE_CACHE_FORCER') ? _TAXONOMIE_CACHE_FORCER : false)) {
166                        // Construire l'URL de l'api sollicitée
167                        $url = iucn_build_url('species', 'assessment', $search['scientific_name']);
168
169                        // Acquisition des données spécifiées par l'url
170                        $requeter = charger_fonction('taxonomie_requeter', 'inc');
171                        $data = $requeter($url);
172
173                        // Récupération des informations choisies parmi l'enregistrement reçu à partir de la configuration
174                        // de l'action.
175                        $api = $GLOBALS['iucn_webservice']['species']['assessment'];
176                        include_spip('inc/filtres');
177                        $data = $api['list'] ? table_valeur($data, $api['list'], null) : $data;
178                        if (!empty($data)) {
179                                foreach ($api['index'] as $_destination => $_keys) {
180                                        $element = $_keys ? table_valeur($data, $_keys, null) : $data;
181                                        $assessment[$_destination] = is_string($element) ? trim($element) : $element;
182                                }
183                        }
184
185                        // Ajout de la catégorie dans un format non abrégé permettant de calculer le libellé traduit.
186                        $assessment['categorie'] = isset($GLOBALS['iucn_categorie'][$assessment['code']])
187                                ? $GLOBALS['iucn_categorie'][$assessment['code']]['item']
188                                : '';
189
190                        // Mise en cache systématique pour gérer le cas où la page cherchée n'existe pas.
191                        cache_ecrire('taxonomie', $cache, $assessment);
192                } else {
193                        // Lecture et désérialisation du cache
194                        $assessment = cache_lire('taxonomie', $file_cache);
195                }
196        }
197
198        return $assessment;
199}
200
201
202// ---------------------------------------------------------------------
203// ------------ API du web service IUCN - Fonctions annexes ------------
204// ---------------------------------------------------------------------
205
206/**
207 * Renvoie la langue telle que le service Wikipedia la désigne à partir du code de langue
208 * de SPIP.
209 *
210 * @api
211 *
212 * @param string $spip_language
213 *        Code de langue de SPIP. Prend les valeurs `fr`, `en`, `es`, etc.
214 *        La variable globale `$iucn_language` définit le transcodage langue IUCNs vers code SPIP.
215 *
216 * @return string
217 *        Langue au sens de IUCN - `fre`, `eng`, `spa` - ou chaine vide sinon.
218 */
219function iucn_find_language($spip_language) {
220
221        if (!$language = array_search($spip_language, $GLOBALS['iucn_language'])) {
222                $language = 'fre';
223        }
224
225        return $language;
226}
227
228
229/**
230 * Construit la phrase de crédits précisant que les données fournies proviennent d'une page de Wikipedia.
231 *
232 * @api
233 *
234 * @param int   $id_taxon
235 *        Id du taxon nécessaire pour construire l'url de la page Wikipedia concernée.
236 * @param array $informations
237 *        Tableau des informations complémentaires sur la source. Pour IUCN ce tableau fourni le ou
238 *        les champs remplis avec IUCN.
239 *
240 * @return string
241 *      Phrase de crédit.
242 */
243function iucn_credit($id_taxon, $informations) {
244        // On recherche le tsn du taxon afin de construire l'url vers sa page sur ITIS
245        $taxon = sql_fetsel('tsn, nom_scientifique', 'spip_taxons', 'id_taxon=' . sql_quote($id_taxon));
246
247        // On crée l'url du taxon sur le site de Wikipedia
248        $url = str_replace('%langue%', 'fr', _TAXONOMIE_WIKIPEDIA_PAGE_BASE_URL)
249                   . rawurlencode($taxon['nom_scientifique']);
250        $link = '<a class="nom_scientifique_inline" href="' . $url . '" rel="noreferrer">' . ucfirst($taxon['nom_scientifique']) . '</a>';
251
252        // La liste des champs concernés (a priori le descriptif)
253        include_spip('inc/taxonomie');
254        $champs = implode(', ', array_map('taxon_traduire_champ', $informations['champs']));
255
256        // On établit la citation
257        $credit = _T('taxonomie:credit_wikipedia', array('champs' => strtolower($champs), 'url_taxon' => $link));
258
259        return $credit;
260}
261
262
263// ----------------------------------------------------------------
264// ------------ Fonctions internes utilisées par l'API ------------
265// ----------------------------------------------------------------
266
267/**
268 * Construit l'URL de la requête IUCN correspondant à la demande utilisateur.
269 *
270 * @internal
271 *
272 * @param string $group
273 *        Groupe d'actions du même type. Prend les valeurs:
274 *        - `species` : groupe des actions de recherche du TSN à partir du nom commun ou scientifique
275 * @param string $action
276 *        Nom de l'action du service IUCN. Les valeurs pour le groupe species sont, par exemple, `assessment`,
277 *        `commonname` et `history`.
278 * @param string $key
279 *        Clé de recherche qui dépend de l'action demandée. Ce peut être le nom scientifique, le TSN, etc.
280 *        Cette clé doit être encodée si besoin par l'appelant.
281 *
282 * @return string
283 *        L'URL de la requête au service
284 */
285function iucn_build_url($group, $action, $key) {
286
287        // On récupère le token enregistré pour l'accès à l'API
288        include_spip('inc/config');
289        $token = lire_config('taxonomie/iucn_token', '');
290
291        // Construire la partie standard de l'URL de l'api sollicitée
292        $url = _TAXONOMIE_IUCN_ENDPOINT_BASE_URL
293                . $group
294                . '/' . rawurlencode($action)
295                . '?token=' . $key;
296
297        return $url;
298}
Note: See TracBrowser for help on using the repository browser.