New file |
0,0 → 1,515 |
<?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) { |
if (isset($_SERVER['REDIRECT_URL'])) { |
$uri = explode('/', $_SERVER['REDIRECT_URL']); |
} else { |
$uri = explode('/', $_SERVER['REQUEST_URI']); |
} |
if(!empty($_SERVER['QUERY_STRING'])) |
parse_str($_SERVER['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; |
} |
} |