Php Library Laravel Package

Technical Evaluation

Context and framing. This is not a community package in the normal sense. It is a vendor-published SDK for Paymob (the Egyptian/North African payment gateway covering Card/Accept, Wallet, Kiosk, and related rails), hosted on GitLab rather than GitHub, with no stars, zero dependents, and no description beyond "Paymob PHP Library." The opportunity score (~50) reflects category relevance, not package health. The correct mental model is an external vendor dependency, not an OSS library you would adopt on reputation. Evaluate it the way you would evaluate a partner-supplied SDK: assume nothing, verify everything, and wrap it.

Architecture fit. The package is a plain PHP library — there is no evidence of a Laravel service provider, config publish stub, facade, or framework-agnostic contract layer. That is a fit gap but a small one: it means integration work lands in our codebase as a thin adapter (config + provider + a PaymobGateway class implementing our own PaymentGateway interface) rather than being free. This is arguably the better outcome, because the adapter becomes the stable seam we own and the vendor lib becomes replaceable. Fit is good at the protocol level (PHP, Composer-installable, HTTP-based gateway API) and neutral-to-poor at the framework level (nothing Laravel-idiomatic is provided).

Integration feasibility. The gating question is distribution. If it is not published on Packagist with tagged, semver-constrained releases, consumption requires a composer.json VCS repository entry pinned to a commit SHA — which means no ^1.0 constraint, no automated upgrade path, and a manual diff review on every bump. That is survivable for a single integration but it is a governance cost that must be accepted explicitly. Secondary feasibility check: does the library abstract its HTTP client (PSR-18/PSR-7) or hard-code Guzzle/cURL? Hard-coded transport complicates testing and conflicts with Laravel's HTTP client conventions and our mocked-facade test strategy.

Technical risk (ranked by blast radius):

Key questions (blocking — need answers before commitment):

1. Is this the officially maintained Paymob SDK, and is the GitLab group paymob-integrations owned by Paymob the company? Who is the accountable maintainer and what is the support channel (email/Slack/SLA)?
2. Is it on Packagist, and does it publish tagged releases with a changelog? What versions of PHP does it support (8.1+? 8.3?)?
3. Which Paymob products and API surfaces does it cover — Accept only, or Wallet/Kiosk/Installments? Does it cover: auth token, order registration, payment key request, iframe redirect, webhook HMAC verification, refund, void, capture, and card tokenization/MOTO?
4. Does it abstract HTTP transport (PSR-18) or couple to Guzzle? Are there tests, and what is coverage on the HMAC and error-mapping paths?
5. What is the error model — typed exceptions, or raw arrays/stdClass responses we must parse defensively?
6. Is there a first-party Laravel package, or is this the only option?

Integration Approach

Stack fit. Assume a plain-PHP library. Our integration surface is deliberately narrow: one PaymobGateway class implementing an internal PaymentGateway contract (authorize, capture, refund, verifyWebhook), one config/paymob.php sourced from environment/secret manager, one service provider binding, and one controller for webhook ingress. Nothing else in the application imports vendor classes directly — this anti-corruption layer is the single most important decision here, because it converts a zero-star dependency from an architectural risk into an interchangeable detail.

Migration path. Given zero dependents and unclear release hygiene, prefer fork-and-vendor over direct VCS reference: mirror the repo into our own GitLab group, tag it, and consume it as a private Composer package. This gives us pinned versions, the ability to patch a payment bug on our own timeline, and an audit trail. Cost is real (we now own the code) but the alternative — a live payment path dependent on an untagged third-party repo we cannot patch quickly — is worse. Revisit vendoring only if Paymob confirms a formal support contract and tagged releases.

Compatibility. Verify against the Laravel and PHP versions in our matrix; a library targeting PHP 8.0/8.1 may be fine today and a blocker at the next LTS upgrade. Confirm no global state, no hard dependency on a specific Guzzle major, and no composer.json conflicts with our existing HTTP stack. Also confirm behavior under Laravel's queue workers and Horizon timeouts — payment calls must not be silently killed mid-flight.

