Fio Api Php Laravel Package

Technical Evaluation

Architecture fit

• Thin, framework-agnostic SDK: no Laravel service provider, no facade, no config publishing. That means it slots in cleanly as a driven adapter behind a port/interface, which is exactly where you want a third-party dependency that touches money.
• Natural home is a service layer or job pipeline: a scheduled command pulls statements, a queued job normalizes and persists them, reconciliation logic sits above the interface. It does not constrain your architecture — and it does not help it either.
• Poor fit for event-driven or webhook-based designs. Fio's API is pull-only with stateful server-side cursors (lastId / lastDate). Your ingestion model must be polling + watermarking, not push. Any assumption of near-real-time balance updates is wrong.
• Scope is narrow: token-authenticated retrieval of account movements (transaction history by period or since last cursor). Payment-order import is adjacent functionality in the Fio API; verify whether this version covers it before planning around it — do not assume.

Integration feasibility

• One composer require, PHP 7.1-era constraints, Guzzle 6. No Laravel auto-discovery, so wiring is a singleton binding in a service provider — trivial.
• Happy path is genuinely small: instantiate the client with a token, call the fetch method, iterate transaction objects. A mid-level developer reaches a working read in half a day.
• The blocker is dependency resolution, not code. Laravel 9+ ships Guzzle 7; this package pins Guzzle 6. Expect Composer to refuse. Fork-and-bump is the escape hatch, at which point you own the dependency.
• No sandbox. Testing requires a live Fio token (a per-account, revocable API token generated in internet banking) or recorded fixtures. Plan for VCR-style cassettes as the contract test strategy, and treat the first live-token run as a gated milestone.

Technical risk

• Unmaintained. Last release August 2017, single maintainer, 37 stars. There is no patch path for PHP 8.x incompatibilities (implicit nullable parameters, dynamic properties, removal of legacy idioms) and no security response for transitive Guzzle issues.
• Financial data surface. The token grants read access to real account movements. That pulls the integration into your PCI/GDPR/PSD2-adjacent scope: secret storage, token rotation, audit logging, least-privilege token issuance. None of this is provided by the package.
• Undocumented upstream. Fio's API documentation is Czech-language PDF material without a formal versioning contract. The wrapper encodes assumptions about response shape that nobody is validating upstream.
• Low strategic upside. Opportunity score of 1.14 and a composite of 2.3 reflect a package that solves a commodity problem (HTTP + XML parse) with a stagnant artifact. The wrapper's value is ergonomics, not capability.

Key questions

1. Which PHP and Laravel versions are in scope? If Laravel 9+, this is a fork decision, not an adoption decision.
2. Read-only statements, or payment-order submission too? The latter materially raises risk and compliance review.
3. What is the reconciliation SLA — minutes, hours, or next business day? This determines whether Fio's throttling and your polling cadence are acceptable.
4. Single account, or multi-account/multi-tenant? Cursors are per token; the answer drives your state model.
5. Is there a real token available for CI and staging, and can we guarantee it is never shared with production?
6. Build vs. reuse: a direct Http::withToken() client for this API is roughly 150–300 lines. Does the wrapper save enough to justify the vendored-dependency tax?

Integration Approach

Stack fit

• Genuine drop-in for Laravel 5.5–7.x on PHP 7.1–7.4. That is a shrinking population.
• For Laravel 9/10/11: Composer conflict on guzzlehttp/guzzle ^6. Options, in order of preference: (a) skip the package and call the API directly with Laravel's HTTP client; (b) fork, bump the Guzzle constraint to ^6|^7, run the fixture suite, publish to a private VCS repo; (c) vendor the source into app/Support and drop the Composer dependency entirely. Do not use --ignore-platform-reqs or replace tricks — they defer the breakage into runtime.

Migration path

• Define a BankStatementProvider interface and your own transaction DTOs. Implement FioApiAdapter wrapping the package. Nothing above the adapter may reference Fio\ types.
• When you replace the package — and on this lifecycle you will — you swap one adapter class. This costs an extra day upfront and is the single highest-leverage decision in the integration.
• Persistence side: unique index on the Fio transaction ID, upsert semantics, and an ingestion-run log table recording cursor before/after. That makes replays and backfills safe and makes duplicates a non-event.

Compatibility

• Run a throwaway composer why-not mhujer/fio-api-php and a PHP 8.1/8.2 static analysis pass before committing to a spike. If PHP 8 fatal errors appear, stop and take the direct-HTTP route.
• Pin exact versions in composer.lock, add roave/security-advisories to catch transitive issues, and record an explicit "we own this" note in the ADR.
• Confirm response formats explicitly — Fio serves XML and JSON; pick one and lock the fixture set to it so format drift surfaces in CI.

Sequencing

1. Spike (2–3 days): live token, fetch one statement, capture cassettes, confirm PHP version compatibility and Composer resolution in the target app.
2. Contract layer (3–5 days): interface, DTOs, adapter, fixture-backed tests covering success, 401, 409/throttle, malformed payload, empty statement.
3. Ingestion pipeline (1 sprint): queued job, idempotent persistence, cursor management, backfill path.
4. Observability and runbook (3–4 days): structured logs, alert on consecutive failures and on watermark gaps, token-expiry alert.
5. Re-evaluation checkpoint: scheduled review at the next Laravel major upgrade, with "replace with in-house client" as the default disposition.

Operational Impact

Maintenance

• Treat this as a vendored dependency from day one. There is no upstream maintenance to rely on; you own patching, PHP-version compatibility, and any Guzzle security bumps.
• Allocate a modest standing budget (a few days per year) for revalidation, concentrated at framework major upgrades.

Support

• Documentation is a short README; upstream API documentation is Czech-language PDFs. Knowledge concentrates in whoever wrote the adapter — mitigate with an ADR, fixtures as living documentation, and a runbook that explains the cursor model in plain terms.
• Incident triage will land on your team, not the package author. There is no support channel.

Scaling

• Throughput is not the constraint — statement size is. Ingestion is bounded by how many transactions come back per window and by Fio's per-token request throttling (roughly one query per 30 seconds on cursor endpoints). Design ingestion as a serialized queue job per token; fan-out will earn you throttling errors.
• Comfortable for SME volumes and typical account counts. If you need hundreds of accounts polled continuously, the per-token throttle becomes the binding constraint and you should design around a scheduler that respects it explicitly.

Failure modes

• Expired or revoked token → 401. Needs an alert and a documented re-issuance runbook; it is the most likely production incident.
• Throttling or transient 409/5xx → retry with backoff on the job, bounded attempts, dead-letter after N.
• Malformed or truncated payload → parser exception; do not persist partial batches. Wrap the whole fetch in a transaction.
• Duplicate transactions from overlapping windows → deterministic unless you enforce a unique key on transaction ID. Enforce it.
• Silent gaps when a poll is skipped (deploy, worker outage) → server-side cursor advances are invisible to you. Add a gap check comparing expected cadence to observed runs.
• Cursor contamination across environments: Fio's cursor state is per token. Sharing a token between staging and production will corrupt both. Issue separate tokens and document it loudly.
• Timezone and currency drift: statements are Europe/Prague-oriented; store timestamps with explicit timezone and never assume the account's currency from locale.

Ramp-up

• Codebase is a handful of small classes; a mid-level PHP developer is productive in a day.
• The real onboarding cost is domain knowledge: Fio's cursor semantics, throttling behavior, statement boundary conventions, and your reconciliation invariants. Budget a week for genuine confidence, and make the fixtures the primary teaching artifact.