Download the PHP package rpillz/laravel-visitor without Composer

Laravel Visitor

Minimalist page-visit analytics for Laravel. Records visits to an isolated SQLite database, resolves country and device info in the background, and surfaces reports through a Filament admin panel plugin — with zero impact on page load times.

Fun fact; this started as a quick way to count visitors. I was blown away to discover tens-of-thousands of bots and crawlers visiting my site every day! This quickly package evolved to be more about blocking unwanted bots... while still keeping tabs on the real(?) visitors.

Features

• All tracking runs on a queued job — never blocks a request
• Separate database connection (SQLite by default) keeps analytics data out of your main DB
• Resolves country & city from a local MaxMind GeoLite2 database (no external API calls)
• Detects device type, browser, and OS from the User-Agent string
• Anonymous by default — no user IDs or IPs stored without opt-in
• User ID tracking opt-in, overridable per-call via Visitor::anonymous()
• Bot tracking — records bots with their name and header fingerprint; unidentified non-browser requests labelled automatically
• Probe path blocking — auto-blocks scanners hitting known attack paths (wp-admin, .env, etc.)
• 404 rate-limit blocking — auto-blocks IPs that rack up too many 404s in a short window
• Request rate limiting — auto-blocks fingerprints that exceed a per-minute request threshold
• Header fingerprinting — tracks and blocks bots that rotate IPs
• Verified crawler passthrough — search engines (Google, Bing, etc.) verified via rDNS or published IP lists bypass auto-blocking
• Bot name blocking — blocks known scrapers and AI crawlers by name, even when IP-verified
• Unverified bot blocking — blocks any crawler that cannot prove its identity
• Agent allow-list — exempt specific User-Agent substrings (uptime monitors, internal crawlers) from bot-name blocking
• Managed robots.txt — optionally serve /robots.txt with Disallow rules via config
• Database-driven ignore/block list — block by IP, user ID, user agent wildcard, or header fingerprint via Filament UI; soft-ignore or hard-block (403 returned); temporary or permanent
• Block logging — records blocked requests for auditing
• Filament v5 plugin with an analytics dashboard and bot management: stats overview, visits chart, top pages, referrers, device breakdown, bot stats, bot list, and ignore/block list management

Requirements

• PHP 8.4+
• Laravel 11+
• Filament 5+ (only required for the admin panel plugin)

Installation

Run the install command:

This publishes the config file, publishes the migration, creates the SQLite database file if needed, and runs the migration. You can also do these steps manually:

Database connection

By default the package registers a visitor SQLite connection automatically, writing to storage/app/visitor.sqlite. No changes to your database.php are needed unless you want to point it at a different database:

Or set the VISITOR_DB_CONNECTION environment variable to use an existing named connection from your app.

Remote database (libSQL / Turso)

To store visit data in a remote Turso database or any libSQL-compatible endpoint, install the Turso driver:

Then configure your .env:

The package auto-registers the connection — no changes to config/database.php are needed unless you have a naming conflict (see below).

Note: The Turso driver requires the libsql PHP extension. See the turso-driver-laravel documentation for installation instructions.

Naming conflicts

The Turso driver resolves connection config from database.connections.libsql. If your app already uses that key for another database, set VISITOR_DB_CONNECTION to a unique name and define the connection manually in your config/database.php:

GeoIP setup

Country and city resolution uses a local MaxMind GeoLite2 database. Download the free GeoLite2-City.mmdb file from MaxMind (free account required) and place it at:

Override the path via VISITOR_GEOIP_DATABASE or in the config. Geo resolution is disabled by default — enable it with VISITOR_GEOIP_ENABLED=true. It is silently skipped if the database file is absent.

Usage

Automatic tracking via middleware

By default the package appends visitor.track to Laravel's web middleware group automatically, so all web routes are tracked with no extra configuration.

To disable auto-tracking and apply the middleware selectively, set auto_track to false in config/visitor.php (or VISITOR_AUTO_TRACK=false in your .env):

