Laravel Pennant Dashboard Laravel Package

Getting Started

1. Install the package and publish its migrations:

   composer require <vendor>/pennant-dashboard
   php artisan vendor:publish --tag=pennant-dashboard-migrations
   php artisan migrate
   

2. Check migration state before using the dashboard:

   php artisan about
   

   The package migration should not appear as pending.
3. Open the dashboard route configured by the package and confirm there is no “run the migrations” banner.
4. First use case: create one low-risk rollout/flag in the dashboard, then branch on it in application code via Rollout::decide() at the point where the decision is needed — typically a controller, middleware, policy, or job. Validate in staging for one user segment before widening exposure.

If your config sets run_migrations to false, the package will not run migrations for you. Publish them explicitly and run them as part of your deployment process.

Implementation Patterns

• Treat the dashboard as the control plane and Rollout::decide() as the runtime API. Operators change rollouts in the dashboard; application code should only call Rollout::decide() rather than reading package tables directly.
• Centralize decision calls. Wrap Rollout::decide() in a small service or middleware so flags are evaluated consistently and can be tested without scattering package calls through controllers.
• Use stable user/segment identifiers. Pass the same identifier shape the dashboard expects so rollout percentages and targeting behave predictably across web requests, queues, and jobs.
• Make migrations part of deployment. For normal deployments, run php artisan migrate before relying on dashboard changes. For controlled migration setups (run_migrations=false), publish migrations again and run them in the release step:

  php artisan vendor:publish --tag=pennant-dashboard-migrations
  php artisan migrate
  

• Gate deployments on migration status. Add php artisan about or migration status to CI/CD checks. The v1.0.2 release specifically improves visibility when the migration is missing; use that signal rather than waiting for dashboard write failures.
• Restrict dashboard access. Put the dashboard behind your normal admin authentication/authorization middleware where the package exposes route configuration. Rollout changes are production behavior changes.
• Test the decision wrapper, not the dashboard. Unit-test your service/middleware that calls Rollout::decide() with known users. Keep dashboard UI testing out of the application suite.
• Promote configuration through environments. Validate the migration and one flag in staging first, then repeat the same publish/migrate sequence in production. Avoid manually altering package tables between environments.

Gotchas and Tips

• v1.0.1+ requires php artisan migrate. v1.0.2 improves the failure mode, but it does not remove the migration requirement.
• run_migrations=false has a publish step. You must publish migrations again before migrating:

  php artisan vendor:publish --tag=pennant-dashboard-migrations
  php artisan migrate
  

• The v1.0.2 fallback can mask an incomplete upgrade. Rollout::decide() continues reading the 1.0.0 tables until you migrate, so flags may appear to work while the dashboard is still not fully upgraded. Do not treat working decide() calls as proof that the upgrade is complete.
• Dashboard write refusals are expected until migration. v1.0.2 replaces silent fallback/500s with a banner and a clear “run the migrations” message. If writes are refused, check migrations first.
• There may be only one warning per process. The release logs one warning per process, not per request. A quiet log after the first request does not mean the migration issue is resolved. Check php artisan about and the dashboard banner.
• Check migrations before debugging application code. If the dashboard returns errors on writes after upgrading, verify migration state before changing rollout logic or package configuration.
• Clear cached config after changing package config. If run_migrations or dashboard settings were changed, run php artisan config:clear or rebuild config cache so the application sees the intended behavior.
• Avoid querying package tables directly. The upgrade path includes table changes; use Rollout::decide() and the dashboard rather than coupling application code to internal schema.
• Extension points to prefer: the run_migrations config option, the pennant-dashboard-migrations publish tag, and the package’s dashboard route/access configuration. Use these instead of patching vendor files.