Laravel Model Stats Laravel Package

Getting Started

1. Install the package

   composer require jhumanj/laravel-model-stats
   

2. Publish the config (and assets/migrations if the package ships them)

   php artisan vendor:publish --provider="Jhumanj\ModelStats\ModelStatsServiceProvider"
   

   The published config/model-stats.php is the single most important file — it is where you register the models that appear on the dashboard, set the route prefix, and configure middleware.

3. Register the models you care about in config/model-stats.php. The package is config-driven: a model only shows up on the dashboard if it is listed there. Start with three to five tables that matter to the business (e.g. User, Order, Post) rather than every model in the app.

4. Run migrations if the published migrations add a stats/snapshot table, then hit the dashboard route (default /model-stats in most versions).

5. First use case: point it at your core tables and use the growth-over-time view as a lightweight "is the product growing?" dashboard — useful in a weekly standup or as a sanity check after a deploy. Treat it as read-only reporting, not a metrics platform; it is not a replacement for a proper analytics/BI tool.

Implementation Patterns

• Config as the registry. Keep the model list in config/model-stats.php and think of it as the dashboard menu. Order the entries by importance — the first models are the ones people see.
• Gate it behind admin middleware. Set the package middleware in config to something like ['web', 'auth', 'can:viewModelStats'] and define a viewModelStats Gate that checks for an admin role. This is the single most common production integration point.
• Environment-aware enablement. Only expose the dashboard in local/staging, or register the service provider conditionally, so production users never see it unless you deliberately want them to. A typical pattern: enable it always in local, and in production only behind your admin guard.
• Link it from your existing admin panel. If you already run Nova/Filament/Backpack, don't duplicate navigation — add a menu item that links to /model-stats. The package's dashboard is a self-contained page, so a link/iframe is the cleanest integration.
• Snapshot workflow (if your version persists stats). If the package stores daily rows rather than querying live, add its artisan command to app/Console/Kernel.php (or the modern routes/console.php schedule) once per day. Verify whether your version is query-on-request or snapshot-based before scheduling anything — this is the one detail that varies most between releases.
• Authorization at the route level. Combine config middleware with a route-level check in a service provider for defence in depth, especially if you change the route prefix.
• Custom labels. Where the config allows a label/alias per model, use it ('Users' instead of App\Models\User::class) — the raw class name is noise for non-developer stakeholders.
• Testing. Add a feature test that hits the dashboard route as an authorized user and asserts a 200, plus one as a guest asserting a redirect/403. This catches middleware regressions when you upgrade Laravel.

Gotchas and Tips

• The package is not actively developed (last release 2023). Check the composer.json constraints before installing on Laravel 11/12 — you may need to fork it, relax constraints, or pin an older Laravel. Do this spike before committing to it in a real project.
• Assets must be republished after upgrades. If the dashboard renders blank or 404s on its JS/CSS, run vendor:publish --force for the package's public assets.
• Config caching. After editing config/model-stats.php in production, run php artisan config:clear / config:cache. A model "missing" from the dashboard is almost always a cached config or a typo in the class name.
• Missing created_at indexes. Most dashboards aggregate by date on the primary table. On large tables this is a full scan. Add an index on created_at (or whatever column the package groups by) before pointing it at your orders table.
• Soft deletes distort totals. If a model uses SoftDeletes, the "total" count usually excludes trashed rows while "created per day" includes them historically. Decide which number you want and document it — someone will ask why the two charts disagree.
• Timezone mismatch. Grouping by created_at in the database's timezone vs. the app's timezone shifts daily buckets. Set DB_TIMEZONE/APP_TIMEZONE consistently or accept off-by-one-day boundaries at the edges.
• Route collisions and prefixing. If /model-stats clashes with an existing route, change the prefix in config rather than editing the package's routes. Remember route caching (route:cache) after changes.
• Authorization is not automatic. Out of the box the route is wide open behind whatever middleware you configure. Treat the default as unsafe for production and add an auth + role check explicitly.
• Large tables / read replicas. Because it queries live data in most configurations, point the package at a read replica if you have one, and avoid loading the dashboard on huge tables during business hours.
• Extension point: fork-friendly. Because the frontend is a compiled bundle, don't try to hack the views in vendor/. If you need custom charts, publish the assets/config, override the route in your own controller, or fork the package — the surface area for extension is small.
• Debugging checklist: (1) is the model in config? (2) did you config:clear? (3) is the middleware blocking you? (4) were assets published? (5) is the table actually populated? Ninety percent of "it doesn't work" reports resolve to one of these five.