Subversion Repositories eFlore/Applications.cel

Rev

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

<?php
/**
* @category  PHP
* @package   jrest
* @author    Raphaël Droz <raphael@tela-botania.org>
* @copyright 2013 Tela-Botanica
* @license   http://www.cecill.info/licences/Licence_CeCILL_V2-fr.txt Licence CECILL
* @license GPL v3 <http://www.gnu.org/licenses/gpl.txt>
*/

/**
 * Service d'import de données d'observation du CEL au format XLS
 *
 * Sont define()'d commme n° de colonne tous les abbrevs retournés par
 * ExportXLS::nomEnsembleVersListeColonnes() préfixés par C_  cf: detectionEntete()
 *
 * Exemple d'un test:
 * $ GET "/jrest/ExportXLS/22506?format=csv&range=*&limite=13" \
 *   | curl -F "upload=@-" -F utilisateur=22506 "/jrest/ImportXLS"
 * # 13 observations importées
 * + cf MySQL general_log = 1
 *  
 **/

set_include_path(get_include_path() . PATH_SEPARATOR . dirname(dirname(realpath(__FILE__))) . '/lib');
// TERM
error_reporting(-1);
ini_set('html_errors', 0);
ini_set('xdebug.cli_color', 2);
require_once('lib/PHPExcel/Classes/PHPExcel.php');
require_once('ExportXLS.php');


date_default_timezone_set("Europe/Paris");

// nombre d'INSERT à cumuler par requête SQL
// (= nombre de lignes XLS à bufferiser)
//define('NB_LIRE_LIGNE_SIMUL', 30);
define('NB_LIRE_LIGNE_SIMUL', 5);

// Numbers of days between January 1, 1900 and 1970 (including 19 leap years)
// see traiterDateObs()
define("MIN_DATES_DIFF", 25569);


class MyReadFilter implements PHPExcel_Reader_IReadFilter {
        // exclusion de colonnes
        public $exclues = array();

        // lecture par morceaux
    public $ligne_debut = 0; 
    public $ligne_fin = 0;

        public function __construct() {}
        public function def_interval($debut, $nb) {
                $this->ligne_debut = $debut;
                $this->ligne_fin = $debut + $nb;
        }
    public function readCell($colonne, $ligne, $worksheetName = '') {
                if(@$this->exclues[$colonne]) return false;
                // si des n° de morceaux ont été initialisés, on filtre...
                if($this->ligne_debut && ($ligne < $this->ligne_debut || $ligne >= $this->ligne_fin)) return false;
                return true;
    } 
} 

class ImportXLS extends Cel  {

        static $ordre_BDD = Array(
                "ce_utilisateur",
                "prenom_utilisateur",
                "nom_utilisateur",
                "courriel_utilisateur",
                "ordre",
                "nom_sel",
                "nom_sel_nn",
                "nom_ret",
                "nom_ret_nn",
                "nt",
                "famille",
                "nom_referentiel",
                "zone_geo",
                "ce_zone_geo",
                "date_observation",
                "lieudit",
                "station",
                "milieu",
                "mots_cles_texte",
                "commentaire",
                "transmission",
                "date_creation",
                "date_modification",
                "date_transmission",
                "latitude",
                "longitude",
                "abondance",
                "certitude",
                "phenologie",
                "code_insee_calcule"
        );

        // cf: initialiser_pdo_ordered_statements()
        // eg: "INSERT INTO cel_obs (ce_utilisateur, ..., phenologie, code_insee_calcule) VALUES"
        // colonnes statiques d'abord, les autres ensuite, dans l'ordre de $ordre_BDD
        static $insert_prefix_ordre;
        // eg: "(<id>, <prenom>, <nom>, <email>, now(), now(), ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
        // dont le nombre de placeholder dépend du nombre de colonnes non-statiques
        // colonnes statiques d'abord, les autres ensuite, dans l'ordre de $ordre_BDD
        static $insert_ligne_pattern_ordre;

        // seconde (meilleure) possibilité
        // cf: initialiser_pdo_statements()
        // eg: "INSERT INTO cel_obs (ce_utilisateur, ..., date_creation, ...phenologie, code_insee_calcule) VALUES"
        static $insert_prefix;
        // eg: "(<id>, <prenom>, <nom>, <email>, ?, ?, ?, now(), now(), ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
        // dont le nombre de placeholder dépend du nombre de colonnes non-statiques
        static $insert_ligne_pattern;

