Cord Laravel Package

Getting Started

cord is a Laravel package for working with shipments, and 3.5.4 is a patch release (no breaking changes) that extends the shipment update payload with estimated dates and drop modes. Upgrade with composer update oliverbj/cord and you're done — but plan to actually use the new fields, because they're the useful part of this release.

Minimal setup:

1. composer require oliverbj/cord
2. Publish the config (php artisan vendor:publish --tag="cord-config" — confirm the exact tag in the package's service provider, as tags change between majors) and add your credentials to config/cord.php / .env.
3. Skim, in this order: the service provider (to see what's bound in the container and which config keys exist), the shipment model/DTO (to see which attributes are mass-assignable and which are cast), and the existing tests (the fastest documentation of real payloads).

First use case: take a shipment you already have locally, then push an update that sets an estimated delivery date and a drop mode. That single flow exercises config, auth, the request builder, and the response mapping — everything you need to know before wiring it into a real workflow.

Implementation Patterns

Treat shipment updates as partial patches. The update method is designed to send only what you pass. Build a dedicated action class rather than sprinkling calls through controllers:

class SyncShipmentUpdate
{
    public function __construct(private Shipment $shipment) {}

    public function handle(array $changes): void
    {
        $this->shipment->update($changes);
    }
}

Then call it with only the fields that actually changed. This keeps you honest about what the API receives and makes the 3.5.4 additions opt-in rather than accidentally defaulted.

Estimated dates: convert at the boundary, not in the model. Keep Carbon instances in your domain and format to whatever the package expects (ISO-8601 or Y-m-d, check the request builder) immediately before dispatch. If you store dates in UTC, convert to the carrier's expected timezone first — an ETA off by a day is a support ticket.

Drop modes: drive them from your own enum. Wrap the package's accepted drop-mode values in a PHP enum with a label() method, and validate incoming user input against it. This gives you one place to update when a carrier adds or removes a mode, and it stops free-text values leaking into the payload.

Separate "create" from "update" paths. Creation and update often take different payload shapes. Don't build one giant toPayload() that serves both — you'll end up sending fields the update endpoint rejects.

Queue the writes. Shipment updates are outbound HTTP calls; do them in a job with $tries, backoff(), and a failed() handler that records the failure against the shipment. Combine with Http::fake() in tests to assert the payload includes estimated_delivery_date and drop_mode only when set.

Surface the data back to users. The obvious day-to-day win: show the estimated date on order tracking pages and let customers choose a drop mode at checkout, persisting it locally and pushing it up asynchronously.

Gotchas and Tips

• Patch semantics cut both ways. Omitting a field usually leaves the remote value untouched, which is what you want — but it means you cannot clear an estimated date by omission. Send an explicit null (and verify the API accepts it) if "no ETA" is a valid state.
• Date format mismatches fail loudly or, worse, silently. If the API accepts 2024-13-01-style garbage without complaint, you'll only find out from a customer. Assert on the outbound payload in a test.
• Drop mode values are carrier-specific. A mode that's valid for one carrier will be rejected by another. Validate per carrier, and log the raw error response — validation errors from shipping APIs are rarely self-explanatory.
• Config caching bites during setup. After editing config/cord.php, run php artisan config:cache (or clear it) — a stale cached config is the #1 cause of "my credentials aren't being picked up."
• Log request/response pairs behind a config flag. 'debug' => env('CORD_DEBUG', false) style. Never log credentials, but do log the payload; the response bodies are where the real error detail lives.
• Make writes idempotent where you can. Retried jobs after a timeout can double-apply an update. Use a unique key per shipment update attempt if the API supports one, or gate on a locally-stored hash of the last-sent payload.
• Extension point: if you need behaviour the package doesn't expose, look for a macroable client or a bindable interface in the container before forking. Binding your own implementation of the client contract is far cheaper to maintain than a fork.
• Upgrade safely: 3.5.4 is a patch with additive features only. If you have tests asserting the exact update payload keys, they may need the two new fields added once you start using them — otherwise the upgrade is a no-op.