Laravel Usps Laravel Package

Getting Started

1. Install and publish config

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

   Set credentials in .env (USPS user ID / OAuth client credentials, sandbox flag). Confirm config/<package>.php points at the sandbox endpoint for local work.

2. Read the README first, then the DPV table. The README explains how Delivery Point Validation works, so if you're validating addresses you know what a DPV confirmation actually guarantees before you build logic around it.

3. Smoke-test from tinker:

   use <Vendor>\<Package>\Facades\<PackageFacade>;
   
   <PackageFacade>::validateAddress([
       'streetAddress' => '123 Main St',
       'city'          => 'Springfield',
       'state'         => 'IL',
       'ZIPCode'       => '62704',
   ]);
   

   Then try the city/state lookup and ZIP lookup endpoints. These are the three flows covered in the new docs response examples — use them as your copy/paste fixtures.

4. First real use case: validate a customer address at checkout, then use the returned standardized address and ZIP+4 to quote shipping via the shipping options endpoint.

Implementation Patterns

Wrap calls behind a thin service layer. The facade is convenient in controllers, but most teams inject a small AddressService / ShippingService that wraps the facade so you can swap in fakes and centralize error handling.

Validation → normalization → quoting chain:

$validated = $this->addressService->validate($input);
if (! $validated->isConfirmed()) {
    // surface suggested correction to the user before continuing
}
$options = $this->shippingService->optionsFor($validated->normalized());

Cache lookup results. ZIP/city-state lookups are effectively static data. Cache aggressively (24h+ keyed by normalized input) and always cache negative results briefly to avoid hammering the API on malformed user input.

Integrate validation as a form request rule or a queue job. For checkout, validate synchronously but degrade gracefully — a USPS timeout should not block the sale. For bulk imports, push validation onto a queue with retries and record per-row outcomes.

Use the response DTOs, not raw arrays. The release tightened PHPDoc on ShippingOptions and the apiPost return types, so prefer typed accessors over array offsets; that keeps PHPStan happy in your own code too.

Test with fixtures. The new docs include response examples for validation, city/state, and ZIP lookup — copy them into tests/fixtures and bind a fake HTTP client so your test suite never touches the network.

Gotchas and Tips

• Upgrade to v13.4.1 if you're on any earlier v13. This release resolves 10 security-audit findings. Treat it as a security patch: bump, run your test suite, and check the diff if you were passing unusual payloads through apiPost.
• Sandbox vs. production credentials differ. A frequent "why is everything empty" bug is pointing production credentials at the sandbox host or vice versa. Log the resolved base URL at boot in non-production.
• DPV results are not binary. "Confirmed" with a missing secondary (apt/suite) is a different outcome than "not found." Read the DPV explanation table before writing conditional logic — otherwise you'll silently accept undeliverable addresses.
• Don't assume a validated address is a mailable address — validation confirms the address exists in USPS data; it doesn't confirm deliverability to a specific recipient or PO box restrictions.
• Rate limits and retries. Wrap calls with a retry (2–3 attempts, exponential backoff) for 5xx and connection errors only; retrying 4xx burns quota and never succeeds.
• Timeouts should be short. Set a 3–5s connect/response timeout so a slow USPS response doesn't hold a web request open.
• Facade mocking. The PHPStan facade-annotation fixes here mean IDE/static-analysis support is better, but for tests prefer Http::fake() over mocking the facade — it exercises the real serialization path.
• Extension point: if you need custom headers or a proxy, resolve the underlying HTTP client through the container rather than editing vendor code; the package's static-analysis tightening suggests the internals are increasingly typed and are safer to extend than to patch.