Count-Clever V1.2 - Dokumentation

(c) 2004-2006 Carsten Meier

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Inhaltsverzeichnis

1. Einleitung
2. Installation
   1. Einbinden des einfachen Counters über SSI
   2. Einbinden des Counters mit mehreren Zählkategorien über SSI
   3. Einbinden des Counters über PHP
   4. Setzen des Zählerstands
3. Anpassen des Aussehens
4. Bibliotheksfunktionen
5. Kontakt

1 Einleitung

Count-Clever ist ein PHP geschriebener Webcounter, der zusätzlich die Anzahl der Besucher ausgibt, die sich zur Zeit auf Ihrer Website aufhalten. Außerdem können Zähler für beliebige Kategorien angelegt und gleichzeitig angezeigt werden. Das Aussehen wird über Templates festgelegt und läßt sich daher leicht an eigene Bedürfnisse anpassen.

Merkmale

• Gibt die Anzahl der Besuche und die Anzahl der Besucher die gleichzeitig online sind aus. Der Zählerstand wird durch weitere Zugriffe eines Besuchers der als online gilt nicht erhöht.
• Mehrere Zählkategorien
• Aussehen ist über Templates frei bestimmbar
• Graphische oder textuelle Ausgabe
• Klare Trennung von Zähler- und Ausgabe-Code
• Effiziente Speicherung in einem binären Format, eine externe Datenbank wird nicht benötigt
• Die Synchronisierung kann wahlweise über File-Locking oder Semaphoren erfolgen. Dadurch wird die evtl. Zerstörung der Counter-Datenbank-Datei bei mehreren konkurrierenden Zugriffen verhindert.

Das Archiv enthält folgende Dateien:

count-clever.php

Counter-Bibliothek

counterdb

Initialisierte Counter-Datenbank-Datei als Vorlage für neue Counter

counter.php

Konfigurierbares Beispiel-Skript, welches die Benutzung des Counters demonstriert

multicounter.php

Beispiel-Skript, welches die Benutzung mehrerer Zählerkategorien demonstriert

init-counter.php

Beispiel-Skript, das eine Counter-Datenbank-Datei mit einem gegebenen Wert initialisiert

counter-digits/

Enthält gif-Bilder für die graphische Ausgabe

LICENSE

Eine Kopie der GNU Lesser General Public License V2.1, unter der dieses Skript lizensiert ist

LIESMICH.html

Die Datei, die Sie gerade lesen

Bei der vorliegenden Fassung handelt es sich um Version 1.2 vom 14.5.2006. Die jeweils aktuelle Version können Sie auf der Count-Clever-Homepage herunterladen. Es wird PHP >= 4.1.0 benötigt. Das Skript wurde unter PHP 4.3.3 und PHP 4.3.10 mit den Laufzeit-Optionen register_globals off und allow_call_time_pass_reference off getestet.

2 Installation

Kopieren Sie die Bibliotheksdatei 'count-clever.php' in ein Verzeichnis innerhalb Ihres PHP-Include-Pfades. Falls das File-Locking auf Ihrem System nicht richtig funktioniert, ändern Sie bitte zuvor die Zeile 53 von

define('COUNTCLEVER_GUARD', COUNTCLEVER_GUARD_FILE_LOCKING);

auf

define('COUNTCLEVER_GUARD', COUNTCLEVER_GUARD_SEMAPHORE);

ab. Dies ist nötig, wenn der Webserver mit einer Multithreaded-API arbeitet, auf den meisten Linux-PHP-Installationen dürfte dieser Schritt jedoch nicht notwendig sein. Details dazu entnehmen Sie bitte der PHP-Dokumentation zu flock().

Danach legen Sie bitte die Datei 'counterdb' an einer beliebigen Stelle des Dateisystems ab. Diese enthält den Zählerstand und muß anschließend noch via chmod 0666 counterdb für den Webserver beschreibbar gemacht werden.

Die folgenden Dateien werden nach einer weiter unten beschriebener Anpassung unterhalb des Document-Root-Verzeichnisses erwartet:

