tomvondracek / bolt-request-analytics
Cookieless, server-side visitor statistics for Bolt CMS 6, built only from the HTTP request: no JavaScript, no identifiers, no raw request storage.
Package info
github.com/Vondry/bolt-server-analytics
Type:bolt-extension
pkg:composer/tomvondracek/bolt-request-analytics
Fund package maintenance!
Requires
- php: >=8.2
- ext-json: *
- ext-mbstring: *
- symfony/cache: ^6.4 || ^7.0
- symfony/lock: ^6.4 || ^7.0
- symfony/polyfill-php84: ^1.43.0
- twig/twig: ^3.30
Requires (Dev)
- bolt/core: ^6.1.10
- phpstan/extension-installer: 1.4.3
- phpstan/phpstan: 2.3.4
- phpstan/phpstan-deprecation-rules: 2.0.5
- phpstan/phpstan-phpunit: 2.1.1
- phpstan/phpstan-strict-rules: 2.1.0
- phpunit/phpunit: ^11.5.58
- rector/rector: 2.8.3
- symplify/easy-coding-standard: ^13.3.17
Suggests
- ext-apcu: Caches the classification of User-Agent strings between requests
Provides
None
Conflicts
- bolt/core: <6.1 || >=7.0
Replaces
None
This package is auto-updated.
Last update: 2026-11-15 20:54:21 UTC
README
Cookieless, server-side visitor statistics for Bolt 6, built only from the HTTP request. No JavaScript on the public site, no cookies, no identifiers, no IP addresses, and the data never leaves your server.
- Pages: which pages are viewed, how often, in which languages, and where visitors go next
- Sources: search engines, AI assistants (ChatGPT, Perplexity, Claude, …), social networks, referrals, UTM campaigns, domain aliases and QR codes
- Visitors: devices, browsers, operating systems, preferred languages, busiest hours
- Problems: broken links (with the page that links to them), site searches, bot traffic by operator
- Insights: the few findings worth acting on, each with its likely cause and a next step
- A summary card on the dashboard and an Analytics page in the backend menu, for 7 days up to 3 years, compared with the period before or the year before
It deliberately never recognises a visitor, so there are no unique visitors, sessions, bounce rates or times on page. Pages are not slowed down: a request is classified only after its response has been sent.
The dashboard card, and the Analytics page (watch a 12-second scroll through it).
Requirements
- Bolt CMS
^6.1, PHP>=8.2 - A SQLite file (default, needs
pdo_sqlite) or a MySQL / MariaDB / PostgreSQL database of its own
Installation
composer require tomvondracek/bolt-request-analytics bin/console extensions:configure --with-config bin/console cache:clear
extensions:configure copies the routes, the menu item and the translations into the project, and --with-config
the configuration to config/extensions/tomvondracek-requestanalytics.yaml. Run it again after every update.
The tables are created on first use and updated after an update. To do it right away, e.g. in a deploy script:
bin/console request-analytics:install
Database
The statistics always live in a database of their own, never in Bolt's, so the site never waits for them. By default
that is the SQLite file var/data/request-analytics.db. To use a server instead, create an empty database and point
the extension to it:
# config/extensions/tomvondracek-requestanalytics.yaml storage: database: '%env(REQUEST_ANALYTICS_DATABASE_URL)%'
# .env.local REQUEST_ANALYTICS_DATABASE_URL="mysql://stats:secret@127.0.0.1:3306/bolt_stats?serverVersion=8.0" # or "postgresql://stats:secret@127.0.0.1:5432/bolt_stats?serverVersion=16"
- The database user needs
CREATE,ALTERandDROP: the extension manages its tables itself (no Doctrine migrations). - Bolt's own database is refused (the same SQLite file, or the same database on the same server).
- On MySQL / MariaDB the tables are always
utf8mb4/utf8mb4_bin, whatever the server's default. - Keep a SQLite file on local, persistent disk (not NFS), and include it in backups.
- When the database is unreachable, visits wait on disk (see How it works) and the dashboard card says what is wrong. Connecting gives up after 5 seconds, so the backend never hangs on it.
Production checklist
| What to check | |
|---|---|
| Access | Only ROLE_ADMIN (and ROLE_DEVELOPER) sees and deletes statistics by default. Change access.view / access.delete to open it to other roles. |
| Timezone | Days and hours follow timezone in config/bolt/config.yaml (Bolt's default is UTC). |
| Cron | Recommended on busy sites, or when nobody logs in for weeks: 0 * * * * cd /path/to/project && bin/console request-analytics:rollup. Without it, statistics are updated only when an admin opens the dashboard. |
| File owners | The web server writes the spool and the SQLite file; cron reads and deletes them. Run cron as the web server's user, or put both in one group (files are created 0660, directories 0770). A file created by cron that the web server can't write is the most common reason the statistics stop. |
| Proxy / CDN | Configure framework.trusted_proxies. If the proxy passes on a different Host than visitors use, list the public hosts in own_hosts. |
| Deploys | With release directories (Deployer, Capistrano, …), add var/request-analytics/ and var/data/ to the shared directories, or waiting visits and the SQLite file are lost on every deploy. |
| Several web servers | Use a shared MySQL / PostgreSQL database and run the cron rollup on every server: each server has its own spool. |
| Full-page cache | Pages served by a cache or CDN without reaching Bolt are not counted. |
| Privacy policy | Describe the processing (purpose, data, retention, GPC / DNT opt-out). This is not legal advice. |
| Testing | Nothing is collected with APP_ENV=dev or APP_DEBUG=1. To test collection locally, use APP_ENV=prod APP_DEBUG=0 and clear the cache. |
Configuration
config/extensions/tomvondracek-requestanalytics.yaml (all keys optional; shown with their defaults):
enabled: true # false: collect nothing, hide the card and menu item access: view: [ROLE_ADMIN] # roles that see the statistics, e.g. [ROLE_ADMIN, ROLE_CHIEF_EDITOR] delete: [ROLE_ADMIN] # roles that may delete them (also need a `view` role) own_hosts: [] # public hosts of the site, e.g. [example.com, www.example.com] aliases: # see "Domain aliases" hosts: [] # e.g. [example.org, poster-a2] target: ~ # e.g. https://example.com (required with hosts) mode: count # count | tag redirect_status: 301 # 301 | 302 | 307 | 308 param: ra_via # query marker in tag mode exclude_paths: ['^/api(/|$)', '^/_', '^/theme/', '^/files/', '^/thumbs/', '\.(css|js|map|png|jpe?g|gif|webp|avif|svg|ico|woff2?|txt|xml)$'] route_templates: true # /product/12345 is stored as /product/:id (also UUIDs, hashes, tokens) search_params: [searchTerm, q, s, search] # site-search parameters; terms are stored redacted count_reloads: true storage: database: '%kernel.project_dir%/var/data/request-analytics.db' # SQLite path or mysql:// / postgresql:// URL collector: spool_dir: '%kernel.project_dir%/var/request-analytics/spool' max_spool_mb: 1024 # stop collecting (and log) above this until the rollup catches up; 0 = no limit ua_cache: apcu # apcu | none aggregation: trigger: admin # admin (on dashboard visits) | cron | both time_budget_ms: 1500 # per dashboard-triggered rollup chunk_size: 25000 widget: target: dashboard_aside_top # dashboard_aside_top | _middle | _bottom | dashboard_below_header | dashboard_bottom default_range: 30d # Analytics page: 7d | 30d | 3m | ytd | 1y | 3y compare: previous # previous | year | none metric: pageviews # pageviews | entries (shown as "Visits") privacy: honor_gpc: true # Sec-GPC: 1 honor_dnt: true # DNT: 1 opt_out_mode: minimal # minimal (count the page only) | skip (store nothing) report_threshold_k: 5 # smaller counts are shown only as "Other" retention_months: 25 # detailed data; daily totals are kept. 0 = forever
- A
tomvondracek-requestanalytics_local.yamlnext to it overrides single values. - Relative paths are relative to the project directory. Paths in the public folder are refused.
- An invalid value is shown on the dashboard card and logged; the collector then pauses until it is fixed. An unknown key (likely a typo) is only reported.
How it works
PUBLIC REQUEST ADMIN
Bolt sends the page Admin opens the dashboard (or cron runs)
│ kernel.terminate │
classify the request rollup: spool ─► raw rows ─► daily aggregates
│ │
append one line to var/request-analytics/spool Analytics page reads the aggregates
Collect. After the response is sent, the request becomes one row of derived values: day and hour, normalised path, device, browser and OS family, language, channel and source. The User-Agent and Referer are read but never stored; the IP address is never read. The row is appended to an hourly spool file, with no database connection (about 0.1 ms). Under PHP-FPM, FrankenPHP or LiteSpeed this happens after the connection is closed.
| Counted | Stored as |
|---|---|
A page opened in a browser (GET navigation, status 2xx or 304) |
page view with all dimensions |
| The same with status 404 | broken link: path and where the link was |
| A bot (bot-like User-Agent, or headers that contradict it) | bot request: only the bot family |
| A request to a domain alias | alias hop: alias, path and source |
Not counted: the backend, AJAX and API calls, assets, prefetches, redirects, errors and exclude_paths. Visitors who
send GPC or DNT are counted without device, browser, source or language (or not at all with opt_out_mode: skip).
Aggregate. The rollup moves spool lines into the database and rolls them into daily aggregate tables, within a time budget; a backlog is worked off over several runs. It is safe to stop at any point: no line is ever counted twice, also with several servers. Only one rollup runs at a time.
Failures never break a page. Any error (full disk, broken config, unreachable database) is logged at level error
to Bolt's log, at most once per 5 minutes. The spool is capped at max_spool_mb.
The Analytics page
Two metrics run through the page:
- Page views: every page opened, including moves within the site.
- Visits: arrivals from outside (search, links, social, newsletters, typed addresses). Without cookies this is
the closest thing to visits. In the config and API it is called
entries.
A period bar (7D, 30D, 3M, YTD, 1Y, 3Y, or a drill-down into a week or month) sets the days of every card, with the comparison period and the metric. The choice is kept in the URL, so links can be shared.
| Card | Shows |
|---|---|
| Headline | Page views, visits, pages per visit, broken links and bot share, each with its change; a click jumps to the details |
| Insights | Findings worth acting on (below); hidden when there are none |
| Trend | Bars by day, week or month, with the comparison as a dashed line |
| Devices, browsers, OS | Shares and their change |
| When visitors come | Average page views per hour and weekday |
| Pages | Most or least viewed (including published pages nobody opened), languages per page, and each page's flow: where visitors came from and went next |
| Languages | Languages of the pages viewed vs. the languages visitors prefer, with gaps marked |
| Sources | Channels and sources with landing pages; UTM campaigns; aliases and QR codes. Empty tabs explain how to fill them |
| Broken links | Missing pages with where the links are, and what to do (fix the link, add a redirect) |
| Site search | What visitors searched for (e-mails, phone numbers and long numbers removed) |
| Bots | Bot share and bots by purpose and operator: search engines, AI crawlers, SEO tools, previews, monitoring, scripts, disguised browsers |
| Manage statistics | For access.delete: delete today, the last 7 / 30 / 90 / N days, or everything |
Values below report_threshold_k are shown as "Other", so combining figures can't single out one visitor. The page
shows what is aggregated, then starts a rollup and redraws; opening it never waits. It is translated into every
language of Bolt's backend; override texts with translations/request_analytics.<locale>.yaml in the project.
Insights
| Insight | Fires when |
|---|---|
| ⚙️ The numbers cannot be trusted | a day without page views after 14 busy ones; the site's own host counted as a referral; ≥ 30 % of visits without a referrer at < 1.1 pages per visit |
| 🔧 Broken links that lose visitors | a missing page linked from the site, or requested ≥ max(k, 10) times from elsewhere; suggests the page probably meant |
| 🔧 Where the lost visits went | visits fell ≥ 20 % (from ≥ 300), split by channel and landing page |
| 🔧 A browser or device stopped working well | its pages per visit fell ≥ 25 % while others changed < 10 % |
| 🚀 A language visitors want | ≥ 10 % and 100 visits ask for a language the site doesn't have |
| 🔧 A translation that doesn't reach its visitors | ≥ 5 % of visits prefer a site language that gets less than half that share of views |
| 🔧 / 🚀 Searched for, but not found | a term searched ≥ max(k, 20) times: 🔧 hard to find when a page has every word, 🚀 missing when none does |
| ⚖️ A translation nobody uses | < 1 % of page views and visits, from 1 000 page views |
Kinds: ⚙️ setup (comes first, and hides the insights that rely on the doubted data), 🔧 fix, 🚀 grow, ⚖️ decide. Changes compare the last 28 complete days with the 28 before; the rest uses the last 90 complete days. Today is never included. Insights resolve themselves when the numbers recover, so there is nothing to dismiss. They are computed on the server, at most once a day, and cached. With two or more fixes, the Analytics menu icon turns into a warning.
Deleting statistics removes every aggregate, raw row and spool file of the chosen days in one transaction, and logs who did it. Only whole days can be deleted. With several web servers, only the spool of the server handling the request is cleared. Backups are not affected.
Domain aliases
A redirect from a second domain (example.org → example.com) never shows up as a Referer, so the alias is counted on
the redirect itself:
| Mode | How | Needs |
|---|---|---|
count (default) |
The extension answers the alias host, counts the hop and redirects to target, keeping path and query |
The alias domain points to this application (with a certificate) and is allowed by framework.trusted_hosts |
tag |
Your registrar or web server redirects to target?ra_via=<alias>; the landing page carries the alias |
A redirect to a fixed URL |
aliases.hosts may also hold markers that are not hosts, e.g. poster-a2 for a QR code pointing to
https://example.com/?ra_via=poster-a2. Only listed markers are stored. Redirects are sent with
Cache-Control: no-store and always stay on target.
Security and privacy
- Access: only the roles of
access.view/access.delete, with a full login ("remember me" is not enough). Others see no menu item, card or page. - Endpoints: the page loads its numbers from backend-only endpoints that require the session, a CSRF token in a
header, and a same-origin request. Every response is
no-store, can't be framed, sniffed or embedded. - Untrusted input: URLs, Referers, UTM values and search terms are normalised to safe whitelists before they are
stored (e.g.
/a/<script>is stored as/a/%3Cscript%3E), checked again when read from the spool, and escaped when shown. - At rest: files are owner-and-group only and never in the public folder. Deleted rows are overwritten
(
secure_delete);request-analytics:install --vacuumalso compacts an older SQLite file. - Stored: daily counters only, each dimension in a separate table, so no row describes a single visitor. Raw rows carry an hour and live only until the next rollup. No IP, identifier, raw header or exact time.
- Disguised bots: a client claiming to be Chrome 90+ whose Client Hints or fetch headers contradict its User-Agent is counted as a bot. One odd header alone never is.
Limitations
- No unique visitors, sessions, bounce rate or time on page (they need an identifier).
- No screen sizes, scroll depth or clicks (they need JavaScript).
- No countries (the IP address is never used) and no exact OS versions or device models (browsers freeze them).
- iPads count as macOS desktops: they send a Mac User-Agent.
- No page × device or page × language breakdowns: those dimensions are stored separately on purpose.
- A bot that imitates every header of a browser is counted as a visitor.
- Numbers are as fresh as the last rollup.
Development
composer install
vendor/bin/phpunit # unit and security suites, on in-memory SQLite
vendor/bin/phpstan analyse --memory-limit=1G
vendor/bin/ecs check src tests
vendor/bin/rector process --dry-run
node .github/scripts/check-template-scripts.mjs
Database tests against a server:
docker run -d --rm --name ra-mysql -e MYSQL_ROOT_PASSWORD=ra -e MYSQL_DATABASE=ra -p 13306:3306 mysql:8.4
RA_TEST_DATABASE_URL='mysql://root:ra@127.0.0.1:13306/ra?serverVersion=8.4' vendor/bin/phpunit --group database
The security tests (tests/Security/) push the payloads of tests/Support/Payloads.php (XSS, template and SQL
injection, CRLF, path traversal, Unicode tricks, …) through every input the extension reads. CI runs everything on PHP
8.2 to 8.5 and against MySQL 8.4, MariaDB 11.4 and PostgreSQL 16, with at least 95 % line coverage.
To try a local checkout in a Bolt project:
composer config repositories.request-analytics '{"type":"path","url":"../bolt-server-analytics"}'
composer require tomvondracek/bolt-request-analytics:@dev
bin/console extensions:configure --with-config
License
MIT. Device, browser, OS and bot icons are from Font Awesome Free 5.15.4, CC BY 4.0.