        /*
          Ces colonnes:
          - sont propres à l'ensemble des enregistrements uploadés
          - sont indépendantes du numéro de lignes
          - n'ont pas de valeur par défaut dans la structure de la table
          - nécessitent une initialisation dans le cadre de l'upload

          initialiser_colonnes_statiques() y merge les données d'identification utilisateur
        */
        public $colonnes_statiques = Array(
                "ce_utilisateur" => NULL,
                "prenom_utilisateur" => NULL,
                "nom_utilisateur" => NULL,
                "courriel_utilisateur" => NULL,

                // fixes (fonction SQL)
                // XXX future: mais pourraient varier dans le futur si la mise-à-jour
                // d'observation est implémentée
                "date_creation" => "now()",
                "date_modification" => "now()",
        );

        public $id_utilisateur = NULL;

        // erreurs d'import
        public $bilan = Array();


        function ExportXLS($config) {
                parent::__construct($config);
        }

        function createElement($pairs) {
                if(!isset($pairs['utilisateur']) || trim($pairs['utilisateur']) == '') {
                        echo '0'; exit;
                }

                $id_utilisateur = intval($pairs['utilisateur']);
                $this->id_utilisateur = $id_utilisateur; // pour traiterImage();

                if(!isset($_SESSION)) session_start();
        $this->controleUtilisateur($id_utilisateur);

        $this->utilisateur = $this->getInfosComplementairesUtilisateur($id_utilisateur);

                $this->initialiser_colonnes_statiques($id_utilisateur);

                // initialisation du statement PDO/MySQL
                // première version, pattern de requête pas génial
                /* list(self;;$insert_prefix_ordre, self::$insert_ligne_pattern_ordre) =
                   $this->initialiser_pdo_ordered_statements($this->colonnes_statiques); */
                list(self::$insert_prefix, self::$insert_ligne_pattern) =
                        $this->initialiser_pdo_statements($this->colonnes_statiques);


                $infos_fichier = array_pop($_FILES);
                
                /*$objPHPExcel = PHPExcel_IOFactory::load($infos_fichier['tmp_name']);
                  $donnees = $objPHPExcel->getActiveSheet()->toArray(NULL,FALSE,FALSE,TRUE);*/

                /*$objReader = PHPExcel_IOFactory::createReader("Excel5");
                $objReader->setReadDataOnly(true);
                $objPHPExcel = $objReader->load($infos_fichier['tmp_name']);*/

                //var_dump($donnees);

                // renomme le fichier pour lui ajouter son extension initiale, ce qui
                // permet (une sorte) d'autodétection du format.
                $fichier = $infos_fichier['tmp_name'];
                $extension = pathinfo($infos_fichier['name'], PATHINFO_EXTENSION);
                if( (strlen($extension) == 3 || strlen($extension) == 4) &&
                        (rename($fichier, $fichier . '.' . $extension))) {
                        $fichier = $fichier . '.' . $extension;
                }

                $objReader = PHPExcel_IOFactory::createReaderForFile($fichier);
                $objReader->setReadDataOnly(true);

                if(is_a($objReader, 'PHPExcel_Reader_CSV')) {
                        $objReader->setDelimiter(',')
                                ->setEnclosure('"')
                                ->setLineEnding("\n")
                                ->setSheetIndex(0);
                }

                // on ne conserve que l'en-tête
                $filtre = new MyReadFilter();
                $filtre->def_interval(1, 2);
                $objReader->setReadFilter($filtre);

                $objPHPExcel = $objReader->load($fichier);
                $obj_infos = $objReader->listWorksheetInfo($fichier);
                // XXX: indépendant du readFilter ?
                $nb_lignes = $obj_infos[0]['totalRows'];

                $donnees = $objPHPExcel->getActiveSheet()->toArray(NULL, FALSE, FALSE, TRUE);
                $filtre->exclues = self::detectionEntete($donnees[1]);

                $obs_ajouts = 0;
                $obs_maj = 0;
                $dernier_ordre = $this->requeter("SELECT MAX(ordre) AS ordre FROM cel_obs WHERE ce_utilisateur = $id_utilisateur");
                $dernier_ordre = intval($dernier_ordre[0]['ordre']) + 1;
                if(! $dernier_ordre) $dernier_ordre = 0;

                // on catch to les trigger_error(E_USER_NOTICE);
                set_error_handler(array($this, 'erreurs_stock'), E_USER_NOTICE);

                // lecture par morceaux (chunks), NB_LIRE_LIGNE_SIMUL lignes à fois
                // pour aboutir des requêtes SQL d'insert groupés.
                for($ligne = 2; $ligne < $nb_lignes + NB_LIRE_LIGNE_SIMUL; $ligne += NB_LIRE_LIGNE_SIMUL) {
                        $filtre->def_interval($ligne, NB_LIRE_LIGNE_SIMUL);
                        $objReader->setReadFilter($filtre);

                        /* recharge avec $filtre actif (filtre sur lignes colonnes):
                           - exclue les colonnes inutiles/inutilisables)
                           - ne selectionne que les lignes dans le range [$ligne - $ligne + NB_LIRE_LIGNE_SIMUL] */
                        $objPHPExcel = $objReader->load($fichier);
                        $donnees = $objPHPExcel->getActiveSheet()->toArray(NULL, FALSE, FALSE, TRUE);

                        // ici on appel la fonction qui fera effectivement l'insertion multiple
                        // à partir des (au plus) NB_LIRE_LIGNE_SIMUL lignes

                        // TODO: passer $this, ne sert que pour appeler des méthodes public qui pourraient être statiques
                        // notamment dans RechercheInfosTaxonBeta.php
                        list($enregistrements, $images) =
                                self::chargerLignes($this, $donnees, $this->colonnes_statiques, $dernier_ordre);
                        if(! $enregistrements) break;

                        echo "===chunk\n";
                        self::trierColonnes($enregistrements);
                        // normalement: NB_LIRE_LIGNE_SIMUL, sauf si une enregistrement ne semble pas valide
                        // ou bien lors du dernier chunk

                        $nb_rec = count($enregistrements);
                        $sql_pattern = self::$insert_prefix .
                                str_repeat(self::$insert_ligne_pattern_ordre . ', ', $nb_rec - 1) .
                                self::$insert_ligne_pattern_ordre;

                        $sql_pattern = self::$insert_prefix .
                                str_repeat(self::$insert_ligne_pattern . ', ', $nb_rec - 1) .
                                self::$insert_ligne_pattern;

                        $this->bdd->beginTransaction();
                        $stmt = $this->bdd->prepare($sql_pattern);
                        $donnees = array();
                        foreach($enregistrements as $e) $donnees = array_merge($donnees, array_values($e));

                        /* debug ici: echo $sql_pattern . "\n"; var_dump($enregistrements, $donnees); die;*/

                        $stmt->execute($donnees);

                        // $stmt->debugDumpParams(); // https://bugs.php.net/bug.php?id=52384
                        $dernier_autoinc = $this->bdd->lastInsertId();
                        $this->bdd->commit();

                        if(! $dernier_autoinc) trigger_error("l'insertion semble avoir échoué", E_USER_NOTICE);

                        $obs_ajouts += count($enregistrements);
                        // $obs_ajouts += count($enregistrements['insert']);
                        // $obs_maj += count($enregistrements['update']);
                        $nb_images_ajoutees = self::stockerImages($this, $enregistrements, $images, $dernier_autoinc);
                }

                restore_error_handler();

                if($this->bilan) echo implode("\n", $this->bilan) . "\n";
                $summary = sprintf("%d observation(s) ajoutée(s)\n%d image(s) attachée(s)",
                                                   $obs_ajouts,
                                                   $nb_images_ajoutees);

                die("$summary");
        }

        static function detectionEntete($entete) {
                $colonnes_reconnues = Array();
                $cols = ExportXLS::nomEnsembleVersListeColonnes('standard');
                foreach($entete as $k => $v) {
                        $entete_simple = iconv('UTF-8', 'ASCII//TRANSLIT', strtolower(trim($v)));
                        foreach($cols as $col) {
                                $entete_officiel_simple = iconv('UTF-8', 'ASCII//TRANSLIT', strtolower(trim($col['nom'])));
                                $entete_officiel_abbrev = $col['abbrev'];
                                if($entete_simple == $entete_officiel_simple || $entete_simple == $entete_officiel_abbrev) {
                                        // debug echo "define C_" . strtoupper($entete_officiel_abbrev) . ", $k ($v)\n";
                                        define("C_" . strtoupper($entete_officiel_abbrev), $k);
                                        $colonnes_reconnues[$k] = 1;
                                        break;
                                }
                        }
                }

                // prépare le filtre de PHPExcel qui évitera le traitement de toutes les colonnes superflues

                // eg: diff ( Array( H => Commune, I => rien ) , Array( H => 1, K => 1 )
                // ==> Array( I => rien )
                $colonnesID_non_reconnues = array_diff_key($entete, $colonnes_reconnues);

                // des colonnes de ExportXLS::nomEnsembleVersListeColonnes()
                // ne retient que celles marquées "importables"
                $colonnes_automatiques = array_filter($cols, function($v) {     return !$v['importable']; });

                // ne conserve que le nom long pour matcher avec la ligne XLS d'entête
                array_walk($colonnes_automatiques, function(&$v) {      $v = $v['nom']; });

                // intersect ( Array ( N => Milieu, S => Ordre ), Array ( ordre => Ordre, phenologie => Phénologie ) )
                // ==> Array ( S => Ordre, AA => Phénologie )
                $colonnesID_a_exclure = array_intersect($entete, $colonnes_automatiques);

                // TODO: pourquoi ne pas comparer avec les abbrevs aussi ?
                // merge ( Array( I => rien ) , Array ( S => Ordre, AA => Phénologie ) )
                // ==> Array ( I => rien, AA => Phénologie )
                return array_merge($colonnesID_non_reconnues, $colonnesID_a_exclure);
        }

