Shaparak Laravel Package

Technical Evaluation

Architecture fit. php-monsters/shaparak is a Laravel package that abstracts Iranian IPGs (Internet Payment Gateways) behind a common handler interface, wired in via a service provider and a publishable config file. Architecturally this is the right shape for a Laravel application: it slots in as a thin anti-corruption layer between the application's checkout domain and the diverse Shaparak-connected PSPs (Behpardakht/Mellat, Sadad, Parsian, Saman, Zarinpal, IDPay, Pay.ir, etc.). The critical caveat is that this is an abstraction over heterogeneous upstreams. Each Iranian gateway has its own request/verify contract, callback payload shape, signature scheme, currency unit (Rial vs. Toman), and in some cases (notably Mellat) a SOAP + client-certificate flow. The package's value is entirely a function of how faithfully it normalizes those differences — which is the first thing to validate, not assume.

Integration feasibility. Mechanically the integration is low-friction: Composer install, Laravel package auto-discovery, vendor:publish for config, per-gateway credentials in .env, then a request → redirect → callback → verify lifecycle. The real cost is outside the code: merchant onboarding with each PSP, callback URL registration and whitelisting in each gateway's panel, sandbox vs. production endpoint differences, and settlement/reconciliation requirements from finance. Budget for that as first-class integration work, not as a follow-up.

Technical risk.

• License (NOASSERTION) is the single largest blocker. You cannot ship this into a commercial product until the actual terms are confirmed in writing. Treat this as a gate, not a caveat.
• Bus factor / maturity. 32 stars and a small maintainer surface means limited peer review and a real chance of stagnation. Verify commit cadence, open-issue responsiveness, and whether tests exist against live or mocked gateways.
• Upstream volatility. Iranian PSP APIs change without much notice, and gateway behavior in production diverges from docs. Any abstraction here has a shelf life measured in months unless actively maintained.
• Environment/geopolitical risk. Package availability, CI runners, and third-party services may be constrained by sanctions and network policy. Confirm your build and deploy pipeline can reliably reach Packagist and the gateway endpoints from your target environment.
• Testing gap. Without merchant sandbox accounts you cannot validate end-to-end. Plan for credentialed integration testing, not unit tests alone.

Key questions. (1) What are the actual license terms? (2) Which gateways are supported, and at what maturity/completeness per gateway? (3) Is there a maintained test suite, and does it cover callback verification and idempotency? (4) What Laravel and PHP versions are supported, and is that matrix CI-enforced? (5) Who is the maintainer, what is the response SLA, and is commercial support or a support contract available? (6) How are currencies, amounts, and rounding handled internally? (7) Does it model verification idempotency explicitly, or is that left to the caller?

Integration Approach

Stack fit. Assumes a modern Laravel application (service provider + config + facade/DI binding) on PHP 8.x. It is a natural fit if you already run Laravel and need multi-gateway Iranian payment support without hand-rolling each PSP. If you are on a non-Laravel PHP stack, the value proposition drops sharply — you would be pulling in Laravel container assumptions for an abstraction you could reimplement more narrowly.

Migration path. Do not call the package directly from controllers or domain services. Wrap it behind a project-owned PaymentGateway interface (initiate / verify / refund-if-supported) with the package as one adapter implementation. This gives you: a stable seam if you later swap the package, a place to enforce idempotency keys and amount validation independent of upstream, and a test double for CI that doesn't require live gateways. If you are migrating off bespoke per-gateway code, port one gateway at a time behind that interface rather than a big-bang cutover.

Compatibility. Confirm the supported Laravel/PHP matrix against your version before committing. Map each target gateway to its callback payload contract and required TLS/certificate configuration — Mellat-style SOAP + mTLS gateways behave very differently operationally from REST/redirect gateways and may need infrastructure changes (outbound certs, IP allowlisting). Verify how the package represents amounts (Rial vs. Toman) and reconcile that against your pricing domain early; this is a classic source of production incidents.

Sequencing.

1. License and maintainer due diligence — hard gate.
2. Spike one high-value gateway in sandbox behind the internal interface; validate request, redirect, callback, verify, and failure paths.
3. Harden the seam: idempotency, amount/currency normalization, structured logging, callback authentication.
4. Roll out additional gateways one at a time, each with its own sandbox validation and runbook entry.
5. Production cutover with a canary (single gateway, limited traffic), then expand.
6. Document the operational runbook and a fork strategy before you depend on it at scale.

Operational Impact

Maintenance. Assume you will eventually own this code. Pin the version, vendor or mirror the dependency, and track upstream commits. Given the star count, plan for the realistic scenario in which the maintainer goes quiet and gateway API drift forces you to patch a fork. Budget a modest recurring maintenance line for this rather than treating it as a set-and-forget dependency.

Support. Expect community-only support, likely in Persian and on Iranian timezones/forums. That is a meaningful operational constraint if your on-call team is elsewhere: incident triage during an Iranian banking holiday or outside regional hours will be on you. Establish direct PSP support contacts (merchant support desks) as your primary escalation path, not the package repo.

Scaling. Payment flows are I/O-bound and callback-driven, so scaling is about correctness under concurrency more than throughput. Verify that callback handling is idempotent, that verification can be safely retried, and that duplicate callbacks (common with gateways that retry) cannot double-credit or double-fulfill. Push verification to a queued job where the gateway permits, and keep the synchronous callback handler minimal. Multi-gateway routing (failover to a secondary PSP) is a strong resilience lever — confirm the package supports selecting a handler at runtime rather than binding one globally.

Failure modes to design for. Gateway downtime or degraded latency; callback never arriving (reconciliation job required); duplicate or out-of-order callbacks; amount/currency mismatch between request and callback; signature or reference-ID validation failure; partial failures where funds are debited but verification fails (the worst case — needs a documented manual reconciliation path); and credential rotation or certificate expiry for mTLS gateways. Each needs an alert and a runbook entry, not just a caught exception.

Ramp-up. A Laravel developer can be productive on the happy path in a day or two. True operational competence — knowing which gateway behaves how under failure, how to reconcile a stuck transaction, how to add a new PSP — takes several weeks and requires Iranian payments domain knowledge that the package documentation may not supply. Plan for a named owner, a written runbook, and at least one engineer who can debug the abstraction itself, not just consume it.