// ------------------------------------------------------------------------- //
// Les Visiteurs - Statistiques de frquentation d'un site web               //
// ------------------------------------------------------------------------- //
// Visitors      - Web site statistics analysis program                      //
// ------------------------------------------------------------------------- //
// Copyright (C) 2000, 2001  J-Pierre DEZELUS <jpdezelus@phpinfo.net>        //
// ------------------------------------------------------------------------- //
//                   phpInfo.net <http://www.phpinfo.net/>                   //
// ------------------------------------------------------------------------- //
//  This program is free software; you can redistribute it and/or modify     //
//  it under the terms of the GNU General Public License as published by     //
//  the Free Software Foundation; either version 2 of the License, or        //
//  (at your option) any later version.                                      //
//                                                                           //
//  This program is distributed in the hope that it will be useful,          //
//  but WITHOUT ANY WARRANTY; without even the implied warranty of           //
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            //
//  GNU General Public License for more details.                             //
//                                                                           //
//  You should have received a copy of the GNU General Public License        //
//  along with this program; if not, write to the Free Software              //
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA //
// ------------------------------------------------------------------------- //
//                                INSTALLATION                               //
// ------------------------------------------------------------------------- //


INSTALLATION
------------
- Dcompressez l'archive dans un rpertoire de votre serveur Web en conservant
  l'arborescence des fichiers.

- S'il s'agit d'une premire installation, crez les 3 tables MySQL ncessaires
   l'application : visiteurs, archives et domaines_xx (o xx correspond au
  code de la langue souhaite pour les noms de domaines). Les requtes de
  cration des tables sont disponibles dans le rpertoire 'sql-tables' et
  portent l'extension '.sql'. Les fichiers domaines_xx crent tous une mme
  table 'domaine' (n'en excuter qu'un seul donc). Vous pouvez ventuellement
  changer les noms de ces 3 tables s'ils rentrent en conflit avec des tables
  dj existantes dans votre base (autres que celles d'une ancienne version des 
  Visiteurs bien sr), vous aurez la possibilit d'indiquer ces nouveaux noms
  dans le fichier de configuration.

    mysql --user=utilisateur --password=motdepasse nombase < archives.sql
    mysql --user=utilisateur --password=motdepasse nombase < visiteurs.sql
    mysql --user=utilisateur --password=motdepasse nombase < domaines_xx.sql

  Si vous ne disposez pas encore d'une base MySQL :

    mysqladmin --user utilisateur --password motdepasse create nombase

- Si vous utilisez PHP 4 ou si votre serveur Web est configur pour 'parser' les
  fichiers .php plutt que les .php3, changez l'extension des fichiers suivants :

    admin/ admin.php3             -> admin/admin.php
    include/ new-visitor.inc.php3 -> include/ new-visitor.inc.php
    include/ config.inc.php3      -> include/ config.inc.php
    index.php3                    -> index.php
    image-vis.php3                -> image-vis.php

  Attention, il est impratif de changer l'extension du fichier config.inc.php
  pour que celui-ci ne puisse pas tre tlcharg.

- Vous pouvez (devez ?), si vous le souhaitez, renommer les fichiers et
  rpertoires suivants (afin de garantir l'intgrit de votre installation) :
  
    Rp. admin/
    Rp. include/
    Rp. include/ modules/
    Rp. include/ caches/

    Fic. include/ new-visitor.inc.php3
    Fic. admin/ admin.php3

  Je vous conseille fortement de renommer au moins le fichier de configuration :
  -> config.inc.php3, pour les mmes raisons que prcdemment.

- Si vous changez le nom du rpertoire 'include' ou le nom du fichier de
  configuration 'config.inc.php3', ditez les fichiers suivants et mettez  jour
  les 2 variables $lvc_include_dir et $lvc_config_name.

    admin/ admin.php3
    include/ new-visitor.inc.php3
    index.php3
    image-vis.php3

- Donnez les droits d'criture dans le rpertoire cache (pour permettre la
  cration des diffrents fichiers de cache) :

    cd include
    chmod 707 caches

  Vous pouvez aussi votre logiciel de transfert FTP pour effectuer cette
  opration (bouton-droit / Proprits).


