Dhlparcel Php Api Laravel Package

Getting Started

• Install with composer require (check the README for the exact vendor/package name and the Laravel version constraint), then publish the config: php artisan vendor:publish --tag=<package>-config. Put credentials in config/services.php and .env — never commit them.
• Read in this order: README.md → the published config file (it documents every knob) → the CHANGELOG entry for v1.5.21, which is where the new customs declaration support is described. The changelog is the fastest way to see whether the declaration is a new builder method, a new model/DTO, or an option on an existing shipment call.
• First use case: build one international shipment end-to-end. Create a shipment, attach a customs declaration, fetch rates, buy a label, and confirm the declaration is embedded in the returned documents. Do this in the package's sandbox/test credentials before wiring it into your checkout flow.
• Sanity-check the container binding (app(<Package>::class)) resolves and that a trivial call returns a response. If the package ships a facade, prefer the injected class in your own services and reserve the facade for tinker/one-off scripts.

Implementation Patterns

• Wrap the package behind your own service. Inject the package client into a ShippingService / CustomsService in your app. This keeps the vendor class out of controllers and makes it a one-file change if declaration APIs shift again.
• Map your Eloquent models to declaration items. Typical shape: order → line items → description, quantity, unitValue, weight, hsCode, countryOfOrigin. Build a toDeclarationItem() method on the line-item model so the mapping lives next to the data instead of in the job.
• Persist the request and the response. Store the declaration payload, the provider's declaration/shipment ID, and the returned label URL on the order (or a shipments table). Reprinting customs paperwork and reconciliations both depend on this; providers often won't let you re-fetch documents later.
• Queue the purchase. Label purchase is a slow, external, non-idempotent call. Dispatch a job, use a unique job keyed on order ID, and record failures explicitly so a retry doesn't double-buy a label.
• Validate at the edge. A FormRequest for HS codes (6–10 digits depending on destination), ISO-2 country codes, positive weights, and a currency matching the order invoice. Catching these in validation is far cheaper than a provider-side rejection after a queue round-trip.
• Handle the webhook/status path separately. Declarations and shipments change state (accepted, held by customs, rejected). Route the package's webhook (or poll) into a listener that writes status to your shipment record and fires your own domain event — don't let provider payload shapes leak into notification/business logic.
• Feature-flag the rollout. Gate declaration creation behind a config flag or Laravel Pennant so you can enable it per-country/per-channel after it's verified with a handful of real orders.
• Testing. Http::fake() (or the package's own fake, if it ships one) with a recorded declaration response; assert your service builds the right payload rather than asserting on the vendor's internal objects.

Gotchas and Tips

• Unit mismatches are the #1 failure. Providers commonly expect grams vs kilograms and cm vs inches, and defaults differ between sandboxes and production. Pin units explicitly in the declaration payload and add a unit test asserting your conversion.
• Declared value must reconcile with the invoice. Customs value, currency, and line-item totals should match the commercial invoice you send the customer; a mismatch is a common cause of held shipments and is a compliance problem, not just a bug.
• HS codes are destination-dependent. A code that's valid for one country can be rejected for another, and some providers require more than 6 digits. Validate against the destination country, and give operators a way to override the code without a deploy.
• Country restrictions and prohibited items. Many providers reject specific commodity/destination combinations at purchase time, not at declaration time. Handle that error path with a human-readable message instead of surfacing the raw provider payload.
• Documents must travel with the label. International labels usually need the declaration embedded (or a separate customs form). Verify the returned document set in sandbox, and confirm your reprint path produces the declaration too — otherwise warehouse reprints ship without paperwork.
• Signature/incoterm fields are required more often than you'd expect. If the new declaration API exposes duties/taxes (DDP vs DDU) or a signature requirement, default them deliberately in config rather than relying on provider defaults.
• Credentials and sandbox/production drift. Ensure the sandbox isn't used in a queue worker that also runs in production (a misconfigured .env on a worker is a classic), and log which environment a declaration was created against so you can distinguish test records.
• PII and logs. Declaration payloads contain names, addresses, and values. Redact them in exception handlers and don't dump full request bodies; check whether the package logs payloads at debug level.
• Extension points to look for: a configurable declaration builder/resolver, macroable client, or contract you can bind in a service provider. Prefer overriding one of those over subclassing a vendor class, which tends to break on minor releases like v1.5.x.
• Before relying on v1.5.21: confirm it's a minor addition and not a silent payload change (read the changelog and diff, if available), and pin the version in composer.json with a tilde (~1.5.0) until you've run one full international order through it.