Getting Started

Install with composer require devoption/beacon, then publish the package config using the publish tag documented in the README. Read config/beacon.php first, followed by the package service provider and ingress provider contract.
In v1.4.0, start by identifying the new ingress provider selection setting. Configure the default provider for local development, then confirm a simple inbound beacon reaches the expected handler before wiring it into staging or production.
First practical use case: choose an ingress provider in config, send a sample beacon through the package’s normal entry point, and verify it is accepted, logged, and dispatched by the configured provider. Once that works locally, promote the same provider configuration per environment.

Implementation Patterns

Prefer config/environment-driven provider selection over hardcoding a provider in application code. Use separate values for local, staging, and production so the ingress mechanism can vary without code changes.
When integrating with existing infrastructure, implement a custom ingress provider against the package contract and bind/register it through the package’s documented extension point. Keep provider-specific behavior out of controllers and jobs.
Protect ingress routes with the appropriate middleware: signature validation, authentication, rate limiting, and CSRF exclusions where required. Keep route prefixes and middleware configurable rather than scattering them across the app.
Use the provider abstraction in tests. Feature-test the ingress route with the configured provider, and unit-test custom providers independently. Where available, use a fake/null/log provider for fast feedback.
Treat provider selection as deployment configuration: include it in environment templates, document it for operations, and verify it after config caching.
For day-to-day debugging, inspect the resolved provider from the container, check route registration with php artisan route:list, and review package logs around ingress handling and provider dispatch.

After changing the ingress provider, clear and rebuild config cache. A stale cached config is the most likely reason a provider change appears to have no effect.
Confirm whether the config expects a provider key, class name, or both. v1.4.0 adds selection, but custom providers still need to satisfy the package contract and be autoloadable.
Watch for ingress route collisions, missing CSRF exceptions, and overly broad middleware. Ingress endpoints often need different middleware from normal web routes.
Avoid switching providers at runtime unless the package explicitly supports per-request resolution. If it does, verify that provider state is not leaked between requests or queued jobs.
When debugging, check route:list, application logs, the published config, and container resolution for the provider class. Add temporary logging around provider selection if the failure is ambiguous.
Treat v1.4.0 as a minor feature release: review the changelog before upgrading, but there are no indicated breaking changes. Pin the version in production and validate the chosen ingress provider in a non-production environment first.