Subversion Repositories eFlore/Projets.eflore-projets

Rev

Rev 934 | Rev 984 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed

<?php
/*
 * @copyright 2013 Tela Botanica (accueil@tela-botanica.org)
 * @author Raphaël Droz <raphael@tela-botanica.org>
 * @license GPL v3 <http://www.gnu.org/licenses/gpl.txt>
 * @license CECILL v2 <http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt>
 *
 * pattern: /service:eflore:0.1/coste/textes/bdtfx.nn:182,631
 * params: txt.format=(htm|txt) ,  retour.champs=(titre,texte,...) , retour.format=(min|max), ...
 *
 * Ce webservice est censé pouvoir:
 * 1) retourner des informations (choisies) à propos d'un ou plusieurs taxon(s) donné(s)
 *        (à partir de son numéro nomenclatural
 * 2) retourner des informations (choisies) à propos de taxons recherchés
 *        (à partir de divers critères)
 *
 * TODO: masque.titre => masque.tag
 * TODO: clarifier l'attribut "tag" retourné (tag de la description ou des clefs de détermination)
 *
 */

// affecte le nombre d'ids autorisés dans le dernier segment d'URL
// *et* la valeur maximale autorisée pour navigation.limite.
define('_COSTE_TEXTE_MAX_RESULT_LIMIT', 500);

// simplifie et accélère la sanitization de l'input:
// SELECT MAX(num_nom) FROM coste_v2_00;
define('_COSTE_TEXTE_MAX_COSTE_NN', 7015 + 1000);
// SELECT MAX(page) FROM coste_v2_00;
define('_COSTE_TEXTE_MAX_COSTE_PAGE', 4126);
// SELECT MAX(tome) FROM coste_v2_00;
define('_COSTE_TEXTE_MAX_COSTE_TOME', 3);
// SELECT MAX(num_taxonomique) FROM coste_v2_00;
define('_COSTE_TEXTE_MAX_BDTFX_NT', 37809);
// SELECT MAX(num_nom) FROM bdtfx_v2_00;
define('_COSTE_TEXTE_MAX_BDTFX_NN', 120816 + 100000);

/* restore_error_handler();
   error_reporting(E_ALL); */
class Textes {
        // paramètres autorisés
        static $allow_params = array(
                'txt.format', 'retour.format', 'retour.champs', 'retour.indexBy',
                'recherche',
                'masque.ns', 'masque.txt', 'masque.page', 'masque.tome', 'masque.famille', 'masque.nt',
                'masque.titre', // masque sur titre de la page wiki correspondante (page "clef" OR page "description")
                'navigation.depart', 'navigation.limite');
        // et valeurs par défaut
        static $default_params = array('txt.format' => 'txt', 'retour.format' => 'max', 'retour.indexBy' => 'coste',
                                                                   'recherche' => 'stricte',
                                                                   'retour.champs' => 'titre,texte,determination,tag',
                                                                   'navigation.depart' => 0, 'navigation.limite' => 50);

