Stock Panel Bundle Laravel Package

Getting Started

• Install the package with Composer, then publish its config and front-end assets:
  • composer require <vendor>/<package>
  • php artisan vendor:publish --tag=<package>-config (and the -assets/-views tags if present)
  • php artisan migrate only if the package ships dashboard/persistence tables — check the migration stub before running it on a shared DB.
• Look first at config/<package>.php. In v1.1.0 the charts dashboard is the headline feature, so the interesting keys are the dashboard route/prefix, the middleware/auth gate, the default chart driver, and cache TTLs. Those four settings explain most "why is my dashboard blank/403/stale" questions.
• Register the dashboard entry point (service provider auto-discovery usually handles it; confirm with php artisan about or route:list | grep dashboard). Then hit the dashboard route as an authenticated user to see the shipped example chart before touching your own data.
• First use case: replace the example chart's data source with a single Eloquent query (e.g. signups per day for the last 30 days), leave caching off initially, and verify the numbers against php artisan tinker before wiring it into the full dashboard. Getting one chart truthful is faster than debugging six at once.

Implementation Patterns

• One chart = one class (or one config array). Keep each chart's query in its own dedicated class/provider rather than a fat controller. That gives you a natural place for caching, authorization, and date-range handling, and makes charts composable across multiple dashboards.
• Dashboard composition. Treat the dashboard as a layout: define which charts appear, their grid width, and their ordering in config or a dashboard definition class, and let the package render. This keeps "add a chart to the exec dashboard" a one-line change instead of a Blade edit.
• Filter/date-range handling. Drive every chart from a single shared filter object (range, timezone, tenant/team id) instead of each chart parsing the request. Return the filter from a request object or a small DTO and pass it into chart data resolvers.
• Caching. Use Cache::remember() keyed on chart-class + filter hash + tenant id and set a TTL matched to your data refresh expectations (5–15 min is typical for operational dashboards). Invalidate explicitly on the write paths that matter, or accept the TTL as the freshness contract and document it.
• Multi-tenant scoping. Apply the tenant/team global scope inside the chart query, not in the controller, so a chart embedded elsewhere can't leak cross-tenant data.
• Livewire/Inertia integration. Wire charts to a filter component that dispatches a refresh event rather than reloading the page; on Inertia, pass chart payloads as props from the controller and let the package's front-end assets render them.
• Testing. Assert on the resolved data (the array/series the chart returns), not on the rendered SVG/canvas. Snapshot the data resolver for a fixed date range with a frozen clock (Carbon::setTestNow), and add one feature test that hits the dashboard route as an authorized and an unauthorized user.

Gotchas and Tips

• Timezone and date bucketing. GROUP BY DATE(created_at) uses the DB timezone; if the user's filter timezone differs, daily buckets drift. Convert in the query (CONVERT_TZ) or bucket in PHP for small ranges, and be consistent between the chart axis labels and the query.
• Config caching. After php artisan config:cache, any dynamic config from the dashboard definition file is frozen. Keep runtime-varying values out of config and in the database or a definition class.
• Asset pipeline. If the package ships pre-built assets, you don't need npm; if it expects a build step, publish the assets and confirm the layout includes the package's stack (@push/@vite). A blank chart area is usually a missing script tag, not a data bug.
• Authorization is opt-in. The default dashboard route is commonly middleware-guarded but not policy-guarded. Add an explicit gate/policy so non-admin users don't see revenue charts.
• N+1 and full-table scans. A chart that "works locally" on 500 rows can time out on production. Always EXPLAIN the aggregate query, add covering indexes on the grouping column, and downsample (hourly → daily) beyond ~90 days.
• Cache stampede on refresh. Many charts resolving simultaneously after a TTL expiry will hammer the DB. Stagger TTLs slightly per chart, or use Cache::flexible()/a lock so only one request recomputes.
• Stale cache after deploy. If chart payload shape changes between versions, bump a cache key prefix version so old serialized payloads don't render as broken charts.
• Extension points. Prefer the package's chart base class and data-provider contract over overriding published views — published views don't get updates, and v1.1.0's dashboard layout changes will silently diverge from your copy. Keep customizations in subclasses and config.
• Upgrading. Pin the version in composer.json and read the changelog for config key renames around the dashboard; re-publish the config with --force only after diffing against your customized copy.