Changeset 92927 in spip-zone


Ignore:
Timestamp:
Nov 14, 2015, 4:57:26 PM (4 years ago)
Author:
eric@…
Message:

Phpdoc du service Wikipedia

Location:
_plugins_/taxonomie/trunk/services
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • _plugins_/taxonomie/trunk/services/itis/itis_api.php

    r92925 r92927  
    3939$GLOBALS['itis_language'] = array(
    4040        /**
    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.
     41         * @var array   $itis_language Variable globale de configuration de la correspondance entre langue Wikipedia
     42         * et code de langue SPIP. La langue du service est l'index, le code SPIP est la valeur.
    4343         */
    4444        'french' => 'fr',
     
    167167 *
    168168 * @api
    169  * @uses api2url_itis
    170  * @uses url2json_data
     169 * @uses api2url_itis()
     170 * @uses url2json_data()
     171 * @global $itis_webservice Configuration des actions du service web ITIS
    171172 *
    172173 * @param string        $action
     
    216217 *
    217218 * @api
    218  * @uses api2url_itis
    219  * @uses url2json_data
    220  * @uses extraire_element
     219 * @uses api2url_itis()
     220 * @uses url2json_data()
     221 * @uses extraire_element()
    221222 *
    222223 * @param int   $tsn
     
    274275 *
    275276 * @api
    276  * @uses api2url_itis
    277  * @uses url2json_data
    278  * @uses extraire_element
     277 * @uses api2url_itis()
     278 * @uses url2json_data()
     279 * @uses extraire_element()
    279280 *
    280281 * @param string        $action
     
    351352 *
    352353 * @api
    353  * @uses api2url_itis
    354  * @uses url2json_data
     354 * @uses api2url_itis()
     355 * @uses url2json_data()
    355356 *
    356357 * @param $language
     
    606607 *
    607608 * @api
    608  * @uses lister_regnes
     609 * @uses lister_regnes()
    609610 *
    610611 * @return array
     
    663664 *
    664665 * @return string
     666 *              L'URL de la requête au service
    665667 */
    666668function api2url_itis($format, $group, $action, $key) {
  • _plugins_/taxonomie/trunk/services/wikipedia/wikipedia_api.php

    r92888 r92927  
    11<?php
    22/**
    3  * Ce fichier contient l'ensemble des constantes et functions implémentant le service web de wikipedia.
     3 * Ce fichier contient l'ensemble des constantes et fonctions implémentant le service web de Wikipedia.
    44 *
    55 * @package SPIP\TAXONOMIE\WIKIPEDIA
     
    1111        /**
    1212         * Préfixe des URL du service web de WIKIPEDIA.
    13          * Le service fournit des données au format JSON
    1413         */
    1514        define('_TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL', 'http://%langue%.wikipedia.org/w/api.php');
     
    2322if (!defined('_TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT'))
    2423        /**
    25          * Période de renouvellement du cache de Wikipedia : 30 jours
     24         * Période de renouvellement du cache de Wikipedia (30 jours)
    2625         */
    2726        define('_TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT', 86400*30);
    2827
    29 /**
    30  * Configuration de la correspondance entre langue Wikipedia et code de langue SPIP.
    31  * La langue du service est l'index, le code SPIP est la valeur.
    32  */
    3328$GLOBALS['wikipedia_language'] = array(
     29        /**
     30         * Configuration de la correspondance entre langue Wikipedia et code de langue SPIP.
     31         * La langue du service est l'index, le code SPIP est la valeur.
     32         */
    3433        'fr' => 'fr',
    3534        'en' => 'en',
     
    4645 * Cette phrase de recherche est toujours le nom scientifique du taxon dans l'utilisation qui en est faite
    4746 * par le plugin Taxonomie.
     47 * Le résultat de la requête est mis en cache pour une durée de plusieurs jours afin d'être servi à nouveau
     48 * sans accès à Wikipedia.
    4849 *
    4950 * @api
    50  *
    51  * @param int       $tsn
    52  *      Identifiant ITIS (TSN) du taxon. Etant donné que ce service s'utilise toujours sur un taxon
    53  *      existant le TSN existe toujours. Il sert à créer le fichier cache.
    54  * @param string    $recherche
    55  *      Chaine de recherche qui est en généralement le nom scientifique du taxon.
    56  * @param string    $langue
    57  *      Langue au sens de Wikipedia qui préfixe l'url du endpoint. Vaut 'fr', 'en', 'es'...
    58  * @param int|null  $section
    59  *      Section de page dont le texte est à renvoyer. Entier supérieur ou égal à 0. Cet argument est
    60  *      optionnel.
    61  *
    62  * @return string
    63  *      Texte trouvé rédigé en mediawiki ou chaine vide sinon. Pour traduire le texte en SPIP
    64  *      il est nécessaire d'utiliser le plugin Convertisseur. Néanmoins, le texte même traduit
    65  *      doit être remanié manuellement.
    66  */
    67 function wikipedia_get($tsn, $recherche, $langue, $section=null) {
     51 * @uses cache_taxonomie_existe()
     52 * @uses ecrire_cache_taxonomie()
     53 * @uses api2url_wikipedia()
     54 * @uses url2json_data()
     55 *
     56 * @param int           $tsn
     57 *              Identifiant ITIS du taxon, le TSN. Etant donné que ce service s'utilise toujours sur un taxon
     58 *              existant le TSN existe toujours. Il sert à créer le fichier cache.
     59 * @param string        $search
     60 *              Chaine de recherche qui est en généralement le nom scientifique du taxon.
     61 * @param string        $language
     62 *              Langue au sens de Wikipedia qui préfixe l'url du endpoint. Vaut `fr`, `en`, `es`...
     63 * @param int|null      $section
     64 *              Section de page dont le texte est à renvoyer. Entier supérieur ou égal à 0 ou `null` pour tout la page.
     65 *              Cet argument est optionnel.
     66 *
     67 * @return string
     68 *              Texte trouvé rédigé en mediawiki ou chaine vide sinon. Pour traduire le texte en SPIP
     69 *              il est nécessaire d'utiliser le plugin Convertisseur. Néanmoins, le texte même traduit
     70 *              doit être remanié manuellement.
     71 */
     72function wikipedia_get($tsn, $search, $language, $section=null) {
    6873        $information = array();
    6974
     
    7176        // sinon on le litet on revoie le tableau du contenu désérialisé.
    7277        include_spip('inc/taxonomer');
    73         if (!$file_cache = cache_taxonomie_existe('wikipedia', $tsn, $langue)
     78        if (!$file_cache = cache_taxonomie_existe('wikipedia', $tsn, $language)
    7479        OR !filemtime($file_cache)
    7580        OR (time()-filemtime($file_cache)>_TAXONOMIE_WIKIPEDIA_CACHE_TIMEOUT)) {
    7681                // Normaliser la recherche: trim et mise en lettres minuscules
    77                 $recherche = strtolower(trim($recherche));
     82                $search = strtolower(trim($search));
    7883
    7984                // Construire l'URL de la function de recherche par nom vernaculaire.
    8085                // L'encodage de la recherche est effectuée dans la fonction.
    81                 $url = api2url_wikipedia('json', 'query', $langue, $recherche, $section);
     86                $url = api2url_wikipedia('json', 'query', $language, $search, $section);
    8287
    8388                // Acquisition des données spécifiées par l'url
     
    99104
    100105                // Mise en cache
    101                 ecrire_cache_taxonomie(serialize($information), 'wikipedia', $tsn, $langue);
     106                ecrire_cache_taxonomie(serialize($information), 'wikipedia', $tsn, $language);
    102107        } else {
    103108                // Lecture et désérialisation du cache
     
    120125 * @api
    121126 *
    122  * @param string    $language_code
    123  *      Code de langue de SPIP. La variable globale $wikipedia_language définit le transcodage langue Wikipedia
    124  *     vers code SPIP.
    125  *
    126  * @return string
    127  *      Langue au sens de Wikipedia ou chaine vide sinon.
     127 * @param string        $language_code
     128 *              Code de langue de SPIP. Prend les valeurs `fr`, `en`, `es`, etc.
     129 *              La variable globale `$wikipedia_language` définit le transcodage langue Wikipedia vers code SPIP.
     130 *
     131 * @return string
     132 *              Langue au sens de Wikipedia - `fr`, `en`, `es` - ou chaine vide sinon.
    128133 */
    129134function wikipedia_spipcode2language($language_code) {
     
    143148 * @api
    144149 *
    145  * @param int   $id_taxon
    146  *      Id du taxon nécessaire pour construire l'url de la page Wikipedia concernée.
    147  * @param array $informations
    148  *      Tableau des informations complémentaires sur la source. Pour Wikipedia ce tableau fourni le champ
    149  *      rempli (descriptif).
     150 * @param int   $id_taxon
     151 *              Id du taxon nécessaire pour construire l'url de la page Wikipedia concernée.
     152 * @param array $informations
     153 *              Tableau des informations complémentaires sur la source. Pour Wikipedia ce tableau fourni le ou
     154 *              les champs remplis avec Wikipedia.
    150155 *
    151156 * @return string
     
    177182
    178183/**
    179  * @param $format
    180  * @param $area
    181  * @param $api
    182  * @param $key
    183  *
    184  * @return string
    185  */
    186 function api2url_wikipedia($format, $action, $langue, $recherche, $section) {
     184 * Construit l'URL de la requête Wikipedia correspondant à la demande utilisateur.
     185 *
     186 * @param string        $format
     187 *              Format du résultat de la requête. Prend les valeurs `json` ou `xml`. Le `json` est recommandé.
     188 * @param string        $action
     189 *              Nom de l'action du service Wikipedia. La seule action `query` est utilisée dans cette API.
     190 * @param string        $language
     191 *              Langue au sens de Wikipedia en minuscules. Prend les valeurs `fr`, `en`, `es`, etc.
     192 * @param string        $search
     193 *              Clé de recherche qui est essentiellement le nom scientifique dans l'utilisation normale.
     194 *              Cette clé doit être encodée si besoin par l'appelant.
     195 * @param int|null      $section
     196 *              Section de la page à renvoyer. Valeur entière de 0 à n ou null si on veut toute la page.
     197 *
     198 * @return string
     199 *              L'URL de la requête au service
     200 */
     201function api2url_wikipedia($format, $action, $language, $search, $section) {
    187202
    188203        // Construire l'URL de l'api sollicitée
    189         $url = str_replace('%langue%', $langue, _TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL) . '?'
     204        $url = str_replace('%langue%', $language, _TAXONOMIE_WIKIPEDIA_ENDPOINT_BASE_URL) . '?'
    190205                . 'action=' . $action
    191206                . '&meta=siteinfo|wikibase'
     
    194209                . '&continue=&redirects=1'
    195210                . '&format=' . $format
    196                 . '&titles=' . rawurlencode(ucfirst($recherche));
     211                . '&titles=' . rawurlencode(ucfirst($search));
    197212
    198213        return $url;
Note: See TracChangeset for help on using the changeset viewer.