Conduit Interfaces Laravel Package

Getting Started

conduit-interfaces is a contracts/abstractions package rather than a batteries-included library, so the fastest path to productivity is reading the interfaces before writing any code.

1. Install it as a direct dependency:

   composer require jordanpartridge/conduit-interfaces:^1.1
   

2. Confirm your environment satisfies the v1.1.0 constraints — PHP 8.2+, laravel-zero/framework ^11.0|^12.0, and illuminate/console ^11.0|^12.0.
3. Open the package source (vendor/jordanpartridge/conduit-interfaces/src) and enumerate the interfaces. These are the API — there is no facade, no config file, and no service provider magic to discover.
4. Your first use case: pick one interface, write a concrete implementation in your app, bind it in a service provider, and inject it into a Laravel Zero command. That loop (contract → implementation → binding → injection) is the entire day-to-day workflow.

If you are starting a new Laravel Zero 12 project, install v1.1.0 from the outset rather than upgrading later; the widened constraints exist specifically so Zero 12 apps can depend on this package cleanly.

Implementation Patterns

Contract-first component design. Keep conduit-interfaces as a dependency of your packages and shared modules, and keep concrete implementations in the consuming application. This is the pattern the release notes call out ("better component architecture and code reuse") — the interfaces package is meant to sit at the bottom of the dependency graph so multiple components can agree on a shape without depending on each other.

Service provider binding. Register implementations explicitly:

public function register(): void
{
    $this->app->bind(
        \JordanPartridge\Conduit\Contracts\SomeConduit::class,
        \App\Conduit\MyConduit::class
    );
}

Prefer bind over singleton unless the implementation is genuinely stateless — CLI commands in Laravel Zero are typically resolved per-invocation, and singletons can leak state across commands in long-running or test scenarios.

Constructor injection into commands. Laravel Zero resolves command constructors through the container, so injecting a conduit interface into a command signature is the cleanest integration point:

public function __construct(private SomeConduit $conduit)
{
    parent::__construct();
}

Remember to call parent::__construct() — Laravel Zero commands will silently fail to register their signature otherwise.

Version constraint hygiene. Because v1.1.0 only widens laravel-zero/framework and illuminate/console, you can safely use ^1.1 across both Zero 11 and Zero 12 projects. If you maintain downstream packages, mirror the same OR-constraint (^11.0|^12.0) rather than pinning, or you will reintroduce the exact conflict this release resolved.

Testing. Since these are interfaces, write your tests against the contract, not the implementation. A small fake implementation bound in TestCase::setUp() keeps command tests fast and lets you assert interaction without touching real I/O.

Gotchas and Tips

• The illuminate/console constraint is the real gate. Laravel Zero 12 pulls illuminate/console 12.x; if any other dependency pins ^11.0, Composer will fail to resolve even though the package now advertises support for both. Run composer why illuminate/console when a conflict appears — the culprit is almost never this package.
• This package adds no runtime behaviour. There is no auto-discovered service provider, no published config, and no migrations. If nothing seems to happen after installing, that is expected: the value only materialises once you implement an interface and bind it.
• Interface changes are breaking for implementors. Even in a patch release, adding a method to an interface breaks every class that implements it. Pin to ^1.1 and read the changelog before bumping minor versions if you have implementations in production; consider shipping an abstract base class or trait on your side to absorb future additions.
• Full Laravel vs Laravel Zero. The package targets Laravel Zero, but the only hard dependency is illuminate/console. It will generally work in a standard Laravel app, but that combination is untested upstream — verify before relying on it.
• Debugging resolution failures. When a command throws "Target [Interface] is not instantiable", the binding is missing or registered in a provider that isn't listed in config/app.php (Zero) — check provider registration order first, then php artisan about / a dd(app()->getBindings()) to confirm the binding exists.
• Extension points are the interfaces themselves. There is no plugin system to hook into. If the provided contracts don't fit, the intended move is to implement them in an adapter and keep your domain types independent, so a future major version of the package doesn't ripple through your codebase.
• Upgrading from 1.0.0 is low-risk — the diff is constraint-only. No code changes, no deprecations, no migration steps. The meaningful action is confirming your composer.lock actually resolved to 1.1.0 rather than staying on 1.0.0 because of a transitive pin.