        /*
         * charge un groupe de lignes
         */
        static function chargerLignes($cel, $lignes, $colonnes_statiques, &$dernier_ordre) {
                $enregistrement = NULL;
                $enregistrements = Array();
                $toutes_images = Array();

                foreach($lignes as $ligne) {
                        //$ligne = array_filter($ligne, function($cell) { return !is_null($cell); });
                        //if(!$ligne) continue;
                        // on a besoin des NULL pour éviter des notice d'index indéfini
                        if(! array_filter($ligne, function($cell) { return !is_null($cell); })) continue;

                        if( ($enregistrement = self::chargerLigne($ligne, $dernier_ordre, $cel)) ) {
                                // $enregistrements[] = array_merge($colonnes_statiques, $enregistrement);
                                $enregistrements[] = $enregistrement;

                                if(isset($enregistrement['_images'])) {
                                        $pos = count($enregistrements) - 1;
                                        $last = &$enregistrements[$pos];
                                        // ne dépend pas de cel_obs, et seront insérées *après* les enregistrements
                                        // mais nous ne voulons pas nous priver de faire des INSERT multiples pour autant
                                        $toutes_images[] = Array("images" => $last['_images'],
                                                                                         "obs_pos" => $pos);
                                        // ce champ n'a pas a faire partie de l'insertion dans cel_obs,
                                        // mais est utile pour cel_obs_images
                                        unset($last['_images']);
                                }

                                $dernier_ordre++;
                        }
                }

                // XXX future: return Array($enregistrements_a_inserer, $enregistrements_a_MAJ, $toutes_images);
                return Array($enregistrements, $toutes_images);
        }


        static function trierColonnes(&$enregistrements) {
                foreach($enregistrements as &$enregistrement) {
                        $enregistrement = self::sortArrayByArray($enregistrement, self::$ordre_BDD);
                        //array_walk($enregistrement, function(&$item, $k) { $item = is_null($item) ? "NULL" : $item; });
                        //$req .= implode(', ', $enregistrement) . "\n";
                }
        }


        static function stockerImages($cel, $enregistrements, $toutes_images, $lastid) {
                $images_insert = 'INSERT INTO cel_obs_images (id_image, id_observation) VALUES %s ON DUPLICATE KEY UPDATE id_image = id_image';
                $images_obs_assoc = Array();

                foreach($toutes_images as $images_pour_obs) {
                        $obs = $enregistrements[$images_pour_obs["obs_pos"]];
                        $id_obs = $lastid // dernier autoinc inséré
                                - count($enregistrements) + 1 // correspondrait au premier autoinc
                                + $images_pour_obs["obs_pos"]; // ordre d'insertion = ordre dans le tableau $enregistrements (commence à 0)
                        foreach($images_pour_obs['images'] as $image) {
                                $images_obs_assoc[] = sprintf('(%d,%d)',
                                                                                          $image['id_image'], // intval() useless
                                                                                          $id_obs); // intval() useless
                        }
                }

                if($images_obs_assoc) {
                        $requete = sprintf($images_insert, implode(', ', $images_obs_assoc));
                        // debug echo "$requete\n";
                        $cel->requeter($requete);
                }

                return count($images_obs_assoc);
        }