Then apply the alias to specific route groups:

Tracking fires in the middleware's terminate() method — after the response is sent to the browser.

Manual tracking

Use the Visitor facade anywhere in your code:

Anonymous tracking

By default (anonymous = true), no user IDs are ever stored. If you've enabled user ID storage globally (anonymous = false), you can force a specific call to skip it:

To enable user ID storage globally, set this in config/visitor.php:

Multi-tenant support

If your app serves multiple tenants, you can route each tenant's visit data and ignore list to a separate database connection. Register a resolver once at boot and the package calls it lazily on every request — no per-request wiring needed:

Both the visits table and the visitor_ignores table (including the Filament ignore list UI) will use whichever connection the resolver returns for the current request.

If no resolver is registered the package behaves exactly as normal, falling back to config('visitor.connection', 'visitor').

Per-tenant database setup

You are responsible for registering each tenant's connection in config/database.php (or dynamically via config([...])) and running the package migrations against it before tracking begins. The package ships two migration stubs — create_visits_table and create_visitor_ignores_table — that you can run against each tenant connection as part of your tenant-provisioning flow.

Per-call connection override

To route a single tracking call to a specific connection without a global resolver:

This takes priority over any registered resolver for that call only.

Pruning old records

Schedule the prune command to keep your database tidy:

The default retention period is 90 days. Override per-run:

Blocking & Bot Protection

The middleware runs active blocking logic before the request reaches your application, so malicious scanners and repeat offenders are rejected at the edge with no application overhead.

Probe path blocking

Requests hitting known scanner paths (wp-admin, .env, phpinfo, etc.) are automatically blocked and the requesting IP is added to the block list. Blocked requests receive a 404 response so scanners get no information about your stack.

Configure the paths and block duration in config/visitor.php:

The default block duration is 3 days (4320 minutes). Set to null for a permanent block, or use VISITOR_PROBE_BLOCK_DURATION to override. Set VISITOR_BLOCK_PROBES=false to disable probe blocking without touching the config file.

404 rate-limit blocking

IPs that generate too many 404 responses in a short window are automatically blocked. This catches scanners that don't match any specific probe path but are obviously enumerating your routes.

Once the threshold is exceeded, further requests from that IP return 429 until the block expires.

Header fingerprinting

The middleware computes a lightweight fingerprint from the request's HTTP headers. This fingerprint is stored alongside each visit and is used when auto-blocking — so a scanner that rotates IPs is still caught and blocked by its fingerprint.

Manual blocks via the Filament Bot List resource also prefer fingerprint-based blocks over user-agent wildcards when a fingerprint is available.

Verified crawlers

When verified_crawlers is enabled, the middleware attempts to verify a crawler using two methods:

• rDNS — the bot's IP reverse-resolves to a hostname that forward-resolves back to the same IP, with a suffix matching a known search engine domain (Googlebot, Bingbot, DuckDuckBot, Yandex, Baidu, Applebot, Qwant, PetalSearch). These domains are hardcoded and do not need configuration.
• IP lists — the bot's IP is checked against CIDR prefix lists published by crawler operators. The default list covers ClaudeBot, BingBot, Meta crawlers, GPTBot, Perplexity, and others.

Verified bots bypass probe-path and 404-rate blocking and fingerprint rate limiting. Their visits are stored with is_verified = true.

Verification results are cached per IP for cache_ttl minutes. IP list responses are cached for 24 hours.

Bot name blocking

Even verified crawlers can be blocked by name. block_verified_bots lists bot names (resolved from the User-Agent) that are rejected regardless of verification status. block_unverified_bots rejects any crawler that identifies itself by name but cannot be verified:

Search engines (Googlebot, Bingbot, etc.) are not in the block_verified_bots list by default — leave them unblocked so they continue to index your site.

Allowing specific agents

Uptime monitors, internal crawlers, and other trusted services may be detected as bots but publish no IP list and have no rDNS to verify against. Add a substring of their User-Agent to allow_agents to let them through regardless of verification status:

