// ------------------------------------------------------------------------- //
// Les Visiteurs - Statistiques de fréquentation 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
------------
- Décompressez l'archive dans un répertoire de votre serveur Web en conservant
  l'arborescence des fichiers.

- S'il s'agit d'une première installation, créez les 3 tables MySQL nécessaires
  à l'application : visiteurs, archives et domaines_xx (où xx correspond au
  code de la langue souhaitée pour les noms de domaines). Les requêtes de
  création des tables sont disponibles dans le répertoire 'sql-tables' et
  portent l'extension '.sql'. Les fichiers domaines_xx créent tous une même
  table 'domaine' (n'en exécuter qu'un seul donc). Vous pouvez éventuellement
  changer les noms de ces 3 tables s'ils rentrent en conflit avec des tables
  déjà existantes dans votre base (autres que celles d'une ancienne version des 
  Visiteurs bien sûr), 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 plutôt 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 impératif de changer l'extension du fichier config.inc.php
  pour que celui-ci ne puisse pas être téléchargé.

- Vous pouvez (devez ?), si vous le souhaitez, renommer les fichiers et
  répertoires suivants (afin de garantir l'intégrité de votre installation) :
  
    Rép. admin/
    Rép. include/
    Rép. include/ modules/
    Rép. 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 mêmes raisons que précédemment.

- Si vous changez le nom du répertoire '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 répertoire cache (pour permettre la
  création des différents fichiers de cache) :

    cd include
    chmod 707 caches

  Vous pouvez aussi votre logiciel de transfert FTP pour effectuer cette
  opération (bouton-droit / Propriétés).


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 données (MySQL, PostgreSQL,
  ...).

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

- Entrez les paramètres de connexion au serveur de base de données (MySQL, ...)

    $lvc_db_host
    $lvc_db_user
    $lvc_db_password
    $lvc_db_database

- Si vous avez changé les noms des tables utilisées 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 début
  d'enregistrement des visiteurs avec l'application.

    $lvc_site_name
    $lvc_site_opening_year 
    $lvc_site_opening_month

- Indiquez le nouveau nom du répertoire 'admin' et éventuellement ceux des 
  répertoires 'include/caches' et 'include/modules' si vous les avez aussi
  renommés.

    $lvc_admin_dir
    $lvc_cache_dir
    $lvc_modules_dir

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

    $lvc_admin_file

- Précisez 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 protégé l'accès à l'application).

    $lvc_view_admin_menus

- Vous pouvez placer un cookie sur votre propre machine pour qu'elle ne soit pas
  enregistrée dans les stats. Cela peut s'avérer nécessaire 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 inséré le script d'enregistrement des visiteurs (voir
  paragraphe suivant 'ENREGISTRER LES VISITEURS') :

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

  Cela crée 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 référents' d'où peut provenir le visiteur et pour
  lesquels on ne l'enregistre pas (c'est généralement l'adresse du site
  lui-même), 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 enregistrés avant qu'un même
  visiteur soit de nouveau enregistré.

    $lvc_between_2_visits

- Il est possible de tronquer à n caractères les agents non reconnus avant
  enregistrement.

    $lvc_agent_max_length

- Lorsque le serveur de base de données est down, les requêtes SQL sont
  enregistrées dans un fichier de log.

    $lvc_log_file

- Vous pouvez définir la durée de vie des différents modules de cache avant
  régénération :

    $lvc_default_cache_delay
    $lvc_delay_archive_month
    $lvc_delay_calendar
    ...

- Et si vous souhaitez voir apparaître les durées des caches et quand ils ont
  été régénérés.

    $lvc_display_cache_delay

- Choisissez le format des images générées. Il dépend de la configuration de PHP
  sur votre serveur et de la version de GD utilisée (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 fréquenta-
  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 utilisés 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 données à 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 préférable de laisser cette valeur à true.

    $lvc_hide_IP

- Vous pouvez complétez ou modifier la liste des moteurs de recherche ou
  annuaires qui référencent votre site. Ils sont définis 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 différents domaines concernés.
  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'entrée 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 répertoire '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 répertoire
'apps/visiteurs', et si vous souhaitez enregistrer les visiteurs à partir de la
page d'accueil index.php3 qui se trouve à la racine, placez en tête 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 utilisée 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 
répertoire d'installation des Visiteurs, ou directement ce répertoire.

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

Vous disposez ensuite d'une interface de navigation pour consulter les
différentes statistiques ou pour accéder 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 différents 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 expliquée dans le paragraphe suivant

  - footer|header.inc.php : l'en-tête et le pied de page des différentes pages.
    il contient aujourd'hui le logo de phpInfo.net et l'éléPHPant mais vous
    pouvez bien-sûr les retirer et y placer votre propre bandeau.


LA VUE 'USER'
-------------
Cette vue vous permet de constituer votre propre page de statistiques à partir
des différents modules disponibles dans les autres vues (DAY, MONTH, YEAR).
Pour cela il suffit d'ajouter les appels aux différents 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 (défini dans view-user.inc.php).
  2ème par. : titre du lien
  3ème par. : type d'icône (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 proposés, l'un pour supprimer les fichiers de cache
générés par l'application, l'autre pour créer les archives des mois écoulés (qui
rendent l'affichage des statistiques beaucoup plus rapide).

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

    - Sélectionnez le mois et l'année à archiver puis vérifiez que l'archive
      n'existe pas déjà.

    - Sélectionnez l'option 'Archiver' pour créer une nouvelle entrée dans la
      table 'archives' qui contiendra un résumé des stats pour le mois choisi.

    - Sélectionnez ensuite l'option 'Exporter' pour récupérer le dump SQL du 
      mois archivé (un fichier texte est téléchargé, il contient tous les
      enregistrements de la table 'visiteurs' pour le mois choisi).

    - Enfin, après vous être assuré que l'archive existe, sélectionnez l'option
      'Purger' pour supprimer définitivement les enregistrements de la table
      'visiteurs' (Cette dernière option n'est pas obligatoire, elle permet
      simplement d'alléger 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 nécessaires après un archivage.

  A chaque étape vous devez fournir le mot de passe d'accès à votre base. Il 
  doit être le même 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 régénération (après archivage par exemple).


PROTEGER LES SCRIPTS
--------------------
- La 1ère protection consiste à renommer les répertoires et fichiers indiqués
  dans la procédure d'installation.

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

- Placez des fichiers .htaccess (ou équivalent suivant votre serveur Web) dans
  les répertoires 'include' et 'admin' pour en  interdire l'accès.


REMARQUES DIVERSES
------------------
- Les utilisateurs des version 1.3x doivent créer 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 définir un autre fichier à utiliser.

    $lvc_css_file