{"id":20655245,"url":"https://github.com/ericsizemore/simple_counter","last_synced_at":"2025-09-01T21:33:53.897Z","repository":{"id":4530974,"uuid":"5671177","full_name":"ericsizemore/simple_counter","owner":"ericsizemore","description":"A simple PHP counter that counts your website visitors.","archived":false,"fork":false,"pushed_at":"2025-04-14T03:14:52.000Z","size":700,"stargazers_count":25,"open_issues_count":3,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T04:25:42.622Z","etag":null,"topics":["counter","file-based","flat-file","hacktoberfest","hit-counter","visitor-counter"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericsizemore.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"ko_fi":"ericsizemore","github":"ericsizemore","tidelift":"packagist/esi/simple_counter"}},"created_at":"2012-09-04T11:00:31.000Z","updated_at":"2025-04-09T00:35:05.000Z","dependencies_parsed_at":"2024-03-23T04:19:38.299Z","dependency_job_id":"f0548759-fde1-44f2-a376-82e216a880bd","html_url":"https://github.com/ericsizemore/simple_counter","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericsizemore%2Fsimple_counter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericsizemore%2Fsimple_counter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericsizemore%2Fsimple_counter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericsizemore%2Fsimple_counter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericsizemore","download_url":"https://codeload.github.com/ericsizemore/simple_counter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249687984,"owners_count":21311148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["counter","file-based","flat-file","hacktoberfest","hit-counter","visitor-counter"],"created_at":"2024-11-16T18:09:40.677Z","updated_at":"2025-04-19T11:52:02.985Z","avatar_url":"https://github.com/ericsizemore.png","language":"PHP","funding_links":["https://ko-fi.com/ericsizemore","https://github.com/sponsors/ericsizemore","https://tidelift.com/funding/github/packagist/esi/simple_counter"],"categories":[],"sub_categories":[],"readme":"# Simple Counter - A simple web hit counter.\n\n[![Build Status](https://scrutinizer-ci.com/g/ericsizemore/simple_counter/badges/build.png?b=master)](https://scrutinizer-ci.com/g/ericsizemore/simple_counter/build-status/master)\n[![Code Coverage](https://scrutinizer-ci.com/g/ericsizemore/simple_counter/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/ericsizemore/simple_counter/?branch=master)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/ericsizemore/simple_counter/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/ericsizemore/simple_counter/?branch=master)\n[![Tests](https://github.com/ericsizemore/simple_counter/actions/workflows/tests.yml/badge.svg)](https://github.com/ericsizemore/simple_counter/actions/workflows/tests.yml)\n[![PHPStan](https://github.com/ericsizemore/simple_counter/actions/workflows/main.yml/badge.svg)](https://github.com/ericsizemore/simple_counter/actions/workflows/main.yml)\n[![Psalm Static analysis](https://github.com/ericsizemore/simple_counter/actions/workflows/psalm.yml/badge.svg?branch=master)](https://github.com/ericsizemore/simple_counter/actions/workflows/psalm.yml)\n[![Type Coverage](https://shepherd.dev/github/ericsizemore/simple_counter/coverage.svg)](https://shepherd.dev/github/ericsizemore/simple_counter)\n[![Psalm Level](https://shepherd.dev/github/ericsizemore/simple_counter/level.svg)](https://shepherd.dev/github/ericsizemore/simple_counter)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ericsizemore_simple_counter\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=ericsizemore_simple_counter)\n[![Latest Stable Version](https://img.shields.io/packagist/v/esi/simple_counter.svg)](https://packagist.org/packages/esi/simple_counter)\n[![Downloads per Month](https://img.shields.io/packagist/dm/esi/simple_counter.svg)](https://packagist.org/packages/esi/simple_counter)\n[![License](https://img.shields.io/packagist/l/esi/simple_counter.svg)](https://packagist.org/packages/esi/simple_counter)\n\n[Simple Counter](https://github.com/ericsizemore/simple_counter/) is a simple PHP counter that counts your website visitors. It has the ability to \neither show the count as plain text or images; and whether to count only unique hits, or all hits. (IP Based)\n\n## Important Note\n\n* As of v6.0.0, Simple Counter is no longer licensed under the GNU LGPLv3 license.\n* v6.0.0 is a complete rewrite of the library, and no GNU LGPLv3 licensed code remains.\n* v5.0.1 and previous are still licensed under the GNU LGPLv3 license.\n\nWith that being said, it is important to read the `Upgrading` section below if you are coming from an older version.\n\n\n## Acknowledgements\n\nThe 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](https://creativecommons.org/licenses/by/4.0/), and were designed by [StreamlineHQ](https://www.streamlinehq.com/freebies/typeface).\n\n\n## Upgrading\n\nPre-v6 -\u003e v6 is not a simple upgrade. Several things have changed in this rewrite, and there are breaking changes.\n\nPlease read [UPGRADING.md](UPGRADING.md) first before attempting an upgrade.\n\n\n## Installation\n\nTo install Simple Counter, first install via composer:\n\n```bash\ncomposer require esi/simple_counter:^6.0\n```\n\nThere are several options defined by default, however you will likely run into issues if you do not change some of them.\nMore information can be found in [Usage](#usage) below.\n\n* Copy the `counter` directory from `vendor/esi/simple_counter` to your webroot\n  * The `counter` directory contains the `logs` and `images` directory.\n  * You can change the name of either directory if you wish, or skip using the `counter` directory all together and just move `logs` and `images` to your webroot.\n    * However:\n      * The ip file and counter file must remain `ips.json` and `counter.json`\n      * The images must be named 0-9.\n* Make sure the `ips.json` and `counter.json` files within your logs directory are writable.\n\n\n## Usage\n\n**More detailed documentation is a work in progress.**\n\nUsage 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.\n\nSimply add the following code to the page where you want the counter to be shown:\n\n```php\n\u003c?php\n\n// Load the composer autoload file, if not already loaded\nrequire_once 'vendor/autoload.php';\n\nuse Esi\\SimpleCounter\\Counter;\nuse Esi\\SimpleCounter\\Storage\\FlatfileStorage;\nuse Esi\\SimpleCounter\\Configuration\\FlatfileConfiguration;\n\n/**\n * $options is an array of:\n *\n * array{\n *     logDir: string,\n *     countFile: string,\n *     ipFile: string,\n *     imageDir: string,\n *     imageExt: string,\n *     uniqueOnly: bool,\n *     asImage: bool,\n *     honorDnt: bool,\n *     visitorTextString?: string\n * }\n *\n * Default values are:\n *\n * [\n *      'logDir'            =\u003e dirname(__DIR__, 2) . '/counter/logs/',\n *      'countFile'         =\u003e 'counter.json',\n *      'ipFile'            =\u003e 'ips.json',\n *      'imageDir'          =\u003e dirname(__DIR__, 2) . '/counter/images/',\n *      'imageExt'          =\u003e '.png',\n *      'uniqueOnly'        =\u003e true,\n *      'asImage'           =\u003e false,\n *      'honorDnt'          =\u003e false,\n *      'visitorTextString' =\u003e 'You are visitor #%s',\n * ] \n */\n// Valid options are:\n$options = [\n    'logDir'            =\u003e '/path/to/some/dir/logs',\n    'countFile'         =\u003e 'counter.json',\n    'ipFile'            =\u003e 'ips.json',\n    'imageDir'          =\u003e '/path/to/some/dir/images',\n    'imageExt'          =\u003e '.png', // '.png', '.jpg' etc. default images are PNG images\n    'asImage'           =\u003e true,   // true = images, false = plain text\n    'uniqueOnly'        =\u003e true,   // true = counts only unique ip's, false = counts all,\n    'honorDnt'          =\u003e false,\n    'visitorTextString' =\u003e 'You are visitor #%s',\n];\n\n/**\n * Important note regarding the 'visitorTextString'. This is the text that is shown if 'asImage' is false.\n *\n * For example, by default, it would show: You are visitor #123.\n * If you wanted to change it to something like: Counter: #123,\n * you would set the 'visitorTextString' option to:\n * \n * 'Counter: #%s'\n */\n\n/**\n * When creating the counter instance, a Storage implementation with a valid Configuration is required.\n * Currently, Simple Counter ships with one Storage implementation, and it's corresponding Configuration:\n *\n * \\Esi\\SimpleCounter\\Storage\\FlatfileStorage\n * \\Esi\\SimpleCounter\\Configuration\\FlatfileConfiguration\n *\n * \\Esi\\SimpleCounter\\Counter can be used as a wrapper, but it is not necessary. For example:\n *\n * $counter = new Counter(\n *     new FlatfileStorage(\n *         FlatfileConfiguration::initOptions($options)\n *     )\n * );\n */\n// Pass custom options\n$counter = new FlatfileStorage(\n    FlatfileConfiguration::initOptions($options)\n);\n\n// ... or if you wish to use defaults\n$counter = new FlatfileStorage(\n    FlatfileConfiguration::initOptions()\n);\n\n// ... or maybe you only want to switch to using images, for example\n$counter = new FlatfileStorage(\n    FlatfileConfiguration::initOptions(['asImage' =\u003e true])\n);\n\n// Finally, call display(). You can either output it directly or save it to a variable if needed\necho $counter-\u003edisplay();\n\n// ... or ...\n\n$hitCount = $counter-\u003edisplay();\n\n// ... do some stuff\necho $hitCount;\n\n?\u003e\n```\n\n## Handling Errors\n\nSimple Counter uses Exceptions for various issues that may arise throughout its process.\n\nCurrently, most exceptions fall under `\\Symfony\\Component\\OptionsResolver\\Exception\\InvalidOptionsException`.\n\nThese exceptions can be thrown if:\n\n* You pass an option that is not defined.\n* A given option's value type does not match the allowed types.\n* When reading/writing to a file encounters an error, since it is likely due to a file name/location issue.\n* For invalid directories or files, in terms of `logDir`, `imageDir`, `countFile`, `ipFile`\n\n\n## About\n\n### Requirements\n\n- Simple Counter works with PHP 8.2.0 or above.\n\n### Submitting bugs and feature requests\n\nBugs and feature requests are tracked on [GitHub](https://github.com/ericsizemore/simple_counter/issues)\n\nIssues are the quickest way to report a bug. If you find a bug or documentation error, please check the following first:\n\n* That there is not an Issue already open concerning the bug\n* That the issue has not already been addressed (within closed Issues, for example)\n\n### Contributing\n\n* See [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Backward Compatibility Promise\n\n* See [backward-compatibility.md](backward-compatibility.md)\n\n### Author\n\nEric Sizemore - \u003cadmin@secondversion.com\u003e - \u003chttps://www.secondversion.com\u003e\n\n### License\n\n#### Simple Counter v6.0.0 and newer\n\n* Licensed under the MIT License. See the [`LICENSE.md`](LICENSE.md) file for details.\n\n#### Simple Counter v5.0.1 and older\n\n* Licensed under the GNU LGPL v3 License. See the [`\u003c= 5.x LICENSE.md`](https://github.com/ericsizemore/simple_counter/blob/5.0.x/COPYING.LESSER) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericsizemore%2Fsimple_counter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericsizemore%2Fsimple_counter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericsizemore%2Fsimple_counter/lists"}