Laravel Visitor Laravel Package

Getting Started

1. Install the package update and publish any new config/migrations:

   composer update <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   php artisan vendor:publish --tag=<package>-migrations
   php artisan migrate
   

2. Run the 1.1 migration on a staging copy first. The migration changes how visits are identified as bot, blocked, or verified, so verify existing rows still classify correctly before production.
3. Look first at the package config file for:
   • bot/crawler allowlists and blocklists
   • middleware registration
   • Filament resource/reporting options
   • cache and retention settings
4. Open the Filament reporting page and filter by the new visit classifications: bot, blocked, and verified.
5. First practical use case: review recent traffic, confirm known search engine crawlers are marked verified, confirm suspicious agents are marked bot, and test the new button-press blocking flow against a staging agent.

Implementation Patterns

Traffic classification and reporting

Use the updated visit model/scopes to drive dashboards and exports:

$verified = Visit::query()->verified()->latest()->paginate();
$bots = Visit::query()->bots()->latest()->paginate();
$blocked = Visit::query()->blocked()->latest()->paginate();

Prefer these scopes over raw column checks so future classification changes remain centralized.

Middleware placement

Register the detection middleware in the appropriate HTTP stack:

• Use global middleware only if every request, including APIs, should be classified.
• Use the web group for browser-facing traffic.
• Exclude health checks, webhooks, asset routes, and internal service calls where blocking would cause operational issues.

Keep middleware ordering intentional: authentication and tenant resolution should usually run before reporting/blocking decisions that depend on the authenticated user or tenant.

Review-and-block workflow

Use the Filament report as an operational queue:

1. Filter to bot traffic.
2. Inspect repetitive agents, paths, or request patterns.
3. Use the button-press block action for confirmed malicious agents.
4. Confirm the block is effective immediately, especially across multiple app servers.
5. Re-check the blocked visit report after deployment to ensure requests are being rejected as expected.

For teams with multiple environments, mirror only confirmed rules from staging to production rather than copying all observed agents.

Handling probing and scraping detection

Treat automatic probing/scraping recognition as a signal, not an unconditional ban. Recommended pattern:

• Let the package classify and report first.
• Alert on spikes in probing/scraping classifications.
• Apply blocking gradually: monitor-only, then block high-confidence agents, then broaden rules.
• Keep an allowlist for uptime monitors, payment providers, search crawlers, partner integrations, and internal tools.

Custom rules and extension points

Put organization-specific agents and exceptions in config rather than hard-coding checks in middleware. If the package exposes detection extension points, use them for:

• custom verified-bot validation
• tenant-specific allowlists
• request-path exclusions
• custom block responses

Keep custom detection rules small, testable, and documented next to the config.

Gotchas and Tips

• Run the 1.1 migration before relying on the new reports. Existing visit rows may need reclassification or backfilling, depending on the package’s migration behavior.
• Test migration performance on large visit tables. Adding or changing classification columns/indexes can lock or slow large tables; use a staging replica and a maintenance window if needed.
• False positives are the main risk. User-agent strings are spoofable. Treat “verified” as stronger evidence than “bot,” and avoid blocking legitimate crawlers based only on a generic agent pattern.
• Clear caches after using the Filament block action. Button-press blocking should be immediate, but cached blocklists can delay enforcement. Confirm cache invalidation works across all app servers.
• Check multi-server consistency. If blocking state is cached locally, one node may continue serving a blocked agent until cache expiry. Prefer a shared cache store.
• Choose block responses deliberately. A 403 is clear but may break integrations; a 410 or empty response can be preferable for scraping. Avoid returning HTML error pages to API clients.
• Do not let reporting middleware break webhooks. Exclude webhook and callback routes, or verify that blocked requests cannot interfere with payment, messaging, or provisioning flows.
• Review Filament authorization. Ensure only intended admin roles can view traffic reports and trigger blocking actions.
• Large reports need filters. Use date ranges, classification filters, and agent/path searches rather than loading full visit tables.
• Probing detection may flag legitimate security testing. Allowlist known penetration-test or monitoring sources during approved windows.
• Keep retention and privacy in mind. Visit records can contain IP addresses and request paths; configure pruning and avoid exporting raw data unnecessarily.
• Debug with controlled requests. Use curl with specific user agents from staging, then inspect the resulting visit record and classification before enabling blocking in production.