Weave Code
Event Sourcing Phpstan Extension Laravel Package
patchlevel/event-sourcing-phpstan-extension
PHPStan extension for patchlevel/event-sourcing that validates aggregates before runtime: flags uninitialized and unused properties, write-only state, event recording inside apply methods, and state changes outside apply.
phpstan extension for event-sourcing library.
Frequently asked questions about Event Sourcing Phpstan Extension
- Is there a PHPStan extension for patchlevel/event-sourcing?
- Yes, patchlevel/event-sourcing-phpstan-extension adds static analysis rules specifically for patchlevel/event-sourcing aggregates. It teaches PHPStan how aggregate properties are initialized and flags event sourcing mistakes before runtime. Install it as a dev dependency alongside the event-sourcing library.
- How do I install patchlevel/event-sourcing-phpstan-extension in a Laravel app?
- Run composer require --dev patchlevel/event-sourcing-phpstan-extension. If phpstan/extension-installer is installed it registers itself automatically; otherwise add vendor/patchlevel/event-sourcing-phpstan-extension/extension.neon to the includes section of phpstan.neon. No service provider or config publishing is required.
- Do I need phpstan/extension-installer for this extension?
- No, it is optional. With phpstan/extension-installer present the extension self-registers after Composer install. Without it, you register the bundled extension.neon manually in every PHPStan configuration file your project uses. Make sure CI uses the same phpstan.neon includes.
- What mistakes does the event-sourcing PHPStan extension detect?
- It reports five main issues: uninitialized aggregate properties, unused properties that no apply method writes, write-only properties that are stored but never read, recording events inside apply methods, and writing state outside apply methods. The last two are correctness errors that would otherwise surface only at runtime. The property checks reduce false positives and design drift.
- Why does PHPStan report recording events inside apply methods?
- Recording events while applying them causes duplicated events when an aggregate is replayed from the event store. The extension flags any call that records a new event inside an apply method so the mistake is caught in CI. This protects event stream integrity and avoids expensive data cleanup later.
- Why is writing state outside apply methods an error in event sourcing?
- Aggregate state must be derived from events so it can be rebuilt on reload. State written outside apply methods is not tied to an event and silently disappears when the aggregate is rehydrated. The extension reports those writes as errors to prevent intermittent invariant violations.
- How does the extension fix PHPStan uninitialized property errors on aggregates?
- It contributes type extensions that understand AggregateRoot and ChildAggregate property initialization through apply methods. PHPStan then knows properties set during event application are initialized, so you do not need @phpstan-ignore comments or lower PHPStan levels. This is especially useful when targeting level max on aggregate classes.
- Does the extension support child aggregates and nested aggregates?
- It provides analysis for both aggregate roots and child aggregates, including property initialization and state rules. Very dynamic code using __get, reflection, or trait-based state may still produce false positives because PHPStan cannot always follow magic access. Review reported issues and use a baseline or targeted ignores where needed.
- Is patchlevel/event-sourcing-phpstan-extension safe for production?
- Yes, it is a dev-only PHPStan extension with no runtime code, service providers, config publishes, or migrations. Require it with --dev so it never ships to production. It only runs during static analysis and cannot cause a production incident.
- Do I need to upgrade this extension when patchlevel/event-sourcing changes?
- Yes, treat the two packages as a lockstep pair. The rules match on the event-sourcing library's API and base-class types, so an upgrade without the matching extension version can silently stop reporting instead of failing loudly. Use Renovate or Dependabot grouping so both packages are updated together, and keep an eye on baseline churn from new rules.
Weaver
How can I help you explore Laravel packages today?