Each value is matched as a case-sensitive substring of the User-Agent string. An agent in this list bypasses both block_verified_bots and block_unverified_bots — it is never blocked by bot-name checks, though explicit IP/fingerprint/user-agent blocks in the ignore list still apply.

Request rate limiting

The fingerprint rate limiter counts every request from a given header fingerprint within a rolling window, catching high-volume scrapers that only hit valid pages (and would never trigger the 404 limiter):

When auto_block is true, a fingerprint that exceeds the threshold is written to the block list so subsequent requests are caught by isBlocked() immediately — no further rate-limiter checks needed.

robots.txt

The package can serve GET /robots.txt with Disallow: / entries for each listed User-agent. Useful for discouraging commercial SEO crawlers and AI scrapers that do respect robots.txt:

Leave enabled as false (the default) if your application already manages its own robots.txt. If you enable this, add robots.txt to exclude_paths so those hits are not recorded in your visit analytics.

Bots that ignore robots.txt are exactly the kind of traffic the probe-path, 404-rate, and fingerprint-rate blocking are designed to catch.

Block logging

Blocked requests are recorded by default for auditing. Disable if you do not need the log:

When enabled, blocked requests are dispatched to the queue and stored as visit records with is_blocked = true. The Visit model's default global scope excludes these from all normal queries, so they never appear in analytics — only in the raw table.

Ignore List & Block List

The ignore/block list controls what happens to a visitor:

• Ignore (tracking skipped) — the visit is silently not recorded; the request proceeds normally
• Block (is_blocked = true) — the request is rejected with a 403 before reaching your application

Entries can target:

Entries can be permanent or temporary (expires_at). Automatic blocks (from probe detection and 404 rate limiting) are flagged is_automatic = true and are distinct from manually added entries.

Managing the list

When the Filament plugin is registered, an Ignore List resource appears in the Analytics navigation group. From there you can add, edit, or remove entries.

When an ignore entry is added, all existing visit records matching that value are deleted immediately. Future visits are silently skipped.

When a block entry is added, the IP, user agent, or fingerprint is rejected at the middleware with a 403 — no application code runs at all.

The list is loaded from the database and cached for 5 minutes (visitor.ignore_list.<connection>). The cache is flushed automatically whenever an entry is added or removed.

Filament Plugin

Register the plugin in your Filament panel provider:

This adds an Analytics page to your panel at /your-panel/analytics with the following widgets and resources:

Analytics dashboard widgets

Resources

The Bot List block action uses the header fingerprint when one is recorded, falling back to a wildcard user-agent rule (*BotName*) when not.

Configuration

Horizon users: TrackVisitJob is a high-frequency, low-importance job that will flood your Horizon dashboard. Add it to the silenced array in config/horizon.php:

What Gets Recorded

Each visit record stores:

Blocked visit records (is_blocked = true) are excluded from all normal queries via a global scope on the Visit model. They are only visible in the raw table or when explicitly calling withoutGlobalScope('exclude_blocked').

GDPR Considerations

By default this package does not track personal data, but does have the option to store IP addresses, Geolocation, and user IDs, which are personal data under GDPR. Depending on your jurisdiction and use case you may need user consent before tracking, or you may want to avoid storing personal data altogether.

Default behaviour (consent-free)

Out of the box, anonymous = true and store_ip = false, so no personal data is stored. Records contain only path, referrer domain, device type, browser, OS, and session ID — none of which are personal data on their own. No consent mechanism is required.

If you want to opt in to storing user IDs and IP addresses (for richer analytics), set these in your .env:

When storing personal data you are responsible for obtaining user consent and disclosing this in your privacy policy.

Right to erasure

To delete all visit records linked to a specific user (GDPR Article 17):

Safe to call from your app's user deletion flow:

Data retention

Set a retention period and schedule the prune command so old records are automatically removed:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• RPillz
• All Contributors

License

The MIT License (MIT). Please see License File for more information.