Api Communication Bundle Laravel Package

Getting Started

Confirm the framework fit first. Despite the request framing this as a Laravel package, imanaging-document/api-communication-bundle is a Symfony bundle (the -bundle suffix and the DependencyInjection/*Extension.php convention are the tells). It will not auto-register in Laravel and will not ship a ServiceProvider. Plan on either:

• using it in a Symfony service that talks to your Laravel app, or
• wrapping the underlying transport classes manually and registering them in a Laravel ServiceProvider.

Pin to v2.0 and read its composer.json before anything else. The new release note is one line — "Version compatible symfony 5" — which is a constraint change with no changelog around it. That single line tells you two things:

1. v2.0 wants Symfony 5 components. Laravel 8.x-era apps sit on Symfony 5.x, so this is the sweet spot. Laravel 9+ moved to Symfony 6.x, and Laravel 10/11 to 6.2/7.x — if the constraint is ^5.0 alone, Composer will refuse to install there.
2. A major bump (1.x → 2.0) accompanied only by "Symfony 5 compatible" suggests the previous line was not Symfony-5-compatible, or that v2.0 dropped Symfony 4/6 support. Which direction it went determines whether v2.0 is an upgrade or a regression for you. Diff composer.json between v1 and v2 to find out.

Minimal steps (Symfony 5 host):

composer require imanaging-document/api-communication-bundle:^2.0

// config/bundles.php
return [
    // ...
    ImanagingDocument\ApiCommunicationBundle\ApiCommunicationBundle::class => ['all' => true],
];

Then look for the extension class under DependencyInjection/ to learn the config tree — that file is the authoritative "documentation" for this bundle, more so than the README given the package's age.

Where to look first, in order:

1. composer.json — settle the version question first. Check the exact symfony/* and HTTP-client constraints against your app's installed versions.
2. README.md / CHANGELOG.md — check whether v2.0 documented a migration. Assume not, given the release-note length.
3. DependencyInjection/Configuration.php — the real config schema (base URLs, credentials, timeouts, per-remote-app settings). Re-read this on v2.0; major bumps in low-traffic bundles frequently rename config keys without saying so.
4. src/ — identify the public service(s) you'll inject. With a description like "Service de communication, par API, entre diverses applications," expect a client/service class plus request/response value objects or a message envelope. Check whether namespaces or class names moved in v2.

First use case: a one-way, low-risk call — fetch a record or push a document from app A to app B — against a staging endpoint, wired through the bundle's service rather than raw Guzzle. That validates config, auth handling, and serialization in one shot.

Sanity check before adopting: 2 stars, effectively no dependents. The v2.0 release shows a pulse, but it is a version-constraint bump, not evidence of active maintenance. Treat this as "read the source, then decide" rather than "composer require and move on."

Implementation Patterns

Inject the service, don't instantiate it. The bundle's value is the DI wiring plus config. Autowire the client interface/class into your own service or controller:

final class DocumentSync
{
    public function __construct(private ApiCommunicationClient $client) {}

    public function push(array $payload): void
    {
        $this->client->send($payload); // confirm method name in src/ — re-verify on v2.0
    }
}

Configure per-remote-application, not globally. "Between diverse applications" implies multiple peers. Model each peer as a named config block (base URI, auth, timeout) and select by name at call time — this keeps credentials out of call sites and makes staging/prod switching a config change.

Keep credentials in env, referenced from config. Symfony's %env(...)% resolution is the idiomatic path; never inline tokens in config/packages/*.yaml that gets committed.

Wrap calls in your own adapter. Given the maintenance risk, define a narrow port in your app (DocumentGateway) and implement it with this bundle. If the bundle dies — or v3.0 jumps to Symfony 6/7 only — you swap one implementation class instead of hunting call sites. This pattern matters more now that you've seen a major bump land with a one-line note.

Laravel-side integration, if you must. Skip the bundle's Symfony DI entirely; pull in its transport/DTO classes only. Then:

// app/Providers/ApiCommunicationServiceProvider.php
$this->app->singleton(ApiCommunicationClient::class, fn ($app) => new ApiCommunicationClient(
    config('services.remote.base_uri'),
    config('services.remote.token'),
));

Bind configuration in config/services.php so it plays nicely with config:cache. On Laravel 9+, expect a dependency-resolution fight (see Gotchas) — plan for the vendor-and-own route.

Treat responses as DTOs, not arrays. If the bundle ships response objects, keep them at the boundary and map to your domain types immediately. If it returns raw arrays/PSR-7, add a mapper — otherwise remote schema drift leaks into your domain.

Test at the HTTP boundary. In Symfony, swap the underlying HTTP client for a mock/scoped client in config/packages/test/. In Laravel, Http::fake() works only if the bundle ultimately routes through the Laravel client — usually it won't, so use Guzzle's MockHandler and inject it into the bundle's client.

Error semantics. Decide up front whether transport failures (timeout, 5xx) raise exceptions or return result objects. Whichever the bundle does, normalize it in your adapter so callers have one contract. Re-check this on v2.0 — exception types are a common silent change in a major bump.

Test both version lines if you're mid-migration. If you have a mixed estate (some Symfony 5 / Laravel 8 services, some Symfony 6 / Laravel 9+), verify v2.0 in the older one and keep 1.x pinned in the newer one until you know whether the constraint is ^5.0 or ^5.0|^6.0.

Gotchas and Tips

No Laravel auto-discovery. A Symfony bundle's getContainerExtension() is meaningless to Laravel. If you composer require it into a Laravel app expecting it to "just work," nothing will be registered. Confirm what you actually need — likely 2–3 classes from src/ — and wire them yourself.

v2.0's Symfony 5 target is the main compatibility hazard. "Compatible symfony 5" sounds like good news, but it can be read two ways: support added for Symfony 5, or support narrowed to Symfony 5. Check the constraint literal in composer.json:

• ^5.0 alone → works with Laravel 8.x, but blocks Laravel 9/10/11 (Symfony 6.x/7.x components).
• ^5.0|^6.0 → broadly usable; the note is understated and harmless.
• Dropped Symfony 4 → anyone on Laravel 6/7 must stay on 1.x.

Run composer why-not imanaging-document/api-communication-bundle 2.0 in each host app before you commit to an upgrade path.

A major bump with no migration notes is a red flag. Before upgrading, diff v1 against v2 across composer.json, DependencyInjection/, and src/. Look specifically for renamed config keys, renamed/moved classes and namespaces, changed method signatures on the client, and changed exception types. In a package with no dependents and no changelog, these land silently and surface as runtime errors in production.

Config tree is the doc. Symfony bundles silently ignore unknown config keys in some setups and hard-fail in others. If a setting appears to do nothing, check Configuration.php for the exact key and whether the extension actually consumes it — a common failure mode in low-traffic bundles, and doubly likely right after a major bump where the config tree may have shifted under you.

Zero dependents means zero field-testing. Nobody else is exercising the edge cases. Read the code paths for: retry behavior, timeout defaults, redirect handling, and how it serializes non-UTF-8 or large payloads. Add your own retry/backoff in the adapter rather than trusting the bundle's.

Debugging:

• Symfony: enable the profiler and inspect the HTTP client panel; if the bundle wraps a PSR-18 client, decorate it with a logging middleware to see raw requests.
• Laravel: register a Guzzle middleware/log tap in your service provider, since the framework's HTTP events won't fire for a foreign client.
• Log the resolved base URI and a redacted auth header at boot — misconfigured endpoints are the #1 cause of "it returns nothing."
• On first run after upgrading to v2.0, log the bundle version and the resolved config tree at boot. It turns a silent behavior change into a visible one.

Extension points to probe in src/: an interface for the transport client (best case — swap it), serializer hooks, and event dispatchers. If none exist, subclassing is your only seam, which argues for the adapter pattern above.

Maintenance posture. MIT license is permissive, so vendoring or forking is legally clean. Pin an exact version — "imanaging-document/api-communication-bundle": "2.0.0" — rather than a floating ^2.0, and add a test that exercises the real response shape; that test is your early warning if a peer app changes its API. Given the pace of releases here (one note after roughly three years of silence), assume the next update may be another constraint bump with equally little ceremony.

When to walk away. If the bundle is mostly a thin Guzzle wrapper plus a few DTOs, the honest call is to copy those DTOs and use Laravel's Http facade or Symfony's HttpClient directly. The bundle's only durable value is convention and config plumbing — and at 2 stars with no dependents, that value is small. v2.0 does not change that calculus; it only makes the version-constraint question slightly more concrete.