complete counter hosting tool
PowerPhlogger 2.2.5
Copyright (c) 2000-2003 Philip Iezzi <webmaster@phpee.com>
Documentation version: $Id: doc.html,v 1.33 2003/08/18 19:11:46 cvs_iezzi Exp $
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
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:
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:
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.
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.
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';
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.
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).
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!
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:
st = 'js']:<script language="JavaScript" type="text/javascript" src="http://www.your_domain.com/pphlogger/showhits.php?id=username&st=js"></script>
st = 'php']:
<?php
define('PPHL_SCRIPT_PATH', '../pphlogger/'); // relative or absolute server path to your pphlogger-dir
$id = "username";
$st = 'php';
include (PPHL_SCRIPT_PATH."showhits.php"); ?>
st = 'img']:<img alt="" src="http://www.your_domain.com/pphlogger/showhits.php?id=username&st=img">
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:
st = 'js']:<script language="JavaScript" type="text/javascript" src="http://www.your_domain.com/pphlogger/showhits.php?id=username&st=js&type=onlineusr"></script>
st = 'php']:
<?php
define('PPHL_SCRIPT_PATH', '../pphlogger/'); // relative or absolute server path to your pphlogger-dir
$id = "username";
$type = "onlineusr";
$st = 'php';
include (PPHL_SCRIPT_PATH."showhits.php"); ?>
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 !):
st = 'img']:<img alt="" src="http://www.your_domain.com/pphlogger/showhits.php?id=username&st=img&mpdl=/files/myfile.zip">
Ok, I hope that was clear enough.
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 | ---------------
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/
GD_enabled
= false in step 3. 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:
define('CFG_PHPEXT', 'php'); to your
new extensionHow 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 |
|