Contracts Laravel Package

Getting Started

complex-heart/contracts is a pure interface/contract package — you install it, but there is almost nothing to "run." Think of it as the shared vocabulary for the Complex Heart SDK ecosystem rather than a feature you wire into a controller.

Minimal setup:

composer require complex-heart/contracts

• Requires PHP 8.x and PSR-4 autoloading under the ComplexHeart\Contracts\ namespace. Confirm the exact PHP constraint in composer.json before installing alongside an older Laravel version.
• Where to look first: open src/ and enumerate the interfaces. There is no facade, no service provider, no config file, and no migrations — the entire package surface is the interface list. The README on GitHub is the fastest inventory; if it's thin, vendor/complex-heart/contracts/src is the source of truth.
• Then look at the consuming SDK (the "Complex Heart SDK" this package was carved out of) to see how each interface is implemented. Interfaces are meaningless without the reference implementations.
• First use case: dependency-inject the interfaces in a Laravel service and bind concrete SDK classes in AppServiceProvider:

// AppServiceProvider::register()
$this->app->bind(
    \ComplexHeart\Contracts\SomeClientContract::class,
    \App\Services\ComplexHeartClient::class
);

Then type-hint the interface in a constructor and let Laravel's container resolve it.

Implementation Patterns

1. Container bindings in a service provider. This is the primary integration point. Register a ComplexHeartServiceProvider that binds every contract you consume to a concrete implementation. Keep the binding map in one place so you can swap SDK versions without touching call sites.

2. Depend on the narrowest interface. If the package exposes several small interfaces (which interface packages usually do), inject only the one you need rather than a mega-interface. This keeps unit tests trivial and mocks minimal.

3. Decorate for cross-cutting concerns. Because implementations are injected by contract, you can wrap them:

class CachingClient implements ClientContract
{
    public function __construct(
        private ClientContract $inner,
        private Cache $cache,
    ) {}

    public function fetch(string $id): Payload
    {
        return $this->cache->remember("ch:$id", 300, fn () => $this->inner->fetch($id));
    }
}

Bind the inner implementation first, then rebind the contract to the decorator — a clean way to add logging, retries, or telemetry without forking the SDK.

4. Mock the contract, not the implementation. In tests, bind a fake implementation of the interface in setUp() (or use $this->instance() / $this->mock()). This is exactly why a contracts package exists.

5. Adapter pattern for SDK boundaries. If the SDK interfaces are awkward for your domain, write a thin adapter in your app that implements the contract and translates to your own models. Your application code stays SDK-agnostic.

6. Contract tests. If you implement these interfaces yourself, write a shared PHPUnit test case (abstract class ClientContractTestCase) asserting the interface's behavioral contract, and extend it for every implementation. This is the pattern PSR-style packages expect.

Gotchas and Tips

• This package has near-zero ecosystem signal (1 star, 0 dependents, very recent release). Treat it as a private-code dependency: pin the version in composer.json and review the source before upgrading. There's no community to catch a broken interface.
• Adding a method to an interface is a breaking change. Because the package is nothing but public API, any interface modification will break every implementor. Lock to a caret range (^1.0) and read the changelog before bumping minor versions — SemVer for pure-interface packages is stricter than for libraries.
• No runtime behavior means classic debugging fails. If BindingResolutionException or a "cannot instantiate interface" error appears, the problem is always a missing container binding, not the package. Use app()->make(SomeContract::class)->get_class() to verify what's actually being resolved.
• Don't add the package's service provider expecting magic. There is likely no provider (or if there is one, it only registers bindings). Adding it to config/app.php when it isn't needed will cause confusing "class not found" errors during php artisan package:discover.
• Watch the PHP version in composer.json. Interface packages often use PHP 8.1+ features (enums, readonly, never return types). If one Laravel app in a monorepo is still on 8.0, the composer resolution will silently keep the whole repo pinned.
• Extension points are limited by design. You extend by implementing the interfaces, not by subclassing or overriding package code. If the interfaces don't fit your use case, define your own contracts in app/Contracts/ and adapt — don't fork the package for a two-line change.
• Prefer your own interfaces where the package is thin. If complex-heart/contracts only exposes one or two interfaces you actually use, it may be cheaper to declare them in your app and drop the dependency entirely. Contracts packages only pay off when multiple packages or services share the same vocabulary.
• Check autoloading before blaming the code. For a package this small, the most common failure is a namespace typo or a stale composer dump-autoload — not the interface definitions themselves.