Mailer Bundle Laravel Package

Getting Started

Pin to ^0.9.0 before you start — this release changes how the payload reaches your endpoint, and code written against a pre-0.9.0 mental model will look broken in confusing ways.

First places to look:

1. The outgoing request builder / transport class. This is where bodyAsString was previously stuffed into a header and where the body is now assembled. Read it before reading anything else; everything else in the package is convenience around this one call.
2. The config file (publish it if you haven't: php artisan vendor:publish). Endpoint URL, credentials, and any header allow-list now matter more than before, because headers are no longer carrying the payload.
3. The package's own tests for the request/response cycle. The fixtures will show you the exact shape of the body the package now sends, which is faster than inferring it from source.

The first use case to prove out end-to-end: send one real payload at a sandbox/receiver you control, then dump the raw request server-side ($request->getContent(), not $request->input()). Confirm three things at once — that the body is non-empty, that no bodyAsString header is present, and that Content-Type is what your receiver expects. If those three hold, the rest of the package's surface area is ordinary.

Implementation Patterns

Receiver-side (most common work). If you own the endpoint, switch from reading a header to reading the raw body:

$payload = json_decode($request->getContent(), true);

Use getContent() rather than input()/all(), because the package is now posting a serialized document and you don't want Laravel's request parsing to reshape it before you validate it.

Version-gated handling during rollout. While old and new senders coexist (they will, during any deploy where the sender and receiver aren't released atomically), branch on presence of the body first and fall back to the header:

$raw = $request->getContent();
$payload = $raw !== ''
    ? json_decode($raw, true)
    : json_decode($request->header('bodyAsString', ''), true);

Log which branch fired — that log line is your cutover signal, and you delete the fallback once it goes quiet.

Outbound integration pattern. Treat the package as a thin transport and keep payload construction in your own action/DTO layer. That way a future transport-level change (this one won't be the last) touches one adapter class instead of every job and listener that fires a request.

Queued sends. Wrap calls in a job with retries rather than firing inline from a controller or an Eloquent observer. Header-based payloads used to fail fast and loudly (oversized headers get rejected at the proxy with a clear 4xx); a body-based send can sit in a timeout instead, so you want retryUntil/backoff and a failed-job hook in place from day one.

Testing. Use Http::fake() and assert against the request body, not headers:

Http::assertSent(fn ($request) => $request->body() === json_encode($expected));

Add one negative assertion that no bodyAsString header is set. It's cheap and it pins the v0.9.0 contract.

Gotchas and Tips

• This is a wire-format change, not a cosmetic one. Anything downstream that reads the header — a proxy rule, a WAF signature, a middleware that copies headers into a queue message, an API gateway mapping — breaks silently with a null payload rather than an error. Grep your infrastructure config, not just your PHP.
• Reverse proxies and body size. Header-based payloads hit header limits (typically 8–16 KB, sometimes 4 KB). Moving to the body lifts that ceiling to client_max_body_size / post_max_size, so payloads that were previously impossible may now be sent — check your receiver's limit before you start passing bigger documents.
• Content-Length vs chunked. If the package streams or uses chunked transfer for larger bodies, some receivers (and some older proxies) reject it. Verify with a payload larger than your typical one, not just the happy-path 200-byte fixture.
• Don't assume Content-Type was set for you. Header transport didn't need one; body transport does. If your receiver's JSON parsing is strict, a missing or text/plain content type is the most likely first bug you'll hit.
• Debugging: when the payload "disappears," check the receiver's raw access log first. A 200 with an empty body read is nearly always a content-type or stream-already-consumed issue, not a package bug.
• Extension point worth knowing: if the package exposes a request/response middleware or a beforeSending-style hook, use it to log $request->body() during rollout. It's the single highest-value place to instrument, and it's usually a one-line addition rather than a subclass.
• Semver caveat: 0.9.x is pre-1.0, so this breaking change is permitted without a major bump. Pin exactly (0.9.*) and read the diff before taking 0.9.1, because further wire-format adjustments are plausible before 1.0.