        /*
          Aucune des valeurs présentes dans $enregistrement n'est quotée
          cad aucune des valeurs retournée par traiter{Espece|Localisation}()
          car ce tableau est passé à un PDO::preparedStatement() qui applique
          proprement les règle d'échappement.
         */
        static function chargerLigne($ligne, $dernier_ordre, $cel) {
                // en premier car le résultat est utile pour
                // traiter longitude et latitude (traiterLonLat())
                $referentiel = self::identReferentiel($ligne[C_NOM_REFERENTIEL]);

                // $espece est rempli de plusieurs informations
                $espece = Array(C_NOM_SEL => NULL, C_NOM_SEL_NN => NULL, C_NOM_RET => NULL,
                                                C_NOM_RET_NN => NULL, C_NT => NULL, C_FAMILLE => NULL);
                self::traiterEspece($ligne, $espece, $cel);

                // $localisation est rempli à partir de plusieurs champs: C_ZONE_GEO et C_CE_ZONE_GEO
                $localisation = Array(C_ZONE_GEO => NULL, C_CE_ZONE_GEO => NULL);
                self::traiterLocalisation($ligne, $localisation, $cel);

                // $transmission est utilisé pour date_transmission
                $transmission = in_array(strtolower(trim($ligne[C_TRANSMISSION])), array(1, 'oui')) ? 1 : 0;


                // Dans ce tableau, seules devraient apparaître les données variable pour chaque ligne.
                // Dans ce tableau, l'ordre des clefs n'importe pas (cf: self::sortArrayByArray())
                $enregistrement = Array(
                        "ordre" => $dernier_ordre,

                        "nom_sel" => $espece[C_NOM_SEL],
                        "nom_sel_nn" => $espece[C_NOM_SEL_NN],
                        "nom_ret" => $espece[C_NOM_RET],
                        "nom_ret_nn" => $espece[C_NOM_RET_NN],
                        "nt" => $espece[C_NT],
                        "famille" => $espece[C_FAMILLE],

                        "nom_referentiel" => $referentiel,

                        "zone_geo" => $localisation[C_ZONE_GEO],
                        "ce_zone_geo" => $localisation[C_CE_ZONE_GEO],

                        // $ligne: uniquement pour les infos en cas de gestion d'erreurs (date incompréhensible)
                        "date_observation" => self::traiterDateObs($ligne[C_DATE_OBSERVATION], $ligne),

                        "lieudit" => trim($ligne[C_LIEUDIT]),
                        "station" => trim($ligne[C_STATION]),
                        "milieu" => trim($ligne[C_MILIEU]),

                        "mots_cles_texte" => NULL, // TODO: foreign-key
                        "commentaire" => trim($ligne[C_COMMENTAIRE]),

                        "transmission" => $transmission,
                        "date_transmission" => $transmission ? date("Y-m-d H:i:s") : NULL, // pas de fonction SQL dans un PDO statement, <=> now()

                        // $ligne: uniquement pour les infos en cas de gestion d'erreurs (lon/lat incompréhensible)
                        "latitude" => self::traiterLonLat(NULL, $ligne[C_LATITUDE], $referentiel, $ligne),
                        "longitude" => self::traiterLonLat($ligne[C_LONGITUDE], NULL, $referentiel, $ligne),

                        // @ car potentiellement optionnelles ou toutes vides => pas d'index dans PHPExcel (tableau optimisé)
                        "abondance" => @$ligne[C_ABONDANCE],
                        "certitude" => @$ligne[C_CERTITUDE],
                        "phenologie" => @$ligne[C_PHENOLOGIE],

                        "code_insee_calcule" => substr($localisation[C_CE_ZONE_GEO], -5) // varchar(5)
                );

                // passage de $enregistrement par référence, ainsi ['_images'] n'est défini
                // que si des résultats sont trouvés
                // "@" car PHPExcel supprime les colonnes null sur toute la feuille (ou tout le chunk)
                if(@$ligne[C_IMAGES]) self::traiterImage($ligne[C_IMAGES], $cel, $enregistrement);

                return $enregistrement;
        }

        static function traiterImage($str, $cel, &$enregistrement) {
                $liste_images = array_filter(explode("/", $str));
                array_walk($liste_images,
                                   function($item, $key, $obj) { $item = $obj->quoteNonNull(trim($item)); },
                                   $cel);
                $requete = sprintf(
                        "SELECT id_image, nom_original FROM cel_images WHERE ce_utilisateur = %d AND nom_original IN (\"%s\")",
                        $cel->id_utilisateur,
                        implode('","', $liste_images));

                $resultat = $cel->requeter($requete);

                if($resultat) $enregistrement['_images'] = $resultat;
        }


        /* FONCTIONS de TRANSFORMATION de VALEUR DE CELLULE */

