Sapient Bundle Laravel Package

Getting Started

Read this first: it's a Symfony bundle, not a Laravel package. lepiaf/sapient-bundle is a thin DI/config wrapper around the lepiaf/sapient library. It ships an Extension + Configuration pair that registers the library's services into Symfony's container. There is no ServiceProvider, no auto-discovery, no facade, and no config/sapient.php. For a Laravel codebase, the bundle itself is effectively dead weight — the library is what you actually want.

Practical triage before you invest any time:

1. Check the archive date and the composer.json constraints. Run composer show lepiaf/sapient-bundle --all and look at the require block. Archived bundles from the Symfony 3/4 era typically pin symfony/*: ^3.4|^4.0 and php: ^7.x. If you're on PHP 8.2+ / Symfony 6/7, composer require will either fail resolution or force you onto abandoned transitive deps. Don't fight it.
2. Open DependencyInjection/SapientExtension.php and DependencyInjection/Configuration.php first. That's the entire value proposition of the bundle — everything else is boilerplate. Ten minutes of reading tells you every service ID and config key. If those two files are trivial (they usually are for a wrapper bundle), the bundle adds nothing you can't replicate in a Laravel provider in ~40 lines.
3. Then look at the underlying lepiaf/sapient library. That's where the actual behaviour lives and where your day-to-day work will happen regardless of framework.

First use case (Laravel): skip the bundle. composer require lepiaf/sapient, then write a SapientServiceProvider that binds the library's entry point as a singleton, publishes a config/sapient.php mirroring the bundle's config tree, and resolves it via the container. You get 100% of the bundle's functionality with none of the framework mismatch.

First use case (Symfony, if you genuinely are on it): register the bundle in config/bundles.php, add a config/packages/sapient.yaml matching the Configuration tree, then autowire the main service into a command and exercise one operation end to end before writing any feature code.

Implementation Patterns

Config-tree mirroring. The bundle's only real contract is its Configuration class. Port it verbatim into config/sapient.php — nested arrays map cleanly onto Symfony's tree builder output. Keep the same key names so documentation and upstream examples still apply, and use env() only at the leaves.

Bind the entry point, not the internals. Don't new library classes in your application code. Bind the top-level service (whatever SapientExtension aliases) as a singleton in the container and inject the interface. If the library exposes no interface, wrap it in your own thin adapter so you have a seam for testing and for the eventual migration off this thing.

Contextual binding over decoration. Symfony users reach for service decoration and compiler passes; in Laravel the equivalent is $this->app->when(MyJob::class)->needs(SapientClient::class)->give(fn () => ...) plus bind()/singleton() in the provider. This is how you'd customise behaviour per-consumer without forking the archived bundle.

Provider skeleton (the whole migration):

public function register(): void
{
    $this->mergeConfigFrom(__DIR__.'/../config/sapient.php', 'sapient');
    $this->app->singleton(SapientClient::class, fn ($app) =>
        new SapientClient($app['config']->get('sapient'))
    );
}

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/sapient.php' => config_path('sapient.php'),
    ], 'sapient-config');
}

Testing. Because the bundle only wires services, your tests should target the library. In Laravel, $this->swap(SapientClient::class, $fake) or $this->instance(...) in setUp(). If you kept the Symfony bundle, use KernelTestCase with a minimal test container — but be aware the bundle likely has no test suite of its own (11 stars, 0 dependents), so you are the QA.

Feature-flag the integration. Put the whole thing behind a config flag and an adapter interface. Given the archive status, you want a one-line rollback when the underlying library stops receiving PHP version bumps.

Gotchas and Tips

• Archived means archived. No security patches, no PHP 8.4/Symfony 7 compatibility work, no issue triage. Treat every line as vendored code you own. Budget for a fork the moment you hit a deprecation.
• Zero dependents is a real signal. Nobody has run this against a modern stack. Expect the composer.json to be stale, the README to reference removed Symfony APIs (AppKernel, services.yml), and the CI badge to be broken.
• No Laravel auto-discovery. If you install it anyway, Laravel will not register the bundle. There is no extra.laravel block. You'd have to instantiate the Extension manually — which is absurd; don't.
• Debugging in Symfony: bin/console debug:container --tag=sapient and debug:config sapient are your friends; they'll surface whether the extension actually loaded. In Laravel, php artisan tinker + app(SapientClient::class) and config('sapient') will tell you the same thing in seconds.
• Config quirks: Symfony tree builders silently drop unknown keys depending on ignoreExtraKeys settings. If a setting appears to have no effect, verify it survived normalisation — this is the single most common wrapper-bundle footgun, and it bites hardest when the bundle is unmaintained and its tree builder predates allowEmptyArrays / ignoreExtraKeys semantics changes.
• Extension points are few. Realistically: a compiler pass (Symfony) or container rebinding (Laravel). If you need more than that, the abstraction is wrong for your use case — use the library directly.
• Dependency resolution traps. A bundle that pins symfony/http-kernel: ^3.4 will drag in old polyfills and can downgrade unrelated packages in a monorepo. Use composer why-not before committing, and prefer --dry-run on the first install.
• Migration path, ranked: (1) use lepiaf/sapient directly behind your own adapter; (2) fork the bundle and vendor just the Extension/Configuration classes; (3) keep the bundle as-is only if you're already on a matching Symfony version and accept the risk. For a Laravel team, option 1 is the only defensible choice.