source: spip-zone/_plugins_/taxonomie/trunk/services/wikipedia/wikipedia_api.php @ 93059

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

Finalisation d'un premier jet complet du phpdoc.

  • Property svn:eol-style set to native
File size: 7.8 KB
Line 
1<?php
2/**
3 * Ce fichier contient l'ensemble des constantes et fonctions implémentant le service web de Wikipedia.
4 *
5 * @package SPIP\TAXONOMIE\SERVICES\WIKIPEDIA
6 * @todo phpdoc : exemples
7 */
8
9if (!defined("_ECRIRE_INC_VERSION")) return;
10
11if (!defined('_TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL'))
12        /**
13         * Préfixe des URL du service web de WIKIPEDIA.
14         */
15        define('_TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL', 'http://%langue%.wikipedia.org/w/api.php');
16
17if (!defined('_TAXONOMIE_WIKIPEDIA_PAGE_BASE_URL'))
18        /**
19         * URL de base pour construire une page de Wikipedia dans une langue donnée
20         */
21        define('_TAXONOMIE_WIKIPEDIA_PAGE_BASE_URL', 'https://%langue%.wikipedia.org/wiki/');
22
23if (!defined('_TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT'))
24        /**
25         * Période de renouvellement du cache de Wikipedia (30 jours)
26         */
27        define('_TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT', 86400*30);
28
29$GLOBALS['wikipedia_language'] = array(
30        /**
31         * Configuration de la correspondance entre langue Wikipedia et code de langue SPIP.
32         * La langue du service est l'index, le code SPIP est la valeur.
33         */
34        'fr' => 'fr',
35        'en' => 'en',
36        'es' => 'es'
37);
38
39
40// ----------------------------------------------------------------------------
41// ------------ API du web service WIKIPEDIA - Actions principales ------------
42// ----------------------------------------------------------------------------
43
44/**
45 * Renvoie le texte de la page ou d'une section de la page à partir d'une phrase de recherche.
46 * Cette phrase de recherche est toujours le nom scientifique du taxon dans l'utilisation qui en est faite
47 * par le plugin Taxonomie.
48 * Le résultat de la requête est mis en cache pour une durée de plusieurs jours afin d'être servi à nouveau
49 * sans accès à Wikipedia.
50 *
51 * @api
52 * @uses cache_taxonomie_existe()
53 * @uses cache_taxonomie_ecrire()
54 * @uses api2url_wikipedia()
55 * @uses service_requeter_json()
56 *
57 * @param int           $tsn
58 *              Identifiant ITIS du taxon, le TSN. Etant donné que ce service s'utilise toujours sur un taxon
59 *              existant le TSN existe toujours. Il sert à créer le fichier cache.
60 * @param string        $search
61 *              Chaine de recherche qui est en généralement le nom scientifique du taxon.
62 * @param string        $language
63 *              Langue au sens de Wikipedia qui préfixe l'url du endpoint. Vaut `fr`, `en`, `es`...
64 * @param int|null      $section
65 *              Section de page dont le texte est à renvoyer. Entier supérieur ou égal à 0 ou `null` pour tout la page.
66 *              Cet argument est optionnel.
67 *
68 * @return string
69 *              Texte trouvé rédigé en mediawiki ou chaine vide sinon. Pour traduire le texte en SPIP
70 *              il est nécessaire d'utiliser le plugin Convertisseur. Néanmoins, le texte même traduit
71 *              doit être remanié manuellement.
72 */
73function wikipedia_get($tsn, $search, $language, $section=null) {
74        $information = array();
75
76        // Si le cache est absent ou invalide on le recrée en utilisant le service web Wikipedia
77        // sinon on le litet on revoie le tableau du contenu désérialisé.
78        include_spip('inc/taxonomer');
79        if (!$file_cache = cache_taxonomie_existe('wikipedia', $tsn, $language)
80        OR !filemtime($file_cache)
81        OR (time()-filemtime($file_cache)>_TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT)) {
82                // Normaliser la recherche: trim et mise en lettres minuscules
83                $search = strtolower(trim($search));
84
85                // Construire l'URL de la function de recherche par nom vernaculaire.
86                // L'encodage de la recherche est effectuée dans la fonction.
87                $url = api2url_wikipedia('json', 'query', $language, $search, $section);
88
89                // Acquisition des données spécifiées par l'url
90                include_spip('inc/taxonomer');
91                $data = service_requeter_json($url);
92
93                // Récupération de la section demandée.
94                if (isset($data['batchcomplete'])
95                AND isset($data['query']['pages'])) {
96                        $reponses = $data['query']['pages'];
97                        $page = reset($reponses);
98                        $id = key($reponses);
99                        if (($id > 0)
100                        AND !isset($page['missing'])
101                        AND isset($page['revisions'][0]['*'])) {
102                                $information['texte'] = $page['revisions'][0]['*'];
103                        }
104                }
105
106                // Mise en cache
107                cache_taxonomie_ecrire(serialize($information), 'wikipedia', $tsn, $language);
108        } else {
109                // Lecture et désérialisation du cache
110                lire_fichier($file_cache, $information);
111                $information = unserialize($information);
112        }
113
114        return $information;
115}
116
117
118// --------------------------------------------------------------------------
119// ------------ API du web service WIKIPEDIA - Fonctions annexes ------------
120// --------------------------------------------------------------------------
121
122/**
123 * Renvoie la langue telle que le service Wikipedia la désigne à partir du code de langue
124 * de SPIP.
125 *
126 * @api
127 *
128 * @param string        $language_code
129 *              Code de langue de SPIP. Prend les valeurs `fr`, `en`, `es`, etc.
130 *              La variable globale `$wikipedia_language` définit le transcodage langue Wikipedia vers code SPIP.
131 *
132 * @return string
133 *              Langue au sens de Wikipedia - `fr`, `en`, `es` - ou chaine vide sinon.
134 */
135function wikipedia_spipcode2language($language_code) {
136        global $wikipedia_language;
137
138        if (!$language = array_search($language_code,  $wikipedia_language)) {
139                $language = '';
140        }
141
142        return $language;
143}
144
145
146/**
147 * Construit la phrase de crédits précisant que les données fournies proviennent d'une page de Wikipedia.
148 *
149 * @api
150 *
151 * @param int   $id_taxon
152 *              Id du taxon nécessaire pour construire l'url de la page Wikipedia concernée.
153 * @param array $informations
154 *              Tableau des informations complémentaires sur la source. Pour Wikipedia ce tableau fourni le ou
155 *              les champs remplis avec Wikipedia.
156 *
157 * @return string
158 *      Phrase de crédit.
159 */
160function wikipedia_credit($id_taxon, $informations) {
161        // On recherche le tsn du taxon afin de construire l'url vers sa page sur ITIS
162        $taxon = sql_fetsel('tsn, nom_scientifique', 'spip_taxons', 'id_taxon='. sql_quote($id_taxon));
163
164        // On crée l'url du taxon sur le site de Wikipedia
165        $url = str_replace('%langue%', 'fr', _TAXONOMIE_WIKIPEDIA_PAGE_BASE_URL)
166                . rawurlencode($taxon['nom_scientifique']);
167        $link = '<a href="' . $url . '"><em>' . ucfirst($taxon['nom_scientifique']) . '</em></a>';
168
169        // La liste des champs concernés (a priori le descriptif)
170        include_spip('inc/taxonomer');
171        $champs = implode(', ', array_map('taxon_traduire_champ', $informations['champs']));
172
173        // On établit la citation
174        $credit = _T('taxonomie:credit_wikipedia', array('champs' => strtolower($champs),'url_taxon' => $link));
175
176        return $credit;
177}
178
179
180// ----------------------------------------------------------------
181// ------------ Fonctions internes utilisées par l'API ------------
182// ----------------------------------------------------------------
183
184/**
185 * Construit l'URL de la requête Wikipedia correspondant à la demande utilisateur.
186 *
187 * @param string        $format
188 *              Format du résultat de la requête. Prend les valeurs `json` ou `xml`. Le `json` est recommandé.
189 * @param string        $action
190 *              Nom de l'action du service Wikipedia. La seule action `query` est utilisée dans cette API.
191 * @param string        $language
192 *              Langue au sens de Wikipedia en minuscules. Prend les valeurs `fr`, `en`, `es`, etc.
193 * @param string        $search
194 *              Clé de recherche qui est essentiellement le nom scientifique dans l'utilisation normale.
195 *              Cette clé doit être encodée si besoin par l'appelant.
196 * @param int|null      $section
197 *              Section de la page à renvoyer. Valeur entière de 0 à n ou null si on veut toute la page.
198 *
199 * @return string
200 *              L'URL de la requête au service
201 */
202function api2url_wikipedia($format, $action, $language, $search, $section) {
203
204        // Construire l'URL de l'api sollicitée
205        $url = str_replace('%langue%', $language, _TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL) . '?'
206                . 'action=' . $action
207                . '&meta=siteinfo|wikibase'
208                . '&prop=revisions&rvprop=content'
209                . (!is_null($section) ? '&rvsection=' . $section : '')
210                . '&continue=&redirects=1'
211                . '&format=' . $format
212                . '&titles=' . rawurlencode(ucfirst($search));
213
214        return $url;
215}
216
217?>
Note: See TracBrowser for help on using the repository browser.