Psst Laravel Package

Getting Started

• Install with Composer on Laravel 12/13 and PHP 8.3+. This is the first standalone 1.0 release, so treat it as a new baseline rather than an in-place upgrade from a pre-1.0 package.
• Start with composer require for the package, then publish its config with the package’s vendor:publish tag and review the generated file before sending anything. Run php artisan config:clear after config changes.
• Confirm Laravel package discovery registered the service provider and facade. If your app disables discovery, register them manually.
• First practical use case: send one low-risk event at the lowest level from a local command or tinker session, then inspect your configured destination and the authenticated /psst-health endpoint.
• Use /psst-health as the first operational check. It returns scalar metrics, so it is suitable for a quick smoke test and for monitoring dashboards once authentication is wired correctly.
• Keep the initial rollout narrow: one event type, immediate delivery, and no queue mode. Add queue mode and transaction-aware enqueue only after the basic path is visible in your logs/metrics.

Implementation Patterns

• Centralize event sending behind a small application service or helper instead of calling the facade throughout the codebase. Map your domain events to the package’s four levels so severity choices stay consistent.
• Use immediate fail-silent delivery for low-risk telemetry where a lost event must never break the request. Use explicit asynchronous queue mode for high-volume or slower delivery paths, and reserve force delivery for rare cases where normal queue/transaction behavior must be bypassed.
• Define stable event identifiers as constants or enums in your app. Do not build identifiers from raw class names, user input, or changing strings; stable identifiers are what make downstream grouping and alerting reliable.
• Build payloads through a single redaction/bounding layer. Explicitly allow-list fields, redact secrets and PII, and keep arrays small because payloads are bounded. Include correlation IDs and stable event IDs rather than large object dumps.
• For database-backed workflows, enqueue inside the transaction when the event should reflect committed state. The transaction-aware behavior means queued events wait for commit; use force delivery only when you deliberately need delivery despite normal transaction/queue semantics.
• Treat retries as best-effort and time-boxed. Transient retries are capped at 24 hours, so do not design business-critical guarantees around infinite retry. Pair queue mode with Laravel queue monitoring and failed-job alerting.
• Expose /psst-health to your monitoring system through authenticated access only. Configure caching appropriate to your scrape interval, and alert on stale last-good values as well as explicit metric errors.
• In tests, fake or wrap the package boundary so you can assert event level, identifier, and redacted payload without relying on real delivery. Use the published config to point at safe test values.

Gotchas and Tips

• Fail-silent immediate delivery is convenient but can hide transport failures. If an event matters operationally, add your own counters/logging around send attempts rather than assuming an exception will surface.
• Queue mode needs a running worker and proper queue supervision. Without that, events will sit in the queue; with misconfigured retries, the 24-hour cap may expire before you notice.
• Transaction-aware enqueue can surprise developers who expect an event immediately after calling the facade. If you need pre-commit visibility, send after commit explicitly or use force delivery deliberately.
• Force delivery bypasses normal safeguards. Use it sparingly and document why each call site needs it.
• Bounded payloads may truncate data silently. Validate that critical fields survive bounding, and prefer identifiers plus small context over full model serialization.
• Last-good health values can make a failing metric look healthy at a glance. Always check freshness/timestamps and cache TTLs, not just the scalar value.
• The /psst-health route is authenticated by design. Do not weaken that for convenience; give your monitor a dedicated credential or internal-only access path.
• After changing package config in deployed environments, clear and rebuild Laravel config cache. Route caching can also affect the health endpoint if routes are cached during deploys.
• Automatic provider/facade discovery is convenient but can mask manual-registration errors in older or customized Laravel setups. If the facade is missing, check bootstrap/providers.php, config/app.php, and package discovery state.
• This is an initial 1.0 release with no documented upgrade path from earlier bundled versions. Pin the version in CI, run the health endpoint and one test event in staging, and avoid relying on undocumented internals until extension points are confirmed in the published config.