Fedex Laravel Package

Getting Started

This package wraps FedEx's print/document-submission flow for Laravel apps, letting you hand off PDFs (statements, invoices, labels, letters) for physical printing without hand-rolling the HTTP client. The current release is 1.0.2.

1. Install and pin the patch version. Require ^1.0.2 rather than ^1.0. The 1.0.2 fix only matters for a narrow input (single-page, single-sided documents), and pinning guarantees you actually get it after composer update.
2. Publish the config (php artisan vendor:publish) and fill in credentials from .env. Confirm whether the package ships separate sandbox/production base URLs and an account number distinct from the API key — that split trips people up on first run.
3. Check the config for a default print/ship option block. Most wrappers of this kind expose defaults for single_sided, duplex, media size, and quantity. Set them explicitly rather than relying on package defaults; the 1.0.2 bug is precisely a case where the default path and the explicit path behaved differently.
4. First use case: send a single one-page PDF, single-sided, to the sandbox endpoint. That is the exact shape of request that was broken before 1.0.2, so it is both the fastest smoke test and your regression probe.
5. Where to look first: the README's payload example, the config file, and the class that assembles the print-job request body. If the package logs raw requests/responses behind a config flag, turn it on in local — the FedEx error text is the fastest route to understanding a rejection.

Implementation Patterns

Wrap submission in a queued job. Printing is a network call to a third party with unpredictable latency. Dispatch a job from your controller, keep the HTTP request fast, and let the queue handle retries. Store the identifier returned by the submission (job/order/document id) on your own model so you can reconcile later.

Build a DTO for print options. Rather than scattering ['single_sided' => true, 'pages' => ...] arrays through controllers, centralise them:

final class PrintRequest
{
    public function __construct(
        public string $diskPath,
        public int $copies = 1,
        public bool $singleSided = true,
        public string $mediaSize = 'LETTER',
    ) {}
}

Then a single mapper converts the DTO to whatever array/object the package expects. When the package's payload shape changes in a future minor, you edit one file.

Resolve documents from a Storage disk, not a raw path. Storage::disk('documents')->path($file) works locally; on S3 you generally need either a stream, a temporary URL, or a local temp copy first. Read the package's accepted input types before assuming a path string is enough.

Validate before you send. Cheap local checks save expensive round-trips: MIME type, file size against the carrier's limit, page count, and page dimensions. Use a PDF library to read the page count for real — do not infer it from file size or from the source template, because generated documents merge and drop pages in ways templates do not predict.

Test with HTTP fakes. Point the package at the sandbox and assert on the outgoing payload rather than on FedEx's response. A test that snapshots the request body for a one-page single-sided document is worth writing today; it is the cheapest guard against a repeat of the 1.0.2 regression.

Gotchas and Tips

• The 1.0.2 fix is a narrow input, not a general one. The bug was specifically a one-page document submitted for single-sided printing. If your document pipeline can ever produce a single-page output (a one-line invoice, a filtered statement, a single-label batch), add an explicit test for it. Multi-page flows would never have surfaced this.
• Prior workarounds are now harmful. Teams on 1.0.0/1.0.1 commonly worked around this by padding single-page documents with a blank page or forcing duplex. After upgrading, remove those hacks — a padded two-page document is now a genuine two-page print job you are paying for, and forced duplex on a one-page doc looks wrong in the output.
• Watch page-count parity with duplex. Duplex jobs with an odd page count depend on the carrier's blank-back handling. Behaviour can differ from the single-sided path, so verify both rather than assuming a fix for one covers the other.
• Terse changelogs are a risk signal. A one-line release note for a production printing integration means you cannot rely on the changelog to tell you what else moved. Diff the package between 1.0.1 and 1.0.2 in vendor/ if the change is small, and read the source of the request builder before upgrading in production.
• Guard against duplicate prints. Queue retries plus automatic HTTP retries can submit the same document twice, and there is no undo on a printed page. Use a job-level $tries/backoff you control, and make the submission idempotent on your side (a print_jobs table with a unique key on your document id).
• Log the raw exchange. Persist the request ID and FedEx's error body on failure. FedEx validation errors are specific and short; a swallowed exception will leave you guessing about paper size, page count, or credential scope.
• Sandbox parity is never perfect. A request that passes in sandbox can still be rejected in production on account permissions or allowed media types. Do one low-cost live print against a real account before going fully live.
• Extension point: if the package resolves its HTTP client or payload builder from the container, bind your own implementation rather than forking the package — it keeps you on the upgrade path, which for a 1.0.x package with terse changelogs is where you want to stay.