CONFIGURATION
-------------
Editez le fichier include/config.inc.php3.

- Choisissez le fichier des messages  utiliser, en fonction de votre langue :

  require($lvc_include_dir.'lang/xxxxx.inc.php');

- Choisissez le fichier d'abstraction de la base de donnes (MySQL, PostgreSQL,
  ...).

  require($lvc_include_dir.'db/db_mysql.inc.php');

- Entrez les paramtres de connexion au serveur de base de donnes (MySQL, ...)

    $lvc_db_host
    $lvc_db_user
    $lvc_db_password
    $lvc_db_database

- Si vous avez chang les noms des tables utilises par l'application, indiquez
  les dans les 3 variables :

    $lvc_table_visitors
    $lvc_table_archives
    $lvc_table_domains

- Donnez le nom du site (pour les graphes et les titres) et la date de dbut
  d'enregistrement des visiteurs avec l'application.

    $lvc_site_name
    $lvc_site_opening_year 
    $lvc_site_opening_month

- Indiquez le nouveau nom du rpertoire 'admin' et ventuellement ceux des 
  rpertoires 'include/caches' et 'include/modules' si vous les avez aussi
  renomms.

    $lvc_admin_dir
    $lvc_cache_dir
    $lvc_modules_dir

- Donnez le nouveau nom du fichier principal d'administration (admin.php3 du
  rpertoire admin).

    $lvc_admin_file

- Prcisez si vous souhaitez avoir un lien vers la console d'admin. sur l'cran
  principal des Visiteurs (attention, dans ce cas l il sera visible des
  internautes si vous n'avez pas protg l'accs  l'application).

    $lvc_view_admin_menus

- Vous pouvez placer un cookie sur votre propre machine pour qu'elle ne soit pas
  enregistre dans les stats. Cela peut s'avrer ncessaire si vous ne disposez
  pas d'une @IP fixe. Vous pouvez donner le nom que vous voulez au cookie (je
  vous conseille d'ailleurs de le changer).
  Pour l'initialiser sur votre machine, il suffit d'appeler dans votre navigateur
  la page o vous avez insr le script d'enregistrement des visiteurs (voir
  paragraphe suivant 'ENREGISTRER LES VISITEURS') :

      http://www.votresite.com/index.php3?ckVisiteurs=1

  Cela cre le cookie "ckVisiteurs"  1 sur votre machine. L'application ne vous
  enregistrera donc plus puisqu'elle trouvera maintenant le cookie. Pensez 
  changer le nom du cookie propos dans le fichier de configuration, pour que
  n'importe qui ne puisse pas aussi le mettre sur sa machine et ainsi ne plus
  tre enregsitr.

    $lvc_cookie_name

- Donnez la liste des 'sites rfrents' d'o peut provenir le visiteur et pour
  lesquels on ne l'enregistre pas (c'est gnralement l'adresse du site
  lui-mme), la liste des machines  ignorer (leurs @IP), et la liste des
  serveurs sur lesquels il ne faut rien enregistrer (machines de tests).

    $lvc_ignore_referer[]
    $lvc_ignore_machines[]
    $lvc_ignore_servers[]

- Indiquez le nombre de visiteurs devant tre enregistrs avant qu'un mme
  visiteur soit de nouveau enregistr.

    $lvc_between_2_visits

- Il est possible de tronquer  n caractres les agents non reconnus avant
  enregistrement.

    $lvc_agent_max_length

- Lorsque le serveur de base de donnes est down, les requtes SQL sont
  enregistres dans un fichier de log.

    $lvc_log_file

- Vous pouvez dfinir la dure de vie des diffrents modules de cache avant
  rgnration :

    $lvc_default_cache_delay
    $lvc_delay_archive_month
    $lvc_delay_calendar
    ...

