Site Statistics

Privacy-first site analytics for your Larapen site. Track page views, unique visitors, referrers, countries, browsers, platforms, search keywords, and marketing campaigns — without third-party scripts or cookies.

Use Cases

Portfolio or Agency Site

You run a portfolio site and want to understand which projects attract the most attention.

• See which portfolio pages get the most views and from which countries.
• Identify top referrer domains driving traffic to your site.
• Track daily and weekly trends without relying on Google Analytics or other third-party tools.

Content-Driven Site with Blog

You publish articles and want to measure their performance over time.

• Compare page views across different time periods (7 days, 30 days, 90 days, 1 year).
• Identify the browsers and platforms your audience uses to optimize for compatibility.
• Use the device type breakdown (desktop vs. mobile vs. tablet) to prioritize responsive design efforts.

Privacy-Conscious Organization

You need basic analytics without embedding third-party tracking scripts or setting cookies.

• All data stays on your own server: no external API calls for tracking (GeoIP is optional).
• Visitor uniqueness is determined via a hashed fingerprint, not cookies or persistent identifiers.
• Configurable data retention automatically purges old records.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+
• MySQL 8.0+

Installation

Step 1: Place the Add-on

Copy or symlink the stats folder into your Larapen "extensions/addons" directory:

Step 2: Activate the Add-on

Go to Admin → Add-ons → Installed Add-ons and activate Site Statistics.

Step 3: Run Migrations

This creates 8 tables: stats_page_views, stats_daily, stats_referrers, stats_countries, stats_browsers, stats_platforms, stats_utm_visits, and stats_utm_daily.

Step 4: Set Permissions

The add-on registers 3 permissions (see Permissions). Assign them to admin roles via Admin → Users → Roles & Permissions.

Step 5: Configure (Optional)

Navigate to Admin → Statistics → Settings to adjust tracking options, data retention, and display preferences. See Configuration.

Configuration

All settings are managed in Admin → Statistics → Settings (stored in the settings table, group stats). Defaults come from config/stats.php.

Setting	Description	Default
stats_enabled	Master switch to enable or disable page view tracking. When disabled, no new data is collected, but existing data remains accessible.	true
stats_retention_days	Number of days to keep raw page view data. Older records are automatically purged daily. Set to 0 to keep data indefinitely.	90
stats_exclude_bots	Exclude known bots and crawlers (Googlebot, Bingbot, etc.) from statistics.	true
stats_exclude_admins	Exclude logged-in admin users from being tracked.	true
stats_track_unique	Track unique visitors using a SHA-256 hash of IP + User-Agent (privacy-friendly, no cookies).	true
stats_geoip_enabled	Resolve visitor IP addresses to countries using the core GeoIP library.	true
stats_per_page	Number of rows shown per page in admin statistics tables.	25
stats_utm_tracking_enabled	Enable automatic capture of UTM parameters (source, medium, campaign, term, content) from incoming URLs.	true

Admin: Overview Dashboard

The overview page (Statistics → Overview) provides a comprehensive snapshot of your site’s traffic. All views accept a ?period= query parameter to change the time range.

Period Selector

A dropdown button available on all statistics pages lets you switch between time periods:

Value	Label
7d	Last 7 days
30d	Last 30 days (default)
90d	Last 90 days
365d	Last 365 days

Dashboard Widget

A traffic summary widget is automatically injected into the main admin dashboard. It displays:

• Today’s Views: total page views for the current day
• Today’s Unique Visitors: unique visitor count for the current day
• This Week’s Views: total views for the current week
• This Month’s Views: total views for the current month
• Trend indicator: percentage change vs. yesterday
• Mini chart: 30-day traffic chart (desktop) / 7-day chart (mobile)

Overview Charts & Metrics

The full overview page includes:

• Summary cards: Total Views and Unique Visitors for the selected period
• Traffic chart: stacked bar chart showing views vs. unique visitors over time
• Top 10 Pages: most viewed pages with view counts
• Top 10 Referrers: top referrer domains driving traffic
• Top 10 Countries: countries by view count
• Top 10 Browsers: browser distribution
• Device type breakdown: desktop, mobile, and tablet proportions shown as progress bars
• Top Platforms: OS distribution (Windows, macOS, Linux, Android, iOS, etc.)

Admin: Reports

Each report provides a dedicated, paginated view for a specific data dimension. All reports support the period selector and respect the stats_per_page setting.

Pages Report

Route: Statistics → Pages

A paginated table of all tracked page paths showing:

• Rank: position by total views
• Path: the URL path (e.g. /about, /portfolio/my-project)
• Views: total page views in the selected period
• Unique Visitors: unique visitor count for that page

Referrers Report

Route: Statistics → Referrers

A paginated table of referrer domains showing:

• Rank: position by total hits
• Domain: the referring domain (e.g. google.com, twitter.com)
• Hits: number of referral visits

Countries Report

Route: Statistics → Countries

A paginated table of visitor countries showing:

• Rank: position by total views
• Country: ISO country code badge + country name
• Views: total views from that country
• Unique Visitors: unique visitors from that country

Browsers Report

Route: Statistics → Browsers

A paginated table of detected browsers showing:

• Rank: position by total views
• Browser: browser name with icon (Chrome, Safari, Firefox, Edge, etc.)
• Share: percentage of total views, displayed as a progress bar
• Views: total views for that browser

