Statamic Resrv Laravel Package

Getting Started

v6.4.0 is a low-risk, additive release: one bug fix (partner/affiliate bookings now resolve), one new optional tag parameter (statuses), and improved error handling (themed 404s + actionable validation messages). No breaking changes, no deprecations — upgrading is a composer update away.

Minimal steps:

1. Update and check the changelog surface. composer update <vendor>/<package> then skim the tag class behind reservationFromUri (usually something like src/Tags/ReservationFromUriTag.php or a Tags/ directory). That single class is the whole story of this release — the URI parsing, the status filter, and the 404 behaviour all live there.
2. Confirm your 404 view exists where the package expects it. The fix that routes tag errors through your themed 404 means the package is now delegating to Laravel's exception/404 rendering. Verify resources/views/errors/404.blade.php exists (or your app's custom handler returns one) and renders sensibly when hit from a tag-driven page rather than a normal route.
3. Smoke-test the affiliate case first. That's the headline fix. Take a known partner/skip-payment booking URI and load the customer-facing page that uses the tag. Before this release it 404'd; it should now render. If it still 404s, you're almost certainly on a cached page or a stale config — see Gotchas.
4. First real use case: a public "your reservation" page (or an affiliate landing page) that takes a URI segment/query param, hands it to the tag, and renders booking details. The tag is the thin layer; your job is the surrounding page, the 404 experience, and deciding which statuses are publicly visible.

If you've never used the tag: start with the default behaviour (no statuses argument) and only reach for the new parameter once you have a concrete need. The defaults are deliberately conservative.

Implementation Patterns

Default lookup — the safe path. Invoke the tag with just the URI. This is what a customer-facing reservation page should do 95% of the time: it returns confirmed/active bookings, now including partner and skip-payment bookings, and excludes pending, expired and cancelled.

{{-- default: confirmed-style statuses only, partner bookings included --}}
@reservationFromUri($uri)
    {{-- reservation found --}}
@else
    {{-- nothing matched --}}
@endreservationFromUri

(Adapt to your package's actual tag syntax — the point is that omitting statuses is the recommended default.)

Explicit status widening — opt in deliberately. The new statuses parameter is pipe-separated and validated against the package's known status list. Use it when you're building an internal view (support dashboard, admin lookup, "show me cancelled reservations") where the public-facing conservatism doesn't apply.

{{-- support tool: show cancelled and expired too --}}
@reservationFromUri($uri, statuses: 'confirmed|cancelled|expired')

Key behaviours to design around:

• Excluded statuses stay excluded unless you name them. pending, expired and cancelled are not included by naming some other status — they only appear when explicitly listed. So statuses: 'confirmed' is narrower than or equal to the default, never wider in the "hidden" categories. Don't assume passing statuses resets to "everything."
• Validation is strict. The value is validated against known statuses, so an unknown token throws rather than silently returning nothing. That's good — it turns a typo into a loud failure — but it means you must not build statuses from untrusted input without whitelisting first.

Pattern: config-driven status sets. Rather than hardcoding pipe strings in views, centralise them:

// config/reservations.php
return [
    'public_statuses'   => 'confirmed',
    'internal_statuses' => 'confirmed|pending|cancelled|expired',
];

Then statuses: config('reservations.internal_statuses') in the internal view, default (no argument) in the public one. This keeps the "which statuses are public?" decision in one reviewable place.

Pattern: guard the parameter at the boundary. If a status set ever comes from a request (e.g. an admin filter dropdown), map it through a fixed array before it reaches the tag:

$allowed = ['confirmed', 'pending', 'cancelled', 'expired'];
$statuses = collect($request->input('statuses', []))
    ->intersect($allowed)
    ->implode('|');

abort_if($statuses === '', 404);

Pattern: distinguish "not found" from "broken". Now that errors render your themed 404, a misconfigured tag and a genuinely missing reservation can look identical to the user. Inside the tag's else/empty branch, log at debug level with the URI so support can tell the two apart:

Log::debug('reservationFromUri: no match', ['uri' => $uri, 'statuses' => $statuses ?? 'default']);

Integration tips. Render the tag inside a normal controller-backed page rather than at the top of a layout, so the rest of the page (nav, footer, analytics) doesn't depend on the tag resolving. If your site has full-page caching, the affiliate fix means previously-cached 404s for partner URIs are now stale — purge by URI prefix after deploy. And if you have feature tests around the reservation page, add one case per status category plus one partner-booking case; that's exactly the regression surface this release touched.

Gotchas and Tips

• Statuses are opt-in, not opt-out. The most common misread of this release: people pass statuses: 'confirmed|cancelled' expecting everything except those two. It's a whitelist. Whatever you list is what gets looked up.
• Pipe-separated means pipes. Not commas, not arrays. A comma-separated string will fail validation and now surfaces as a themed 404 plus a validation error — which is arguably worse to debug than a stack trace because the page looks fine-ish. Check storage/logs/laravel.log for the actionable message the release notes mention.
• The themed 404 can mask configuration errors in production. That's the trade-off of the fix. In local/staging, keep APP_DEBUG=true so the "clear, actionable messages" actually reach you; in production, make sure your 404 template logs the underlying reason (or that the package does) before rendering.
• Your 404 view must survive being rendered from a tag context. If your errors/404.blade.php calls helpers, composers, or view-shared data that assume a routed request, it may itself throw — turning a clean 404 into a 500. Test the 404 path directly.
• Affiliate/partner bookings: verify against the skip-payment path specifically. The fix targets partner bookings where payment is skipped. If you have multiple affiliate flows (some paying, some not), test each; it's plausible only the skip-payment branch changed, and a paying-partner booking may have been fine all along.
• Cache invalidation is the likely cause of "the fix didn't work." Page cache, response cache, CDN, and any tag-output caching layer all need clearing. Also check whether your app memoises tag results per-URI within a request.
• Don't over-broaden public pages while debugging. It's tempting to slap statuses: 'confirmed|pending|expired|cancelled' on the customer page to "see what's there." That leaks cancelled/expired reservations to anyone with a URI. Keep the wide set on internal tooling only.
• Extension points to inspect: the tag's status constant/list (so your config values match exactly, including casing), the URI parser (trailing slashes, URL-encoded segments, query strings — a parser that's strict about the URI shape will 404 before the status logic ever runs), and whether the tag resolves through a repository/service you can swap or fake in tests. If the status list is a private constant, prefer mirroring it in config rather than reaching into the class.

Bottom line: upgrade confidently, test the affiliate path and the 404 template, and treat statuses as an internal-tooling escape hatch rather than something customer-facing pages should set.