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ésstatic $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éfautstatic $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 GETpublic 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 HTTPif (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 iciif(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:nnstatic 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 besoinstatic 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éfautif(!$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_champsstatic function addSQLToFieldSynonym(Array $syno) {return array_intersect_key(self::$allow_champs, array_flip($syno));}// request handlerstatic 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-outif(!$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 nomenclaturalRetourne 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;}}