Contracts Laravel Package

Getting Started

Install symfony/contracts via Composer: composer require symfony/contracts. This meta-package pulls in all domain-specific contracts (e.g., symfony/cache-contracts, symfony/event-dispatcher-contracts, symfony/translation-contracts). Start by identifying a concrete use case—like caching or event handling—and choose the appropriate interface (e.g., Symfony\Contracts\Cache\CacheInterface). Then install a compatible implementation: typically a Symfony component (symfony/cache, symfony/event-dispatcher) or a third-party library that declares the contract in its provide section. In Laravel, your first real win comes from replacing framework-specific type hints (e.g., CacheManager) with the Symfony contract in non-Laravel-bound services or packages.

Implementation Patterns

• Interface-first service design: In your service layer, inject Symfony\Contracts\Cache\CacheInterface or Symfony\Contracts\EventDispatcher\EventDispatcherInterface instead of Laravel’s concrete facades or repositories. This decouples business logic from the underlying framework.
• Binding contracts to Laravel implementations: In AppServiceProvider, use alias() to map Symfony contracts to Laravel equivalents:

  $this->app->alias(\Symfony\Contracts\Cache\CacheInterface::class, \Illuminate\Cache\Repository::class);
  $this->app->alias(\Symfony\Contracts\EventDispatcher\EventDispatcherInterface::class, \Illuminate\Events\Dispatcher::class);
  

  This enables autowiring—your classes can type-hint Symfony interfaces and still use Laravel’s underlying implementations.
• Framework-agnostic packages: Build reusable libraries (e.g., a payment or notification module) that only depend on symfony/contracts. Consumers of your package can then plug in their own implementations (Symfony, Laravel, Doctrine, etc.) without your code knowing the difference.
• Laravel bridge packages: Leverage Laravel’s official use of Symfony contracts (e.g., symfony/mailer underpins Mail::to()->send()). When building your own mailer or queueing abstractions, implement Symfony\Contracts\Translation\TranslatorInterface or Symfony\Contracts\Translation\TranslatorAwareInterface for seamless integration.

Gotchas and Tips

• No runtime code: Remember—symfony/contracts is only interfaces and traits. No configuration, no commands, no database migrations. All behavior lives in the implementation packages.
• Package granularity: While symfony/contracts is a meta-package, you usually only need specific contract packages (e.g., symfony/translation-contracts). Install only what you use (composer require symfony/cache-contracts) to avoid bloat.
• PSR alignment ≠ identical semantics: Contracts often extend PSR interfaces (e.g., CacheInterface extends Psr\SimpleCache\CacheInterface) but add richer functionality (e.g., retry strategies, tagged invalidation). Always inspect docblocks—don’t assume 1:1 parity.
• Laravel autowiring quirks: Laravel doesn’t automatically resolve Symfony contracts unless you alias them or define explicit bindings. If you get Target class does not exist errors for interfaces, verify your alias() calls or register explicit bindings.
• Avoid leaking contracts into domain models: Use contracts at infrastructure boundaries (repositories, APIs, event listeners)—not in core domain value objects. Keep your domain pure; only adapt at the edges.
• Debug tip: Run composer why symfony/cache-contracts and composer why-not symfony/cache-contracts to trace dependency conflicts. Also, inspect installed packages with composer show -i | grep symfony/*-contracts to confirm which contract packages you’re actually using.