Amazongiftcode Laravel Package

Getting Started

v2.0.0 targets Laravel 12/13 on PHP 8.2–8.4; Laravel 11 still installs via the illuminate/support constraint but is untested and may be blocked by Composer's advisory policy.

1. composer require the package (^2.0), then publish the config: php artisan vendor:publish --tag=... (check config/ in the package for the tag name).
2. Put credentials in .env — access key, secret, partner ID, region. Never commit them; the config file should only read from env().
3. Point the endpoint at the AGCOD sandbox (agcod-v2-gamma.*) first. Production (agcod-v2.*) issues real, funded codes — a mistake there is a real-money mistake.
4. First use case: instantiate AWS (credentials + region), hand it to AmazonGiftCode, call the create method with an amount, currency and an idempotency requestId, then read the code off CreateResponse.

Resolve both objects from the container rather than new-ing them in controllers — that is what makes the rest of this assessment's testing and mocking advice possible.

Confirm exact constructor/method signatures against the README and tests/ rather than guessing; the new test suite is the most reliable documentation the package has ever had, especially the "public API" and "response parsing" cases.

Implementation Patterns

Constructor injection for the HTTP layer. The headline change: AWS and AmazonGiftCode accept an optional ClientInterface as a constructor argument (defaulting to the bundled cURL client). Bind your own implementation in a service provider to get Guzzle / Laravel Http behaviour — retries with backoff, proxies, timeouts, request logging, or a tracing middleware — without forking the package. Keep the default client if you have no such needs; behaviour is unchanged.

Wrap it in a domain service. Don't call AmazonGiftCode from controllers. A thin GiftCardIssuer service (bound as a singleton, injecting AmazonGiftCode) gives you one place for validation, idempotency keys, persistence and event dispatch, and one place to swap when the API changes.

Idempotency is the core workflow. AGCOD deduplicates on the requestId you supply. Generate it once per business intent (e.g. an order line), persist it alongside the pending record, and reuse the same value on every retry — including queued-job retries and manual re-runs. A fresh UUID per attempt is how you accidentally issue two gift cards.

Queue the create call. Network calls to Amazon should be in a job with $tries, backoff() and failed() handling. Guard the job with WithoutOverlapping keyed on the order ID. On success, store the gcId, the code (encrypted cast), amount and currency; dispatch a domain event for fulfilment.

Balance checks as scheduled monitoring. Call the balance endpoint (CreateBalanceResponse) from a scheduled command, store the value, and alert on a low-water mark. This is the cheapest way to avoid a production outage where every issuance fails because the partner account is dry.

Test against a fake ClientInterface. The new PHPUnit + Testbench suite exists precisely so you can do the same: bind a fake client returning canned success/error XML-or-JSON bodies, and assert your service's behaviour (persisted record, dispatched event, exception surfaced to the user). No sandbox credentials, no cost, no flakiness.

Upgrade path. Bump to ^2.0, run your test suite, then grep for any code that relied on the previous crash-on-error behaviour (see below). Nothing else in the release is breaking for application code.

Gotchas and Tips

The "fix" changes error semantics — audit for it. CreateResponse and CreateBalanceResponse no longer raise an undefined-key error when Amazon omits cardInfo / availableFunds. Any code that caught that error (or let it bubble) as a failure signal will now receive an object with nulls and may sail straight past it. Treat null cardInfo / availableFunds as a failure explicitly, and prefer checking the response status/acknowledgement field when present.

A 200 is not success. AGCOD returns HTTP 200 with a failure status in the body for many error conditions (invalid amount, insufficient funds, duplicate request). Parse the status, not just the transport code.

Don't conflate 0.0 with "not parsed". After the fix, an unparseable balance yields null; a genuinely empty account yields a numeric zero. Branch on is_null() first, and fail loudly on null rather than casting to float.

Clock skew breaks signing. AWS Signature V4 rejects requests whose timestamp drifts (~5 minutes). On containers with poor time sync you get intermittent InvalidSignatureException-style failures that look like bad credentials. Run NTP; and if you swap in a ClientInterface, remember signing still happens in AWS — your client must not mangle Authorization/X-Amz-Date headers.

Redact aggressively. Gift card codes are bearer cash. Keep them out of logs, exception messages (many HTTP clients dump the full body into exceptions), queue payloads, and Telescope/Horizon views. Encrypt at rest and restrict the model's $hidden.

Amount and currency are validated server-side and unforgiving. Use the currency's minor-unit precision (2 for USD, 0 for JPY) and check the per-currency min/max before calling; a local guard gives a far better error message than an AGCOD rejection.

Configuration quirks. Region and endpoint are coupled — the wrong region against a -gamma host (or vice versa) produces opaque auth failures rather than a clear "wrong endpoint". Validate the combination at boot in a service provider, and cache the config (config:cache) in production so env() is never read at runtime.

Extension points to prefer. ClientInterface for transport, a decorator around your domain service for metrics/auditing, and events for cross-cutting reactions. Avoid subclassing the response objects — the release just showed how their shape can shift.

CI coverage you can rely on. The GitHub Actions matrix covers Laravel 12/13 and PHP 8.2–8.4 only. If you are still on Laravel 11, treat this package as "installs but unsupported": pin the version, and prioritise the framework upgrade, since Composer's advisory policy can also refuse the install outright. Scrutinizer is gone — don't wire badges or status checks to it.