PowerPhlogger documentation

complete counter hosting tool

PowerPhlogger 2.2.5
Copyright (c) 2000-2004 Philip Iezzi, phpee.com
Documentation version: $Id: doc.html 2608 2004-04-20 20:25:48Z cvs_iezzi $

This is no complete documentation of the features and functionality of PowerPhlogger. It just covers parts of it and is always getting updated. If you wish to add a section or complete an incomplete section, you're welcome to take part of this documentation. Just send me your changes and I'm going to include them in this file.

Local documents: CHANGELOG | README | LICENSE


Requirements


Installation

Warning for Mac users: php seems not to like Mac end of lines character ("\r") and Stuffit unstuffs with Mac formats, of course.
So you'll have to resave as in Bbedit to unix style ALL PowerPhlogger scripts before uploading them to your server.

Quick Install:

  1. Untar or unzip the distribution (be sure to unzip the subdirectories): tar xzvf pphlogger-x.x.x.tar.gz
  2. Open the file config.inc.php in your favourite editor and change the values for host, user, password, and database to fit your environment.
  3. It is recommended that you protect the /admin/ directory (unless it's on a closed intranet), for example with HTTP-AUTH (in a .htaccess file).
  4. Open the file <www.your-host.com>/<your-install-dir>/admin/setup.php in your browser. PowerPhlogger now loads the default configuration. Check the default configuration values and click 'next'. Go through the whole setup procedure till you get to the admin-area.
  5. Start setting up new useraccounts in the admin area. Your users will get notified automatically as soon as you create a new account.

Upgrading from an older version:
It is strongly recommended that you follow exact upgrade instructions! Please always refer to the current instructions on www.phpee.com/upgrade.php.
Usually, you can stick to the following scheme, though:


PPhlogger HTML Code

PowerPhlogger gives you the possibility to track your entire Web Site. The PPhlogger HTML code is able to automatically detect the name(s) and the Url(s) of your pages.
You need to upload the pphlogger.js file to your server and place the PPhlogger HTML code into all your Web site Pages. Both, you can find in your confirmation email or - if you have lost that - when you enter your useraccount, in the "settings" area.

Standard Implementation

Here's the code you should enter in your pages:

 <script language="JavaScript" type="text/javascript" src="pphlogger.js"></script>
<noscript><img alt="" src="http://www.your_domain.com/pphlogger/pphlogger.php?id=your_username&st=img"></noscript>

Make sure src="pphlogger.js" is refering to the correct location where you have placed your pphlogger.js. If you're not able to use a relative path, use an absolute path like src="http://www.your_domain.com/somewhere/pphlogger.js" , this works the same.
For visibility options, please check the visibility section.

Special Implementation (PHP)

WARNING: All PowerPhlogger-users should use the standard implementation described above!
The following special implementation is only for PPhlogger-admins who run their site on the same server where the PPhlogger installation is located. Other users that are not on the same server are not able to take advantage of this special implementation at all!
Actually, I do not recommend to use this method as it hasn't been tested yet.

The main advantage by calling PowerPhlogger directly from PHP is, that PPhlogger like this tracks every visitor, even search-bots that don't call up any JavaScript or images on your site.
There are two ways of calling PPhlogger directly from PHP:

PHP only

Use this implementation if you would like to completely hide your counter. No code at all will be visible on your site and you will be able to track anyone entering your site.
Place the following code at the top of your page:

<?php
$id = "username";
define('PPHL_SCRIPT_PATH', '/home/your_domain/htdocs/pphlogger/'); // relative (e.g. "pphlogger/") or absolute path to your PP-directory
$st = 'php';
include(PPHL_SCRIPT_PATH."pphlogger.php");
?>

Please make sure, the code is definitely placed at the top of your script/page! As PowerPhlogger sets cookies each time a visitor enters or reloads your pages, it's not possible to call pphlogger.php after some other output.
If you do not place this code correctly, you would get the following error (unless you set an output_buffering value in your php.ini):
Warning: Cannot add header information - headers already sent by ...
There is another disadvantage: By calling pphlogger.php through PHP you won't be able to track the visitor's screen resolution and color depth. Instead of those values, you'll just find a zero-value in your logs. If you're worried about that, read the next section and try to use the PHP&JS combination.

PHP&JS combination

Since PPhlogger 2.2.2 I've added this new way of calling PPhlogger. This is the better solution the the PHP-only implementation.
That's how it works: You call pphlogger.php directly in PHP. The visitor get's logged and pphlogger.php returns some JS-Code. This JS-Code calls up pphlogger.php again (from client-side) in order to provide PPhlogger with the missing variables that were not able to get directly in PHP.
Like this you will take advantage of the direct PHP logging and still will not miss any data like the visitor's screen resolution and color depth.

Use the following code and make sure this gets executed somewhere between the <body></body> tags:

<?php
$id = "username";
define('PPHL_SCRIPT_PATH', '/home/your_domain/htdocs/pphlogger/'); // relative (e.g. "pphlogger/") or absolute path to your PP-directory
$st = 'phpjs'; // $showme = 'y';
include(PPHL_SCRIPT_PATH."pphlogger.php");
?>

This is the ideal solution for webmasters who run PPhlogger on the same server where they run their site(s). Actually this consumes a little bit more capacity but that's no big deal (All other useraccounts are only able to call PPhlogger by IMG/JS).

To make your counter visible (text-output), uncomment $showme = 'y';


Visibility

PowerPhlogger is able to make the counter visible on each user's site. Users are not required to run PHP on their server. There are other possibilities to make your counter visible. Since version 2.1.4 PowerPhlogger supports even text-output - it's each user's own choice how to display their counter.
It's pretty hard to figure out how to do this correctly, so please read this documentation.

[1] userprofile settings

When you log into your account, you'll find a tab 'userprofile'. That's the place where you can change all basic settings of your account.
You'll find a checkbox 'visible'. This is the global switch for all counter images/text on your whole site. If you uncheck this, you won't be able to make your counter visible at any place. Default is checked and most of you probably better keep it checked.
Below you'll find a pulldown-menu that contains TrueType-fonts. These fonts are used for your counter image creation. Other counter scripts often use premade images and you only got a choice between a limited number of styles. - Not in PowerPhlogger! In PowerPhlogger you can choose your own TrueType fonts for your counter image. If you can't find a suitable font just upload new ones into your ttf_fonts/ directory.
below you'll find two color-palettes. The first one sets the foreground color, the color of the letters. The second one sets the background-color. If you check the 'transparent background'-checkbox, your background color will be transparent.Still you should set a matching background-color to make your counter image look smoothly.
On the left side of the color-palettes you'll find an input-field that accepts all three kind of color-notations:

plain-text:   blue
RGB:          00+00+255
Hexadecimal:  #0000FF

Don't forget the insert the '+' if you use RGB format and don't forget to enter '#' before a hexadecimal string.
By clicking on 'Save configuration' your result will be displayed on the bottom (sample image).

[2] pphlogger.js - visitor tracking

In order to track your visitors, you need to upload pphlogger.js to your server. This file transfers all the visitor's data to PowerPhlogger which could be located on another machine that supports PHP. I'm not going to explain how exactly this file acts but I want to make clear how to use it to make your counter visible.
Default is set to invisible. No matter if you checked 'visible' in your userprofile or not!
The checkbox 'visible' in your userprofile is just kind of a global switch that turns off all visibility. The visibility still has to be set on each page where you want it to show up!
We're going to use the following two variables: showme = 'y|n' and st = 'js|img'.
st stands for "show-type" and specifies the way how your visitors should get tracked. showme is the local switch for visibility.

valid values for the st variable:

st='js'      for text output (DEFAULT)
st='img'     for image output

If you wish to make your counter visible, you need to set showme = 'y'

showme='n'   invisible (DEFAULT)
showme='y'   visible

Ok, basically your PowerPhlogger code that you insert on each page, looks like this:

 <script language="JavaScript" type="text/javascript" src="pphlogger.js"></script>
<noscript><img alt="" src="http://www.your_domain.com/pphlogger/pphlogger.php?id=your_username&st=img"></noscript>

As default is showme = 'n' and st = 'js', your counter would be completely invisible. In order to change mode insert another line before those two lines:

 <script>showme='y'; st='js'</script>
 <script language="JavaScript" type="text/javascript" src="pphlogger.js"></script>
<noscript><img alt="" src="http://www.your_domain.com/pphlogger/pphlogger.php?id=your_username&st=img"></noscript>

This example would make your counter visible and show it as text. Same thing with image-output, just change the st variable to 'img' - then you'll be able to see the nice image you have created in you userprofile.
I do not recommend to use the combination st='y'; showme='n' as this would output a 1x1 pixel image. It's cleaner to handle invisibility through the 'js'-output = empty string!

[3] showhits.php

Above you found a description of how to make the counter visible on your page. Let's say you put the PowerPhlogger-code in the footer of your pages and you wish to display it somewhere else on your page... or let's say you would like to show the number of people currently online or the number of hits of the current day.
showhits.php can do a lot!
Its purpose is just to display different information and not to track visitors. showhits.php will not alter anything in your database.
There are 3 different ways to display showhits.php:

st='js'      for text output (DEFAULT)
st='php'     for text output (if PowerPhlogger is located on the same server)
st='img'     for image output

The appropriate usage for those 3 modes are:

The variable showme has no meaning in showhits.php - it is always set to 'y'. If you would not like to make it visible, you wouldn't call this script, right?! This script is only meant to display stuff, that's why it is always visible.

There's a couple of more things that showhits.php can display. It can output today's hits, today's pageimpressions, this month's hits/pageimpressions, current online users, amount of customers, total pageimpressions, download hits etc.
For, you just need to add another variable the code that has been described above: type

----------------------------------------------------------------------------
 type=   hits | pageviews | today | todayviews | yesterday | yesterdayhits |
         month | monthviews | onlineusr | customers | mpdl
 mpdl=   /your_url


         description:
         hits:           shows total hits (default)
         pageviews:      shows total pageimpressions
         today:          shows today's hits
         todayviews:     shows today's pageimpressions
         yesterday:      shows yesterday's hits
         yesterdayviews: shows yesterday's pageimpressions
         month:          shows current month's hits
         monthviews:     shows current month's pageimpressions
         onlineusr:      shows current online users
         customers:      shows amount of activated useraccounts
----------------------------------------------------------------------------

Let's make an example: You wish to display the current online users as text in your page:

Now, lets say you wish to display how many times /files/myfile.zip got downloaded. You wish to display this as an image (sure, you can display it also as txt using Javascript or PHP !):

 

Ok, I hope that was clear enough.


URL handling

dynamic website

A URL can be structured into the following components: <scheme>://<user>@<host>:<port>/<path>?<query>#<fragment>
Usually people do not want to store the whole URL into PowerPhlogger's logging table. In the multi-page list we do not want to make any difference between URLs with various different query-strings. e.g. abc.php?f=4&i=2136&t=2066 should be handled the same as abc.php or abc.php?f=4&i=2000&t=2015. Usually we don't want to store the whole URL including the whole query-string.

Now, let's say you're using a dynamically built site that is just made of one single page. e.g. we only got list.php and the actual content of this page gets generated out of the information located in the query-part of the URL. That's where we actually need to distinguish between URLs with various different query-strings.
At this point we're using the "short query" user setting. Each user can specify his own query-strings that he wish to get logged. He has to enter the query-strings into the textbox, each separated by a newline.

example:

http://www.abc.com/abc.php?date=200111&s=d46df4e47043bfab5d08fee9d24e0146&threadid=100&page=news

short query:
------------
| date     |
| page     |
------------

result:
-------
http://www.abc.com/abc.php?date=200111&page=news

By specifying "date" and "page" we're able to cut the query-string down to those two values and stripping off all the other stuff. e.g. we don't need to store the session-ID (s=d46df4e47043bfab5d08fee9d24e0146).

If we enter a "*" as short query string, then nothing will be stripped off and PowerPhlogger will keep the whole query-string.

http://www.abc.com/abc.php?date=200111&s=d46df4e47043bfab5d08fee9d24e0146&threadid=100&page=news

short query:
------------
| *        |
------------

result:
-------
http://www.abc.com/abc.php?date=200111&s=d46df4e47043bfab5d08fee9d24e0146&threadid=100&page=news

As default, the "short query"-string is empty. That way PowerPhlogger would strip off the whole query string.

index.* --> /

This list is for those who would like to handle "index.*" as "/".
Enter all index.* into this setting box, separated by newlines, e.g.:

---------------
| index.html  |
| index.php   |
| index.phtml |
---------------

download counter - dlcount.php

There's a download counter integrated in PowerPhlogger. In order to use it you just need to modify your links:

use this syntax, if yourfile.zip is located relative to your primary URL (the first URL you set in your userprofile):


 <a href="[path_to_pphlogger]/dlcount.php?id=[username]&url=/yourfile.zip">yourfile.zip</a>

If the file is located anywhere else, use an absolute path:


 <a href="[path_to_pphlogger]/dlcount.php?id=[username]&url=http://www.somewhereelse.com/yourfile.zip">yourfile.zip</a>

Make sure you enter your correct username (without brakets '[]')!
[path_to_pphlogger] must be the correct path to your pphlogger-directory, e.g. http://www.abc.com/pphlogger/


Troubleshooting

  1. Any PHP errors about function "imagecreate" does not exist indicates that your PHP installation does not include the GD library. This must be present.
    If you're not able to get GD to work, try to set GD's image-type manually in /admin/setup.php step 3. If you can't get it running at all set GD_enabled = false in step 3.

  2. If you are running PHP 4.06 and get an error saying "GD was not built with truetype support" you should know that this is a known problem with GD+PHP 4.06. There are some workarounds (search the net!) but it is really recommended that you instead upgrade to at least PHP 4.1.1 and configure PHP with --with-gd-native-ttf (Please also note that the built in TTF uses point size for fonts whereas Truetype 2 uses pixels.)
    Please DON't ask me how to resolve the GD Font problem. All mail regarding this will go straight to /dev/null. Upgrade to 4.1.1!

  3. If you're using PHP 4.1.x and you're not able to see the counter image on your userprofile settings page, this may be a another bug in PHP/GD. Run /admin/setup.php and edit the ttf_location setting in step 3. Default is "relative". Change it to an absolute path to your ttf_fonts-dir: e.g. "/home/yourpage_com/htdocs/pphlogger/ttf_fonts/".
    This bug has been reported to the PHP-group: http://bugs.php.net/bug.php?id=15212

FAQ - Frequently Asked Questions

What's this CSS-editor for?
Since PowerPhlogger 2.2.0 we're no longer using static CSS files. You may have noticed, that there is just one single CSS file located in the /css/ directory: common.css
The main idea: Use a single CSS file and generate the color content dynamically. Like this we got just one standardized CSS file in which we need to make changes. I guess the user still got enough choices. He can adjust a lot of colors by creating his own CSS profiles using the CSS editor.
A user can enter the CSS editor through the userprofile-page where he'll find a link below the CSS pull-down menu.
There are default styles and user specific styles. If a user wants to create a new style, he just takes an existing one, clicks on 'edit' and he'll be able to enter his color values - e.g. 'blue' or '0000FF' or '0+0+255' - the form accepts pretty every color string syntax. If the user edits his own profile he'll be able to save it. If it's a default profile, he'll be just able to create a new one based on the one he selected.

When I'm trying to create a new useraccount, there's the message "Sorry, currently we cannot offer any free accounts on this server !" showing up...
When setting up PowerPhlogger, you forgot to set "Enable User Self-Signup" to true. You'll find this value in the setup-process step 1. Go to /admin/ and enter the setup procedure.

When do I need to press the [ clean-up ] link in the bottom-right corner of the calendar?
The [ clean-up ] is only used if your calendar is somehow messed-up. Usually this should NEVER happen, so you don't actually ever need to use this link.
If you click on it, all you calendar information will be deleted and recalculated (without affecting any logs! don't worry :). If you got a huge amount of logs in your logs-table (by "huge" I mean like 200 logs/day throughout a whole year...) then it may take a long time to recalculate. Due to the maximum execution time that is usually set to 30 seconds the script may break. Just reload it again and again till you see the calendar. While it is running DO NOT RELOAD! Always wait till it is done.
Due to an enormous server load, this [ clean-up ] link has been disabled for users who are just logged in as guests.

What does "mp" mean?
mp stands for "multi-page" and is the amount of pageimpressions by user. It shows how many pages a user was viewing and how many reloads he has done.

I'd like to contribute to a translation into my language. What do I need to translate?
Currently there are four files you need to translate: /lang/xx.inc.php, /lang/xx_tld.inc.php, /messages/email_newuser_xx.txt, and /messages/email_notif_xx.txt
The /lang/xx.inc.php is the main language localization file. Please name it with a two digit language code (xx).
Take e.g. en.inc.php as template and replace all language strings with your translation. Otherwise please don't make any changes in this file. We'll take care of it to import your translated files into our next distribution.
We're always happy about new translations! Thanks to everyone who'd like to contribute!

What's showhits.php for?
showhits.php makes your counter visible. By calling this script you'll be able to show the following information:
[type] = hits | pageviews | today | todayviews | yesterday | yesterdayhits | month | monthviews | onlineusr | customers
For further information please check: showhits.php usage

How do I track referrers on a framed site?
edit your pphlogger.js file:
uncomment (remove the '//') the following line on top of the file: pp_frames = TRUE;
WARNING: This may cause a Javascript security error on several browsers in case your frameset is not located on the same domain. For people using a "stealth frame" like Namezero or MyDomain offers, it will be impossible to track referrers!

I need to use .php3 or some other extension, not .php
The extension .php is the prefered default extension for all PHP4 versions. It is the extension used by the PHP team and Zend.com. For this reason, PowerPhlogger comes with this extension.
The easiest way is to use this extension is to make Apache or your webserver parse these as PHP files. In Apache you need to add a line like:
AddType application/x-httpd-php3 .php

If that is not an option, you can change it by following these steps:

  1. change ALL .php file extensions to your new extension. You can do this manually or by using the following script: /upgrade/extchange.php (see instructions inside the file!)
  2. edit main_location.inc and change define('CFG_PHPEXT', 'php'); to your new extension

How do make download-hits visible on my page?
Use showhits.php and call it up through an IMG-Tag, PHP, or JavaScript.
Check the instructions inside showhits.php and check the samples above: showhits.php usage
Instead of using type=[type] you specify the download-URL: mpdl=/your_url/...


last modified on 19th July 2002 Valid XHTML 1.0!      Valid CSS!