        // les champs de base de coste_v2_00
        // mysql -N tb_eflore<<<"SHOW FIELDS FROM coste_v2_00"|egrep -v 'page_'|awk '{print $1}'|xargs -i -n1 printf "'%s' => 'c.%s',\n" {} {}
        static $allow_champs = array(
                'coste:nn' => 'c.num_nom',
                'bdtfx:nn' => 'IF(c.flore_bdtfx_nn = "",NULL,c.flore_bdtfx_nn)',
                'bdtfx:nt' => 'c.flore_bdtfx_nt',
                'num_nom' => 'c.num_nom',
                'num_nom_retenu' => 'c.num_nom_retenu',
                'num_tax_sup' => 'c.num_tax_sup',
                'rang' => 'c.rang',
                'nom_sci' => 'c.nom_sci',
                'nom_supra_generique' => 'c.nom_supra_generique',
                'genre' => 'c.genre',
                'epithete_infra_generique' => 'c.epithete_infra_generique',
                'epithete_sp' => 'c.epithete_sp',
                'type_epithete' => 'c.type_epithete',
                'epithete_infra_sp' => 'c.epithete_infra_sp',
                'cultivar_groupe' => 'c.cultivar_groupe',
                'cultivar' => 'c.cultivar',
                'nom_commercial' => 'c.nom_commercial',
                'auteur' => 'c.auteur',
                'annee' => 'c.annee',
                'biblio_origine' => 'c.biblio_origine',
                'notes' => 'c.notes',
                'nom_addendum' => 'c.nom_addendum',
                'nom_francais' => 'c.nom_francais',
                'nom_coste' => 'c.nom_coste',
                'auteur_coste' => 'c.auteur_coste',
                'biblio_coste' => 'c.biblio_coste',
                'num_nom_coste' => 'c.num_nom_coste',
                'num_nom_retenu_coste' => 'c.num_nom_retenu_coste',
                'num_tax_sup_coste' => 'c.num_tax_sup_coste',
                'synonymie_coste' => 'c.synonymie_coste',
                'tome' => 'c.tome',
                'page' => 'c.page',
                'nbre_taxons' => 'c.nbre_taxons',
                'flore_bdtfx_nn' => 'c.flore_bdtfx_nn',
                'flore_bdtfx_nt' => 'c.flore_bdtfx_nt',
                'image' => 'c.image',
                'image_auteur' => 'c.image_auteur',
                'nom_sci_html' => 'c.nom_sci_html',

                // handly duplicate (redirigé vers nom_sci ou nom_sci_html selon que txt.format vaut "txt" ou "htm"
                'titre' => 'c.nom_sci',

                // champs spécifiques (et étrangères)
                'texte' => 'dsc.body',
                'determination' => 'cle.body',
                'tag' => 'dsc.tag',
                'famille' => 'b.famille', // cf sqlAddJoins()
                '*' => 'XXX' // spécial
        );

        // les champs suivants disparaissent de la liste utilisée pour former la requête SQL
        // (ils sont exclue lorsque '*' est utilisée, ce sont généralement des synonymes)
        static $special_champs = array('nom_sci_html', 'nom_sci', '*', 'flore_bdtfx_nn', 'flore_bdtfx_nt', 'num_nom');

        // ces champs sont toujours dans les résultats (cf sqlSelectFields()
        static $champs_obligatoires = array('coste:nn', 'bdtfx:nn');


        // le pattern utilisé pour la recherche dite "floue"
        static $soundex_scheme = '(%1$s LIKE %2$s OR SOUNDEX(%1$s) = SOUNDEX(%2$s) OR SOUNDEX(REVERSE(%1$s)) = SOUNDEX(REVERSE(%2$s)))';

        // contrainte du point d'entrée d'API webservice Tela lors d'un GET
        public function consulter($ressources, $parametres, $db = NULL) {
                if (!$db) {
                        // http_response_code(500);
                        throw new Exception('no DB', 500);
                }

                // parser la requête et filtrer les paramètres valides
                // en cas d'accès HTTP
                if (array_key_exists('QUERY_STRING', $_SERVER)) {
                        self::requestParse($uri, $params);
                } else {// en cas d'accès phpunit
                        $uri = $ressources;
                }

                // renvoie du plain/text d'aide (cf fin de programme)
                if (count($uri) == 1 && $uri[0] == 'aide') {
                        die(self::aide());
                }

                if (is_null($parametres)) {
                        $parametres = Array();
                }
                $params = self::requestFilterParams($parametres);
                // les contraintes liées aux ids (passés comme composants d'URL)
                // sont ajoutées aux params [sans être accepté comme paramètre d'URL]
                $params['_ids'] = self::requestFilterIds($uri);

                // XXX: temporaires, passage de $db aux fonctions
                // de toolkits
                $req = self::getCosteInfo($params, $db);

                $res = $db->recupererTous($req);
                $err = mysql_error();
                if (!$res && $err) {
                        // http_response_code(400);
                        // if(defined('DEBUG') && DEBUG) header("X-Debug: $req");
                        throw new Exception('not found', 400);
                }

                // rapide formatage des résultats:
                $matches = 0;

                if ($res) {
                        // nombre de matches (sans LIMIT) utilisé pour l'en-tête
                        $matches = $db->recuperer('SELECT FOUND_ROWS() AS total');
                        $matches = intval($matches['total']);
                }

                // reformate les résultats pour les indexer par coste:nn par défaut
                // cependant le paramètre retour.indexBy permet de choisir une indexation par num_nom de bdtfx
                $clef_index = $params['retour.indexBy'] == 'coste' ? 'coste:nn' : 'bdtfx:nn';
                $res2 = array();
                foreach ($res as $v) {
                        if (!$v[$clef_index]) {
                                throw new Exception('format error: index NULL, use retour.indexBy=coste', 409);
                        }
                        $res2[$v[$clef_index]] = $v;
                }

                // l'appelant s'occupera du json_encode()
                // même si ça démange d'exit'er ici
                if(strpos($_SERVER['SCRIPT_NAME'], 'phpunit') === FALSE) header("Content-Type: application/json; charset=utf-8");
                return array('entete' => array(
                        'depart' => $params['navigation.depart'],
                        'limite' => $params['navigation.limite'],
                        'total' => count($res2),
                        'match' => $matches),
                                         'resultats' => $res2);
        }


