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

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

Mise en cohérence du nom des caches Wikipédia.
Ajout d'une fonction et d'un formulaire de vidage des caches.

  • Property svn:eol-style set to native
File size: 8.9 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 */
8if (!defined('_ECRIRE_INC_VERSION')) {
9        return;
10}
11
12if (!defined('_TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL')) {
13        /**
14         * Préfixe des URL du service web de WIKIPEDIA.
15         */
16        define('_TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL', 'https://%langue%.wikipedia.org/w/api.php');
17}
18
19if (!defined('_TAXONOMIE_WIKIPEDIA_PAGE_BASE_URL')) {
20        /**
21         * URL de base pour construire une page de Wikipedia dans une langue donnée
22         */
23        define('_TAXONOMIE_WIKIPEDIA_PAGE_BASE_URL', 'https://%langue%.wikipedia.org/wiki/');
24}
25
26if (!defined('_TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT')) {
27        /**
28         * Période de renouvellement du cache de Wikipedia (30 jours)
29         */
30        define('_TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT', 86400 * 30);
31}
32
33$GLOBALS['wikipedia_language'] = array(
34        /**
35         * Configuration de la correspondance entre langue Wikipedia et code de langue SPIP.
36         * La langue du service est l'index, le code SPIP est la valeur.
37         */
38        'fr' => 'fr',
39        'en' => 'en',
40        'es' => 'es'
41);
42
43
44// ----------------------------------------------------------------------------
45// ------------ API du web service WIKIPEDIA - Actions principales ------------
46// ----------------------------------------------------------------------------
47
48/**
49 * Renvoie, à partir d'une phrase de recherche, soit le texte de la page ou d'une section de la page avec ou pas
50 * la liste des autres pages possibles, soit la liste des langues de la page.
51 * Cette phrase de recherche est toujours le nom scientifique du taxon dans l'utilisation qui en est faite
52 * par le plugin Taxonomie.
53 * Le résultat de la requête est mis en cache pour une durée de plusieurs jours afin d'être servi à nouveau
54 * sans accès à Wikipedia.
55 *
56 * @api
57 * @uses cache_taxonomie_existe()
58 * @uses cache_taxonomie_ecrire()
59 * @uses wikipedia_build_url()
60 * @uses inc_taxonomie_requeter()
61 *
62 * @param array  $search
63 *        Tableau contenant le taxon à cherché sous une forme textuelle et numérique:
64 *        - `name` : chaine de recherche qui est en généralement le nom scientifique du taxon.
65 *        - `tsn`  : identifiant ITIS du taxon, le TSN. Etant donné que ce service s'utilise toujours sur un taxon
66 *                   existant le TSN existe toujours. Il sert à créer le fichier cache.
67 * @param string $spip_language
68 *        Code de langue SPIP dans lequel on souhaite récupérer la page Wikipedia.
69 * @param int    $section
70 *        Section de page dont le texte est à renvoyer. Entier supérieur ou égal à 0 ou `null` pour tout la page.
71 * @param array  $options
72 *        Tableau d'options qui peut contenir les index suivants :
73 *        - `reload`  : force le recalcul du cache.
74 *        Cet argument est optionnel.
75 *
76 * @return array
77 *        Texte trouvé rédigé en mediawiki ou chaine vide sinon. Pour traduire le texte en SPIP
78 *        il est nécessaire d'utiliser le plugin Convertisseur. Néanmoins, le texte même traduit
79 *        doit être remanié manuellement.
80 */
81function wikipedia_get_page($search, $spip_language, $section = null, $options = array()) {
82
83        // Initialisation du tableau de sortie et du tableau d'options
84        $information = array();
85
86        // Si le cache est absent ou invalide on le recrée en utilisant le service web Wikipedia
87        // sinon on le lit et on renvoie le tableau du contenu désérialisé.
88        if (!empty($search['name'] and !empty($search['tsn']))) {
89                // Détermination de la langue Wikipedia
90                $language = wikipedia_find_language($spip_language);
91
92                // Construction des options permettant de nommer le fichier cache.
93                include_spip('inc/taxonomie_cacher');
94                $options_cache = array('language' => $spip_language);
95                if ($section !== null) {
96                        $options_cache['section'] = $section;
97                }
98
99                if (!empty($options['reload'])
100                or !$file_cache = cache_taxonomie_existe('wikipedia', 'get', $search['tsn'], $options_cache)
101                or !filemtime($file_cache)
102                or (time() - filemtime($file_cache) > _TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT)
103                or (_TAXONOMIE_CACHE_FORCER)) {
104                        // Normaliser la recherche: trim et mise en lettres minuscules
105                        $title = strtolower(trim($search['name']));
106
107                        // Calcul de l'url de la requête: on supprime
108                        $url = wikipedia_build_url($title, $language, $section);
109
110                        // Acquisition des données spécifiées par l'url
111                        $requeter = charger_fonction('taxonomie_requeter', 'inc');
112                        $data = $requeter($url);
113
114                        // Récupération de la section demandée.
115                        if (isset($data['query']['pages'])) {
116                                $reponses = $data['query']['pages'];
117                                $page = reset($reponses);
118                                $id = key($reponses);
119                                if (($id > 0) and !isset($page['missing'])) {
120                                        $information['text'] = isset($page['revisions'][0]['*']) ? $page['revisions'][0]['*'] : '';
121                                        $information['links'] = isset($page['links']) ? $page['links'] : array();
122                                        $information['languages'] = isset($page['langlinks']) ? $page['langlinks'] : array();
123                                }
124
125                                // Mise en cache systématique pour gérer le cas où la page cherchée n'existe pas.
126                                cache_taxonomie_ecrire(
127                                        serialize($information),
128                                        'wikipedia',
129                                        '',
130                                        $search['tsn'],
131                                        $options_cache);
132                        }
133                } else {
134                        // Lecture et désérialisation du cache
135                        lire_fichier($file_cache, $contenu);
136                        $information = unserialize($contenu);
137                }
138        }
139
140        return $information;
141}
142
143
144// --------------------------------------------------------------------------
145// ------------ API du web service WIKIPEDIA - Fonctions annexes ------------
146// --------------------------------------------------------------------------
147
148/**
149 * Renvoie la langue telle que le service Wikipedia la désigne à partir du code de langue
150 * de SPIP.
151 *
152 * @api
153 *
154 * @param string $spip_language
155 *        Code de langue de SPIP. Prend les valeurs `fr`, `en`, `es`, etc.
156 *        La variable globale `$wikipedia_language` définit le transcodage langue Wikipedia vers code SPIP.
157 *
158 * @return string
159 *        Langue au sens de Wikipedia - `fr`, `en`, `es` - ou chaine vide sinon.
160 */
161function wikipedia_find_language($spip_language) {
162
163        if (!$language = array_search($spip_language, $GLOBALS['wikipedia_language'])) {
164                $language = 'fr';
165        }
166
167        return $language;
168}
169
170
171/**
172 * Construit la phrase de crédits précisant que les données fournies proviennent d'une page de Wikipedia.
173 *
174 * @api
175 *
176 * @param int   $id_taxon
177 *        Id du taxon nécessaire pour construire l'url de la page Wikipedia concernée.
178 * @param array $informations
179 *        Tableau des informations complémentaires sur la source. Pour Wikipedia ce tableau fourni le ou
180 *        les champs remplis avec Wikipedia.
181 *
182 * @return string
183 *      Phrase de crédit.
184 */
185function wikipedia_credit($id_taxon, $informations) {
186        // On recherche le tsn du taxon afin de construire l'url vers sa page sur ITIS
187        $taxon = sql_fetsel('tsn, nom_scientifique', 'spip_taxons', 'id_taxon=' . sql_quote($id_taxon));
188
189        // On crée l'url du taxon sur le site de Wikipedia
190        $url = str_replace('%langue%', 'fr', _TAXONOMIE_WIKIPEDIA_PAGE_BASE_URL)
191                   . rawurlencode($taxon['nom_scientifique']);
192        $link = '<a class="nom_scientifique_inline" href="' . $url . '" rel="noreferrer">' . ucfirst($taxon['nom_scientifique']) . '</a>';
193
194        // La liste des champs concernés (a priori le descriptif)
195        include_spip('inc/taxonomie');
196        $champs = implode(', ', array_map('taxon_traduire_champ', $informations['champs']));
197
198        // On établit la citation
199        $credit = _T('taxonomie:credit_wikipedia', array('champs' => strtolower($champs), 'url_taxon' => $link));
200
201        return $credit;
202}
203
204
205// ----------------------------------------------------------------
206// ------------ Fonctions internes utilisées par l'API ------------
207// ----------------------------------------------------------------
208
209/**
210 * Construit l'URL de la requête Wikipedia correspondant à la demande utilisateur.
211 *
212 * @internal
213 *
214 * @param string $search
215 *        Clé de recherche qui est essentiellement le nom scientifique dans l'utilisation normale.
216 *        Cette clé doit être encodée si besoin par l'appelant.
217 * @param string $language
218 *        Code de langue au sens de Wikipedia qui préfixe l'url du endpoint. Vaut `fr`, `en`, `es` pour l'instant.
219 * @param array  $section
220 *        Section de page dont le texte est à renvoyer. Entier supérieur ou égal à 0 ou `null`
221 *        pour tout la page.
222 *        Cet argument est optionnel.
223 *
224 * @return string
225 *        L'URL de la requête au service
226 */
227function wikipedia_build_url($search, $language, $section = null) {
228
229        // Construire la partie standard de l'URL de l'api sollicitée
230        $url = str_replace('%langue%', $language, _TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL)
231                . '?'
232                . 'action=query'
233                . '&format=json'
234                . '&continue=&redirects=1'
235                . '&prop=revisions|links|langlinks&rvprop=content&pllimit=500&lllimit=500&llprop=url'
236                . '&titles=' . rawurlencode(ucfirst($search));
237
238        // Choix d'une section précise si demandé.
239        $url .= (!empty($section) ? '&rvsection=' . $section : '');
240
241        return $url;
242}
Note: See TracBrowser for help on using the repository browser.