- Et si vous souhaitez voir apparatre les dures des caches et quand ils ont
  t rgnrs.

    $lvc_display_cache_delay

- Choisissez le format des images gnres. Il dpend de la configuration de PHP
  sur votre serveur et de la version de GD utilise (faire un phpinfo() pour 
  avoir plus d'infos sur l'extension GD).

    $lvc_images_format

- Pour les histogrammes, donnez les chelles de base (fonction de la frquenta-
  tion de votre site).

    $lvc_base_img_last_months
    $lvc_base_img_day_per_hour
    $lvc_base_img_per_hour
    ...

- Indiquez les noms des fichiers motifs utiliss pour les histogrammes (nom sans
  l'extension qui est obtenue par $lvc_images_format).

    $lvc_pattern_last_months
    $lvc_pattern_day_per_hour
    $lvc_pattern_per_hour
    $lvc_pattern_per_day

- Modifiez ventuellement les couleurs des graphes.

    $lvc_color_bg_out
    $lvc_color_bg_in
    $lvc_color_maxvalue
    ...

- Donnez le nombre de lignes de donnes  afficher par type de tableau.

    $lvc_nb_last_visitors
    $lvc_nb_last_months
    $lvc_nb_months_calendar
    ...

- Indiquez si vous souhaitez masquer ou non une partie des @IP et des hostnames
  de vos visiteurs. Il est prfrable de laisser cette valeur  true.

    $lvc_hide_IP

- Vous pouvez compltez ou modifier la liste des moteurs de recherche ou
  annuaires qui rfrencent votre site. Ils sont dfinis dans le fichier :
  
    include/ engines-list.ini
  
  Dans le cas d'un moteur de recherche, indiquez son nom entre crochets, le mot
  cl utilis sur l'url suivi du signe =, puis les diffrents domaines concerns.
  Exemple :

    [AltaVista]
    q=
    www.altavista.com
    www.altavista.fr
    fr.altavista.com

  Pour les annuaires, indiquez le nom entre crochets, 'directory' sur la ligne
  suivante (sans signe =), puis les domaines. Exemple :
    
    [Yahoo !]
    directory
    fr.dir.yahoo.com


ENREGISTRER LES VISITEURS
-------------------------
Sur chaque page d'entre de votre site Web o vous souhaitez enregistrer vos
visiteurs placez le code suivant :

    $lvc_include_dir = 'path_to/include-dir/';
    include($lvc_include_dir.'new-visitor.inc.php3');

$lvc_include_dir indique le chemin vers le rpertoire 'include' de l'application
Les Visiteurs  partir du fichier appelant le script 'new-visitor.inc.php3'.
Si vous avez install Les Visiteurs  la racine de votre site, dans le rpertoire
'apps/visiteurs', et si vous souhaitez enregistrer les visiteurs  partir de la
page d'accueil index.php3 qui se trouve  la racine, placez en tte du script :

    $lvc_include_dir = 'apps/visiteurs/include/';
    include($lvc_include_dir.'new-visitor.inc.php3');

Attention  bien renseigner la variable '$lvc_include_dir' puisqu'elle est
ensuite utilise par 'new-visitor.inc.php3' pour charger le fichier de
configuration.


CONSULTER LES STATISTIQUES
--------------------------
La consultation des statistiques se fait en appelant la page index.php3 du 
rpertoire d'installation des Visiteurs, ou directement ce rpertoire.

  http://www.votresite.com/apps/mes-visiteurs/

Vous disposez ensuite d'une interface de navigation pour consulter les
diffrentes statistiques ou pour accder au module d'administration si vous
avez configur l'application pour le faire (variable $lvc_view_admin_menus 
true).


PERSONNALISER LES VISITEURS
---------------------------
Vous disposez de diffrents moyens pour personnaliser l'application.

  - config.inc.php3 : le fichier de configuration principal

  - css/visiteurs.css : la feuille de style CSS

  - view-user.inc.php : la vue USER explique dans le paragraphe suivant

  - footer|header.inc.php : l'en-tte et le pied de page des diffrentes pages.
    il contient aujourd'hui le logo de phpInfo.net et l'lPHPant mais vous
    pouvez bien-sr les retirer et y placer votre propre bandeau.