Sequencing:

1. Spike (1–2 days): sandbox credentials, walk the full happy path (order → payment key → iframe → webhook) using raw library calls in a tinker script. No framework code.
2. Contract tests: fixtures for success, decline, 3DS challenge, timeout, and duplicate webhook. These become the regression gate for every future bump.
3. Adapter + HMAC verification: implement PaymobGateway, with webhook signature verification and replay protection (idempotency key on Paymob's transaction ID) as first-class requirements, not follow-ups.
4. Reconciliation: a scheduled job that queries Paymob for the day's transactions and diffs against local payment records. This catches webhook loss — the failure mode most likely to cost money and least likely to be noticed.
5. Production behind a flag, single-currency, single-product first; expand rails (Wallet/Kiosk) only after the card path is stable.

Operational Impact

Maintenance. We are effectively the maintainers. Budget a named owner (backend lead), a pinned version, and a scheduled quarterly review: dependency audit, sandbox regression run, and a diff read of upstream changes. Treat any upstream bump as a change to a PCI-adjacent path — code review plus contract tests, no exceptions. If the fork route is taken, add a monthly check that upstream has not gone dark (no commits in 12 months = fork becomes permanent, document that).

Support. Escalation has two distinct halves: library defects (us, via the fork) and gateway defects (Paymob merchant support). Get a named Paymob technical contact and, critically, confirm whether merchant support will engage on SDK issues at all — many gateways support their API but disclaim their SDKs. Without that, our on-call runbook needs the API documentation as the primary reference and the library as an implementation detail.

Scaling. The library is a thin HTTP client; scaling is a property of Paymob's API limits, not the package. The real scaling concerns are (a) connection pooling and timeouts on synchronous payment calls inside web requests — prefer short timeouts plus async confirmation via webhook over long blocking calls; (b) queue worker concurrency against Paymob rate limits; (c) idempotency so retries under load cannot double-charge. Confirm whether Paymob publishes rate limits; if not, assume conservative defaults and instrument.

Failure modes to design for explicitly:

• Webhook delivered but HMAC verification fails or is skipped → forged payment confirmations. Non-negotiable: verify, then reject.
• Webhook lost or delayed → order stuck pending. Mitigate with the reconciliation job and a status-poll fallback.
• Duplicate/replayed webhooks → double fulfillment. Mitigate with an idempotency table keyed on Paymob transaction ID.
• Timeout on capture with unknown outcome → never blind-retry; query transaction status first.
• Library throws an untyped/opaque error on an unexpected response shape → ensure the adapter maps everything to our domain errors so upstream changes cannot crash checkout with a 500.
• Upstream repo disappears or force-pushes → the fork is the mitigation; do not rely on the public repo for reproducibility.

Ramp-up. Low technical ramp-up (small API surface, PHP-only, ~1 day for a competent Laravel engineer to be productive with the spike done). The real ramp-up is domain: Paymob's auth-token → order → payment-key flow, HMAC concatenation rules, and the distinction between authorization and capture are the things engineers get wrong. Budget 2–3 days of documentation reading and sandbox experimentation, and write an internal runbook covering the flow, the error taxonomy, and the reconciliation procedure. Total credible estimate to production-ready: 2–3 engineer-weeks, of which roughly half is adapter, HMAC, idempotency, and reconciliation work that this library does not provide.

Bottom line. Adopt conditionally — as a reference implementation and protocol guide wrapped in our own adapter, not as a trusted framework dependency. The 0-star/0-dependent profile is acceptable for a vendor SDK but demands that we own versioning (fork), own the seam (adapter), and own the money-critical behaviors the library may not implement (HMAC verification, idempotency, reconciliation). If Paymob confirms maintainership, tagging, and a support channel, drop the fork and consume directly.