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 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 | |