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

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

Renommage des utilitaires pour les grouper par préfixe sémantique.
Phpdoc et packages.

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