LA VUE 'USER'
-------------
Cette vue vous permet de constituer votre propre page de statistiques  partir
des diffrents modules disponibles dans les autres vues (DAY, MONTH, YEAR).
Pour cela il suffit d'ajouter les appels aux diffrents modules dans le fichier
view-user.inc.php. Exemple :

  echo '<A NAME="calendar"></A>';
  echo insert_cached_module('<mod-calendar cache='.$lvc_delay_calendar.'>');

Puis de placer un lien vers ce module dans le menu USER en modifiant le fichier
menu-user.inc.php. Exemple :

  echo link_module('#calendar', $lvm_calendar, ICON_ARRAY);

  1er  par. : nom de la balise (dfini dans view-user.inc.php).
  2me par. : titre du lien
  3me par. : type d'icne (ICON_GRAPH, ICON_ARRAY, ICON_MIXED, ICON_PUCE)


ADMINISTRER L'APPLICATION
-------------------------
*******************************************************************************
  ATTENTION !
  Les scripts du module d'administration utilisent JavaScript / JScript.
*******************************************************************************

Deux modules vous sont proposs, l'un pour supprimer les fichiers de cache
gnrs par l'application, l'autre pour crer les archives des mois couls (qui
rendent l'affichage des statistiques beaucoup plus rapide).

o ARCHIVAGE :
  -----------
  L'archivage n'est pas automatique, il se dclenche manuellement via la console
  d'administration en dbut de chaque mois (archivage du mois pass).
  
  Pour archiver un mois, suivre les tapes suivantes :

    - Slectionnez le mois et l'anne  archiver puis vrifiez que l'archive
      n'existe pas dj.

    - Slectionnez l'option 'Archiver' pour crer une nouvelle entre dans la
      table 'archives' qui contiendra un rsum des stats pour le mois choisi.

    - Slectionnez ensuite l'option 'Exporter' pour rcuprer le dump SQL du 
      mois archiv (un fichier texte est tlcharg, il contient tous les
      enregistrements de la table 'visiteurs' pour le mois choisi).

    - Enfin, aprs vous tre assur que l'archive existe, slectionnez l'option
      'Purger' pour supprimer dfinitivement les enregistrements de la table
      'visiteurs' (Cette dernire option n'est pas obligatoire, elle permet
      simplement d'allger la taille de la base). Dans l'affichage des stats
      d'un mois donn, si un archivage est trouv dans la base, c'est lui qui
      est utilis et pas les ventuels enregistrements de la table visiteurs.
      C'est pourquoi ils ne sont plus ncessaires aprs un archivage.

  A chaque tape vous devez fournir le mot de passe d'accs  votre base. Il 
  doit tre le mme que celui donn dans votre fichier de configuration.

o CACHE :
  -------
  Vous avez aussi la possibilit de supprimer les fichiers de cache sur le
  disque afin de forcer leur rgnration (aprs archivage par exemple).


PROTEGER LES SCRIPTS
--------------------
- La 1re protection consiste  renommer les rpertoires et fichiers indiqus
  dans la procdure d'installation.

- Changez l'extension du fichier de configuration en fonction de votre version
  de PHP pour qu'il ne soit pas tlcharg, surtout si vous n'avez pas renomm
  les rpertoires.

- Placez des fichiers .htaccess (ou quivalent suivant votre serveur Web) dans
  les rpertoires 'include' et 'admin' pour en  interdire l'accs.


REMARQUES DIVERSES
------------------
- Les utilisateurs des version 1.3x doivent crer la table 'archives' qui
  n'existait pas dans cette version.

- Vous pouvez modifier les couleurs des pages de statistiques en modifiant la
  feuille de style CSS css/visitors.css. Une variable dans le fichier de
  configuration permet de dfinir un autre fichier  utiliser.

    $lvc_css_file