Platforms Report

Route: Statistics → Platforms

A paginated table of detected operating systems showing:

• Rank: position by total views
• Platform: OS name with icon (Windows, macOS, Linux, Android, iOS, Chrome OS)
• Share: percentage of total views, displayed as a progress bar
• Views: total views for that platform

Admin: Keywords

The Keywords section (Statistics → Keywords) provides insight into how visitors find your site through UTM parameter tracking (marketing campaigns).

UTM Parameter Tracking

UTM tracking automatically captures marketing campaign parameters from incoming URLs. When a visitor arrives via a URL containing UTM parameters (e.g., ?utm_source=newsletter&utm_campaign=spring_sale), the data is recorded and displayed in the Keywords section.

Tracked Parameters

Parameter	Description	Example
utm_source	Traffic source (required for tracking to activate)	google, newsletter, facebook
utm_medium	Marketing medium	cpc, email, social
utm_campaign	Campaign name	spring_sale, product_launch
utm_term	Search term or keyword	web+design, laravel+cms
utm_content	Ad or link variant (for A/B testing)	banner_v1, sidebar_link

Reports

UTM data is available in two dedicated tabs within the Keywords section:

• UTM Terms: shows all tracked utm_term values with visit counts, sources, and landing pages
• UTM Campaigns: shows all tracked utm_campaign values with visit counts, sources, and mediums

The overview page also shows summary cards with total UTM visits and unique UTM visitors for the selected period.

Admin: Settings

The settings page (Statistics → Settings) is organized into four sections:

Tracking Options

Toggle switches for controlling what data is collected:

• Enable Tracking: master switch to start/stop data collection
• Track Unique Visitors: enable SHA-256 fingerprint-based unique visitor tracking
• Enable Country Detection: resolve IPs to countries via GeoIP
• Exclude Bots: filter out known crawlers and bots
• Exclude Admin Users: don’t track logged-in admin users

Data Management

• Data Retention: dropdown to select retention period (Unlimited, 30, 60, 90, 180, 365, or 730 days)
• Items Per Page: dropdown to select pagination size (10, 15, 25, 50, or 100 items)

UTM Tracking

Toggle to enable or disable automatic capture of UTM parameters from incoming URLs. When enabled, the tracking middleware extracts utm_source, utm_medium, utm_campaign, utm_term, and utm_content from visitor URLs.

Privacy Notice

An informational box reminding administrators that the add-on is privacy-friendly: no third-party scripts, no cookies, and all visitor fingerprints are hashed.

Updating

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

Step 3: Clear Caches

Step 4: Verify

Visit Statistics → Overview and confirm that data is displaying correctly. Check the settings page to verify your configuration is preserved.

Troubleshooting

No data is being recorded

• Check that stats_enabled is set to true in Statistics → Settings.
• Verify the add-on is activated in Admin → Add-ons.
• If you are logged in as an admin, check that stats_exclude_admins is not enabled (or test in a private/incognito browser window).
• Ensure the migrations have been run (php artisan migrate): the stats_page_views table must exist.

Country data is missing or shows “Unknown”

• Verify stats_geoip_enabled is true.
• Check that the core GeoIP driver is configured correctly in Admin → Settings → GeoIP.
• Local/private IPs (127.0.0.1, 192.168.x.x, etc.) cannot be resolved and will show as unknown.
• If using an API-based GeoIP driver, check that the API key is valid and has not exceeded rate limits.
• For production, consider using the MaxMind Database driver (maxmind_database) with the GeoLite2-City.mmdb file for reliable offline lookups.

Dashboard widget is not showing

• The widget is injected via a view composer. Ensure the add-on is active and the ServiceProvider has booted.
• Clear the view cache: php artisan view:clear.
• Verify the user has the stats.view permission.

Statistics pages show “No data available”

• If the add-on was just installed, wait for some front-end traffic to be recorded.
• Try changing the period selector to a wider range (e.g. 90 days or 365 days).
• Check if data retention has purged older records: adjust stats_retention_days if needed.

Bot traffic is inflating statistics

• Enable stats_exclude_bots in settings. This filters out 30+ known bot patterns.
• Note that some bots use legitimate-looking User-Agent strings and may not be detected. Review the stats_page_views table’s is_bot column to audit.

UTM data is not being recorded

• Check that stats_utm_tracking_enabled is set to true in Statistics → Settings.
• UTM tracking requires at minimum the utm_source parameter in the URL. URLs without utm_source are ignored.
• Verify URLs contain valid UTM parameters: ?utm_source=test&utm_term=keyword.
• The main stats tracking must also be enabled (stats_enabled) for UTM tracking to work.

High database storage usage

• Reduce the stats_retention_days setting to a shorter period.
• The daily scheduled task at 3:00 AM automatically purges old data. Ensure your Laravel scheduler is running: php artisan schedule:work (or configured via cron).
• The stats_page_views table grows fastest. Aggregate tables (stats_daily, etc.) are much smaller since they store one row per dimension per day.

Performance concerns with high traffic

• The middleware processes asynchronously after the response is sent: it does not add latency to page loads.
• All statistics queries use aggregate tables with proper indexes, not the raw stats_page_views table.
• For very high traffic sites, consider reducing retention to 30 days and using the offline MaxMind GeoIP driver to avoid external API calls.