Billingo Bundle Laravel Package

Technical Evaluation

Critical framing note: despite being submitted under a "Laravel/PHP package" prompt, padam87/billingo-bundle is a Symfony bundle, not a Laravel package. It ships a Bundle class, a DI extension, and a config tree — none of which Laravel's service container understands. Treat this as a source of reference code, not a drop-in dependency.

Architecture fit

• The value is in the transport layer (Billingo API client, auth, request/response mapping) and the domain objects (invoices, partners, blocks, bank accounts, documents). The bundle wrapper is the least reusable part for a Laravel shop.
• Expect Symfony-leaning coupling: constructor injection via YAML/XML service definitions, Symfony HTTP Client or PSR-18 client, possibly Symfony Serializer for DTO hydration. Reusable, but only after stripping the container wiring.
• Underlying library may be a separate SDK (e.g. an official or community Billingo client). Confirm whether the bundle is a thin shell over a standalone package — if so, depend on the SDK and skip the bundle entirely.

Integration feasibility

• Two viable paths: (1) install the bundle, exclude bundle registration, and manually bind the underlying client in a Laravel service provider; (2) fork/vendor the client classes into app/ or a private package. Path 1 is fragile across bundle releases; path 2 is ~1 day of work and gives you full control.
• No Laravel artifacts exist: no service provider, no config publish, no facade, no error-type mapping to Laravel conventions.
• Recommended alternative: implement the API surface with Saloon (Laravel-native HTTP client) against Billingo's documented API, using this repo as a spec for endpoints, payload shapes, and edge cases. Scope is small — likely 15–25 endpoints for our use case.

Technical risk

• Vetting risk (high): 1 star, 0 dependents. Effectively zero production signal. No evidence of CI, test suite, or downstream validation.
• Bus factor (high): single-maintainer package in a regulated domain.
• Compliance risk (high): invoicing is legally load-bearing in Hungary (NAV online invoice reporting, sequential numbering, retention). A serialization bug or silent retry can produce a legally invalid invoice or a numbering gap. This is not a domain where "it probably works" is acceptable.
• API churn (medium): Billingo has iterated API versions; older versions were deprecated. Pin to a known version and track the vendor changelog rather than the bundle's.
• Maturity signals (mixed): a 2026-04-25 release suggests recent attention, so it is not abandoned — but a recent release with one star may indicate a personal-use library rather than a supported product.
• Opportunity score 4.54 is low and correct: the package is a thin wrapper over a vendor HTTP API. Building or owning this is cheap; there is little strategic leverage in adopting it.

Key questions for the maintainer / spike

1. Does the bundle delegate to a standalone client library, and what is that library's status?
2. Which Billingo API version does it target, and how are breaking changes handled?
3. Is there a test suite, and does it run against a sandbox or recorded fixtures?
4. How does it handle idempotency, duplicate-invoice prevention, and retries on network timeouts?
5. Does it track NAV submission status (pending/accepted/rejected) or only fire-and-forget?
6. License terms — permissive enough to vendor and modify?
7. PHP and Symfony version constraints; any transitive deps that conflict with a Laravel 10/11/12 stack?

Integration Approach

Stack fit

• Poor as a package; good as a specification. Laravel and Symfony share PSR interfaces (PSR-18 HTTP client, PSR-7 messages, PSR-3 logging), so the transport-level code is portable — the Symfony DI/config layer is not.
• Our stack should own the integration seam: a BillingoGateway interface in app/Contracts, a Saloon-backed implementation, and a single service provider binding. Vendor code never appears in domain services.

Migration path

• Greenfield: no migration, only a decision. Skip the bundle.
• If the bundle is already installed somewhere: extract a BillingoClient boundary, run old and new implementations behind a feature flag, and diff responses on read-only calls before cutting over writes.
• Do not attempt incremental "use the bundle for reads, native for writes" — split implementations double the surface for invoice-state divergence.

Compatibility

• Verify PHP constraint against our runtime (likely PHP 8.2/8.3) and Symfony component versions against Laravel's bundled Illuminate releases. Symfony 5/6/7 component mixing with a Laravel app is usually tolerable for HTTP client and serializer, but transitive version pins are the common breakage.
• Confirm PSR-18 vs. Guzzle-specific usage; Laravel ships Guzzle, so Guzzle-specific code is actually fine here.

Sequencing

1. Spike (2–3 days): stand up a Billingo sandbox account, enumerate the flows we need (create partner → issue invoice → submit to NAV → poll status → download PDF / cancel-storno), and validate the bundle's coverage against that list. Output: coverage matrix, not a prototype.
2. Domain contract: define InvoiceGateway with explicit semantics for idempotency keys, numbering, and failure states. Design this before choosing an implementation.
3. Build or vendor: if the spike shows full coverage and clean code, vendor the client into a private package. Otherwise implement with Saloon from the vendor docs.
4. Laravel wiring: service provider, config file, credential handling via secrets manager (not .env in production), queue for outbound calls.
5. Compliance review: walk the flow with Hungarian accounting/tax counsel before any real invoice is issued. Non-negotiable.
6. Parallel run: issue test invoices in sandbox against the existing process, reconcile field-by-field, then staged rollout by entity or invoice type.

Operational Impact

Maintenance

• Assume we own it. Plan to vendor or fork within the first quarter; do not depend on upstream releases for fixes in a regulated flow. Budget roughly 1–2 engineer-days per quarter for API/version drift and dependency updates.
• Track Billingo's API changelog directly, not the package's release notes — the vendor is the source of truth.

Support

• No community, no dependents, no Stack Overflow corpus. Support for genuine issues is upstream vendor documentation plus our own on-call. That is an acceptable trade only because the domain surface is small.
• Escalation for NAV rejections goes to Billingo support and Hungarian tax counsel, not to a package maintainer. Make that route explicit in the runbook.

Scaling

• Volume is low relative to web traffic — invoicing is bursty, not sustained. The binding constraint is Billingo's rate limits and NAV submission latency, not throughput.
• Push all outbound calls to a queue with per-account rate limiting and exponential backoff. Never issue an invoice on the request path of a customer-facing action.
• Long-term storage: persist the Billingo invoice ID, our idempotency key, the NAV submission status, and the raw response payload for every attempt. Retention requirements make this mandatory regardless of vendor.

Failure modes to design for explicitly

• Duplicate invoices from retried timeouts — enforce client-generated idempotency keys and a local uniqueness constraint on (partner, amount, period).
• Numbering gaps — legally sensitive; the vendor assigns numbers, so never retry a create blindly after an ambiguous failure. Query-then-decide.
• Partial failure between our database commit and the Billingo create call — outbox pattern, not a bare API call.
• NAV rejection or outage — invoices may be issued but unsubmitted; need a reconciliation job and an operator alert, not silent failures.
• Auth token expiry / credential rotation — handle 401 with a single refresh-and-retry, then fail loudly.
• Silent DTO drift when Billingo adds required fields — schema validation on responses plus a canary invoice in staging.

Ramp-up

• The API is the easy part. Engineers need Hungarian invoicing domain context: VAT (ÁFA) rates and exemptions, NAV online invoice obligations, storno/cancellation rules, retention periods, and the difference between issuing and reporting. Budget 2–3 weeks of domain ramp-up for the first engineer, plus structured access to an accountant.
• Mitigate bus factor by pairing a second engineer on the compliance review and runbook authoring, not just the code.

Bottom line for the TPM: adopt Billingo as a vendor, but do not adopt this bundle as a dependency. Use it as a spec, own a thin Laravel-native client behind a domain interface, and spend the saved integration time on idempotency and compliance review — those are where the actual risk lives.