Laravel Events Laravel Package

Product Decisions This Supports

• Build vs. buy for audit/event history: This package is a credible “buy/adopt” option when the product needs durable, queryable persistence of Laravel domain events without building custom audit logging, diffing, correlation, and MongoDB query layers.
• Roadmap and upgrade planning: v4.0.0 is a correctness/quality major release, not a passive dependency bump. PM should schedule an upgrade assessment, code-freeze window, and deployment runbook because of enum string changes, final classes, serializer contract changes, dependency updates, and MongoDB index changes.
• Compliance and customer-support use cases: Persisted event logs with correlation/causation, user context, diffs, and filtered queries support audit trails, incident investigation, support diagnostics, and “what changed?” workflows.
• API and integration contracts: The string-backed enum change means downstream APIs, reports, exports, and UI code that compare or return enum cases as strings must move to ->value. PM should treat this as a cross-team compatibility item, not just a library upgrade.
• Architecture and extension strategy: Concrete package classes becoming final limits subclassing. Product/engineering should prefer composition and EventPersisterInterface in tests and integrations, which is a healthier long-term dependency boundary.
• Operational readiness: The MongoDB index set changed, so adoption or upgrade requires a planned php artisan events:install-indexes step. This affects deployment checklists, environment parity, and possibly rollout sequencing.
• Quality and maintainability signal: PHPStan max, strict rules, PHPMD, Pint PER-CS 3.0, CaptainHook, CodeQL, CI gates, and Docker support indicate active maintenance and stronger correctness guarantees, which lowers long-term platform risk.

When to Consider This Package

Consider adoption when:

• The product runs Laravel 12/13 with MongoDB and needs durable event/audit persistence rather than ad-hoc logging.
• You need queryable event history with event name/class/id filters, correlation/causation tracing, diffs, metadata, and guest/user context handling.
• You want a package-maintained event persistence layer instead of building and owning serializers, query DTOs, index management, and subscriber plumbing.
• You can absorb major-version upgrade work: enum ->value call-site updates, dependency upgrades, Mongo reindexing, and test changes away from mocking final classes.
• You value testability/observability improvements such as EventPersisterInterface, optional PSR-20 clock, PSR-3 logger, typed exceptions, and query guard/executor components.
• You can run the provided Docker/CI baseline or equivalent and validate MongoDB index behavior in staging.

Look elsewhere when:

• Your platform is relational-only, has no MongoDB operational capability, or cannot support index migrations as part of releases.
• You need a full event-sourcing/CQRS framework with replay, projections, and stream processing rather than event persistence and querying.
• Your architecture depends on subclassing concrete package services or removed bag DTOs (EventDiffData, EventMetadataData); this release intentionally narrows those extension points.
• You cannot tolerate breaking API changes or cross-team call-site updates for enum string handling.
• You need vendor-backed SLA/support or a long-term API freeze that this package does not claim.
• You are on older Laravel/PHP versions outside the supported matrix; validate runtime requirements, including the PHP 8.5 + MongoDB Docker baseline, before committing.

How to Pitch It (Stakeholders)

For executives: This package can accelerate delivery of audit trails, compliance evidence, and incident diagnostics by persisting Laravel domain events with searchable context and change diffs. v4.0.0 hardens correctness and quality, but it is a breaking major release: plan a controlled upgrade rather than an automatic dependency update.

For engineering: v4.0.0 improves dependency inversion, observability, query safety, date hydration, diff correctness, bulk persistence, guest-context handling, and CI quality gates. The upgrade requires concrete work: replace string enum comparisons with ->value, stop subclassing final services, use EventPersisterInterface in tests, update removed DTO usage, refresh dependencies, and re-run events:install-indexes.

Recommendation: Treat v4.0.0 as a planned platform upgrade. Inventory enum/string call sites and subclassing first, validate MongoDB index changes in staging, run the full test suite against the new interfaces, and then roll out with an explicit deployment checklist.