Voyeur Bundle Laravel Package

Getting Started

• Read this first: it is a Symfony bundle, not a Laravel package. Do not composer require namshi/voyeur-bundle into a Laravel app. Its Extension/CompilerPass/kernel wiring has no Laravel equivalent, and its symfony/* transitive constraints will collide with the v6/v7 components Laravel 10/11 already pull. The realistic on-ramp is isolation, not installation.
• Where to look first: the bundle's DependencyInjection/ config tree (the keys that define the URL list, output paths, and diff threshold) and the console command that drives capture and diff. There is no usable documentation; those two files are the docs.
• Minimal first step: stand it up in a sidecar container or a small standalone Symfony console app with its own composer.json, invoked from CI. The Laravel app owns only the URL config and consumes the pass/fail result — it never runs the browser.
• First use case: pick 3–5 revenue-critical templates, capture a baseline, deploy to staging, recapture, then diff. Do not start with a whole-site crawl; you will exhaust the runner and drown in diffs.
• If you actually want this inside Laravel: plan to reimplement the loop (config-driven URL list → headless screenshots → diff → report) as an Artisan command backed by Playwright or Dusk+diff, rather than porting the bundle. For most Laravel teams, that is the getting-started.

Implementation Patterns

• Baseline → deploy → recapture → diff → review is the only workflow the package supports. Treat baselines as versioned artifacts that you regenerate deliberately, not on every run.
• CI sequencing: wire it in as a non-blocking report first, then promote it to a blocking deploy gate only once the false-positive rate is tolerable on consecutive no-op deploys.
• Curated URL list, not a crawl. Keep 5–15 hand-picked critical flows in config, not code. Scale is the enemy here — capture is CPU/memory-heavy and effectively serial per browser instance.
• Auth and sessions: inject cookies / basic-auth headers at capture time, and assert the authenticated view rendered. A session-gated page that silently captures a login screen and "diffs clean" is a false negative that hides real regressions.
• Determinism by default: freeze animations, wait for fonts and lazy images and network idle, and mask dynamic regions (timestamps, A/B buckets, ads, personalization) before diffing.
• Artifact handling: write captures to a known directory with a retention policy, and have the diff report reference those paths so reviewers can inspect the actual images.
• Port pattern for Laravel: mirror the same shape as an Artisan command — a config-driven URL list, a headless-driver abstraction, a diff step with a tolerance threshold, and a JSON/HTML report. Keep execution out of the web process.

Gotchas and Tips

• The Symfony/Laravel seam is the first wall. No service-provider adapter exists; --ignore-platform-reqs produces runtime fatals rather than a working install. Isolate or replace — there is no clean coexistence in one vendor/ tree.
• PhantomJS-era browser backend. Archived, no ARM64 builds, flagged by supply-chain scanners, and unreliable on modern flexbox/grid/webfonts. Assume the capture layer must be swapped; if the bundle allows a driver swap, that is the key extension point.
• Flaky diffs kill adoption. Animation state, lazy-loaded images, webfont timing, and network jitter generate false positives. Without deterministic waits and masking, the gate becomes a rubber stamp people learn to ignore.
• False negatives are worse than false positives. A crashed browser or missing artifact commonly reports as "zero diffs." Treat missing captures as a hard failure, never a pass, and alert on capture-level errors, not just diff results.
• Unbounded disk growth. Before/after images accumulate with no built-in retention; cap the directory and add a lifecycle policy before it fills a CI runner or shared volume.
• Check the diff algorithm early. Determine whether tolerance is configurable or a naive pixel compare — antialiasing and font-rendering variance dominate the output otherwise.
• Maintenance is yours from day one. Zero dependents, no active maintainer, no Stack Overflow answers, no security patches. Budget an explicit owner and a quarterly review, or the tool rots silently.
• Don't judge the concept by this dependency. The workflow is sound and roughly a few hundred lines; this bundle is a reference implementation to read and borrow from, not a durable dependency to ship on.