Simple Counter is a simple PHP counter that counts your website visitors. It has the ability to either show the count as plain text or images; and whether to count only unique hits, or all hits. (IP Based)
- As of v6.0.0, Simple Counter is no longer licensed under the GNU LGPLv3 license.
- v6.0.0 is a complete rewrite of the library, and no GNU LGPLv3 licensed code remains.
- v5.0.1 and previous are still licensed under the GNU LGPLv3 license.
With that being said, it is important to read the Upgrading section below if you are coming from an older version.
The icons used for the default image set (0-9 'png' images found in counter/images/) are licensed under the CC BY 4.0 DEED license, and were designed by StreamlineHQ.
Pre-v6 -> v6 is not a simple upgrade. Several things have changed in this rewrite, and there are breaking changes.
Please read UPGRADING.md first before attempting an upgrade.
To install Simple Counter, first install via composer:
composer require esi/simple_counter:^6.0There are several options defined by default, however you will likely run into issues if you do not change some of them. More information can be found in Usage below.
- Copy the
counterdirectory fromvendor/esi/simple_counterto your webroot- The
counterdirectory contains thelogsandimagesdirectory. - You can change the name of either directory if you wish, or skip using the
counterdirectory all together and just movelogsandimagesto your webroot.- However:
- The ip file and counter file must remain
ips.jsonandcounter.json - The images must be named 0-9.
- The ip file and counter file must remain
- However:
- The
- Make sure the
ips.jsonandcounter.jsonfiles within your logs directory are writable.
More detailed documentation is a work in progress.
Usage is fairly simple once installed. There is currently one option for the type of counter you wish to use, and that is the FlatfileStorage. A DatabaseStorage is slated for an upcoming release.
Simply add the following code to the page where you want the counter to be shown:
<?php
// Load the composer autoload file, if not already loaded
require_once 'vendor/autoload.php';
use Esi\SimpleCounter\Counter;
use Esi\SimpleCounter\Storage\FlatfileStorage;
use Esi\SimpleCounter\Configuration\FlatfileConfiguration;
/**
* $options is an array of:
*
* array{
* logDir: string,
* countFile: string,
* ipFile: string,
* imageDir: string,
* imageExt: string,
* uniqueOnly: bool,
* asImage: bool,
* honorDnt: bool,
* visitorTextString?: string
* }
*
* Default values are:
*
* [
* 'logDir' => dirname(__DIR__, 2) . '/counter/logs/',
* 'countFile' => 'counter.json',
* 'ipFile' => 'ips.json',
* 'imageDir' => dirname(__DIR__, 2) . '/counter/images/',
* 'imageExt' => '.png',
* 'uniqueOnly' => true,
* 'asImage' => false,
* 'honorDnt' => false,
* 'visitorTextString' => 'You are visitor #%s',
* ]
*/
// Valid options are:
$options = [
'logDir' => '/path/to/some/dir/logs',
'countFile' => 'counter.json',
'ipFile' => 'ips.json',
'imageDir' => '/path/to/some/dir/images',
'imageExt' => '.png', // '.png', '.jpg' etc. default images are PNG images
'asImage' => true, // true = images, false = plain text
'uniqueOnly' => true, // true = counts only unique ip's, false = counts all,
'honorDnt' => false,
'visitorTextString' => 'You are visitor #%s',
];
/**
* Important note regarding the 'visitorTextString'. This is the text that is shown if 'asImage' is false.
*
* For example, by default, it would show: You are visitor #123.
* If you wanted to change it to something like: Counter: #123,
* you would set the 'visitorTextString' option to:
*
* 'Counter: #%s'
*/
/**
* When creating the counter instance, a Storage implementation with a valid Configuration is required.
* Currently, Simple Counter ships with one Storage implementation, and it's corresponding Configuration:
*
* \Esi\SimpleCounter\Storage\FlatfileStorage
* \Esi\SimpleCounter\Configuration\FlatfileConfiguration
*
* \Esi\SimpleCounter\Counter can be used as a wrapper, but it is not necessary. For example:
*
* $counter = new Counter(
* new FlatfileStorage(
* FlatfileConfiguration::initOptions($options)
* )
* );
*/
// Pass custom options
$counter = new FlatfileStorage(
FlatfileConfiguration::initOptions($options)
);
// ... or if you wish to use defaults
$counter = new FlatfileStorage(
FlatfileConfiguration::initOptions()
);
// ... or maybe you only want to switch to using images, for example
$counter = new FlatfileStorage(
FlatfileConfiguration::initOptions(['asImage' => true])
);
// Finally, call display(). You can either output it directly or save it to a variable if needed
echo $counter->display();
// ... or ...
$hitCount = $counter->display();
// ... do some stuff
echo $hitCount;
?>Simple Counter uses Exceptions for various issues that may arise throughout its process.
Currently, most exceptions fall under \Symfony\Component\OptionsResolver\Exception\InvalidOptionsException.
These exceptions can be thrown if:
- You pass an option that is not defined.
- A given option's value type does not match the allowed types.
- When reading/writing to a file encounters an error, since it is likely due to a file name/location issue.
- For invalid directories or files, in terms of
logDir,imageDir,countFile,ipFile
- Simple Counter works with PHP 8.2.0 or above.
Bugs and feature requests are tracked on GitHub
Issues are the quickest way to report a bug. If you find a bug or documentation error, please check the following first:
- That there is not an Issue already open concerning the bug
- That the issue has not already been addressed (within closed Issues, for example)
- See CONTRIBUTING.md
Eric Sizemore - admin@secondversion.com - https://www.secondversion.com
- Licensed under the MIT License. See the
LICENSE.mdfile for details.
- Licensed under the GNU LGPL v3 License. See the
<= 5.x LICENSE.mdfile for details.
