Clients Bundle Laravel Package

Technical Evaluation

Architecture fit tefps/clients-bundle is a Symfony-first integration client for the TEFPS declaration platform, published by Polyconseil. For a TPM the important signal is the -bundle suffix: it ships Symfony container wiring, a configuration tree, and DI-managed services. Laravel has no bundle lifecycle, so the package will install but never boot on its own. The realistic fit is a thin adapter — instantiate the underlying client from a Laravel service provider, bind it as a singleton, and keep the bundle registration class out of the picture entirely. That is a bounded wiring problem, not an architectural blocker, but it does mean we consume the package as a vendored library rather than as designed. Expect a generated or semi-generated API client underneath: wide endpoint coverage, shallow ergonomics, PSR-18/Guzzle transport, serializer-based hydration.

Integration feasibility Feasible in a one-to-two-day spike. Composer is the only real gate. The things a TPM needs validated before commitment are: Symfony component version pins conflicting with Laravel's transitive symfony/* set; the PHP version floor (a 7.x target may install on 8.x but is untested there); and whether the client core is separable from the bundle or whether business logic lives inside DI-configured services. If the latter, we are reimplementing wiring by hand, which changes the estimate.

Technical risk High, and driven by adoption evidence rather than code quality: 0 stars, 0 dependents, score 0. There is no community patch flow, no ecosystem security advisories, and no observable maintenance cadence. For a client sitting on a regulatory filing path that is material — a silent upstream API change produces failed statutory declarations, not a broken UI. Secondary risks: undocumented auth model (API key vs. OAuth2 client credentials), no published retry or idempotency semantics, unclear sandbox availability, and licence clarity for forking.

Key questions

1. Is this the officially sanctioned client, and who owns the TEFPS API contract?
2. Is a supported sandbox and credential set available to us?
3. REST/JSON or SOAP/XML legacy interface?
4. Is the bundle class separable from the client core, or is DI wiring load-bearing?
5. What is the licence, and are we permitted to fork and self-maintain?
6. Which entity categories and declaration types does it cover — does it solve our filing obligation?
7. What is the upstream regeneration policy, and is there a changelog?

Integration Approach

Stack fit Poor-to-adequate. A Symfony bundle asked to run in Laravel. The impedance is concentrated in wiring, not runtime behaviour — once the client object exists it is just PHP making HTTP calls. Treat the framework mismatch as a bounded adapter problem and sequence the work accordingly.

Migration path Do not adopt incrementally across the codebase. Contain it:

1. Isolated spike in a scratch branch — install, resolve Composer, authenticate to sandbox, execute one read and one write.
2. Wrap the client behind our own narrow interface (TefpsDeclarationGateway or similar) with domain-shaped methods. No vendor DTOs leak into controllers, jobs, or models.
3. Bind via a dedicated Laravel service provider; register config under config/tefps.php and keep credentials in the secret store.
4. Feature-flag the gateway. The existing manual/portal-based filing remains the fallback until parity is proven.

Compatibility Pin by exact version — or by commit hash if no tags exist — and commit the lockfile. Assume no semver discipline. Run the app's test suite against PHP 8.x with deprecations promoted to errors during the spike so the true constraint surface surfaces early rather than in production.

Sequencing Spike → contract validation against sandbox → adapter + tests → shadow-mode runs against real filings (compute the payload, don't submit) → limited production submission for one entity → general rollout. Budget explicit time for the legal/administrative onboarding of credentials; in French tele-declaration systems that is frequently the long pole, not the code.

Operational Impact

Maintenance We should plan to own this. With zero dependents and no visible maintainer activity, the working assumption is fork-and-vendor: mirror the repository internally, patch it ourselves, and treat upstream as a reference implementation rather than a dependency. Budget a standing, low-but-nonzero allocation — a few days per quarter — plus a defined trigger to re-sync when the TEFPS contract changes.

Support No vendor SLA, no community. Internal escalation only. Mitigate with an internal README documenting auth flow, sandbox endpoints, payload shapes, and known quirks — this package will not document itself, and the next engineer will not have the spike context.

Scaling Throughput is not the concern; the TEFPS API is the bottleneck and we will be a low-volume caller. The real characteristic is temporal burstiness: declaration platforms concentrate load in the days before statutory deadlines. Design for that explicitly — queue submissions, apply jittered retry with backoff, and never let a deadline-week cron fan out synchronously. If the client offers no idempotency key, build duplicate-submission detection on our side before we ever retry a write.

Failure modes

• Silent schema drift — upstream changes a field, hydration succeeds with nulls, we file an incomplete declaration. Mitigate with contract tests and strict validation of the outgoing payload against our own domain rules before transmission.
• Auth expiry / credential rotation — token refresh not handled by the generated client; failures surface as opaque 401s at deadline. Needs explicit handling and alerting.
• Partial failure on batch submissions — no transactional semantics across calls; requires per-item status tracking and a reconciliation job.
• Composer resolution breakage on framework upgrades — an unmaintained package pinning old Symfony components will eventually block a Laravel major upgrade. That day is the real cost of this dependency and belongs on the risk register now.
• Deadline-week outage with no fallback — the reason the manual portal path must remain documented and rehearsed, not merely remembered.

Ramp-up Low for the code — a mid-level PHP engineer is productive on the client in two to three days. High for the domain: TEFPS declaration semantics, entity categories, reporting periods, and rounding/units for declared quantities is where the schedule actually goes. Pair the engineer with whoever currently owns the filing process and treat that person as the requirements source of truth.