Pipo Scanner Laravel Package

Getting Started

This release is documentation-first, so the fastest path to a working integration is now the README itself — it ships a full usage guide, a step-by-step integration example, and a flow diagram of how the browser event and Livewire method hand off to each other.

• Install the package with Composer and publish its config (php artisan vendor:publish --tag=...). The new configuration reference in this release is the authoritative list of keys — read it before touching anything else, since defaults are tuned for the common case and most projects won't need to override more than one or two values.
• Check the LICENSE file is present (MIT) before adding it to a client codebase — it is now, so redistribution and internal policy review are unblocked.
• Add the package's front-end asset/Blade include to the layout or component view. If your build uses Vite, confirm the asset is pulled through your normal pipeline rather than a hard-coded CDN path.
• Wire the Livewire side: the release documents the browser event and the Livewire method as a pair. Your first use case is almost always the smallest possible loop — fire the browser event, have it land on the Livewire method, and return a trivial value you can see in the rendered component. Treat that as your smoke test before adding real logic.

The flow diagram is the piece to look at first if anything behaves unexpectedly later; it makes the direction of data travel explicit, which is the thing most integrations get wrong on day one.

Implementation Patterns

The package is built around a two-sided contract — a browser event in, a Livewire method out — so most day-to-day usage follows a small number of shapes.

• Component-owned integration. Keep the Blade include, the event dispatch, and the Livewire method inside one component. This keeps the wiring obvious and makes the component portable between pages.
• Event-to-method binding as the seam. Dispatch from JS after the user action completes, not before. If the browser event fires optimistically, your Livewire method will run against stale state and you'll chase phantom bugs.
• Config as the integration surface. Use the published config for behaviour that differs per environment or per tenant (thresholds, feature switches, endpoint overrides). Avoid copying config values into component properties — you lose the ability to change them without a deploy of your own code.
• Returning state to the browser. Where the Livewire method needs to feed something back to the front end, keep that in a Livewire-dispatched event rather than reaching into the DOM directly. It round-trips cleanly and is testable with Livewire's event assertions.
• Testing. Assert the Livewire method in isolation with Livewire::test(...)->call(...), and cover the browser side with a Dusk/browser test that exercises the real event dispatch. The two halves fail independently, so test them independently.
• Mobile parity. Run the integration example verbatim on a real Android and a real iOS device before writing custom code. The release's mobile section covers the platform differences; reproducing the documented setup first gives you a known-good baseline to diff against when your variation breaks.

Gotchas and Tips

• HTTPS is not optional on mobile. The release's mobile considerations call this out for a reason: device and browser APIs the package relies on are gated behind a secure context. http:// on a LAN IP will appear to work on desktop and fail on a phone, which is a genuinely confusing first-day bug.
• Clear the config cache after publishing. php artisan config:cache in a deploy pipeline will happily serve the old defaults. If a config change appears to do nothing locally-but-not-in-CI, this is almost always it.
• Silent method mismatches. A misspelled Livewire method name or a renamed event typically produces nothing at all rather than an error. When the flow diagram says data should be moving and it isn't, check the event name and method name character-by-character before debugging logic.
• Permission denial is a normal state, not an error. On mobile, users decline prompts and then decline them permanently. Handle the denied branch explicitly and give users a route back, or you'll get bug reports that are really just a cached "deny".
• iOS and Android diverge at the edges. Behaviour around prompt persistence, backgrounding, and lifecycle differs. The new mobile section documents the known cases; anything outside them deserves a real-device check rather than an emulator assumption.
• Event name collisions. Namespacing your dispatched events (prefix with the component or feature) avoids collisions when several components share a page — a Livewire page with three components is the common failure mode.
• Debugging order. Browser console first (did the event fire?), then Livewire's devtools/network payload (did the method run and what did it receive?), then application logs. Working outward from the browser saves time because the browser half fails far more often.
• Extension points. The config file is the intended extension surface; the flow diagram shows where the package's own behaviour stops and yours begins. Prefer composing around those seams over patching vendor files, which will be overwritten on the next patch release — and this release cadence (documentation and licensing in a patch bump) suggests the maintainer is actively tidying the package, so expect more patches.