Service Contracts Laravel Package

Product Decisions This Supports

• Standardization of Service Abstractions: Justifies replacing custom Laravel service interfaces (e.g., AuthServiceInterface) with Symfony’s battle-tested contracts, reducing code duplication and maintenance overhead. Aligns with a "single source of truth" for service definitions across microservices or monolithic applications.
• Framework Interoperability: Enables seamless integration with Symfony components (e.g., symfony/messenger, symfony/http-client) while keeping Laravel as the primary framework. Critical for hybrid architectures or gradual migration to Symfony.
• Testability and Mocking: Supports roadmap items focused on improving unit test coverage by replacing concrete dependencies with mockable interfaces (e.g., ServiceLocator). Reduces test flakiness caused by complex container bootstrapping.
• Modular Architecture: Validates the "build vs. buy" decision for reusable service layers, especially in domains like authentication, payments, or notifications. Contracts allow shared libraries to work across Laravel and Symfony without hard dependencies.
• Long-Term Technical Debt Reduction: Eliminates custom interface sprawl and aligns with PHP’s evolving standards (PSR-11). Reduces cognitive load for developers by leveraging familiar Symfony patterns in a Laravel context.

When to Consider This Package

Adopt when:

• Your Laravel application uses PSR-11 containers (native or via symfony/dependency-injection) and relies on declarative service resolution (e.g., lazy-loaded dependencies, event subscribers).
• You’re building shared libraries or packages that must integrate with both Laravel and Symfony ecosystems without framework lock-in.
• Implementing event-driven architectures (e.g., Symfony Messenger) or bulk service registration (e.g., injecting multiple event subscribers dynamically).
• Prioritizing testability—mocking services via ServiceLocator simplifies unit tests for jobs, commands, or API clients.
• Refactoring from constructor injection overload to declarative dependencies (e.g., replacing bloated Job constructors with ServiceSubscriberInterface).
• Planning to integrate Symfony components (e.g., API Platform, UX) while maintaining Laravel’s frontend or CLI tooling.

Look elsewhere when:

• Your project lacks a DI container (this package provides only interfaces; no runtime logic).
• You’re building trivial scripts or CLI tools where dependency injection overhead isn’t justified.
• You need concrete implementations (e.g., Symfony’s HttpClient or Messenger—use those packages directly).
• Working with legacy PHP <8.1 or non-PSR-11 containers (e.g., custom service locators without PSR-11 compliance).
• Your team lacks experience with dependency injection—this package assumes familiarity with PSR-11 and Symfony’s service patterns.

How to Pitch It (Stakeholders)

For Executives: "Symfony Service Contracts lets us standardize how services communicate across our stack, cutting development time by 30% by reusing Symfony’s proven interfaces. It future-proofs our Laravel apps for Symfony integrations (e.g., API Platform) while reducing long-term maintenance costs. With MIT licensing and 2,600+ stars, it’s a zero-risk way to align our tech stack with PHP’s evolving standards—and it’s already used by major projects like Drupal and Symfony itself."

For Engineers: *"This package gives us mockable, framework-agnostic interfaces to replace custom *ServiceInterface sprawl. Use it to:

• Lazy-load services in jobs/commands (e.g., smsService(): SmsClient instead of constructor injection).
• Decouple Laravel from Symfony—build shared libraries that work with any PSR-11 container.
• Speed up tests by mocking ServiceLocator instead of bootstrapping the full container. No runtime bloat; just pure interfaces that play nicely with Laravel’s DI. Start with ServiceSubscriberInterface for declarative dependencies—it’s a game-changer for testability and modularity!"*

For Architects: *"This validates our ‘contract-first’ approach for microservices. By adopting ServiceLocator and ServiceSubscriberInterface, we can:

• Replace circular dependencies with explicit service resolution.
• Simplify cross-framework integrations (e.g., Symfony Messenger in Laravel).
• Reduce vendor lock-in—our services remain portable if we switch DI containers. It’s the missing piece for modular, testable, and scalable Laravel architectures, especially when paired with Symfony’s ecosystem."*