Event Dispatcher Implementations Laravel Package

Technical Evaluation

Architecture Fit The package (psr-discovery/event-dispatcher-implementations) provides PSR-compliant event dispatcher implementations, aligning well with Laravel’s event system (which relies on PSR-14). The update to PHP 8.2+ is non-breaking for core functionality but enforces stricter compatibility with modern PHP features (e.g., named arguments, union types). This aligns with Laravel’s own PHP 8.2+ support (since v10.x), reducing version skew risks.

Integration Feasibility

• Laravel Compatibility: The package is already PSR-compliant, so integration with Laravel’s Illuminate\Events\Dispatcher or third-party dispatchers (e.g., symfony/event-dispatcher) is seamless. No architectural changes are required.
• Dependency Graph: The package has minimal dependencies (PSR-11 Container, PSR-14 Events), reducing collision risks with Laravel’s ecosystem.
• Testing Overhead: Existing tests for event dispatching logic remain valid, but PHP 8.2’s stricter type system may require updates to custom event handlers or middleware.

Technical Risk

• Breaking Change: The PHP 8.2 requirement is low-risk for Laravel projects already on PHP 8.2+ (Laravel 10+). Projects on PHP 8.1 or below will need a parallel migration (see Integration Approach).
• Feature Risk: No new features or deprecations; risk is limited to PHP version constraints.
• Performance: No changes to core logic; impact is neutral.

Key Questions

1. PHP Version Alignment: Is the project’s PHP version (8.1 or below) a blocker for adopting this package? If so, what’s the timeline for upgrading?
2. Event Handler Compatibility: Are there custom event handlers or middleware using deprecated PHP 8.1 features (e.g., array() syntax, foreach by reference) that could fail?
3. Dependency Conflicts: Could this package conflict with existing PSR-11/PSR-14 implementations (e.g., Laravel’s built-in dispatcher)?
4. Testing Strategy: How will the team validate event dispatching behavior post-upgrade (e.g., unit tests for custom events)?

Integration Approach

Stack Fit

• Laravel 10+: Native Fit. PHP 8.2+ is required, and Laravel 10+ already enforces this. Use the package as a drop-in replacement for Laravel’s default dispatcher or alongside it for specialized use cases (e.g., testing, microservices).
• Laravel 9.x/PHP 8.1: Conditional Fit. Requires either:
  • Downgrading to package v1.1.1 (if PHP 8.1 support is critical), or
  • Upgrading PHP to 8.2+ in parallel with Laravel 10.x.
• Non-Laravel PHP 8.2+: Full Fit. Ideal for standalone PHP applications using PSR-14.

Migration Path

1. Assessment Phase:
   • Audit custom event handlers/middleware for PHP 8.2 compatibility (use PHPStan or PHP 8.2 migration tools).
   • Check for conflicts with existing PSR-11/PSR-14 containers (e.g., Laravel’s Illuminate\Contracts\Container\ContainerInterface).
2. Dependency Update:
   • Update composer.json to require psr-discovery/event-dispatcher-implementations:^1.2.
   • Run composer update and resolve dependencies.
3. Testing Phase:
   • Test event dispatching in isolation (e.g., php artisan tinker for one-off events).
   • Run integration tests covering critical event flows (e.g., job dispatching, middleware execution).
4. Rollout:
   • Deploy to staging with feature flags for event-related features.
   • Monitor for deoptimizations (unlikely) or type-related errors.

Compatibility

• Backward Compatibility: The package’s API remains unchanged (PSR-14 compliance). Only the runtime environment (PHP 8.2+) is affected.
• Laravel-Specific: No Laravel-specific changes, but ensure the package isn’t shadowed by Laravel’s EventServiceProvider or app/Events directory.
• Third-Party: Verify compatibility with packages like laravel-notification-channels or spatie/laravel-event-scheduler if they interact with event dispatchers.

Sequencing

1. Upgrade PHP (if <8.2) → Upgrade Laravel (if <10) → Update Package.
2. For zero-downtime deployments, consider:
   • Running PHP 8.2 in a separate container (e.g., Docker) during migration.
   • Using feature flags to toggle the new dispatcher incrementally.

Operational Impact

Maintenance

• Proactive: Minimal. The package is low-maintenance (no moving parts beyond PSR compliance).
• Reactive: Monitor for:
  • PHP 8.2 deprecation warnings in custom event logic (e.g., @deprecated attributes).
  • Composer dependency conflicts during updates.

Support

• Developer Onboarding: Document the PHP 8.2 requirement and any custom event handler changes in the team’s runbook.
• End-User Impact: None. End users interact with events via Laravel’s facade (event()) or DI container, not the underlying package.

Scaling

• Performance: No changes to event dispatching performance. Scaling behavior is identical to v1.1.1.
• Resource Usage: Neutral. The package adds no additional processes or memory overhead.

Failure Modes

Ramp-Up

• Team Training: 1-hour session on:
  • PHP 8.2 features/breaking changes (focus on events/middleware).
  • PSR-14 event dispatching patterns.
• Documentation Updates:
  • Add a UPGRADE.md note for PHP 8.2 migration steps.
  • Update architecture diagrams to reflect the new dispatcher (if used).
• Tooling:
  • Enable PHP 8.2 in CI/CD pipelines immediately.
  • Add a phpstan/extension-installer rule to catch PHP 8.2 incompatibilities early.