counter-digits/*

werden für die graphische Ausgabe benötigt

counter.php

wird für den einfachen Counter benötigt

multicounter.php

wird bei mehreren Zählerkategorien benötigt

init-counter.php

wird zum Setzen eines Zählerstands benutzt

Alternativ können Sie auch alle Dateien in einem entsprechenden Verzeichnis unterhalb von Document-Root ablegen.

2.1 Einbinden des einfachen Counters über SSI

Passen Sie den Pfad zu Ihrer 'counterdb'-Datei in der Variablen $counterdb_filename der Datei 'counter.php' entsprechend an. Nun müssen Sie noch folgendes SSI-Statement an der Stelle in Ihre .shtml-Datei einfügen, an der der Counter erscheinen soll:

<!--#include virtual="counter.php" -->

2.2 Einbinden des Counters mit mehreren Zählkategorien über SSI

Erzeugen Sie für jede Zählerkategorie eine eigene Counter-Datenbank-Datei durch Kopieren und Umbenennen der Datei 'counterdb', und machen Sie diese wie oben angegeben beschreibbar. Nun verändern Sie die Datei 'multicounter.php' bitte folgendermaßen:

• Setzen Sie den Pfad zu Ihren Counter-Datenbankdateien in der Variablen $counterdb_prefix. (Abschließenden / nicht vergessen!)
• Geben Sie in dem Array $counters jeweils den Namen der Counter-Datenbank-Datei als Schlüssel und den dazu darzustellenden Titel als Wert an.

Fügen Sie bitte jetzt noch folgendes SSI-Statement in Ihre .shtml-Datei ein. Ersetzen Sie dabei COUNTER durch die für diese Seite zu benutzende Counter-Datenbank-Datei (ohne Pfad!).

<!--#include virtual="multicounter.php?counter=COUNTER" -->

Der erste Eintrag im $counters-Array wird als Master-Counter angesehen und unabhängig vom übergebenen Counter immer hochgezählt.

2.3 Einbinden des Counters über PHP

Passen Sie die Datei 'counter.php' bzw. 'multicounter.php' wie oben beschrieben an. In der Datei 'multicounter.php' ersetzen Sie bitte noch die Variable $_GET['counter'] (in Zeile 35) durch $counter. Nun können Sie den Counter mit folgenden include-Statements einbinden:

include 'counter.php';

bzw.

$counter = 'COUNTER';
include 'multicounter.php';

Wenn Sie die Ausgabe selbst erledigen möchten, verfahren Sie bitte wie im Abschnitt Bibliotheksfunktionen beschrieben.

2.4 Setzen des Zählerstands

Setzen Sie in dem Skript 'init-counter.php' die Variablen $counterdb_filename auf den zu setzenden Zähler, sowie $initial_counter_value auf den gewünschten Zählerstand. Rufen Sie nun das Skript in Ihrem Webbrowser auf. Sie sollten das Skript nach Gebrauch wieder löschen oder es in einem geschützten Bereich speichern, da ansonsten jeder durch einen Aufruf der URL den Zählerstand zurücksetzen kann!

3 Anpassen des Aussehens

Das Aussehen des Counters wird durch Templates festgelegt, welche als Arrays angelegt sind. In der Datei 'counter.php' ist ein Template für den einfachen Counter definiert. Es ist in der Variablen $counter_template abgelegt und enthält die folgende Elemente:

'format'

sprintf-Format-String mit %1$s für die Besucheranzahl und %2$s für die Online-Anzeige

'visits_format'

sprintf-Format-String für die Besucheranzahl

'online_format'

sprintf-Format-String für die Onlineanzeige

'gfx'

Array mit Infos zu den graphischen Ziffern in den folgenden Elementen:

'prefix'

Prefix für den Ziffer-Dateinamen

'suffix'

Suffix für den Ziffer-Dateinamen

'attrib'

Zusätzliche Attribute für das <IMG>-Element, z.B. Breiten- und Höhenangaben.

Ist 'gfx' nicht gesetzt, werden den Ziffern textuell ausgegeben. Das $multicounter_template in der Datei 'multicounter.php' enthält folgende zusätzliche Elemente:

'prefix'

wird vor dem Counter ausgegeben (z.B. <table>)

'postfix'

wird nach dem Counter ausgegeben (z.B. </table>)

'format'

sprintf-Format-String der für jede Kategorie ausgegeben wird. %1$s für die Besucheranzahl, %2$s für die Online-Anzeige, %3$s für den Namen der Kategorie

Die einzelnen Elemente können Sie nach eigenen Bedürfnissen abändern. Details zu sprintf-Format-Strings finden Sie in der PHP-Dokumentation.

4 Bibliotheksfunktionen

In der Datei 'count-clever.php' werden die folgenden Funktionen zur Verarbeitung von Counter-Datenbank-Dateien definiert:

boolean countclever_init_counter(string counterdbname, integer initial_counter_value)

Initialisiert die Counter-Datenbank-Datei mit dem gegebenem Wert. Gibt bei Erfolg true, im Fehlerfall false zurück.

mixed countclever_get_counter_values(string counterdbname)

Gibt die Werte der angegebenen Counter-Datei in einem Array mit den folgenden Schlüsseln zurück: 'signature', 'visitshi' und 'visits'. Im Fehlerfall wird false geliefert.

mixed countclever_process_counter(string counterdbname, integer entrylivetimeinsecs, boolean isvisit)

Diese Funktion implementiert den eigentlichen Besucherzähler und gibt bei Erfolg ein Array mit den folgenden Elementen zurück:

'visits'

Der aktuelle Zählerstand

'online'

Die Anzahl der Besucher die zur Zeit online sind

'entry_found'

Wahrheitswert, der angibt, ob die IP-Adresse bereits in der Online-Liste vorhanden ist. Dadurch kann der Counter beispielsweise auch benutzt werden, um Funktionen für eine bestimmte Zeitdauer zu blockieren.

entrylivetimeinsecs gibt an, wie lange ein Besucher als online gilt; isvisit, ob der Aufruf als Besuch gewertet werden soll.

Um Besuche nach Kategorien getrennt auszuwerten, wird für jede Kategorie eine eigene Counter-Datenbank-Datei angelegt und countclever_process_counter() darauf ausgeführt. Für die aktuelle Kategorie wird dabei isvisit auf true gesetzt. Die Daten der andenen Kategorien können durch entsprechende Aufrufe von countclever_process_counter() mit isvisit = false in Erfahrung gebracht werden.

Ausgabefunktionen

Neben der Verarbeitung der Counter-Dateien werden die Zählerwerte von diesen Funktionen zusätzlich formatiert und als druckbarer String zurückgegeben. Es werden dabei zu den oben beschriebenen Parametern weitere, wie z.B. ein Template, angegeben.

string countclever_get_counter(string counterdbname, integer entrylivetimeinsecs, boolean isvisit, array template)

Ruft die Funktion countclever_process_counter() auf und liefert einen, mit Hilfe des Templates formatierten, String.

string countclever_get_multi_counter(string counterdbprefix, array counters, integer entrylivetimeinsecs, string currentcounterkey, array template)

Gibt einen kompletten Counter mit mehreren Zählerkategorien als String zurück.

Zusätzlich sind noch die Funktionen countclever_print_counter() und countclever_print_multi_counter() enthalten, die den Counter via print direkt ausgeben.

Kompatibilitätsfunktionen

Zur Kompatibilität mit Vorgängerversionen sind die Funktionen init_counter(), get_counter() und process_counter() enthalten. Diese sollten nicht mehr benutzt werden, und können, falls es zu Namenskollisionen kommen sollte, gelöscht werden.

5 Kontakt

Aktuelle Informationen finden Sie auf der Count-Clever-Homepage. Wenn Sie Fragen zu dem Skript stellen, oder einen Kommentar abgeben möchten, können Sie dies im Count-Clever-Forum tun. Bitte geben Sie bei Problemen immer die verwendeten PHP- und Skript-Versionen an!

Unterstützen Sie die Entwicklung weiterer, frei verfügbarer Skripte durch das Setzen eines Links zu www.internalscripts.de. Vielen Dank!

Anschrift des Autors

Fragen zur Benutzung des Skripts bitte im Forum stellen!