        // la fonction centrale: récupère les infos à partir de paramètres
        // et une optionnelle contrainte sur coste:nn ou bdtfx:nn
        static function getCosteInfo(array $params, $db) {
                // contraintes (WHERE):
                $constraints = self::sqlAddConstraint($params, $db);
                // XXX: que faire en l'absence de contrainte ? pour l'instant : "WHERE 1"

                // champs:
                $champs_valides_non_formattes = NULL;
                $champs_valides = self::sqlSelectFields($params, $champs_valides_non_formattes);

                // joins:
                $other_join = self::sqlAddJoins($params, $champs_valides_non_formattes);
                $requete_tpl = "SELECT SQL_CALC_FOUND_ROWS  %s".
                        "FROM tb_eflore.coste_v2_00 c ".
                        "       LEFT JOIN tela_prod_wikini.florecoste_pages dsc ON c.page_wiki_dsc = dsc.tag AND dsc.latest = 'Y' ".
                        "       LEFT JOIN tela_prod_wikini.florecoste_pages cle ON c.page_wiki_cle = cle.tag AND cle.latest = 'Y' ".
                        " %s ".
                        "WHERE %s ORDER BY c.num_nom LIMIT %u, %u -- %s ";
                $req = sprintf($requete_tpl,
                        $champs_valides, // dans le SELECT (parmi champs coste_v2_00)
                        // autre join, si nécessaire
                        $other_join ? $other_join : '',

                        // where
                        $constraints ? implode(' AND ', $constraints) : '1',

                        // limit
                        $params['navigation.depart'],
                        $params['navigation.limite'],
                        __FILE__ . ':' . __LINE__);

                return $req;
        }