        // TODO: PHP 5.3, utiliser date_parse_from_format()
        // TODO: parser les heures (cf product-owner)
        // TODO: passer par le timestamp pour s'assurer de la validité
        static function traiterDateObs($date, $ligne) {
                // TODO: see https://github.com/PHPOffice/PHPExcel/issues/208
                if(is_double($date)) {
                        if($date > 0)
                                return PHPExcel_Style_NumberFormat::toFormattedString($date, PHPExcel_Style_NumberFormat::FORMAT_DATE_YYYYMMDD2) . " 00:00:00";
                        trigger_error("ligne \"{$ligne[C_NOM_SEL]}\": " .
                                                  "Attention: date antérieure à 1970 et format de cellule \"DATE\" utilisés ensemble",
                                                  E_USER_NOTICE);
                        
                        // throw new Exception("erreur: date antérieure à 1970 et format de cellule \"DATE\" utilisés ensemble");

                        // attention, UNIX timestamp, car Excel les décompte depuis 1900
                        // cf http://fczaja.blogspot.fr/2011/06/convert-excel-date-into-timestamp.html
                        // $timestamp = ($date - MIN_DATES_DIFF) * 60 * 60 * 24 - time(); // NON

                        // $timestamp = PHPExcel_Calculation::getInstance()->calculateFormula("=" . $date . "-DATE(1970,1,1)*60*60*24"); // NON

                        // echo strftime("%Y/%m/%d 00:00:00", $timestamp); // NON
                }
                else {
                        $timestamp = strtotime($date);
                        if(! $timestamp) {
                                if($date) trigger_error("ligne \"{$ligne[C_NOM_SEL]}\": Attention: date erronée ($date)", E_USER_NOTICE);
                                return NULL;
                        }
                        return strftime("%Y-%m-%d 00:00:00", strtotime($date));
                }
        }

        static function identReferentiel($referentiel) {
                // SELECT DISTINCT nom_referentiel, COUNT(id_observation) AS count FROM cel_obs GROUP BY nom_referentiel ORDER BY count DESC;
                if(strpos(strtolower($referentiel), 'bdtfx') !== FALSE) return 'bdtfx:v1.01';
                if(strpos(strtolower($referentiel), 'bdtxa') !== FALSE) return 'bdtxa:v1.00';
                if(strpos(strtolower($referentiel), 'bdnff') !== FALSE) return 'bdnff:4.02';
                if(strpos(strtolower($referentiel), 'isfan') !== FALSE) return 'isfan:v1.00';

                if($referentiel) {
                        trigger_error("ligne \"{$ligne[C_NOM_SEL]}\": Attention: référentiel inconnu", E_USER_NOTICE);
                }
                return NULL;
                /* TODO: cf story,
                   En cas de NULL faire une seconde passe de détection à partir du nom saisi
                   + accepter les n° de version */
        }

        static function traiterLonLat($lon = NULL, $lat = NULL, $referentiel = 'bdtfx:v1.01', $ligne) {
                // en CSV ces valeurs sont des string, avec séparateur en français (","; cf défauts dans ExportXLS)
                if($lon && is_string($lon)) $lon = str_replace(',', '.', $lon);
                if($lat && is_string($lat)) $lat = str_replace(',', '.', $lat);

                // sprintf applique une précision à 5 décimale (comme le ferait MySQL)
                // tout en uniformisant le format de séparateur des décimales (le ".")
                if($lon && is_numeric($lon) && $lon >= -180 && $lon <= 180) return sprintf('%.5F', $lon);
                if($lat && is_numeric($lat) && $lat >= -90 && $lat <= 90) return sprintf('%.5F', $lat);

                if($lon || $lat) {
                        trigger_error("ligne \"{$ligne[C_NOM_SEL]}\": " .
                                                  "Attention: longitude ou latitude erronée",
                                                  E_USER_NOTICE);
                }
                return NULL;

                /* limite france métropole si bdtfx ? ou bdtxa ? ...
                   NON!
                   Un taxon d'un référentiel donné peut être théoriquement observé n'importe où sur le globe.
                   Il n'y a pas lieu d'effectuer des restriction ici.
                   Cependant des erreurs fréquentes (0,0 ou lon/lat inversées) peuvent être détectés ici.
                   TODO */
                $bbox = self::getReferentielBBox($referentiel);
                if(!$bbox) return NULL;

                if($lon) {
                        if($lon < $bbox['EST'] && $lon > $bbox['OUEST']) return is_numeric($lon) ? $lon : NULL;
                        else return NULL;
                }
                if($lat) {
                        if($lat < $bbox['NORD'] && $lat > $bbox['SUD']) return is_numeric($lat) ? $lat : NULL;
                        return NULL;
                }
        }


