Context Navigation

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

Visit:

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

Note: See TracBrowser for help on using the repository browser.

Download in other formats: