Service Contracts Laravel Package

Getting Started

Start by installing the package via Composer:

composer require symfony/service-contracts

This package contains only interfaces, so it won’t add runtime behavior until you integrate it into a DI-aware context (e.g., Symfony’s DependencyInjection component or Laravel’s container with适配). Your first immediate use case is likely implementing ServiceSubscriberInterface in services like Laravel command handlers or job classes to declare dependencies declaratively—e.g., fooService(): FooService—instead of constructor injection. Review the ServiceSubscriberInterface and ServiceLocator contracts first; they’re the most practical entry points for decoupling service usage.

Implementation Patterns

• Service Subscribers in Laravel Jobs/Commands: Implement ServiceSubscriberInterface in ShouldQueue jobs or Artisan commands. Combine with Laravel’s container (which implements Psr\Container\ContainerInterface) to resolve services lazily via a ServiceLocator. Avoids bloating constructor signatures for rarely-used dependencies (e.g., SMS, email, or third-party API clients).
• Bulk Handler Registration: Use ServiceLocator to inject collections of related services (e.g., multiple EventSubscriberInterface implementations in a domain layer) without circular dependency risks or tight coupling.
• Framework-Agnostic Library APIs: When building shared packages (e.g., a generic payment or notification library), type-hint for ServiceSubscriberInterface instead of concrete types. This lets consumers pass any PSR-11-compliant service locator (including Laravel’s container) without hard dependency on Symfony.
• Test-Driven Service Mocking: In feature tests, build a ServiceLocator with mock services (e.g., new ServiceLocator(['mailer' => $mockMailer])) and inject it into subscribers—eliminates full container bootstrapping and improves test speed.

Gotchas and Tips

• Zero runtime logic: Remember: only interfaces. You won’t see new services appear in php artisan list or Route::get()—it works silently under DI containers. Verify integration with Laravel’s App::make() or Container::bind() logic.
• Laravel container compatibility: Laravel’s Container implements Psr\Container\ContainerInterface, but some older implementations or custom extensions might not. Confirm compatibility via app()->get('foo') works before relying on ServiceSubscriberInterface.
• Request-scoped services: Avoid storing long-lived ServiceLocator instances that resolve short-lived services (e.g., request(), session())—this can cause stale references or memory leaks. Use constructor injection for per-request dependencies instead.
• Missing service errors: By default, ServiceSubscriberTrait throws ServiceNotFoundException for unbound services. Override defaultServices or extend ServiceSubscriberTrait to customize fallback behavior (e.g., return null or throw a domain-specific exception).
• Silent deprecations: Though the package hasn’t updated since 2020,Symfony’s ecosystem keeps it compatible. When upgrading Symfony components, run composer require symfony/contracts to align versions—especially symfony/dependency-injection, which integrates tightly with these contracts.