        static function traiterEspece($ligne, Array &$espece, $cel) {
                if(!$ligne[C_NOM_SEL]) return;

                // nom_sel reste toujours celui de l'utilisateur
                $espece[C_NOM_SEL] = trim($ligne[C_NOM_SEL]);

                $taxon_info_webservice = new RechercheInfosTaxonBeta($cel->config);

                $ascii = iconv('UTF-8', 'ASCII//TRANSLIT', $ligne[C_NOM_SEL]);

                // TODO: si empty(C_NOM_SEL) et !empty(C_NOM_SEL_NN) : recherche info à partir de C_NOM_SEL_NN
                $resultat_recherche_espece = $taxon_info_webservice->rechercherInfosSurTexteCodeOuNumTax($ligne[C_NOM_SEL]);

                // on supprime les noms retenus et renvoi tel quel
                // on réutilise les define pour les noms d'indexes, tant qu'à faire
                if (empty($resultat_recherche_espece['en_id_nom'])) {
                        // XXX; tout à NULL sauf C_NOM_SEL ci-dessus ?
                        $espece[C_NOM_SEL_NN] = $ligne[C_NOM_SEL_NN];
                        $espece[C_NOM_RET] = $ligne[C_NOM_RET];
                        $espece[C_NOM_RET_NN] = $ligne[C_NOM_RET_NN];
                        $espece[C_NT] = $ligne[C_NT];
                        $espece[C_FAMILLE] = $ligne[C_FAMILLE];

                        return;
                }

                // succès de la détection = écrasement du numéro nomenclatural saisi...
                $espece[C_NOM_SEL_NN] = $resultat_recherche_espece['en_id_nom'];
                // et des info complémentaires
                $complement = $taxon_info_webservice->rechercherInformationsComplementairesSurNumNom($resultat_recherche_espece['en_id_nom']);
                $espece[C_NOM_RET] = $complement['Nom_Retenu'];
                $espece[C_NOM_RET_NN] = $complement['Num_Nom_Retenu'];
                $espece[C_NT] = $complement['Num_Taxon'];
                $espece[C_FAMILLE] = $complement['Famille'];
        }


        static function traiterLocalisation($ligne, Array &$localisation, $cel) {
            $identifiant_commune = trim($ligne[C_ZONE_GEO]);
                if(!$identifiant_commune) {
                        $departement = trim($ligne[C_CE_ZONE_GEO]);
                        goto testdepartement;
                }


                $select = "SELECT DISTINCT nom, code  FROM cel_zones_geo";
        
                if (preg_match('/(.*) \((\d+)\)/', $identifiant_commune, $elements)) {
                        // commune + departement : montpellier (34)
                        $nom_commune=$elements[1];
                        $code_commune=$elements[2];
                    $requete = sprintf("%s WHERE nom = %s AND code LIKE %s",
                                                           $select, $cel->quoteNonNull($nom_commune), $cel->quoteNonNull($code_commune.'%'));
                }
                elseif (preg_match('/^(\d+|(2[ab]\d+))$/i', $identifiant_commune, $elements)) {
                        // Code insee seul  
                        $code_insee_commune=$elements[1];
                    $requete = sprintf("%s WHERE code = %s", $select, $cel->quoteNonNull($code_insee_commune));
                }
                else {
                        // Commune seule (le departement sera recupere dans la colonne departement si elle est presente)
                        // on prend le risque ici de retourner une mauvaise Commune
                        $nom_commune = str_replace(" ", "%", iconv('UTF-8', 'ASCII//TRANSLIT', $identifiant_commune));
                    $requete = sprintf("%s WHERE nom LIKE %s", $select, $cel->quoteNonNull($nom_commune.'%'));
                }
        
                $resultat_commune = $cel->requeter($requete);
                // TODO: levenstein sort ?

                // cas de la commune introuvable dans le référentiel
                // réinitialisation aux valeurs du fichier XLS
                if(! $resultat_commune) {
                        $localisation[C_ZONE_GEO] = trim($ligne[C_ZONE_GEO]);
                        $localisation[C_CE_ZONE_GEO] = trim($ligne[C_CE_ZONE_GEO]);
                } else {
                        $localisation[C_ZONE_GEO] = $resultat_commune[0]['nom'];
                        $localisation[C_CE_ZONE_GEO] = $resultat_commune[0]['code'];
                }

                $departement = &$localisation[C_CE_ZONE_GEO];

        testdepartement:
                if(strpos($departement, "INSEE-C:", 0) === 0) goto protectloc;

                if(!is_numeric($departement)) goto protectloc; // TODO ?
                if(strlen($departement) == 4) $departement = "INSEE-C:0" . $departement;
                if(strlen($departement) == 5) $departement = "INSEE-C:" . $departement;
                // if(strlen($departement) <= 9) return "INSEE-C:0" . $departement; // ? ... TODO

                $departement = trim($departement); // TODO

        protectloc:
                $localisation[C_ZONE_GEO] = $localisation[C_ZONE_GEO];
                $localisation[C_CE_ZONE_GEO] = $localisation[C_CE_ZONE_GEO];
        }



