The following description applies to a generic BBClone installation, that does not reflect particular weblogs/content management systems. For this purpose it's recommended you take a look at our links page first, which features a listing to external resources. Setup ===== If you are a Windows user you should prefer the *.zip package because its included documentation uses Windows style formatting, which means it will be readable in applications like Notepad, too. If your favorite editor hasn't got a problem with Unix formatted documents, you can also download the *.tar.gz archive. There are two ways to upload BBClone via FTP. Either you upload the package and extract it on the server or you upload the already extracted files. As a rule of thumb, whenever shell access is available, you should extract the archive on the server because it will save you a lot of time and ensures all files are copied to their destination. If there's no shell access or you simply don't know how to operate on such a shell you can upload the single files to your server. But be aware there are a couple of pitfalls: Your FTP client must have been configured to treat *.php, *.inc and *.png files as binary files. Uploading them in ascii mode may break the application or result in broken images. Ask your FTP client's vendor how to configure it, if you feel unsure about it and its documentation doesn't give any hints You have to double check whether really all files have been copied to their destination. Sometimes it happens that FTP servers unexpectedly shut down the connection or runs into a timeout if there's a large amount of files. Your FTP client should offer options to resume incomplete files and skip already existing files of the same size. It will make your life much easier It's a good idea to make something like a sketch about the documents structure on your server. You need to know the path to your BBClone installation directory and how to get there from each point of your site you wish to monitor the traffic. Example: www.example.com | index.php (1) | | |----bbclone/ | | |----subdirectory/ | | | index.php (2) The path to BBClone in document (1) would be "bbclone/", because "index.php" resides in the root directory. But be aware of document (2). It's path is different, because it's path starting from the www-root is actually "subdirectory/index.php". In other words at the same level as the BBClone directory. So in order to get to the BBClone directory we need to move one level up and then enter the BBClone directory. That's why the path to BBClone for document (2) is "../bbclone/. The ".." tell the server to move to the parent directory first. If you browse BBClone's directory you'll notice a directory called "var/". In Unix land, a var directory contains frequently alterred files, typically stuff like logs or data bases would be stored there. BBClone will store its data there, but in order to do so the server needs to be allowed to write to some files. The files are: counter[0-15].inc -> contains the raw connection data of a visitor access.php -> contains the data used for global and time statistics last.php -> contains the data used for detailed statistics .htalock -> lockfile needed while writing to the files mentioned above To make these files writable for the server apply the "chmod" command. If your server doesn't know "chmod" contact your hosting company for getting the appropriate command. If your PHP runs as Apache module then "chmod 666" will be the right command. "644" won't work because the server accesses the file as a different user, which would restrict access to read-only, as "644" would only grant write access for the owner. If your PHP runs as cgi-binary then "chmod 644" may already be sufficient, since the server will use your user id for accessing the files. If unsure, use "chmod 666". Now the code needs to be added to the files you wish to monitor. It's a good idea to create a test file at first to see whether BBClone is already working. To do you can use the following sample and point your browser to it. Attention! You have to customise this snippet to suit your needs. _BBC_PAGE_NAME contains the title you want to use for the page. This title will be displayed in your stats later. _BBCLONE_DIR The path to the BBClone directory. Remember the sketch from 1.3? Now you need the result of your preparation for setting this variable. You may need to change this entry depending on the file's location. If unsure, please reread section 1.3. Don't forget the trailing slash at the end of the directory. You can also use the following snippet: define("_BBCLONE_DIR", "bbclone/"); define("COUNTER", _BBCLONE_DIR."mark_page.php"); if (is_readable(COUNTER)) include_once(COUNTER); ?> This time we left out the page title. If BBClone doesn't find one it will automatically create one derived from the file's path. This is useful if you have a lot of pages and want to automate the naming process. Now that we tested anything and found it working, we can go on to register visits. The "traditional" method requires *.php pages. You also need to have permissions to run PHP (of course). If you want to put your code somewhere else the file needs to be included into a *.php file eventually, so the server recognises it and is able to run the PHP interpreter. Inside of PHP files not everything is necessarily PHP code. Sometimes passages of code alter with pure html. each PHP codeblock is started with "". If you want to add the code within such a PHP code block, you will have to write: define("_BBC_PAGE_NAME", "Test"); define("_BBCLONE_DIR", "bbclone/"); define("COUNTER", _BBCLONE_DIR."mark_page.php"); if (is_readable(COUNTER)) include_once(COUNTER); (or without the page title, see 1.4 for details) If however you're outside of such a block and find nothing but html tags then you need to add the php enclosings so the server knows it has to parse this passage as PHP code. Please note that the server can't run php from within a *.html file. In this case you would see the counter code "as is" in the html source If you run an apache server and are allowed to use .htaccess you can even monitor your *.html pages without ever editing or renaming them. Attention: THE FOLLOWING CODE ISN'T GUARANTUEED TO RUN EVERYWHERE. IF IT DOESN'T WORK FOR YOU THERE'S NOTHING TO BE DONE ABOUT IT. 1. Add the following to your .htaccess: AddType application/x-httpd-php .htm .html php_value auto_append_file "/the/path/that/leads/to/count.php" The path needs to be a local absolute path like the example above. Create the file "count.php" and add the following: In our example "count.php" is situated in the www-root. If your files are located elsewhere you need to modify the paths accordingly (see 1.3). An absolute path is required to make this snippet work. If you don't know the absolute path to your BBClone directory you can do the following: Go to your bbclone directory, open index.php in your favorite editor and add the line: echo "<?php\n" ."define("_BBCLONE_DIR", "" .dirname(__FILE__)."/");\n" ."define("COUNTER", _BBCLONE_DIR."" ."mark_page.php");\n" ."if (is_readable(COUNTER)) include_once(COUNTER);\n" ."?>\n"; Point your browser to it, copy and paste the output and save it into a file as "count.php" (to stick with our example). Don't forget to remove the line from index.php afterwards else it will be displayed each time you call your stats. Now the following will happen: Each time someone calls one of the ".htm" or ".html" pages the code snippet with the counter code will be automatically appended. BBClone will automatically create a page title derived from the file's path which will be used in the page stats then. The BBClone Team (c) 2004