Interface Alert Policy Manager Laravel Package

Getting Started

• Install with composer require drakelid/interface-alert-policy-manager and let Laravel's package discovery register the service provider. If you are on a version-pinned setup, confirm the constraint resolves to ^1.9 before running composer update.
• Publish the package assets before writing any code:

  php artisan vendor:publish --provider="Drakelid\InterfaceAlertPolicyManager\InterfaceAlertPolicyManagerServiceProvider"
  

  Review the published config file first — for a policy engine the config is the real API surface (default policy resolution, evaluation cadence, notification channels, queue connection). Most "why isn't my alert firing" reports trace back to a config default rather than a bug.
• Run the migrations and confirm the tables land where you expect. Policy packages usually ship policies, policy_assignments (or a pivot), and an alert_events/alert_history table. Read the migration files to learn the schema — the README is usually thinner than the migrations.
• Skim these directories in order: src/Contracts (the extension points you'll actually implement), src/Models, src/Console/Commands (what runs and when), then src/Notifications.
• First use case: create a single policy, attach it to one interface/subject, and run the evaluation command manually (php artisan interface-alert:... — check php artisan list for the exact signature). Watching one policy produce one alert end-to-end teaches you more than reading the whole README.
• Note on v1.9.0: the release notes are only a link to the GitHub compare view. Treat the diff as the source of truth — open compare/v1.8.1...v1.9.0 and scan for changes under src/Contracts, config keys, and migrations before upgrading.

Implementation Patterns

• Policy-as-data, not policy-as-code. Define alert thresholds in seeders or a dedicated admin surface rather than hardcoding them. That is the point of the package: operators change thresholds without a deploy.
• Bind the contracts in a service provider rather than extending package classes. Implement the evaluation/notification contracts and register them:

  $this->app->bind(AlertEvaluator::class, App\Alerts\CustomEvaluator::class);
  

  This survives minor upgrades far better than subclassing internals.
• Wrap policy creation in your own action/DTO layer. Keep your domain (devices, sites, interfaces) on your side of the boundary, and translate to the package's models at the edge. When the package's schema shifts, you patch one adapter instead of forty call sites.
• Drive evaluation from the scheduler, not from request handlers. Register the package command in routes/console.php or Kernel::schedule() with withoutOverlapping() and onOneServer() if you run multiple app nodes.
• Queue the notification side. Alerts are bursty by nature; force the package's jobs onto a dedicated queue (alerts) so a noisy incident never starves your transactional jobs. Set a short retry_after relative to your evaluation interval.
• Use events for fan-out. If the package dispatches domain events on alert state change, listen for them to sync into PagerDuty/Slack/ticketing instead of adding channels inside the package config. That keeps the package a detector and your app the router.
• Test with a fake transport. In feature tests, swap the notification channel for a Notification::fake()-style assertion or a log driver so alert tests don't page anyone. Assert on the persisted alert-event rows; that's the durable contract.
• Multi-tenant: scope policies by tenant/team ID early, via a global scope on your own repository layer. Retrofitting tenancy onto a policy table after the fact is painful.

Gotchas and Tips

• Empty release notes are a yellow flag, not a red one. For v1.9.0 you only have a compare link. Before upgrading, read the diff for: renamed config keys (silently fall back to defaults), new nullable columns (fine), and any signature change in src/Contracts (breaking for your bindings). Pin to 1.8.* in production until you've done that read.
• Config caching bites. After publishing or editing the config, php artisan config:clear in local and remember that config:cache in deploy means you cannot mutate policy defaults at runtime via config().
• Publish-then-upgrade drift. Published migrations and configs do not update themselves. Keep a short note of the published file list and re-diff them each minor bump; this is the single most common source of "works on fresh install, broken on existing app".
• Timezone and interval math. Threshold windows (for 5 minutes) are usually evaluated against now() in app timezone while stored timestamps may be UTC. Assert this explicitly with a test that freezes time.
• Idempotency of evaluation. Confirm whether re-running the command re-fires the same alert. If not guaranteed, add your own dedupe key (policy + subject + window) before wiring it to a pager.
• Overlap and flapping. Use withoutOverlapping() and consider a minimum re-notify interval; interfaces flapping at a threshold boundary will otherwise generate a notification storm.
• Log the evaluation decision, not just the alert. A debug line per policy/subject with the compared values is what turns a support ticket into a five-minute fix.
• Extension points to prefer: contracts, config, and events. Avoid class ... extends on package internals and avoid relying on protected methods — both are the first things a minor release changes.