        // SQL helpers
        // le préfix de coste_v2_00 est "c"
        // le préfix de florecoste_pages sur la description est est "dsc"
        // le préfix de florecoste_pages sur la clef de détermination est est "cle"
        static function sqlAddConstraint($params, $db) {
                $stack = array();
                if (!empty($params['masque.ns'])) {
                        if ($params['recherche'] == 'etendue') {
                                $stack[] = 'c.nom_sci LIKE '.$db->proteger('%' . trim($params['masque.ns']).'%');
                        } elseif($params['recherche'] == 'floue') {
                                $stack[] = sprintf(self::$soundex_scheme,
                                        'c.nom_sci',
                                        $db->proteger('%'.trim($params['masque.ns']).'%'));
                        } else {
                                $stack[] = 'c.nom_sci = '.$db->proteger(trim($params['masque.ns']));
                        }
                }

                // le masque sur texte est toujours un LIKE() "étendue", sauf si "floue" spécifié
                if(!empty($params['masque.txt'])) {
                        if($params['recherche'] == 'floue') {
                                $stack[] = sprintf(self::$soundex_scheme,
                                        'dsc.body',
                                        $db->proteger('%'.trim($params['masque.txt']).'%'));
                        }
                        else {
                                $stack[] = 'dsc.body LIKE '.$db->proteger('%'.trim($params['masque.txt']).'%');
                        }
                }

                if(!empty($params['masque.titre'])) {
                        if($params['recherche'] == 'stricte') {
                                $stack[] = sprintf('(dsc.tag = %1$s OR cle.tag = %1$s)',
                                        $db->proteger(trim($params['masque.titre'])));
                        }
                        else {
                                $stack[] = sprintf('(dsc.tag LIKE %1$s OR cle.tag LIKE %1$s)',
                                        $db->proteger('%'.trim($params['masque.titre']).'%'));
                        }
                }

                if(array_key_exists('masque.famille', $params)) {
                        $stack[] = 'b.famille LIKE '.$db->proteger(trim($params['masque.famille']));
                }

                if(array_key_exists('masque.page', $params)) {
                        $stack[] = 'c.page = '.intval($params['masque.page']);
                }

                if(array_key_exists('masque.tome', $params)) {
                        $stack[] = 'c.tome = '.intval($params['masque.tome']);
                }

                if(array_key_exists('masque.nt', $params)) {
                        $stack[] = 'c.flore_bdtfx_nt = '.intval($params['masque.nt']);
                }

                // ajout de la contrainte sur coste:nn ou bdtfx:nn si un composant d'URL supplémentaire
                // comportant un #id existe, cf self::requestFilterIds()
                $o_stack = array();
                if (array_key_exists('_ids', $params) && $params['_ids']) {
                        if ($params['_ids']['coste']) {
                                $o_stack[] = sprintf("c.num_nom IN (%s)", implode(',', $params['_ids']['coste']));
                        }
                        if ($params['_ids']['bdtfx']) {
                                $o_stack[] = sprintf("c.flore_bdtfx_nn IN (%s)", implode(',', $params['_ids']['bdtfx']));
                        }
                }
                if ($o_stack) {
                        $stack[] = '(' . implode(' OR ', $o_stack) . ')';
                }

                return $stack;
        }


        // $unmerged contient la même liste de champs que celle renvoyée
        // à la différence que celle-ci n'est pas reformatée et s'avère donc
        // utilisable plus aisément dans sqlAddJoins() qui peut en avoir besoin
        static function sqlSelectFields($params, &$unmerged) {
                $champs = $params['retour.champs'];
                // champs coste_v2_00
                $c = self::addSQLToFieldSynonym(explode(',', $champs));
                if (isset($c['*'])) {
                        $t = array_diff_key(self::$allow_champs, array_flip(self::$special_champs));
                } else {
                        // just loop below
                        $t = $c;
                }

                // si aucun des champs fournis n'est valide
                // on se rappelle nous-même après avoir réinitialisé retour.champs
                // avec les champs par défaut
                if(!$t) {
                        $params['retour.champs'] = self::$default_params['retour.champs'];
                        return self::sqlSelectFields($params);
                }

                if(array_key_exists('titre', $t))
                        $t['titre'] = $params['txt.format'] == 'txt' ? 'c.nom_sci' : 'c.nom_sci_html';

                // champs obligatoires:
                $t = array_merge($t, self::addSQLToFieldSynonym(self::$champs_obligatoires));
                $unmerged = $t;

                // XXX: PHP-5.3
                $ret = array();
                foreach($t as $k => $v) {
                        if (strpos($k, ':') !== FALSE) {
                                $ret[] = "$v AS \"$k\"";
                        } else {
                                $ret[] = "$v AS $k";
                        }
                }
                return implode(',',$ret);
        }

        static function sqlAddJoins($params, $champs) {
                $j = '';
                // ces tests doivent correspondre aux champs générés par sqlSelectFields()
                // ou contraintes générées par sqlAddConstraint()
                if(array_key_exists('masque.famille', $params) ||
                   array_key_exists('famille', $champs)) {
                        $j .= 'LEFT JOIN tb_eflore.bdtfx_v2_00 b ON c.flore_bdtfx_nn = b.num_nom';
                }

                return $j;
        }