        /* HELPERS */

        // http://stackoverflow.com/questions/348410/sort-an-array-based-on-another-array
        static function sortArrayByArray($array, $orderArray) {
                $ordered = array();
                foreach($orderArray as $key) {
                        if(array_key_exists($key, $array)) {
                                $ordered[$key] = $array[$key];
                                unset($array[$key]);
                        }
                }
                return $ordered + $array;
        }

        // retourne une BBox [N,S,E,O) pour un référentiel donné
        static function getReferentielBBox($referentiel) {
                if($referentiel == 'bdtfx:v1.01') return Array(
                        'NORD' => 51.2, // Dunkerque
                        'SUD' => 41.3, // Bonifacio
                        'EST' => 9.7, // Corse
                        'OUEST' => -5.2); // Ouessan
                return FALSE;
        }

        // ces valeurs ne sont pas inséré via les placeholders du PDO::preparedStatement
        // et doivent donc être échappées correctement.
        public function initialiser_colonnes_statiques() {
                $this->colonnes_statiques = array_merge($this->colonnes_statiques,
                                                                                                Array(
                                                                                                        "ce_utilisateur" => $this->id_utilisateur,
                                                                                                        "prenom_utilisateur" => $this->quoteNonNull($this->utilisateur['prenom']),
                                                                                                        "nom_utilisateur" => $this->quoteNonNull($this->utilisateur['nom']),
                                                                                                        "courriel_utilisateur" => $this->quoteNonNull($this->utilisateur['courriel']),
                                                                                                ));

        }

        static function initialiser_pdo_ordered_statements($colonnes_statiques) {
                return Array(
                        // insert_ligne_pattern_ordre
                        sprintf('INSERT INTO cel_obs (%s, %s) VALUES',
                                        implode(', ', array_keys($colonnes_statiques)),
                                        implode(', ', array_diff(self::$ordre_BDD, array_keys($colonnes_statiques)))),

                        // insert_ligne_pattern_ordre
                        sprintf('(%s, %s ?)',
                                        implode(', ', $colonnes_statiques),
                                        str_repeat('?, ', count(self::$ordre_BDD) - count($colonnes_statiques) - 1))
                );
        }

        static function initialiser_pdo_statements($colonnes_statiques) {
                return Array( 
                        // insert_prefix
                        sprintf('INSERT INTO cel_obs (%s) VALUES ',
                                        implode(', ', self::$ordre_BDD)),


                        // insert_ligne_pattern, cf: self::$insert_ligne_pattern
                        '(' .
                        // 3) créé une chaîne de liste de champ à inséré en DB
                        implode(', ', array_values(
                                // 2) garde les valeurs fixes (de $colonnes_statiques),
                                // mais remplace les NULL par des "?"
                                array_map(function($item) { return is_null($item) ? '?' : $item; },
                                                  // 1) créé un tableau genre (nom_sel_nn => NULL) depuis self::$ordre_BDD
                                                  // et écrase certaines valeurs avec $colonnes_statiques (initilisé avec les données utilisateur)
                                                  array_merge(array_map(function() { return NULL; }, array_flip(self::$ordre_BDD)), $colonnes_statiques
                                )))) .
                        ')'
                );
        }

        // équivalent à CEL->Bdd->proteger() (qui wrap PDO::quote),
        // sans transformer NULL en ""
        private function quoteNonNull($chaine) {
                if(is_null($chaine)) return "NULL";
                if(!is_string($chaine)) die("erreur __FILE__, __LINE__");
                return $this->bdd->quote($chaine);
        }

        public function erreurs_stock($errno, $errstr) {
                $this->bilan[] = $errstr;
        }
}