Filament Panel Screenshot Catalogue Laravel Package

Getting Started

• Install with composer require and publish the config (php artisan vendor:publish --tag="...-config"). The package shells out to a headless browser, so confirm the runtime prerequisites it documents (Node/Puppeteer or a Chrome/Chromium binary, --no-sandbox in containers) before writing any code — most "it doesn't work" reports are environment issues, not API issues.
• Look first at the published config file (browser binary path, default viewport/device scale, timeout, storage disk, queue settings) and then at the package's capture entry point (facade/service class). Those two files tell you 90% of what you need; the rest is per-call options.
• First use case: capture a single page to a configured disk from a queued job, not from a controller. A controller capture blocks the request for seconds and couples user latency to browser health. Dispatch a job, store the path on your model, and render the image from there.
• Because of 5.9.0, your first smoke test should be a URL that you know is not gated — then deliberately test a login-gated one to see the new failure surface.

Implementation Patterns

Single capture, persisted on a model Wrap the capture call in a small service or action class rather than scattering facade calls. Have it return a value object (path, final URL, captured-at, status) so the rest of the app never depends on the package's internals. Store the path plus the final URL on your model — the final URL is now the key diagnostic field for the 5.9.0 behaviour.

Queued bulk capture / backfill Use a dedicated queue (e.g. captures) with a longer --timeout than your default workers, and chunk IDs with Bus::batch() or LazyCollection. Make jobs idempotent (unique key on target + date, WithoutOverlapping middleware) so retries and backfills don't produce duplicate files or duplicate rows. Rate-limit with RateLimited middleware if you're capturing a third-party site.

Handling the 5.9.0 landing-mismatch failure The new behaviour is the important design driver: instead of receiving a wrong-but-successful image, you get a failure with a reason when the browser ends up on a consent screen, onboarding flow, or login page. Model this as a distinct outcome, not a generic error:

• Catch the package's failure exception and branch on the reason. Persist a status enum: captured, blocked (redirect/consent/login), error (timeout, DNS, HTTP 5xx).
• Treat blocked as terminal — do not put it on the normal retry ladder. Retrying a consent wall just burns browser starts.
• Surface blocked in your UI/admin as "requires attention" with the final URL, so someone can fix auth/cookies rather than silently shipping a login screenshot to a customer.
• Keep a catch-all so unexpected failures don't take down a batch; use Bus::batch()->allowFailures() and inspect failedJobs().

Authenticated and consent-gated targets For pages behind a login, pass a session/cookies (pre-authenticated storage state) or hit a tokenised preview URL. For cookie-consent walls, prefer a deterministic bypass (seed the consent cookie) over scripted clicking. The 5.9.0 check is effectively your regression test that these mechanisms are still valid — when auth silently expires, you'll now get a clear blocked reason instead of a plausible-looking screenshot of a login form.

Wait strategies and custom scripts Use the package's wait-for-selector / wait-for-network-idle options and any pre-capture script hook for dismissing overlays or forcing lazy images to load. Encode these as named "capture profiles" in your own config (e.g. marketing, app-dashboard) so behaviour is consistent across jobs.

Scheduling and freshness Schedule periodic re-captures with ->withoutOverlapping() and a onOneServer() guard. Pair each capture with a retention/cleanup job that deletes stale files from the disk.

Testing Fake the capture layer in feature tests and assert your branching logic — especially that a blocked reason does not retry and does mark the record. Keep a small, tagged integration suite (staging, real browser) for the handful of URLs you care about; assert both success and the intended blocked cases.

Gotchas and Tips

• 5.9.0 is a behavioural change, not just a bug fix. Any code that assumed "no exception = correct screenshot" needs auditing. Look for places where you ignore a boolean return, blanket-catch \Throwable and store nothing, or assume a capture job's success means the image is usable. Existing rows captured before the upgrade may contain login pages — consider a one-off re-capture of your most-viewed targets.
• Distinguish mismatch from timeout. A slow SPA can momentarily render a redirect/interstitial; make sure your wait strategy is settled before the check, otherwise you'll see flaky blocked results on pages that are actually fine. If you see intermittent mismatch on a known-good URL, raise the wait, don't disable the check.
• Expired sessions look identical to consent walls from the failure reason alone. Always log the final URL and HTTP status alongside the reason; that's what turns a vague failure into a five-minute fix.
• Queue worker timeouts and browser leakage. Set the job timeout above the browser timeout plus overhead, and restart workers on deploy. Orphaned Chrome processes are the classic cause of "works locally, dies in production after a day".
• Container/CI environment. Missing fonts, no /dev/shm, and the Chrome sandbox are the usual culprits for blank or crashed renders. Prefer documenting a known-good image over debugging per-project.
• Storage disk and visibility. Decide public vs private up front; URLs generated against the wrong disk are a common post-launch bug. Namespace filenames with a UUID or model key to avoid overwrites on re-capture.
• Determinism. Animations, lazy-loaded images, web fonts, and carousels make captures non-reproducible. Freeze where the package allows; otherwise accept small diffs and avoid pixel-diff assertions on marketing pages.
• Extension points worth knowing: custom pre-capture scripts, configurable viewport/device-scale per call, event hooks for captured/failed, and the failure-reason payload introduced in 5.9.0 — that last one is the right place to hang your own alerting rather than parsing log strings.