Laravel Route Statistics Laravel Package

Technical Evaluation

Architecture Fit

• Observability & Analytics: The package excels at providing granular route-level analytics (e.g., per-user/team usage, HTTP methods, status codes, and parameters). This aligns well with Laravel applications needing usage tracking, auditing, or feature adoption metrics without heavy instrumentation.
• Lightweight Design: Leverages aggregation (hourly/daily/monthly) to minimize database bloat, making it suitable for high-traffic or long-running applications where raw request logging would be prohibitive.
• Extensibility: Supports custom context data (e.g., team_id) and conditional logging (via middleware/request macros), allowing integration with existing auth/team systems or selective instrumentation.
• Dependency: Relies on bilfeldt/laravel-request-logger, which may introduce indirect complexity (e.g., queued logging, custom loggers).

Integration Feasibility

• Laravel Ecosystem: Native support for Laravel 8–13 and PHP 7.4–8.5 ensures compatibility with most modern stacks. Breaking changes in v4.0+ (e.g., PHP 8.2+ requirement) may necessitate version alignment.
• Database Schema: Publishes a single migration (route_statistics table) with fields like user_id, team_id, route, parameters, and status. No foreign key constraints by default, requiring manual setup if referencing custom user/team models.
• Middleware Hooks: Three activation methods (global middleware, route-specific middleware, or ad-hoc request macros) provide flexibility but require strategic placement to avoid performance overhead on non-critical routes.
• Artisan Commands: route:stats and route:unused offer quick insights but assume the package is already integrated.

Technical Risk

• Performance Impact:
  • Global middleware: Logs every request, risking database load in high-throughput systems. Mitigate by using route-specific middleware or conditional logging.
  • Aggregation: While efficient, second-level aggregation (e.g., hourly/day/month) may complicate queries if custom reporting is needed.
• Data Retention: No built-in TTL/purging mechanism; requires manual cleanup (e.g., via Laravel schedules or custom jobs).
• Custom User/Team Models: Default user() relationship assumes Laravel’s App\Models\User. Polyfill required if using custom auth systems (e.g., Spatie\Permission or Brefink\Teams).
• Parameter Logging: Route parameters are stored as JSON, which may bloat storage for complex routes (e.g., nested resources). Consider selective logging (e.g., only id fields).
• Queued Logging: Enabled by default in v2.1+, but queue failures (e.g., dead letters) could silently drop logs. Monitor failed_jobs table.

Key Questions

1. Scope of Logging:
   • Should all routes be logged, or only critical paths (e.g., /api/v1/*)?
   • How will unauthenticated traffic be handled (e.g., IP-based aggregation)?
2. Data Retention:
   • What’s the lifecycle of logged data (e.g., 30 days, 1 year)?
   • Will custom purging be needed (e.g., via Laravel schedules)?
3. Customization:
   • Are custom user/team models in use? If so, how will the user() relationship be configured?
   • Are route parameters needed for all routes, or only specific ones?
4. Performance:
   • What’s the expected request volume? Will global middleware be viable, or is selective middleware required?
   • Are database indexes needed for query performance (e.g., on user_id, route, date)?
5. Monitoring:
   • How will logging failures (e.g., queue timeouts) be alerted?
   • Will custom reports be built on top of this data (e.g., via Laravel Scout or third-party tools)?

Integration Approach

Stack Fit

• Laravel Versions: Supports 8–13 (with v4.x requiring 10+). Upgrade path:
  • If on Laravel <10, use v3.x (PHP 8.1+).
  • If on Laravel 10–13, use v4.x (PHP 8.2+).
• PHP Versions: Align with Laravel’s requirements (e.g., PHP 8.5 for Laravel 13).
• Database: Compatible with MySQL, PostgreSQL, SQLite (Laravel’s default drivers). No schema migrations for custom databases.
• Queue System: Uses Laravel queues for logging. Ensure database/Redis queue drivers are configured if relying on queued logging.
• Auth Systems:
  • Defaults to Laravel’s User model. For custom auth (e.g., Brefink\Teams), configure the user_model in config/route-statistics.php.
  • Supports team-based aggregation (e.g., team_id), useful for SaaS apps.

Migration Path

1. Dependency Alignment:
   • Update composer.json to target the correct Laravel/PHP version (e.g., "bilfeldt/laravel-route-statistics": "^4.0" for Laravel 10+).
   • Run composer update bilfeldt/laravel-route-statistics.
2. Schema Migration:
   • Publish and run migrations:

     php artisan vendor:publish --provider="Bilfeldt\LaravelRouteStatistics\LaravelRouteStatisticsServiceProvider" --tag="migrations"
     php artisan migrate
     

   • Customization: Add indexes if needed (e.g., user_id, route, date).
3. Configuration:
   • Publish config:

     php artisan vendor:publish --provider="Bilfeldt\LaravelRouteStatistics\LaravelRouteStatisticsServiceProvider" --tag="config"
     

   • Update config/route-statistics.php for:
     • user_model (if not App\Models\User).
     • queue_connection (if not using default).
     • log_parameters (disable if not needed).
4. Middleware Integration:
   • Option A (Global): Add to bootstrap/app.php:

     $middleware->prepend(\Bilfeldt\LaravelRouteStatistics\Http\Middleware\RouteStatisticsMiddleware::class);
     

   • Option B (Selective): Apply to route groups:

     Route::middleware(['routestatistics'])->group(function () {
         // Critical routes only
     });
     

   • Option C (Ad-hoc): Use in controllers:

     $request->routeStatistics();
     

5. Testing:
   • Verify logs appear in route_statistics table.
   • Test Artisan commands:

     php artisan route:stats --route="dashboard"
     php artisan route:unused
     

Compatibility

• Existing Middleware: No conflicts if placed before other middleware (e.g., auth). Ensure RouteStatisticsMiddleware runs after request parsing but before response generation.
• Custom Requests: Works with Laravel’s Request class. No issues with API resources or form requests.
• Third-Party Packages:
  • Auth: Compatible with Laravel Breeze, Sanctum, Passport, etc.
  • Teams: Works with Brefink\Teams or similar if team_id is added to context.
  • Logging: Uses Laravel’s logging facade; no conflicts with Monolog or other loggers.

Sequencing

1. Development:
   • Start with selective middleware (e.g., API routes) to test impact.
   • Use route:stats to validate data collection.
2. Staging:
   • Enable global middleware and monitor database growth.
   • Set up purging (e.g., daily cleanup of logs >30 days old).
3. Production:
   • Roll out with feature flags (e.g., toggle middleware via config).
   • Monitor queue failures and database performance.
   • Build dashboards (e.g., using Laravel Nova, Filament, or custom views).

Operational Impact

Maintenance

• Database:
  • Schema: Minimal (single table). No complex relationships.
  • Indexes: Add manually if querying by user_id, route, or date.
  • Backups: Include route_statistics in database backups if retention >7 days.
• Configuration:
  • Centralized in config/route-statistics.php. Easy to override via environment variables.
• Updates:
  • Minor: Safe (e.g., v4.3 → v4.4). Follow [UPGRADE.md](https://github.com/bilfeldt/laravel-route-statistics/blob/main/