Weave Code
Contracts Laravel Package
symfony/contracts
Symfony Contracts is a set of small, consistent PHP interfaces and traits extracted from Symfony components. They provide proven abstractions for loose coupling and interoperability, helping you type-hint services and reuse battle-tested implementations across frameworks and PSR-compatible libraries...
A set of abstractions extracted out of the Symfony components
Frequently asked questions about Contracts
- Does Symfony Contracts work with Laravel?
- Yes. Symfony Contracts is framework-agnostic, so Laravel can use its interfaces as type hints and map them to concrete services through container bindings. Laravel does not natively implement every Symfony Contract, so you need adapters or Symfony components for the actual implementations. It fits best in decoupled infrastructure layers and reusable packages.
- How do I install symfony/contracts in a Laravel app?
- Most Laravel apps receive Symfony contract packages transitively through Symfony components. Install only the split package you need with Composer, such as symfony/cache-contracts or symfony/event-dispatcher-contracts. Use Laravel 10+ with PHP 8.1+ and Contracts v3.x or newer for best compatibility. After installation, bind the interfaces in a service provider before injecting them.
- Which Symfony Contracts version should I use with Laravel 10?
- Laravel 10 and PHP 8.1+ pair best with Symfony Contracts v3.x or newer. Avoid v2.x for modern Laravel apps because of PHP 8 compatibility constraints. Check the versions required by Symfony components already in your dependency tree to avoid version skew.
- How do I bind Symfony Contracts interfaces in Laravel's service container?
- Register explicit bindings or aliases in AppServiceProvider, mapping each contract interface to an adapter or concrete implementation. For example, bind CacheInterface to a bridge around Laravel's cache repository, or to a Symfony cache implementation. Laravel autowiring will not resolve unknown Symfony interfaces unless the binding exists.
- Why do I get Target class does not exist when injecting a Symfony contract?
- Laravel autowiring only resolves concrete classes or interfaces that are explicitly bound. Symfony Contracts are interfaces and are not automatically mapped to Laravel services. Add a bind or alias in a service provider, or avoid injecting the contract until the adapter is registered. Clear config and container caches after changing bindings.
- Do Symfony Contracts replace Laravel's Illuminate Contracts?
- No. Laravel's Illuminate Contracts are framework-specific and cover Laravel internals, while Symfony Contracts are framework-agnostic abstractions shared across PHP ecosystems. They can coexist in the same application. Use Symfony Contracts when you need portability or cross-framework interoperability, not as a blanket replacement.
- What Symfony Contracts are most useful in Laravel?
- Cache, event dispatcher, HTTP client, translation, and service contracts are common candidates. They help decouple cache access, event dispatching, outbound HTTP calls, translations, and service locators from Laravel-specific types. Mailer-related contracts are also relevant if you build framework-agnostic notification or mailing libraries. Start with one boundary and test it before expanding.
- Do I need symfony/cache or symfony/http-client to use the contracts?
- Yes, contracts define interfaces but do not provide full implementations. You must install a concrete implementation such as symfony/cache, symfony/http-client, or a third-party library that satisfies the contract. Alternatively, write an adapter around Laravel's existing service. Without an implementation, binding and injection will fail at runtime.
- How should I test Symfony Contracts in a Laravel application?
- Unit-test your adapters against the contract methods and edge cases, and use mocks or simple fake implementations for consumers. For integration tests, bind the fake in the container and assert behavior through Laravel's test helpers. Include tests for semantics the contract implies, such as cache retry behavior or HTTP client middleware. This protects you from version and implementation differences.
- Is Symfony Contracts production-ready and safe for Laravel apps?
- The contracts themselves are battle-tested and designed for backward compatibility with Symfony components. Production risk comes from integration details: version skew, incomplete bindings, semantic gaps, and adapters that do not fully honor the interface. Benchmark any hot paths and validate contract compliance before rollout.
Weaver
How can I help you explore Laravel packages today?