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

Last change on this file since 113783 was 113783, checked in by root, 3 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: 8.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 */
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/cache');
94                $cache = array(
95                        'service'  => 'wikipedia',
96                        'action'   => 'get',
97                        'tsn'      => $search['tsn'],
98                        'language' => $spip_language
99                );
100                if ($section !== null) {
101                        $cache['section'] = $section;
102                }
103
104                if (!empty($options['reload'])
105                or (!$file_cache = cache_existe('taxonomie', $cache))
106                or !filemtime($file_cache)
107                or (time() - filemtime($file_cache) > _TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT)
108                or (defined('_TAXONOMIE_CACHE_FORCER') ? _TAXONOMIE_CACHE_FORCER : false)) {
109                        // Normaliser la recherche: trim et mise en lettres minuscules
110                        $title = strtolower(trim($search['name']));
111
112                        // Calcul de l'url de la requête: on supprime
113                        $url = wikipedia_build_url($title, $language, $section);
114
115                        // Acquisition des données spécifiées par l'url
116                        $requeter = charger_fonction('taxonomie_requeter', 'inc');
117                        $data = $requeter($url);
118
119                        // Récupération de la section demandée.
120                        if (isset($data['query']['pages'])) {
121                                $reponses = $data['query']['pages'];
122                                $page = reset($reponses);
123                                $id = key($reponses);
124                                if (($id > 0) and !isset($page['missing'])) {
125                                        $information['text'] = isset($page['revisions'][0]['*']) ? $page['revisions'][0]['*'] : '';
126                                        $information['links'] = isset($page['links']) ? $page['links'] : array();
127                                        $information['languages'] = isset($page['langlinks']) ? $page['langlinks'] : array();
128                                }
129
130                                // Mise en cache systématique pour gérer le cas où la page cherchée n'existe pas.
131                                cache_ecrire('taxonomie', $cache, $information);
132                        }
133                } else {
134                        // Lecture et désérialisation du cache
135                        $information = cache_lire('taxonomie', $file_cache);
136                }
137        }
138
139        return $information;
140}
141
142
143// --------------------------------------------------------------------------
144// ------------ API du web service WIKIPEDIA - Fonctions annexes ------------
145// --------------------------------------------------------------------------
146
147/**
148 * Renvoie la langue telle que le service Wikipedia la désigne à partir du code de langue
149 * de SPIP.
150 *
151 * @api
152 *
153 * @param string $spip_language
154 *        Code de langue de SPIP. Prend les valeurs `fr`, `en`, `es`, etc.
155 *        La variable globale `$wikipedia_language` définit le transcodage langue Wikipedia vers code SPIP.
156 *
157 * @return string
158 *        Langue au sens de Wikipedia - `fr`, `en`, `es` - ou chaine vide sinon.
159 */
160function wikipedia_find_language($spip_language) {
161
162        if (!$language = array_search($spip_language, $GLOBALS['wikipedia_language'])) {
163                $language = 'fr';
164        }
165
166        return $language;
167}
168
169
170/**
171 * Construit la phrase de crédits précisant que les données fournies proviennent d'une page de Wikipedia.
172 *
173 * @api
174 *
175 * @param int   $id_taxon
176 *        Id du taxon nécessaire pour construire l'url de la page Wikipedia concernée.
177 * @param array $informations
178 *        Tableau des informations complémentaires sur la source. Pour Wikipedia ce tableau fourni le ou
179 *        les champs remplis avec Wikipedia.
180 *
181 * @return string
182 *      Phrase de crédit.
183 */
184function wikipedia_credit($id_taxon, $informations) {
185        // On recherche le tsn du taxon afin de construire l'url vers sa page sur ITIS
186        $taxon = sql_fetsel('tsn, nom_scientifique', 'spip_taxons', 'id_taxon=' . sql_quote($id_taxon));
187
188        // On crée l'url du taxon sur le site de Wikipedia
189        $url = str_replace('%langue%', 'fr', _TAXONOMIE_WIKIPEDIA_PAGE_BASE_URL)
190                   . rawurlencode($taxon['nom_scientifique']);
191        $link = '<a class="nom_scientifique_inline" href="' . $url . '" rel="noreferrer">' . ucfirst($taxon['nom_scientifique']) . '</a>';
192
193        // La liste des champs concernés (a priori le descriptif)
194        include_spip('inc/taxonomie');
195        $champs = implode(', ', array_map('taxon_traduire_champ', $informations['champs']));
196
197        // On établit la citation
198        $credit = _T('taxonomie:credit_wikipedia', array('champs' => strtolower($champs), 'url_taxon' => $link));
199
200        return $credit;
201}
202
203
204// ----------------------------------------------------------------
205// ------------ Fonctions internes utilisées par l'API ------------
206// ----------------------------------------------------------------
207
208/**
209 * Construit l'URL de la requête Wikipedia correspondant à la demande utilisateur.
210 *
211 * @internal
212 *
213 * @param string $search
214 *        Clé de recherche qui est essentiellement le nom scientifique dans l'utilisation normale.
215 *        Cette clé doit être encodée si besoin par l'appelant.
216 * @param string $language
217 *        Code de langue au sens de Wikipedia qui préfixe l'url du endpoint. Vaut `fr`, `en`, `es` pour l'instant.
218 * @param array  $section
219 *        Section de page dont le texte est à renvoyer. Entier supérieur ou égal à 0 ou `null`
220 *        pour tout la page.
221 *        Cet argument est optionnel.
222 *
223 * @return string
224 *        L'URL de la requête au service
225 */
226function wikipedia_build_url($search, $language, $section = null) {
227
228        // Construire la partie standard de l'URL de l'api sollicitée
229        $url = str_replace('%langue%', $language, _TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL)
230                . '?'
231                . 'action=query'
232                . '&format=json'
233                . '&continue=&redirects=1'
234                . '&prop=revisions|links|langlinks&rvprop=content&pllimit=500&lllimit=500&llprop=url'
235                . '&titles=' . rawurlencode(ucfirst($search));
236
237        // Choix d'une section précise si demandé.
238        $url .= (!empty($section) ? '&rvsection=' . $section : '');
239
240        return $url;
241}
Note: See TracBrowser for help on using the repository browser.