Search by

tomvondracek / bolt-request-analytics

Vondry

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!

Vondry

Statistics

Installs: 11

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-15 20:48 UTC

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: page views of the last 30 days with their change, a chart of the days and today's count

The Analytics page: period bar, headline figures and insights. Click to watch a scroll through the whole page.

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, ALTER and DROP: 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.yaml next 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 --vacuum also 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.