Api Bundle Laravel Package

Technical Evaluation

Architecture fit

• keboola/api-bundle is a Symfony bundle, not a Laravel package. It assumes Symfony's DI container, HttpKernel, Config component, and bundle registration model — none of which map cleanly onto Laravel's service container or HTTP kernel.
• Release 6.3.0 reinforces this: every change is expressed in Symfony idioms — KeboolaApiExtension, a container service ID constant (AUTH_MANAGE_CLIENT_FACTORY_ID), autowired ManageApiClientFactory, and AuthenticatorTestTrait for functional tests. There is still no Laravel service provider, facade, publishable config, or Artisan surface.
• The bundle is a thin Symfony glue layer over Keboola's API client and DTOs. The reusable value for a Laravel team is the underlying client logic, not the bundle wiring — and 6.3.0 is a pure wiring/config release, which is exactly the layer we would not adopt.
• Fit remains low as a bundle, medium as a source of client code if the core is separable.

Integration feasibility

• First task is still a source audit: identify whether API transport, auth, pagination, retries, and DTOs live in this repo or in a separate keboola/php-api-client dependency. If the latter, integrate that library directly and skip the bundle entirely.
• 6.3.0 sharpens this question. The new keboola_api.auth.client_options.backoff_max_tries option and the factory-ID change are both extension-layer concerns, implying meaningful retry/auth behavior sits behind container-configured clients we would have to re-implement or manually construct. Budget for replicating the retry policy explicitly rather than inheriting it.
• If transport logic is embedded in bundle services, we can still instantiate those classes manually from a Laravel service provider, provided they do not require a booted Symfony kernel. The new default retry cap (3 tries, 7 s backoff ceiling) is small enough to reimplement natively, which lowers the cost of the "skip the bundle" path.
• Composer constraint risk is unchanged and still real: the bundle will pin symfony/* ranges that may collide with the Symfony components Laravel already locks (HttpKernel, Config, Console). A composer why-not analysis against our Laravel version is a gating step.
• Feasibility verdict: conditional — viable behind an anti-corruption layer, not viable as a drop-in dependency.

Technical risk

• Adoption signals remain weak: 0 stars, 0 dependents, no visible external community. Support is effectively single-vendor.
• The 6.3.0 release is a partial positive signal on hygiene: the project is on a maintained 6.x line (a 6.2.0 → 6.3.0 delta exists), the changelog is scoped and conventional, and the change is a semver-appropriate minor. This narrows — but does not eliminate — the earlier concern about release-metadata irregularity. The version numbering is coherent; the previously flagged anomalous release date is still unexplained and should be treated as an open question rather than a resolved one.
• The release confirms that internal Symfony container keys are part of the practical contract: anyone stubbing ManageApiClientFactory::class must now retarget AUTH_MANAGE_CLIENT_FACTORY_ID. That is a test-harness-visible change shipped in a minor bump. Treat container keys, service IDs, and autowiring behavior as unstable internals we should not bind to.
• New behavioural default worth flagging: auth-path clients now fail fast at 3 tries with backoff capped at 7 s. This is a silent resilience reduction for existing consumers (previously unbounded or differently bounded), and it is explicitly asymmetric — storage_client_options clients and autowired ManageApiClientFactory calls are unaffected. Two retry semantics in one codebase is a diagnosability hazard.
• The package is optimized for Keboola's own services rather than general-purpose consumption; API surface stability and BC guarantees remain undocumented.
• MIT license is permissive and permits forking, which mitigates abandonment risk but transfers maintenance cost to us.
• Blast radius is contained if we isolate it behind an interface and keep a raw-HTTP fallback.

Key questions

• Does it require a full Symfony application context, or can its services be constructed standalone?
• Which Keboola APIs does it cover (Storage, Connection, Manage), and which auth model (Storage API token, Master token, OAuth)?
• Is there a standalone client library we should depend on instead — and if so, was the 6.3.0 retry change made there, or only in the bundle?
• What was the auth retry behavior before 6.3.0 (i.e., is backoff_max_tries: 3 a tightening of an existing default), and is a 7 s ceiling acceptable against our p95 auth latency and Keboola's transient-failure profile?
• Why are controller-facing storage_client_options clients left with different retry semantics than auth clients? Is that intentional or an incomplete rollout?
• What is the supported PHP/Symfony matrix, and does it conflict with our Laravel version?
• Is the 2026 release date genuine? What is the actual release cadence and maintainer commitment?
• What test coverage exists, and are there integration tests against a Keboola sandbox?
• Are there documented rate limits, retry semantics, and job lifecycle contracts?

Integration Approach

Stack fit

• Target stack: Laravel 10/11/12 on PHP 8.2+. Expect friction on shared symfony/* transitive dependencies.
• Preferred pattern is unchanged: define a KeboolaClientContract in our domain layer and implement it with either (a) a thin adapter over the bundle's client classes, or (b) a native Saloon/Guzzle client against the Keboola REST API. Option (b) is the lower-risk default if the audit shows the bundle is mostly wiring — and 6.3.0 is further evidence that the bundle's churn is in wiring.
• 6.3.0 adds a concrete data point for option (b): the vendor's chosen auth retry policy is now 3 tries / 7 s cap, which is trivial to reproduce natively. We do not need the bundle to get sane auth resilience; if anything, we need to own it so it is consistent and tunable per tenant.
• If the bundle cannot be cleanly instantiated outside Symfony, run it as a separate Symfony sidecar service and communicate over HTTP or a queue. This preserves vendor code while keeping Laravel clean.

Migration path

1. Audit — read composer.json, identify the standalone client dependency, map services to transport/DTO/auth concerns. Include the 6.3.0 diff to confirm which retry logic lives in the bundle versus a dependency.
2. Spike — authenticate against a Keboola sandbox project, execute one read and one job-creation flow in a scratch Laravel app. Explicitly measure auth behavior under induced 5xx/429 to see whether the 3-try/7 s default is sufficient or needs to be overridden.
3. Wrap — implement the contract with the adapter; add config, credential binding, and error mapping in a service provider. Define one retry policy for all Keboola calls in our config, overriding or bypassing the bundle's asymmetric defaults.
4. Fallback — if the spike fails on constraints or kernel coupling, switch to direct HTTP implementation behind the same contract with no upstream impact. Replicate the fail-fast auth semantics deliberately, not by accident.

Compatibility

• Verify symfony/* constraint overlap with the Laravel version in use; resolve via Composer aliasing or by isolating the dependency in a separate service.
• Confirm PHP extension requirements (curl, json, mbstring) and Guzzle major version alignment.
• Confirm Keboola API version compatibility and token scope requirements per environment.
• Note for anyone maintaining a test harness: stubs must target KeboolaApiExtension::AUTH_MANAGE_CLIENT_FACTORY_ID rather than ManageApiClientFactory::class as of 6.3.0. Do not encode either key into our own fixtures — stub our contract instead.

Sequencing

• No sequencing change is required; 6.3.0 contains no migration obligation for us unless we are already pinned to the bundle, which we are not.
• Ship read-only extraction paths first (lowest write risk, easiest rollback), then job submission, then configuration writes.
• Introduce behind a feature flag with dual-run comparison against any existing manual integration.
• Do not block other roadmap work on this package; it is a candidate, not a committed dependency.

Operational Impact

Maintenance

• Vendor-maintained with negligible community contribution. If Keboola deprioritizes it, we inherit the fork under MIT.
• The 6.2.0 → 6.3.0 delta is a mildly encouraging maintenance signal within the 6.x line, but it is a single data point and the maintainer commitment and cadence remain undocumented.
• Budget ongoing effort for Composer constraint patching on every Laravel/PHP upgrade. Pin exact versions and vendor the code if the integration becomes business-critical.
• Treat the anomalous release metadata and the minor-version container-key change as signals to review upstream tags and diffs before adopting, rather than trusting semver alone.

Support

• Support channel is Keboola's commercial relationship, not open-source community. Confirm entitlement before depending on it.
• No public issue history to mine for known failure modes; we must build our own runbook and incident playbook.
• The 6.3.0 auth retry change is exactly the class of behaviour that will not surface in upstream docs and will surprise on-call engineers. Document our own effective retry/timeout values and the fact that upstream defaults differ by client type.
• Internal documentation will be net-new; assume upstream docs are sparse.

Scaling

• The package is a stateless API client; scaling is bounded by Keboola API rate limits and job queue throughput, not by the library.
• Long-running Keboola jobs must be dispatched to Laravel queue workers with idempotency keys to avoid duplicate job submission on retry.
• The 7 s backoff ceiling means auth failures surface quickly under sustained Keboola degradation. That is desirable for fail-fast, but it removes headroom for riding out transient blips; capacity planning should assume auth-dependent requests will error rather than queue-and-retry during a Keboola incident.
• Implement backoff on 429/5xx, connection reuse, and per-tenant token isolation.

Failure modes

• Token expiry or rotation breaking auth silently.
• New: auth-path fail-fast (3 tries / 7 s cap) surfacing credential-provider blips as hard failures in jobs that previously would have recovered.
• New: inconsistent retry semantics between auth clients and controller-facing clients producing hard-to-reproduce, path-dependent intermittent failures.
• New: engineers upgrading the bundle in a downstream service hitting the AUTH_MANAGE_CLIENT_FACTORY_ID test-harness change and seeing red CI with no obvious cause.
• Rate limiting (429) cascading into job failures without backoff.
• Partial batch failures producing inconsistent local state.
• Composer constraint breakage on Laravel upgrade, blocking deploys.
• Bundle bootstrap errors if someone attempts native Laravel registration.
• Upstream DTO or response shape changes without semver signalling.
• API deprecation on Keboola's side with no migration notice.

Ramp-up

• Engineer ramp-up is low on Symfony mechanics (we avoid them) but moderate on Keboola domain concepts: projects, buckets, tables, configurations, job lifecycle.
• 6.3.0 adds a small amount of required context — the auth-vs-controller client distinction and the fail-fast posture — that any engineer touching Keboola authentication must understand. Fold this into onboarding notes rather than relying on upstream changelogs.
• Estimate one to two sprints for audit, spike, adapter, and tests before production exposure. Unchanged by this release.
• Recommend a single owning engineer for the adapter and a documented fallback path so the team is never blocked by upstream.