source: spip-zone/_plugins_/taxonomie/trunk/services/itis/itis_api.php @ 96992

Last change on this file since 96992 was 96992, checked in by eric@…, 3 years ago

Phpdoc et formatage PSR SPIP

  • Property svn:eol-style set to native
File size: 23.6 KB
Line 
1<?php
2/**
3 * Ce fichier contient l'ensemble des constantes et fonctions implémentant le service de taxonomie ITIS.
4 *
5 * @package SPIP\TAXONOMIE\SERVICES\ITIS
6 * @todo    phpdoc : exemples
7 */
8if (!defined('_ECRIRE_INC_VERSION')) {
9        return;
10}
11
12if (!defined('_TAXONOMIE_ITIS_ENDPOINT_BASE_URL')) {
13        /**
14         * Préfixe des URL du service web de ITIS.
15         */
16        define('_TAXONOMIE_ITIS_ENDPOINT_BASE_URL', 'http://www.itis.gov/ITISWebService/');
17}
18
19if (!defined('_TAXONOMIE_ITIS_TAXON_BASE_URL')) {
20        /**
21         * URL de base d'une page d'un taxon sur le site d'ITIS.
22         * Cette URL est fournie dans les credits.
23         */
24        define('_TAXONOMIE_ITIS_TAXON_BASE_URL', 'http://www.itis.gov/servlet/SingleRpt/SingleRpt?search_topic=TSN&search_value=');
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.itis.gov');
33}
34
35if (!defined('_TAXONOMIE_ITIS_REGEXP_RANKNAME')) {
36        /**
37         * Ligne d'un fichier ITIS hiérachie généré.
38         * Il est indispensable de respecter les majuscules des noms de groupe pour éviter de matcher
39         * les suborder, infrakingdom...
40         */
41        define('_TAXONOMIE_ITIS_REGEXP_RANKNAME', '#(%groups_list%):\s*(\w+)\s*\[([^\]]*)\]\s*\[(\d+)\]#');
42}
43
44
45$GLOBALS['itis_language'] = array(
46        /**
47         * Variable globale de configuration de la correspondance entre langue Wikipedia
48         * et code de langue SPIP. La langue du service est l'index, le code SPIP est la valeur.
49         */
50        'french'  => 'fr',
51        'english' => 'en',
52        'spanish' => 'es'
53);
54$GLOBALS['itis_webservice'] = array(
55        /**
56         * Variable globale de configuration de l'api des actions du service web ITIS
57         */
58        'search'     => array(
59                'commonname'     => array(
60                        'function' => 'searchByCommonName',
61                        'argument' => 'srchKey',
62                        'list'     => 'commonNames',
63                        'index'    => array('tsn' => 'tsn'),
64                        'find'     => array('nom_commun' => 'commonName')
65                ),
66                'scientificname' => array(
67                        'function' => 'searchByScientificName',
68                        'argument' => 'srchKey',
69                        'list'     => 'scientificNames',
70                        'index'    => array('tsn' => 'tsn'),
71                        'find'     => array('nom_scientifique' => 'combinedName')
72                )
73        ),
74        'vernacular' => array(
75                'vernacularlanguage' => array(
76                        'function' => 'getTsnByVernacularLanguage',
77                        'argument' => 'language',
78                        'list'     => 'vernacularTsns',
79                        'index'    => array('tsn' => 'commonName')
80                )
81        ),
82        'getfull'    => array(
83                'record' => array(
84                        'function' => 'getFullRecordFromTSN',
85                        'argument' => 'tsn',
86                        'list'     => '',
87                        'index'    => array(
88                                'nom_scientifique' => 'scientificName/combinedName',
89                                'rang'             => 'taxRank/rankName',
90                                'regne'            => 'kingdom/kingdomName',
91                                'tsn_parent'       => 'parentTSN/parentTsn',
92                                'auteur'           => 'taxonAuthor/authorship',
93                                'nom_commun'       => 'commonNameList/commonNames',
94                        )
95                )
96        ),
97        'get'        => array(
98                'scientificname' => array(
99                        'function' => 'getScientificNameFromTSN',
100                        'argument' => 'tsn',
101                        'list'     => '',
102                        'index'    => array('string', 'combinedName'),
103                ),
104                'kingdomname'    => array(
105                        'function' => 'getKingdomNameFromTSN',
106                        'argument' => 'tsn',
107                        'list'     => '',
108                        'index'    => array('string', 'kingdomName'),
109                ),
110                'parent'         => array(
111                        'function' => 'getHierarchyUpFromTSN',
112                        'argument' => 'tsn',
113                        'list'     => '',
114                        'index'    => array('string', 'parentTsn'),
115                ),
116                'rankname'       => array(
117                        'function' => 'getTaxonomicRankNameFromTSN',
118                        'argument' => 'tsn',
119                        'list'     => '',
120                        'index'    => array('string', 'rankName'),
121                ),
122                'author'         => array(
123                        'function' => 'getTaxonAuthorshipFromTSN',
124                        'argument' => 'tsn',
125                        'list'     => '',
126                        'index'    => array('string', 'authorship'),
127                ),
128                'coremetadata'   => array(
129                        'function' => 'getCoreMetadataFromTSN',
130                        'argument' => 'tsn',
131                        'list'     => '',
132                        'index'    => array('array', ''),
133                ),
134                'experts'        => array(
135                        'function' => 'getExpertsFromTSN',
136                        'argument' => 'tsn',
137                        'list'     => 'experts',
138                        'index'    => array('array', ''),
139                ),
140                'commonnames'    => array(
141                        'function' => 'getCommonNamesFromTSN',
142                        'argument' => 'tsn',
143                        'list'     => 'commonNames',
144                        'index'    => array('array', array('language' => 'commonName')),
145                ),
146                'othersources'   => array(
147                        'function' => 'getOtherSourcesFromTSN',
148                        'argument' => 'tsn',
149                        'list'     => 'otherSources',
150                        'index'    => array('array', ''),
151                ),
152                'hierarchyfull'  => array(
153                        'function' => 'getFullHierarchyFromTSN',
154                        'argument' => 'tsn',
155                        'list'     => 'hierarchyList',
156                        'index'    => array('array', ''),
157                ),
158                'hierarchydown'  => array(
159                        'function' => 'getHierarchyDownFromTSN',
160                        'argument' => 'tsn',
161                        'list'     => 'hierarchyList',
162                        'index'    => array('array', ''),
163                ),
164        ),
165);
166
167
168// -----------------------------------------------------------------------
169// ------------ API du web service ITIS - Actions principales ------------
170// -----------------------------------------------------------------------
171
172/**
173 * Recherche un taxon dans la base ITIS par son nom commun ou scientifique
174 * et retourne son identifiant unique nommé TSN ou 0 si le taxon n'existe pas.
175 * Selon le critère de correspondance de la recherche (stricte ou pas) la fonction
176 * retourne un ou plusieurs taxons.
177 *
178 * @api
179 * @uses api2url_itis()
180 * @uses service_requeter_json()
181 *
182 * @param string $action
183 *        Recherche par nom commun ou par nom scientifique. Prend les valeurs `commonname` ou `scientificname`
184 * @param string $search
185 *        Nom à rechercher précisément. Seul le taxon dont le nom coincidera exactement sera retourné.
186 * @param bool   $strict
187 *        `true` indique une correspondance stricte de la chaine recherchée ce qui a pour conséquence de renvoyer
188 *        une seule valeur de TSN. `false` indique une correspondance partielle et peut donc renvoyer plusieurs TSN.
189 *
190 * @return array
191 *        Si la recherche est stricte, la fonction retourne l'identifiant unique TSN dans la base ITIS
192 *        ou 0 si la recherche échoue.
193 *        Sinon, la fonction retourne une liste de couples de valeurs (TNS, valeur trouvée).
194 */
195function itis_search_tsn($action, $search, $strict = true) {
196        global $itis_webservice;
197        $tsn = array();
198
199        // Normaliser la recherche: trim et mise en lettres minuscules
200        $search = strtolower(trim($search));
201
202        // Construire l'URL de la fonction de recherche
203        $url = api2url_itis('json', 'search', $action, rawurlencode($search));
204
205        // Acquisition des données spécifiées par l'url
206        include_spip('inc/taxonomer');
207        $data = service_requeter_json($url);
208
209        // Récupération du TSN du taxon recherché
210        $api = $itis_webservice['search'][$action];
211        if (!empty($data[$api['list']])) {
212                // La recherche peut renvoyer plusieurs taxons. Suivant le critère de correspondance de la recherche
213                // on renvoie le "bon" taxon ou tous les taxons trouvés.
214                list($tsn_destination, $tsn_key) = each($api['index']);
215                list($search_destination, $search_key) = each($api['find']);
216                foreach ($data[$api['list']] as $_data) {
217                        if ($_data) {
218                                if (!$strict
219                                        or ($strict and (strcasecmp($_data[$search_key], $search) == 0))
220                                ) {
221                                        $tsn[] = array(
222                                                $tsn_destination    => intval($_data[$tsn_key]),
223                                                $search_destination => $_data[$search_key]
224                                        );
225                                        if ($strict) {
226                                                break;
227                                        }
228                                }
229                        }
230                }
231        }
232
233        return $tsn;
234}
235
236
237/**
238 * Renvoie l'ensemble des informations sur un taxon désigné par son identifiant unique TSN.
239 *
240 * @api
241 * @uses api2url_itis()
242 * @uses service_requeter_json()
243 *
244 * @param int $tsn
245 *        Identifiant unique du taxon dans la base ITIS, le TSN
246 *
247 * @return array
248 *        Si le taxon est trouvé, le tableau renvoyé possède les index associatifs suivants:
249 *        - `nom_scientique`    : le nom scientifique du taxon en minuscules
250 *        - `rang`            : le nom anglais du rang taxonomique du taxon
251 *        - `regne`            : le nom scientifque du règne du taxon en minuscules
252 *        - `tsn_parent`        : le TSN du parent du taxon ou 0 si le taxon est un règne
253 *        - `auteur`            : la citation d’auteurs et la date de publication
254 *        - `nom_commun`        : un tableau indexé par langue (au sens d'ITIS en minuscules, `english`, `french`,
255 *        `spanish`) fournissant le nom commun dans chacune des langues
256 */
257function itis_get_record($tsn) {
258        global $itis_webservice;
259        $record = array();
260
261        // Construire l'URL de l'api sollicitée
262        $url = api2url_itis('json', 'getfull', 'record', strval($tsn));
263
264        // Acquisition des données spécifiées par l'url
265        include_spip('inc/taxonomer');
266        $data = service_requeter_json($url);
267
268        // Récupération des informations choisies parmi l'enregistrement reçu à partir de la configuration
269        // de l'action.
270        $api = $itis_webservice['getfull']['record'];
271        include_spip('inc/filtres');
272        $data = $api['list'] ? table_valeur($data, $api['list'], null) : $data;
273        if (!empty($data)) {
274                foreach ($api['index'] as $_destination => $_keys) {
275                        $element = $_keys ? table_valeur($data, $_keys, null) : $data;
276                        $record[$_destination] = is_string($element) ? trim($element) : $element;
277                }
278        }
279
280        // On réorganise le sous-tableau des noms communs
281        $noms = array();
282        if (is_array($record['nom_commun'])
283                and $record['nom_commun']
284        ) {
285                foreach ($record['nom_commun'] as $_nom) {
286                        $noms[strtolower($_nom['language'])] = trim($_nom['commonName']);
287                }
288        }
289        // Et on modifie l'index des noms communs avec le tableau venant d'être construit.
290        $record['nom_commun'] = $noms;
291
292        return $record;
293}
294
295
296/**
297 * Renvoie les informations demandées sur un taxon désigné par son identifiant unique TSN.
298 *
299 * @api
300 * @uses api2url_itis()
301 * @uses service_requeter_json()
302 *
303 * @param string $action
304 *        Type d'information demandé. Prend les valeurs
305 *        - `scientificname`    : le nom scientifique du taxon
306 *        - `kingdomname`        : le règne du taxon
307 *        - `parent`            : le taxon parent dont son TSN
308 *        - `rankname`        : le rang taxonomique du taxon
309 *        - `author`            : le ou les auteurs du taxon
310 *        - `coremetadata`    : les métadonnées (à vérifier)
311 *        - `experts`            : les experts du taxon
312 *        - `commonnames`        : le ou les noms communs
313 *        - `othersources`    : les sources d'information sur le taxon
314 *        - `hierarchyfull`    : la hiérarchie complète jusqu'au taxon
315 *        - `hierarchydown`    : la hiérarchie (à vérifier)
316 * @param int    $tsn
317 *        Identifiant unique du taxon dans la base ITIS (TSN)
318 *
319 * @return string|array
320 *        Chaine ou tableau caractéristique du type d'information demandé.
321 */
322function itis_get_information($action, $tsn) {
323        global $itis_webservice;
324
325        // Construire l'URL de l'api sollicitée
326        $url = api2url_itis('json', 'get', $action, strval($tsn));
327
328        // Acquisition des données spécifiées par l'url
329        include_spip('inc/taxonomer');
330        $data = service_requeter_json($url);
331
332        // On vérifie que le tableau est complet sinon on retourne un tableau vide
333        $api = $itis_webservice['get'][$action];
334        include_spip('inc/filtres');
335        $data = $api['list'] ? table_valeur($data, $api['list'], null) : $data;
336        list($type, $index) = $api['index'];
337
338        if ($type == 'string') {
339                $information = '';
340                if (!empty($data[$index])) {
341                        $information = $data[$index];
342                }
343        } else {
344                $information = array();
345                if ($data) {
346                        $first_value = reset($data);
347                        if ($first_value) {
348                                if (!$index) {
349                                        $information = $data;
350                                        $format = "format_$action";
351                                        if (function_exists($format)) {
352                                                $information = $format($information);
353                                        }
354                                } else {
355                                        list($destination, $key) = each($index);
356                                        foreach ($data as $_data) {
357                                                $information[strtolower($_data[$destination])][] = $_data[$key];
358                                        }
359                                }
360                        }
361                }
362        }
363
364        return $information;
365}
366
367
368/**
369 * Renvoie la liste des noms communs définis pour certains taxons dans une langue donnée mais
370 * tout règne confondu.
371 * Peu de taxons sont traduits dans la base ITIS, seules le français, l'anglais et
372 * l'espagnol sont réellement utilisables.
373 * Pour l'anglais, le nombre de taxons est très important car les 4 règnes non supportés par
374 * le plugin Taxonomie sont fortement traduits.
375 *
376 * @api
377 * @uses api2url_itis()
378 * @uses service_requeter_json()
379 *
380 * @param $language
381 *        Langue au sens d'ITIS écrite en minuscules. Vaut `french`, `english`, `spanish`...
382 *
383 * @return array
384 *        Tableau des noms communs associés à leur TSN. Le format du tableau est le suivant:
385 *        - l'index représente le TSN du taxon,
386 *        - la valeur fournit le tableau des noms communs, chaque nom étant préfixé du code de langue
387 *        de SPIP (ex: `[fr]bactéries`)
388 */
389function itis_list_vernaculars($language) {
390        global $itis_webservice, $itis_language;
391        $vernaculars = array();
392
393        // Construire l'URL de l'api sollicitée
394        $url = api2url_itis('json', 'vernacular', 'vernacularlanguage', $language);
395
396        // Acquisition des données spécifiées par l'url
397        include_spip('inc/taxonomer');
398        include_spip('inc/distant');
399        $data = service_requeter_json($url, _INC_DISTANT_MAX_SIZE * 7);
400
401        $api = $itis_webservice['vernacular']['vernacularlanguage'];
402        if (!empty($data[$api['list']])) {
403                $tag_language = '[' . $itis_language[$language] . ']';
404                list($destination, $name_key) = each($api['index']);
405                foreach ($data[$api['list']] as $_data) {
406                        if (!empty($_data[$destination])
407                                and !empty($_data[$name_key])
408                        ) {
409                                $vernaculars[$_data[$destination]][] = $tag_language . $_data[$name_key];
410                        }
411                }
412        }
413
414        return $vernaculars;
415}
416
417
418// -----------------------------------------------------------------------------------------------
419// ------------ API du web service ITIS - Fonctions de lecture des fichiers de taxons ------------
420// -----------------------------------------------------------------------------------------------
421
422/**
423 * Lit le fichier hiérarchique ITIS des taxons d'un règne et renvoie la liste des taxons retenus.
424 *
425 * @api
426 *
427 * @param string $kingdom
428 *        Nom scientifique du règne en lettres minuscules : `animalia`, `plantae`, `fungi`.
429 * @param string $upto
430 *        Rang taxonomique minimal jusqu'où charger le règne. Ce rang est fourni en anglais et en minuscules.
431 *        Il prend les valeurs :
432 *        - `phylum` (pour le règne Animalia) ou `division` (pour les règnes Fungi et Plantae),
433 *        - `class`,
434 *        - `order`,
435 *        - `family`,
436 *        - `genus`.
437 * @param int    $sha_file
438 *        Sha calculé à partir du fichier de taxons correspondant au règne choisi. Le sha est retourné
439 *        par la fonction afin d'être stocké par le plugin.
440 *
441 * @return array
442 *        Chaque élément du tableau est un taxon. Un taxon est un tableau associatif dont chaque
443 *        index correspond à un champ de la table `spip_taxons`. Le tableau est ainsi prêt pour une
444 *        insertion en base de données.
445 */
446function itis_read_hierarchy($kingdom, $upto, &$sha_file) {
447        $hierarchy = array();
448        $sha_file = false;
449
450        include_spip('inc/taxonomer');
451        static $group_ids = array(
452                'kingdom' => 1,
453                'class'   => 3,
454                'order'   => 4,
455                'family'  => 5,
456                'genus'   => 6,
457                'specie'  => 7
458        );
459        $rang_phylum = $kingdom == _TAXONOMIE_REGNE_ANIMAL ? 'phylum' : 'division';
460        $group_ids[$rang_phylum] = 2;
461        asort($group_ids);
462
463        if (array_key_exists($upto, $group_ids)) {
464                include_spip('inc/charsets');
465                // Construire la regexp qui permet de limiter la hiérarchie comme demandée
466                $groups_list = implode('|', array_map('ucfirst', array_slice(array_flip($group_ids), 0, $group_ids[$upto])));
467                $regexp = str_replace('%groups_list%', $groups_list, _TAXONOMIE_ITIS_REGEXP_RANKNAME);
468
469                $file = find_in_path('services/itis/' . ucfirst($kingdom) . '_Genus.txt');
470                if (file_exists($file)
471                        and ($sha_file = sha1_file($file))
472                ) {
473                        $lines = file($file);
474                        if ($lines) {
475                                $groups = array();
476                                for ($i = 1; $i <= array_search($upto, $group_ids); $i++) {
477                                        $groups[$i] = 0;
478                                }
479                                // Scan du fichier ligne par ligne
480                                foreach ($lines as $_line) {
481                                        $taxon = array(
482                                                'regne'      => $kingdom,
483                                                'nom_commun' => '',
484                                                'descriptif' => '',
485                                                'edite'      => 'non'
486                                        );
487                                        if (preg_match($regexp, $_line, $match)) {
488                                                // Initialisation du taxon
489                                                $taxon['rang'] = strtolower($match[1]);
490                                                $taxon['nom_scientifique'] = strtolower($match[2]);
491                                                $taxon['auteur'] = importer_charset(trim($match[3]), 'iso-8859-1');
492                                                $tsn = intval($match[4]);
493                                                $taxon['tsn'] = $tsn;
494
495                                                // Recherche du parent
496                                                $taxon_group_id = $group_ids[$taxon['rang']];
497                                                if ($taxon_group_id == 1) {
498                                                        // On traite à part le cas du règne qui ne se rencontre qu'une fois en début de fichier
499                                                        $taxon['tsn_parent'] = 0;
500                                                } else {
501                                                        for ($i = $taxon_group_id - 1; $i >= 1; $i--) {
502                                                                if ($groups[$i]) {
503                                                                        $taxon['tsn_parent'] = $groups[$i];
504                                                                        break;
505                                                                }
506                                                        }
507                                                }
508
509                                                // Insertion du taxon dans la hiérarchie
510                                                $hierarchy[$tsn] = $taxon;
511
512                                                // Stockage du groupe venant d'être inséré
513                                                $groups[$taxon_group_id] = $tsn;
514                                                // On vide les groupes d'après
515                                                for ($i = $taxon_group_id + 1; $i <= 5; $i++) {
516                                                        $groups[$i] = 0;
517                                                }
518                                        }
519                                }
520                        }
521                }
522        }
523
524        return $hierarchy;
525}
526
527
528/**
529 * Lit le fichier des noms communs - tout règne confondu - d'une langue donnée et renvoie un tableau
530 * de tous ces noms indexés par leur TSN.
531 * La base de données ITIS contient souvent plusieurs traductions d'une même langue pour un taxon donné. Cette
532 * fonction met à jour séquentiellement les traductions sans s'en préoccuper. De fait, c'est la dernière traduction
533 * rencontrée qui sera fournie dans le tableau de sortie.
534 *
535 * @api
536 *
537 * @param string $language
538 *        Langue au sens d'ITIS écrite en minuscules. Vaut `french`, `english`, `spanish` etc.
539 * @param int    $sha_file
540 *        Sha calculé à partir du fichier des noms communs choisi. Le sha est retourné
541 *        par la fonction afin d'être stocké par le plugin.
542 *
543 * @return array
544 *        Tableau des noms communs d'une langue donnée indexé par TSN. Le nom commun est préfixé
545 *        par le tag de langue SPIP pour être utilisé simplement dans une balise `<multi>`.
546 */
547function itis_read_vernaculars($language, &$sha_file) {
548        global $itis_language;
549        $vernaculars = array();
550        $sha_file = false;
551
552        // Ouvrir le fichier de nom communs correspondant au code de langue spécifié
553        $file = find_in_path("services/itis/vernaculars_${language}.csv");
554        if (file_exists($file)
555                and ($sha_file = sha1_file($file))
556        ) {
557                // Lecture du fichier csv comme un fichier texte sachant que :
558                // - le délimiteur de colonne est une virgule
559                // - le caractère d'encadrement d'un texte est le double-quotes
560                $lines = file($file);
561                if ($lines) {
562                        // Créer le tableau de sortie à partir du tableau issu du csv (TSN, nom commun)
563                        $tag_language = '[' . $itis_language[$language] . ']';
564                        foreach ($lines as $_line) {
565                                list($tsn, $name) = explode(',', trim($_line));
566                                $vernaculars[intval($tsn)] = $tag_language . trim($name, '"');
567                        }
568                }
569        }
570
571        return $vernaculars;
572}
573
574
575// ---------------------------------------------------------------------
576// ------------ API du web service ITIS - Fonctions annexes ------------
577// ---------------------------------------------------------------------
578
579/**
580 * Renvoie la langue telle que le service ITIS la désigne à partir du code de langue
581 * de SPIP.
582 *
583 * @api
584 *
585 * @param string $spip_language
586 *        Code de langue de SPIP. Prend les valeurs `fr`, `en`, `es`, etc.
587 *        La variable globale `$itis_language` définit le transcodage langue ITIS vers code SPIP.
588 *
589 * @return string
590 *      Langue au sens d'ITIS en minuscules - `french`, `english`, `spanish` - ou chaine vide sinon.
591 */
592function itis_spipcode2language($spip_language) {
593        global $itis_language;
594
595        if (!$language = array_search($spip_language, $itis_language)) {
596                $language = '';
597        }
598
599        return $language;
600}
601
602
603/**
604 * Construit la phrase de crédits précisant que les données fournies proviennent de la base de données
605 * d'ITIS.
606 *
607 * @api
608 *
609 * @param int   $id_taxon
610 *        Id du taxon nécessaire pour construire l'url de la page ITIS fournissant une information complète sur
611 *        le taxon.
612 * @param array $informations
613 *        Tableau des informations complémentaires sur la source. Pour ITIS ce tableau est vide.
614 *
615 * @return string
616 *        Phrase de crédit.
617 */
618function itis_credit($id_taxon, $informations = array()) {
619        // On recherche le TSN du taxon afin de construire l'url vers sa page sur ITIS
620        $taxon = sql_fetsel('tsn, nom_scientifique', 'spip_taxons', 'id_taxon=' . sql_quote($id_taxon));
621
622        // On crée l'url du taxon sur le site ITIS
623        $url_taxon = _TAXONOMIE_ITIS_TAXON_BASE_URL . $taxon['tsn'];
624        $link_taxon = '<a href="' . $url_taxon . '" rel="noreferrer"><em>' . ucfirst($taxon['nom_scientifique']) . '</em></a>';
625        $link_site = '<a href="' . _TAXONOMIE_ITIS_SITE_URL . '" rel="noreferrer">' . _TAXONOMIE_ITIS_SITE_URL . '</a>';
626
627        // On établit la citation
628        $credit = _T('taxonomie:credit_itis', array_merge(array('url_site' => $link_site, 'url_taxon' => $link_taxon), $informations));
629
630        return $credit;
631}
632
633
634/**
635 * Calcule le sha de chaque fichier ITIS fournissant des données, à savoir, ceux des règnes et ceux des noms
636 * communs par langue.
637 *
638 * @api
639 *
640 * @return array
641 *    Tableau à deux index principaux:
642 *        - `taxons`        : tableau associatif indexé par règne
643 *        - `traductions`    : tableau associatif par code de langue SPIP
644 */
645function itis_review_sha() {
646        global $itis_language;
647        $shas = array();
648
649        include_spip('inc/taxonomer');
650        $kingdoms = explode(':', _TAXONOMIE_REGNES);
651
652        foreach ($kingdoms as $_kingdom) {
653                $file = find_in_path('services/itis/' . ucfirst($_kingdom) . '_Genus.txt');
654                if (file_exists($file)
655                        and ($sha_file = sha1_file($file))
656                ) {
657                        $shas['taxons'][$_kingdom] = $sha_file;
658                }
659        }
660
661        foreach (array_keys($itis_language) as $_language) {
662                $file = find_in_path("services/itis/vernaculars_${_language}.csv");
663                if (file_exists($file)
664                        and ($sha_file = sha1_file($file))
665                ) {
666                        $shas['traductions'][$itis_language[$_language]] = $sha_file;
667                }
668        }
669
670        return $shas;
671}
672
673
674// ----------------------------------------------------------------
675// ------------ Fonctions internes utilisées par l'API ------------
676// ----------------------------------------------------------------
677
678/**
679 * Construit l'URL de la requête ITIS correspondant à la demande utilisateur.
680 *
681 * @param string $format
682 *        Format du résultat de la requête. Prend les valeurs `json` ou `xml`. Le `json` est recommandé.
683 * @param string $group
684 *        Groupe d'actions du même type. Prend les valeurs:
685 *        - `search`        : groupe des actions de recherche du TSN à partir du nom commun ou scientifique
686 *        - `vernacular`    : groupe de l'action fournissant les noms communs d'une langue donnée
687 *        - `getfull`        : groupe de l'action fournissant l'ensemble des informations d'un taxon
688 *        - `get`            : groupe des actions fournissant une information précise sur un taxon
689 * @param string $action
690 *        Nom de l'action du service ITIS. Les valeurs dépendent du groupe. Par exemple, pour le groupe
691 *        `search` les actions sont `commonname` et `scientificname`.
692 * @param string $key
693 *        Clé de recherche qui dépend de l'action demandée. Ce peut être le nom scientifique, le TSN, etc.
694 *        Cette clé doit être encodée si besoin par l'appelant.
695 *
696 * @return string
697 *        L'URL de la requête au service
698 */
699function api2url_itis($format, $group, $action, $key) {
700        global $itis_webservice;
701
702        // Construire l'URL de l'api sollicitée
703        $url = _TAXONOMIE_ITIS_ENDPOINT_BASE_URL
704                   . ($format == 'json' ? 'jsonservice/' : 'services/ITISService/')
705                   . $itis_webservice[$group][$action]['function'] . '?'
706                   . $itis_webservice[$group][$action]['argument'] . '=' . $key;
707
708        return $url;
709}
Note: See TracBrowser for help on using the repository browser.