Iugu Bundle Laravel Package

Technical Evaluation

Architecture fit — This is the decisive issue: hugomn/iugu-bundle is a Symfony bundle, not a Laravel package. It integrates via Symfony's Bundle class, DependencyInjection\Extension, and FrameworkBundle auto-registration. Laravel has no bundle loader; it boots service providers. Laravel does consume Symfony components (HttpFoundation, Console, etc.), but a bundle is a FrameworkBundle construct and cannot be registered in a Laravel application. Adopting this package as-is in a Laravel codebase is not feasible without forking it into a service provider — at which point the only thing you are reusing is ~100 lines of container wiring around the actual Iugu SDK. The value proposition collapses: you want the Iugu API client, not this bundle. The real dependency to evaluate is the underlying official Iugu PHP SDK (verify the currently maintained client on Packagist) or direct REST calls via Guzzle.

Integration feasibility — Low, and deliberately so. A Laravel-native wrapper is a small, well-understood build: a config/iugu.php (API token, account/private token, sandbox flag), a service provider binding a typed client interface into the container, an optional facade, and a gateway abstraction so Iugu can be swapped. That is roughly 1–3 engineering days including tests — materially cheaper than the compliance and upgrade risk of resurrecting a 2016 Symfony bundle. If the underlying need is narrow (create invoice, charge card token, handle webhook), a thin Guzzle client is often preferable to any third-party wrapper.

Technical risk — High, and concentrated in abandonment.

• Age/stack drift: Last release 2016-09-27. That is PHP 5.6/7.0-era and Symfony 2.x/3.x-era code. Expect deprecated DI patterns, ContainerAware-style service location, and probable fatal errors on PHP 8.x (typed property conflicts, removed each(), dynamic property deprecation, etc.). Symfony 4+ removed several APIs this bundle likely relies on.
• API drift: The Iugu platform has evolved substantially since 2016 (PIX, revised webhook signing, marketplace/split semantics, token model changes). A bundled, pinned SDK version is a liability rather than an asset — you inherit an API client frozen against a contract that has moved.
• Zero signal: 0 stars, 0 dependents, no ecosystem. No security disclosure channel, no maintainer responsiveness expectation, no third party who has validated it in production. This is a single-author artifact, not a dependency.
• PCI/compliance surface: Iugu is a tokenization gateway; the safe pattern is client-side tokenization so raw PAN never touches your servers. If this bundle's ergonomics encourage server-side card capture, you expand PCI DSS scope (SAQ D) for no benefit.
• License: verify before any fork. If permissive (MIT), forking is viable; if not, the bundle is a dead end.

Key questions — (1) Do we actually need this bundle at all, or only the Iugu REST API? (2) What is the real official SDK's release cadence and PHP 8 support? (3) Which Iugu capabilities are in scope — one-off charges, subscriptions, boleto, PIX, marketplace split? (4) Are we handling raw card data anywhere, or strictly tokens? (5) Who owns Iugu credential rotation and webhook secret management? (6) Is a fork-and-maintain budget approved, or is this a "no" by default?

Recommendation: Do not adopt. Use the maintained official SDK (or a thin Guzzle client) behind a Laravel service provider and a gateway interface.

Integration Approach

Stack fit — Replace the bundle with a Laravel-native adapter. Concretely: App\Payments\Iugu\IuguClient implementing a PaymentGateway contract; IuguServiceProvider binding it as a singleton with config injected; config/iugu.php reading from env (IUGU_API_TOKEN, IUGU_ACCOUNT_ID, IUGU_SANDBOX); secrets in a vault or encrypted env, never in the repo. Keep the Iugu-specific client behind the interface so domain code never imports Iugu namespaces — this is the single highest-leverage decision for future provider swaps and for testability (fake the interface in tests rather than mocking HTTP).

Migration path — If nothing is in production, this is greenfield: build the adapter, skip the bundle entirely. If a Symfony service already uses the bundle, do not bridge the two containers — that path leads to a dual-container runtime and duplicated config. Instead, extract the bundle's effective configuration and service definitions (they are few), re-express them as a Laravel provider, and port call sites to the new interface. Treat the old bundle as documentation, not as code to reuse.

Compatibility — Pin the official SDK to a version explicitly supporting your PHP runtime (target PHP 8.2/8.3) and verify against Laravel 10/11. Confirm Guzzle major version alignment to avoid dependency conflicts with Laravel's HTTP client stack. Add a composer why-not check in CI as a guard. Validate against the Iugu sandbox, not production, for all contract tests.

Sequencing —

1. Spike (1 day): confirm official SDK health, license, PHP 8 support, and Iugu API version in use.
2. Contract definition: model PaymentGateway around your domain (charge, refund, webhook event), not around Iugu's endpoint shape.
3. Adapter + provider + config; unit tests with a faked interface, integration tests against sandbox.
4. Webhook receiver: verify signature, persist raw payload idempotently, enqueue processing, return 200 fast.
5. Reconciliation job against Iugu's API as source of truth before go-live.
6. Only then wire into checkout flows.

Operational Impact

Maintenance — The bundle itself is unmaintained and should carry no maintenance burden because it should not be installed. The residual burden is the official SDK plus your adapter. Budget ~2–4 days/quarter for SDK upgrades, plus on-call coverage for payment incidents. If you fork the bundle instead, budget an owner and a review cadence — an unowned fork in the payment path is an unacceptable risk.

Support — No maintainer to escalate to; Iugu's vendor support will not cover third-party wrapper bugs and will (reasonably) ask you to reproduce against their API directly. Your adapter shrinks this to a single, debuggable seam. Ensure the team can read raw Iugu API responses — log request IDs (X-Request-Id or equivalent) on every call so vendor tickets are actionable.

Scaling — Iugu calls are synchronous HTTP; in PHP-FPM they block a worker. Under checkout load, apply explicit connect/read timeouts (2–5s), circuit-break on repeated failures, and never call Iugu inline in a webhook handler — enqueue it. Expect rate limits; implement exponential backoff with jitter and honor Retry-After. Idempotency keys are mandatory on charge creation: retries without them are how duplicate charges happen, and duplicate charges in Brazil mean refunds, chargebacks, and support load. Webhook volume should be absorbed by a queue with a dead-letter path.

Failure modes — Enumerate and instrument: gateway timeout with unknown charge state (resolve via lookup before retry, never blind-retry); webhook lost or delivered twice (idempotent upsert keyed on Iugu event/resource ID); token expiry on saved cards; boleto and PIX asynchronous settlement and expiry windows (do not treat "created" as "paid"); split/marketplace reconciliation mismatches; CPF/CNPJ and BRL formatting errors surfacing as opaque 400s; credential rotation causing a silent 401 storm. Each needs an alert, not just a log line.

Ramp-up — The bundle offers no ramp-up benefit worth having. The genuine ramp-up cost is domain, not code: Brazilian payment mechanics (boleto settlement, PIX expiry, installment/parcelamento rules, chargeback windows, and any fiscal/NF-e obligations around invoicing). Allocate more time to that than to the integration. For a TPM, the framing is simple: this package's score of 0, zero dependents, and a 2016 last release make it a no on adoption — but the underlying business need (Iugu integration in Laravel) is a small, low-risk, well-scoped build that should be staffed directly.