        // d'un tableau de type array("coste:nn", "type_epithete")
        // retourne
        // un tableau de type array("coste:nn" => "c.num_nom", "type_epithete" => "c.type_epithete")
        // basé sur self::$allow_champs
        static function addSQLToFieldSynonym(Array $syno) {
                return array_intersect_key(self::$allow_champs, array_flip($syno));
        }

        // request handler
        static function requestParse(&$ressource, &$params) {
                $uri = explode('/', $_SERVER['REDIRECT_URL']);
                if(!empty($_SERVER['QUERY_STRING']))
                        parse_str($_SERVER['REDIRECT_QUERY_STRING'], $params);
                $ressource = array_slice($uri, array_search('textes', $uri) + 1, 3);
        }

        // supprime l'index du tableau des paramètres si sa valeur ne correspond pas
        // au spectre passé par $values.
        static function unsetIfInvalid(&$var, $index, $values) {
                if(array_key_exists($index, $var) && !in_array($var[$index], $values))
                        unset($var[$index]);
        }

        static function requestFilterParams(Array $params) {
                $p = array_intersect_key($params, array_flip(self::$allow_params));
                self::unsetIfInvalid($p, 'txt.format', array('txt', 'htm'));
                self::unsetIfInvalid($p, 'retour.format', array('min','max'));
                self::unsetIfInvalid($p, 'retour.indexBy', array('coste', 'bdtfx'));
                self::unsetIfInvalid($p, 'recherche', array('stricte','etendue','floue'));

                if(isset($params['masque.ns'])) $p['masque.ns'] = trim($params['masque.ns']);
                if(isset($params['masque.texte'])) $p['masque.texte'] = trim($params['masque.texte']);

                if(isset($params['masque.famille'])) {
                        // mysql -N<<<"SELECT DISTINCT famille FROM bdtfx_v2_00;"|sed -r "s/(.)/\1\n/g"|sort -u|tr -d "\n"
                        $p['masque.famille'] = preg_replace('/[^a-zA-Z %_]/', '', iconv("UTF-8",
                                                                                                                                                        "ASCII//TRANSLIT",
                                                                                                                                                        $params['masque.famille']));
                }

                // TODO: use filter_input(INPUT_GET);
                // renvoie FALSE ou NULL si absent ou invalide
                $p['navigation.limite'] = filter_var(@$params['navigation.limite'],
                        FILTER_VALIDATE_INT,
                        array('options' => array(
                                'default' => NULL,
                                'min_range' => 1,
                                'max_range' => _COSTE_TEXTE_MAX_RESULT_LIMIT)));
                $p['navigation.depart'] = filter_var(@$params['navigation.depart'],
                        FILTER_VALIDATE_INT,
                        array('options' => array(
                                'default' => NULL,
                                'min_range' => 0,
                                'max_range' => _COSTE_TEXTE_MAX_COSTE_NN)));
                $p['masque.page'] = filter_var(@$params['masque.page'],
                        FILTER_VALIDATE_INT,
                        array('options' => array(
                                'default' => NULL,
                                'min_range' => 0,
                                'max_range' => _COSTE_TEXTE_MAX_COSTE_PAGE)));
                $p['masque.tome'] = filter_var(@$params['masque.tome'],
                        FILTER_VALIDATE_INT,
                        array('options' => array(
                                'default' => NULL,
                                'min_range' => 0,
                                'max_range' => _COSTE_TEXTE_MAX_COSTE_TOME)));
                $p['masque.nt'] = filter_var(@$params['masque.nt'],
                        FILTER_VALIDATE_INT,
                        array('options' => array(
                                'default' => NULL,
                                'min_range' => 0,
                                'max_range' => _COSTE_TEXTE_MAX_BDTFX_NT)));

                // on filtre les NULL, FALSE et '', mais pas les 0, d'où le callback()
                // TODO: PHP-5.3
                $p = array_filter($p, create_function('$a','return !in_array($a, array("",false,null),true);'));
                $p = array_merge(self::$default_params, $p);

                return $p;
        }

