simba-jirira-source / laravel-analytics

v0.6.1 2026-08-16 17:06 UTC

Requires

• php: ^8.3
• illuminate/auth: ^12.0||^13.0
• illuminate/database: ^12.0||^13.0
• illuminate/http: ^12.0||^13.0
• illuminate/routing: ^12.0||^13.0
• illuminate/support: ^12.0||^13.0
• illuminate/validation: ^12.0||^13.0
• illuminate/view: ^12.0||^13.0
• livewire/livewire: ^4.0

Requires (Dev)

• larastan/larastan: ^3.9
• laravel/agent-detector: ^2.0
• laravel/chisel: ^0.1
• laravel/pao: ^1.0
• laravel/pint: ^1.29
• laravel/prompts: ^0.3
• orchestra/testbench: ^10.0||^11.0
• pestphp/pest: ^4.6||^5.0
• pestphp/pest-plugin-laravel: ^4.1||^5.0
• pestphp/pest-plugin-type-coverage: ^4.0.4||^5.0
• phpstan/extension-installer: ^1.4

MIT

• simba-jirira-source

• analytics
• laravel
• tracking
• privacy
• self-hosted
• laravel-package
• first-party
• web-analytics
• simba-jirira-source
• application-analytics
• visitor-analytics

Published on Packagist.org on 2026-08-16 17:10 UTC

README

First-party, self-hosted application analytics for Laravel.

Track page views, unique visitors, HTTP errors, and optional IP bans in your application's own database. Enable an optional Livewire 4 dashboard when you want KPIs, trends, and management screens inside your Laravel app — without routing analytics data through a third-party platform by default.

See docs/SCREENSHOTS.md for recommended dashboard screenshots.

Why Laravel Analytics?

Laravel Analytics provides first-party analytics designed specifically for Laravel applications. It is intended for teams who want analytics data stored alongside their application rather than depending entirely on an external analytics service.

• Analytics data stays in the application's own database
• Tracking is disabled by default
• Raw IP storage is disabled by default
• Privacy-aware visitor hashing
• Laravel-native package architecture (service provider, middleware, contracts, Artisan commands)
• HTTP error analytics alongside traffic metrics
• Optional exact IPv4/IPv6 access controls
• Optional Livewire 4 dashboard with authorization gates
• Configurable retention and pruning
• SQLite, MySQL, and PostgreSQL tested in CI
• Laravel 12 and 13 tested in CI
• PHP 8.3–8.5 tested in CI

Pre-1.0 development. See GitHub Releases and CHANGELOG.md for released versions.

Key Features

Capability	Default	Notes
Page views	Off	Middleware-based traffic tracking
Unique visitors	Privacy-aware hashing	Hashed identifiers; raw IP off by default
HTTP error analytics	Off	Fingerprinted error aggregation
Exact IPv4/IPv6 bans	Off	Optional middleware enforcement
Retention / pruning	90 days	analytics:prune command
Livewire dashboard	Off	Gate or invokable authorization required
Cross-database support	SQLite, MySQL, PostgreSQL	Integration tests in CI
Replaceable contracts	Configurable	Visitor, traffic, and error recorders
Composer security auditing	In CI and composer verify	security.yml workflow

How It Differs

Capability	Laravel Analytics	External analytics integration
Data stored in application database	Yes	Usually no
Self-hosted analytics data	Yes	Depends on provider
Page views	Yes	Yes
Unique visitors	Yes	Yes
HTTP error analytics	Yes	Usually separate tooling
Exact IP access controls	Yes	Usually separate
External analytics account required	No	Usually yes
Laravel-native Livewire dashboard	Yes (optional)	Depends on provider
SQLite / MySQL / PostgreSQL CI	Yes	Not applicable

Quick Start

1. Install the package and publish config plus migrations (see Installation).
2. Run migrations.
3. Enable features explicitly in config/analytics.php:

'enabled' => true,

'tracking' => [
    'traffic' => true,
    'errors' => true,
],

'ip_banning' => [
    'enabled' => false,
],

'dashboard' => [
    'enabled' => true,
    'authorization' => 'viewAnalyticsDashboard',
    'middleware' => ['web', 'auth'],
],

