PHPackages daandelange/simplestats - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. daandelange/simplestats ActiveKirby-plugin[Utility & Helpers](/categories/utility) daandelange/simplestats ======================= Very minimal visitor analytics for your kirby website. v1.x-dev(4mo ago)712.2k↑121.4%8[11 issues](https://github.com/Daandelange/kirby-simplestats/issues)MITPHPPHP >=8.2.0 Since Aug 16Pushed 4mo ago4 watchersCompare [ Source](https://github.com/Daandelange/kirby-simplestats)[ Packagist](https://packagist.org/packages/daandelange/simplestats)[ Docs](https://github.com/Daandelange/kirby-simplestats#readme)[ RSS](/packages/daandelange-simplestats/feed)WikiDiscussions master Synced 2d ago READMEChangelog (10)Dependencies (3)Versions (32)Used By (0) SimpleStats =========== [](#simplestats) Track page views, referrers and devices on your Kirby 5 website. This plugin provides a simple solution for **self-hosted**, **minimal** and **non-intrusive** visitor analytics. [![Simplestats Screenshot](k3-SimpleStats.gif)](k3-SimpleStats.gif) - It tracks **referrer URLs** to keep track of who links to your website, categorised as either `search`, `social` or `website`. - It tracks **device information** (device types, browser engine, OS family; all version-less) for keeping track of how your website is visited. - It tracks **page visits**, counting 1 hit per page per unique user per language, every 24H. - The collected data is stored in a **.sqlite database** (raw data) which you could query for custom purposes. The `Stats` class also exposes most collected data. - A panel area **visualises** the data in charts. Note @bogdancondorachi is doing some awesome modernisations to the k4-and-k5-tested codebase, you can checkout the [v1 branch here](https://github.com/Daandelange/kirby-simplestats/tree/v1) (alpha). ### How it works [](#how-it-works) - Tracking happens when the page is served by Kirby. - A crypted user-unique fingerprint is stored in order to track unique page views. *[The formula](https://github.com/Daandelange/kirby-simplestats/search?q=getUserUniqueString) is more or less `sha1( base64_encode( mix( anonimize(IP, 0.0.0.x) + trunc(UserAgent) + Salt)) )`.*It's stored together with a list of visited pages, the device category (bot/mobile/desktop/tablet/other), the browser's engine (Gecko/Webkit/Blink/Other) and OS Family. This data is kept for a very short amount of time to ensure only counting unique hits. - After 24H, the collected data is processed and any user identifying data is deleted : - The visited pages' hit counts are incremented, globally and per language. - Device, Engine and OS Family are separately incremented. - Referrers are processed immediately and are not bound to any user-related identifier. - All data is summed up on a monthly basis by default. You can easily change this "timeframe" to `weekly` or even provide your own custom timeframe utility. ### Current state [](#current-state) Consider this plugin beta. Any feedback or bug reports are welcome. It's been successfully running on multiple production websites for a few years. The tracking part is almost done and a panel view is available, when the panel interface & sections will be more polished, I'll consider a first release. Please note that the database structure might evolve over time, until a more stable release is available (*for which you'll be able upgrade your old databases; the upgrade meccanism already works*). ### Contributing [](#contributing) I guess a lot of options could be added to suit the plugin for a wider variety of website setups. The panel interface could also be improved and translated. Any contributions (discussions, reports, feedback and pull requests) are welcome, as long as the collected stats stay minimal and reasonably non-intrusive. You may also have a look at the [open issues](https://github.com/Daandelange/kirby-simplestats/issues/). --- Setup ----- [](#setup) ### Requirements [](#requirements) - A recent Kirby installation (currently tested with 5.0.0+) and support for SQLite3. - There's an automatic requirements checker in the `Information` tab of the plugin's panel view, feel free to use that for double-checking requirements. Note For Kirby 3, I recommend to use version `0.6.x-beta` as version `0.7.0-beta` introduces Kirby 5 compatibility. It might be Kirby 3 compatible but I'm not supporting it anymore. However, I'm happy to accept retro-compatibility PRs. ### Installation [](#installation) - **Option 1** : Download Download and copy this repository to `/site/plugins/simplestats`. - **Option 2** : Git submodule ``` git submodule add https://github.com/daandelange/kirby-simplestats.git site/plugins/simplestats ``` Eventually add `--depth 1` to discard the repo commit history. (saves disk space) - **Option 3** : Composer (*update the command to match the latest version*) `composer require daandelange/simplestats:~0.6.2-beta` (update with `composer update`) *Note: While `SimpleStats` is still alpha, there is no stable channel for composer, so you need to specify the unstable version.* *Note: I don't make a release for every small change. If you want to use the latest version with composer, you can manually enter a commit :* `composer require daandelange/simplestats:dev-master#dbdb4a2 --with-dependencies`. Important After installing the plugin and **before starting your webserver**, you have to configure the plugin. Whenever you change the tracking resolution (or your website's language setup), start with a fresh database file. ### Updating [](#updating) Before updating, make sure to **backup your database file**. If something goes wrong, you'll be able to retrieve your stats by replacing the database file later. Depending on the installation method you used, proceed to the logical steps to update. After updating: - Review new options and configure as wished. - Sometimes, a database upgrade is needed. If so, head to the panel's `Information` tab and follow instructions in the upgrade section. - It's also a good idea to check the log file for any errors. --- ### Configuration [](#configuration) #### Language setup [](#language-setup) Multi-language websites are supported. For each page, there's a global counter, with an optional counter for each language. *Warning:* Do not add or remove languages to your Kirby installation without resetting your database file ! Also, the panel view has not (yet?) been translated. **Note:** During the alpha phase, I'm working with a multi-language context. While I try to test single language setups from time to time, SimpleStats might break occasionally in these setups. #### Database Configuration [](#database-configuration) The database file is a simple `.sqlite` file that holds all tracking data. You can view it from the dedicated panel area, or by including smaller widget sections in the panel page editor. The popular Sqlite format allows you to easily grab the data and visualise it your way, or import it in other software. It's recommended to occasionally backup your stats database file. ##### Tracking Resolution and Kirby Languages [](#tracking-resolution-and-kirby-languages) Important Please note that *the database is tightly bound to the tracking resolution* option (`daandelange.simplestats.tracking.timeFrameUtility`) and *can not* be changed afterwards. Changing the resolution while keeping the same database file results in unefined behaviour. If changing, prefer starting with a fresh database. The same goes for Kirby's Language setup: *if you change your multilanguage settings*, you need to create a new database file (however, manually editing the previous database file, you might be able to preserve your data). This [could be automated with update scripts](https://github.com/Daandelange/kirby-simplestats/issues/14). ##### Generating Stats [](#generating-stats) Tip If you'd like to populate the database with some fake stats (useful for testing or developing SimpleStats), you can use the panel interface to generate some in the "Information" tab. #### Legal configuration [](#legal-configuration) Depending on your local laws, you might need to sit down and define how personal visitor data is handled. You might want to inspect the source code to know what's going on in details. As the license states, there's no guarantee whatsoever. #### Config Options [](#config-options) Like any Kirby plugin, many options can be set in your `site/config/config.php`. All available options are listed and explained in `src/config/options.php`. Example : ``` // site/config/config.php // The custom variable types (SimpleStatsTimeFrameUtility, SimplestatsTrackingMode) are namespaced, you can shorten their invocations with the line below: // use daandelange\SimpleStats\SimpleStatsTrackingMode; require_once(__DIR__ . '/../plugins/d-simplestats/src/models/SimpleStatsTrackingMode.php'); return [ // [...] your options ... // Simplestats 'daandelange.simplestats.panel.enable' => false, // Disable the panel view completely 'daandelange.simplestats.tracking.enableReferers' => false, // Disable referer tracking 'daandelange.simplestats.tracking.timeFrameUtility' => new \daandelange\SimpleStats\SimpleStatsTimeFrameUtilityWeekly(), // Here you can put your custom inherited class from SimpleStatsTimeFrameUtility 'daandelange.simplestats.tracking.timeFrameUtility' => 'weekly', // Alternative 'daandelange.simplestats.tracking.method' => \daandelange\SimpleStats\SimpleStatsTrackingMode::OnImage, ]; ``` Here's a list with options that have been tested. *(the `daandelange.simplestats` part has been stripped)* You might also find some more detailed information in the comments of `options.php`. OptionTypeDefaultDescriptionComment**TRACKING**`tracking.timeFrameUtility`String | SimpleStatsTimeFrameUtility`'monthly'`Set the trackign resolution class that handles time conversions to periods. **(change with caution!)**Possible string values: `Monthly`, `Weekly`.`tracking.enableReferers`BooltrueEnables tracking referrers. Gives an insight of who links to your website.`tracking.enableDevices`BooltrueEnables tracking of minimal hardware configurations (device information)`tracking.enableVisits`BooltrueEnables tracking page visits (frequentation)`tracking.enableVisitLanguages`BooltrueEnables a counter per language per page.Only effective in multi-language Kirby installations and `enableVisits` enabled.`tracking.ignore.roles`Array`['admin']`Ignore any tracking for connected users with these roles.`tracking.ignore.pages`Array`[]`Ignore tracking for these page ids.Make sure to use the full id, not the slug.`tracking.ignore.templates`Array`['error']`Ignore tracking for pages with these templates.Checked against `template()` and `intendedTemplate()``tracking.ignore.bots`BoolfalseIgnore tracking any bots.`tracking.ignore.botVisits`BooltrueIgnore counting bot page views.`tracking.ignore.botReferers`BooltrueIgnore tracking referrers sent by bots.`tracking.salt`String`'CHANGEME'`A unique hash, used to generate a unique user id from visitor data.Recommended to change, ensures that user identifying information is hard to retrieve if your database leaks.`tracking.anonimizeIpBits`Number`1`Anonymise the IP address of X bits.Use `0` for no anonymisation, `4` for full anonymisation.`tracking.method`SimplestatsTrackingMode`onLoad`Tracking mode. See `SimplestatsTrackingMode` for more information.`onLoad` is the only fully automatic mode, others need manual attention.**PANEL**`panel.dismissDisclaimer`BoolfalseDismisses the panel disclaimer message.`panel.enable`BooltrueEnable/Disable viewing stats in the panel.`panel.authorizedRoles`Array`['admin']`User roles that are allowed to view statistics from the panel.`panel.breadcrumbLabel`String`'SimpleStats'`Breadcrumb shown in the panel.`panel.hideBots`BoolfalseTo hide bot information from the devices tab.`panel.defaultTimeSpan`Integer-1To set the range (in periods) for the default panel view.Use `-1` for viewing the whole available range. Use `4` for 4 weeks or months.### Integrating to your page [](#integrating-to-your-page) #### Tracking method [](#tracking-method) If you want to use the default `onLoad` tracking method, no further action is required, the plugin automatically hooks to Kirby route events. If you choose any other tracking method, you'll need to integrate the method in your code. > **Possible Tracking Methods:** (Config value: `tracking.method`) > > - `SimpleStatsTrackingMode::OnLoad` : Uses kirby's route hooks to track content when it's served. > *Pros*: Ensures that every request is tracked. > *Cons*: Slows down the page serve time. > *Setup steps*: None. > - `SimpleStatsTrackingMode::OnImage` : Generate a simple image tag within your HTML. > *Pros*: Doesn't slow down page serve time. > *Cons*: You trust the user to load the image. > *Setup steps*: You need to call `$page->simpleStatsImage()` in your template code. You probably want to do this once in `site/snippets/footer.php` for example. > - `SimpleStatsTrackingMode::Disabled` : Disables tracking, no further action is needed. (now much tested yet) > *Setup steps*: None. > - `SimpleStatsTrackingMode::Manual` : Manually call the tracking function. > *Pros*: Very flexible, might solve edge-case-usage. > *Setup steps*: You have to call `SimpleStats::track()` manually. Additionally, you need to populate the http headers argument accordingly to track referers and device information. #### Panel Area [](#panel-area) The panel area is accessible under this url : `/panel/simplestats`. If you're using a custom panel menu, you can add the simplestats area to your menu. ```