        static function requestFilterIds($uri) {
                if(count($uri) != 1) return NULL;

                // getNN* renvoient le num_nom passé comme segment d'URI:
                // - soit un id selon coste (num_nom dans coste_v2_00)
                // - soit un id selon bdtfx (num_nom dans bdtfx_v2_00)
                // ou bien l'extrait du pattern bdtfx.nn:(#id)
                $ids_coste = array_filter(array_map(array(__CLASS__, 'getNNCoste'), explode(',', $uri[0])));
                $ids_bdtfx = array_filter(array_map(array(__CLASS__, 'getNNBdtfx'), explode(',', $uri[0])));

                // en cas d'échec (tous les id sont invalides), bail-out
                if(!$ids_bdtfx && !$ids_coste) {
                        // http_response_code(500);
                        throw new Exception('not supported', 500);
                }

                return array(
                        'coste' => array_slice($ids_coste, 0, intval(_COSTE_TEXTE_MAX_RESULT_LIMIT / 2) ),
                        'bdtfx' => array_slice($ids_bdtfx, 0, intval(_COSTE_TEXTE_MAX_RESULT_LIMIT / 2) )
                );
        }

        static function aide() {
                header("Content-Type: text/plain; charset=utf-8");
                return sprintf("Service coste/textes:

Retourne des informations (choisies) à propos d'un taxon donné (à partir de son numéro nomenclatural
Retourne des informations (choisies) à propos de taxons recherchés (à partir de divers critères)
Les résultats sont indexés. La clef par défaut est le num_nom d'après coste (attribut \"coste:nn\")
Usage:  coste/textes[/<liste-num_nom>]?<params>

* le paramètre \"retour.indexBy\" affecte le mode d'indexation (\"bdtfx\" ou \"coste\" (defaut))
* <liste-num_nom> étant une liste de numéros nomenclaturaux de taxons séparés par des virgules au format:
 - <#id>: un numéro nomenclatural dans la base coste
 - <bdtfx.nn:#id>: un numéro nomenclatural dans la base bdtfx
* retour.champs une liste de champs séparés par des virgules parmi *,%s
* les paramètres acceptés sont les suivants: %s
* les champs retournés par défaut sont les suivants: %s
* le paramètre \"recherche\" affecte les masques \"ns\" et \"texte\"
* le paramètre \"famille\" est traité via LIKE et accepte les caractères '_' et '%%'
* le paramètre \"retour.format\" est inutilisé pour l'instant.

Exemples:
/service:eflore:0.1/coste/textes/bdtfx.nn:182?retour.champs=titre
        # retourne l'Acer monspessulanum
/service:eflore:0.1/coste/textes/182?retour.champs=titre
        # retourne la Roemeria violacea (bdtfx:nn = 56272)
/service:eflore:0.1/coste/textes/182,bdtfx.nn:182?retour.champs=titre
        # retourne les deux précédents
/service:eflore:0.1/coste/textes?masque.titre=Cla001Thalamiflores&retour.champs=titre
        # retourne la section de Coste relatives aux Thalamiflores
/service:eflore:0.1/coste/textes?masque.titre=Thalamiflores&recherche=floue&retour.champs=titre
        # idem, en utilisant une recherche floue
/service:eflore:0.1/coste/textes?masque.titre=Cla001Thalamiflores&retour.champs=titre&retour.indexBy=bdtfx
        # retourne une erreur de format car cette section de coste n'est associée à aucun taxon de la BDTFX
",
                        implode(',', array_keys(self::$allow_champs)),
                        implode(',', self::$allow_params),
                        self::$default_params['retour.champs']
                );
        }

        static function getNNCoste($refnn) {
                if (is_numeric($refnn)) {
                        $t = intval($refnn);
                        if ($t >= 1 && $t < _COSTE_TEXTE_MAX_COSTE_NN) return $t;
                }
                return FALSE;
        }

        static function getNNBdtfx($refnn) {
                if(strpos($refnn, 'bdtfx.nn:') !== 0) return FALSE;
                $t = intval(str_replace('bdtfx.nn:', '', $refnn));
                if($t >= 1 && $t < _COSTE_TEXTE_MAX_BDTFX_NN) return $t;
                return FALSE;
        }
}