1. Define dashboard authorization in your application:

use Illuminate\Support\Facades\Gate;

Gate::define('viewAnalyticsDashboard', fn ($user) => /* your policy */);

1. Visit /analytics (or your configured dashboard.path) when the dashboard is enabled.

When enabled is true and tracking toggles are on, middleware is registered on the web group automatically.

Installation

composer require simba-jirira-source/laravel-analytics

The service provider registers automatically via Laravel package discovery.

Publish configuration

php artisan vendor:publish --tag=analytics-config

Publish and run migrations

Migrations are not loaded automatically. Publish them, then migrate:

php artisan vendor:publish --tag=analytics-migrations
php artisan migrate

Publish everything (optional)

php artisan vendor:publish --tag=analytics
php artisan migrate

Tag	Contents
analytics-config	config/analytics.php
analytics-migrations	Database migrations
analytics-views	Blade / Livewire views
analytics-lang	Translation files
analytics-assets	Public assets

See docs/INSTALLATION.md for the full walkthrough.

Privacy by Default

By default the package:

• does not enable tracking, banning, or the dashboard;
• does not store raw IP addresses;
• hashes visitor identifiers using application-specific salt;
• does not associate authenticated users unless configured;
• excludes dashboard routes from self-tracking.

See docs/PRIVACY.md. This package provides technical privacy controls but does not itself make an application compliant with any specific privacy law or regulatory framework.

Compatibility

Requirement	Supported
PHP	8.3+ (8.3–8.5 in CI)
Laravel	12, 13
Livewire	4 (required dependency; dashboard is optional via config)
Databases	SQLite, MySQL, PostgreSQL (integration CI)

Dashboard

The optional Livewire 4 dashboard provides overview metrics, traffic trends, top pages and referrers, error details, and IP ban management when explicitly enabled and authorized.

See docs/DASHBOARD.md.

Artisan Commands

Command	Description
analytics:prune	Remove records older than the configured retention window
analytics:ip-ban {ip}	Ban an exact IPv4 or IPv6 address
analytics:ip-unban {ip}	Remove an active ban

Pruning is not scheduled automatically. See docs/RETENTION.md.

Configuration

All settings live in config/analytics.php. See docs/CONFIGURATION.md for every key.

Extension points (contracts):

• SimbaJirira\LaravelAnalytics\Contracts\VisitorIdentifier
• SimbaJirira\LaravelAnalytics\Contracts\AnalyticsRecorder
• SimbaJirira\LaravelAnalytics\Contracts\ErrorRecorder

Public integration uses Laravel contracts, config keys, middleware aliases, and Artisan commands. There is no facade; a first-party event API is planned for a future release.

Testing

composer install
composer verify

Individual gates:

composer test              # prepare, PHPStan, Pint, type coverage, Pest
composer test:types        # Pest type coverage (skipped automatically on Windows)
composer analyse           # PHPStan (level 7)
composer lint:check        # Pint
composer test:unit         # Pest (sequential on Windows, parallel elsewhere)
composer test:database     # cross-database integration tests
composer security:audit    # Composer security audit

PHPStan level 7 via Larastan. Run composer run prepare before composer analyse when analysing locally.

Documentation

Topic	Document
Installation	docs/INSTALLATION.md
Configuration	docs/CONFIGURATION.md
Privacy	docs/PRIVACY.md
Architecture	docs/ARCHITECTURE.md
Visitor identification	docs/VISITOR_IDENTIFICATION.md
Dashboard	docs/DASHBOARD.md
Retention	docs/RETENTION.md
Releases	docs/RELEASES.md
GitHub repository setup	docs/GITHUB_REPOSITORY_SETUP.md
Screenshot guidance	docs/SCREENSHOTS.md
Contributing	.github/CONTRIBUTING.md
Security policy	.github/SECURITY.md
Changelog	CHANGELOG.md

Contributing

Please read CONTRIBUTING.md before opening a pull request. See CODE_OF_CONDUCT.md.

Security

Report security issues privately. See SECURITY.md.

Versioning

This project follows Semantic Versioning. APIs may change before 1.0.0. See CHANGELOG.md.

License

The MIT License. See LICENSE.md.

Credits

• simba-jirira-source