Filament Qr Code Laravel Package

Product Decisions This Supports

• Feature scoping for verified scan workflows: Server-side validation remains the core value, and PMs can scope attendance check-in, asset audits, ticket redemption, inventory moves, and access-controlled site entries without a bespoke scanner-plus-validation stack.
• Multi-step operational workflows: v0.6.0 sequences now support conditional steps (ScanStep::when() — skipped, not required, and their value dropped), repeat counts (k / n), server-driven active step/labels/values, goToStep(), resetSequence(), and setRepeatCount(). Flows like PO → SKU → lot? → serials are now in-package rather than custom orchestration. This is a scope-expanding capability: receiving, put-away, pick-and-pack, and serialized asset capture move from "build" to "configure."
• Build vs. buy: The package now covers scan, server-side rules/lookups/closures/custom stages, normalization, duplicate suppression, rejection handling, feedback, multi-step sequencing, and audit events. The extension surface (lookupUsing(), ->pipe(Stage::class), normalizeWith(), macros) pushes the "requirements diverge sharply" line further out — more edge cases stay inside the package. Building internally now means owning Livewire plumbing, browser cooldown logic, sequence state machines, normalization parity, and view customization.
• Security and trust posture: Server-side checks are unchanged in principle and strengthened in practice — normalizeUsing() now runs on the server before rules and lookup, and normalization presets apply identically in browser and server, removing a class of "client says normalized, server says raw" mismatches. Custom ScanCheckStage pipes run after built-in checks, on live scan and on submit.
• Operator UX decisions: Success/error tones, vibration, flash feedback, clearOnReject(), and camera pausing carry forward. Runtime control (#33) adds a new dimension: server-side option changes are picked up on every Livewire re-render without re-creating the scanner (in-flight scan finishes first), with syncOptions(OptionsSync::Refresh) for explicit qr-scanner-refresh / qr-sequence-refresh events. PMs can change targets, modes, or pause/resume based on app state without designing around component remounts — relevant to POS, warehouse, and front-desk ergonomics.
• Audit and observability: ScanAccepted / ScanRejected now carry statePath, livewireClass, livewireId, sequence, and values; ScanSequenceCompleted gains livewireClass / livewireId; QrCodeScanned gains a state_path context (audited when enabled). Multi-scanner pages and multi-step flows are now attributable in analytics — a prerequisite for per-station or per-operator adoption metrics.
• Design and branding decisions without forking: Views are split into publishable sub-views with fi-qr-* classes, data-qr-part markers, extraAttributes(), QrCodeRenderHook render hooks, and --fi-qr-* CSS variables. Rendered output is otherwise unchanged. PMs can approve UI customization (kiosk styling, embedded layouts, custom input hardware) without owning a fork.
• Delivery velocity: php artisan make:qr-scan-field Name [--sequence] [--force] with publishable stubs standardizes how the team scaffolds scanners and sequences; the linted, API-verified recipe set (pos, warehouse, manufacturing, generator-page, custom-input, styling) is a real de-risking signal for estimation.
• Roadmap sequencing: Additions are additive, but v0.6.0 has a real upgrade checklist (asset refresh, view republish, recordKey(), route rename). Still an incremental feature, not a platform migration — but budget a half-day, not a coffee break, if views are customized.
• 1.0 trajectory: The filament-qr-code.image route name is now documented as a deprecated alias, removed in 1.0. That's a positive roadmap signal — the maintainer is converging on a stable surface — and a scheduling input: plan the rename before 1.0 lands.

When to Consider This Package

Consider adoption when:

• The product is a Laravel application using Filament for admin, operations, or internal tooling, and QR scanning is a first-class input rather than a one-off.
• You need server-side verification of scanned codes — rules, model lookups, lookupUsing() closures, or custom ScanCheckStage pipes — with consistent behavior on live scan and form submit.
• The workflow is multi-step or conditional (receiving, serialization, lot capture, guided audits) and you want sequences with repeat counts, conditional skip semantics, and per-step accept/reject hooks instead of hand-rolled state machines.
• You need normalization parity between browser and server (normalizeWith(trim, uppercase, stripPrefix)) so scan matches don't diverge from submit validation.
• You want built-in duplicate suppression, cooldown, rejection clearing, and feedback without building browser-side scan pipelines.
• You need event hooks with attribution context (ScanAccepted, ScanRejected, ScanSequenceCompleted, QrCodeScanned) for audit, analytics, per-device/per-station metrics, or downstream workflow triggers.
• You need to change scanner behavior at runtime from page code (feed, pause, resume, reset, setOptions, goToStep) without remounting components.
• You want UI customization as configuration — published sub-views, render hooks, CSS variables — rather than a fork.
• You are comfortable with a v0.x package and can absorb minor upgrade steps (php artisan filament:assets, view republishing, recordKey(), route rename). Note the vendor ships an UPGRADE.md per release — a reasonable maturity signal.

Look elsewhere when:

• The scanning surface is not Filament — customer-facing storefronts, native mobile apps, or standalone kiosks outside the admin panel.
• You require offline-first scanning, native camera integrations, or hardware scanner SDKs beyond browser-based camera input. (Note: window.FilamentQrCode.router / createInputRouter are now public and documented for shared hardware input routing, which helps keyboard-wedge scanners but does not make the package offline-capable.)
• You need a stable 1.0+ API contract with long-term support guarantees; deprecations are now being declared, but this is still pre-1.0.
• The product cannot depend on Livewire round-trips for validation, or on pausing the camera during server checks. Runtime control reduces remount friction but does not remove the server dependency.
• You have heavily customized the package views and cannot absorb periodic re-publish/merge work each minor release.

How to Pitch It (Stakeholders)

For executives: The package has moved from "trustworthy scanning" to "configurable scanning operations." Multi-step guided workflows with conditional steps, runtime behavior changes, and custom validation are now configuration rather than custom development — which pulls receiving, warehousing, serialization, and POS-style flows into scope at low incremental cost. Audit events now carry enough context to attribute scans to a specific form, component, and sequence, enabling per-station adoption and reconciliation reporting. The 1.0 deprecation path is now visible, reducing platform risk. The upgrade is additive, but requires an asset refresh and view republishing — a routine, bounded task.

For engineering: v0.6.0 adds runtime control (scan.sync_options = 'morph', OptionsSync::Refresh, explicit qr-scanner-refresh / qr-sequence-refresh events, per-element element.qrScanner / element.qrScanSequence API, targeted window events), and sequence primitives (goToStep(), resetSequence(), setRepeatCount(), ScanStep::when(), onStepAccepted() / onStepRejected()). Extension points: lookupUsing() with fallback: true, closure-accepting lookup() model/column, normalizeWith() presets applied browser- and server-side, ->pipe(Stage::class) with the ScanCheckStage contract (container-resolved, also on submit), macroable ScanStep, and step closures receiving $get/$livewire/$step/$values. Views are split into publishable sub-views with fi-qr-* classes, data-qr-part markers, extraAttributes(), QrCodeRenderHook, and --fi-qr-* CSS variables; scanner x-data no longer embeds options (now on data-qr-options), and the sequence view gained a data-qr-options wrapper — this is the main re-publish hazard. ScanResult::$record is now mixed; use recordKey(). QrScanSequence::make() now runs setUp() / configureUsing(); sequences with a state path fill to []. Scaffold with make:qr-scan-field --sequence. Upgrade: read UPGRADE.md, run php artisan filament:assets, republish customized views, migrate off filament-qr-code.image.

Recommendation: Treat v0.6.0 as the point where the package supports orchestrated scanning, not just verified scanning. Pilot on one Filament workflow with a sequence (e.g. PO → SKU → lot? → serials) plus server-side lookup and audit events, and measure scan latency and operator error rates before expanding. Separately, if views are customized, schedule the republish now and retire the deprecated filament-qr-code.image route ahead of 1.0.