Subversion Repositories eFlore/Projets.eflore-projets

Compare Revisions

Ignore whitespace Rev 853 → Rev 854

/trunk/services/modules/0.1/coste/Textes2.php
New file
0,0 → 1,397
<?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/textes2/bdtfx.nn:182
* 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 taxon donné (à 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
*
*/
 
/*restore_error_handler();
error_reporting(E_ALL);*/
class Textes2 {
// paramètres autorisés
static $allow_params = array(
'txt.format', 'retour.format', 'retour.champs',
'recherche',
'masque.ns', 'masque.txt', 'masque.page', 'masque.tome', 'masque.famille',
'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', '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(
'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
static $special_champs = array('nom_sci_html', 'nom_sci', '*');
// 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);
}
// en cas d'accès phpunit
else {
$uri = $ressources;
}
 
if(is_null($parametres)) $parametres = Array();
$params = self::requestFilterParams($parametres);
 
// renvoie du plain/text d'aide (cf fin de programme)
if(count($uri) == 1 && $uri[0] == 'aide') return self::aide();
$id = 0;
// getNN renvoie le num_nom passé comme segment d'URI
// ou bien l'extrait du pattern bdtfx.nn:#id
if(count($uri) == 1) $id = self::getNN($uri[0]);
 
 
// en cas d'échec (id invalide), bail-out
// note: NULL is ok, mais FALSE est le retour de getNN()
if($id === FALSE || count($uri) > 1) {
// http_response_code(500);
throw new Exception('not supported', 500);
}
 
// XXX: temporaires, pour chopper $db dans l'instance
// (non disponibles dans nos helpers statics)
$GLOBALS[__FILE__] = $db;
$req = self::getCosteInfo($params, $id);
unset($GLOBALS[__FILE__]);
$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 num_nom
$res2 = array();
foreach($res as $v) {
$res2[$v['num_nom']] = $v;
}
 
// l'appelant s'occupera du json_encode()
// même si ça démange d'exit'er ici
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 central: récupère les infos à partir de paramètres
// et une optionnel contrainte de num_nom
static function getCosteInfo(array $params, $id = NULL) {
assert('is_int($id)');
 
// contraintes (WHERE):
$constraints = self::sqlAddConstraint($params);
// ajout de la contrainte sur num_nom si un composant d'URL supplémentaire
// comportant un #id existe
if($id) array_unshift($constraints, "c.num_nom = $id");
 
 
// 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);
 
$req = sprintf(<<<EOF
SELECT SQL_CALC_FOUND_ROWS c.num_nom, %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
EOF
,
$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) {
$q = $GLOBALS[__FILE__];
 
$stack = array();
if(!empty($params['masque.ns'])) {
if($params['recherche'] == 'etendue')
$stack[] = 'c.nom_sci LIKE ' . $q->proteger('%' . trim($params['masque.ns']) . '%');
elseif($params['recherche'] == 'floue')
$stack[] = sprintf(self::$soundex_scheme,
'c.nom_sci',
$q->proteger('%' . trim($params['masque.ns']) . '%'));
else
$stack[] = 'c.nom_sci = ' . $q->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',
$q->proteger('%' . trim($params['masque.txt']) . '%'));
}
else {
$stack[] = 'dsc.body LIKE ' . $q->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)',
$q->proteger(trim($params['masque.titre'])));
}
else {
$stack[] = sprintf('(dsc.tag LIKE %1$s OR cle.tag LIKE %1$s)',
$q->proteger('%' . trim($params['masque.titre']) . '%'));
}
}
 
if(array_key_exists('masque.famille', $params)) {
$stack[] = 'b.famille LIKE ' . $q->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']);
}
 
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 = array_intersect_key(self::$allow_champs, array_flip(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';
 
$unmerged = $t;
 
// XXX: PHP-5.3
$ret = array();
foreach($t as $k => $v) {
$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_v1_02 b ON c.num_nom = b.num_nom';
}
 
return $j;
}
 
// 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('textes2', $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, '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_v1_02;"|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' => 500)));
$p['navigation.depart'] = filter_var(@$params['navigation.depart'],
FILTER_VALIDATE_INT,
array('options' => array('default' => NULL,
'min_range' => 0,
'max_range' => 10000))); // count(1) from coste_v2_00
 
// 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 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)
 
Usage:
coste/textes/bdtfx.nn:#id?<params>
coste/textes/#id?<params>
coste/textes?<params>
* #id étant un numéro nomenclatural d'un taxon 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",
implode(',', array_keys(self::$allow_champs)),
implode(',', self::$allow_params),
self::$default_params['retour.champs']
);
}
 
static function getNN($refnn) {
if(is_numeric($refnn) && intval($refnn) >= 1) return intval($refnn);
if(strpos($refnn, 'bdtfx.nn:') !== 0) return FALSE;
return intval(str_replace('bdtfx.nn:', '', $refnn));
}
}