Nativephp Mobile Ocr Laravel Package

Product Decisions This Supports

• On-device capture-to-text features without a native team. The package wraps camera capture, page scanning and OCR behind a Laravel facade, events and a FakeBridge test double. A PM can scope features like receipt capture, invoice/PO intake, ID and form scanning, asset-tag lookup, or "add note from photo" and ship them from the PHP codebase instead of staffing an iOS/Android workstream.
• Build vs. buy, resolved toward "buy the plumbing, build the workflow." MIT-licensed, so the platform integration (permissions, orientation, downscaling, memory handling, temp-file lifecycle) is free; your engineering budget goes into the domain layer — parsing fields, matching records, validating totals. Compare against cloud OCR/LLM extraction: on-device wins on marginal cost per scan (zero) and privacy (no image leaves the device), and loses on structured extraction quality.
• Roadmap sequencing is now defensible. v1.0.0 is a genuine 1.0: consistent pixel coordinates across both platforms, deterministic error taxonomy, documented events, a JS library for Inertia/Vue/React, and tests. That means the risky, demo-breaking work is behind you and the remaining effort is product surface, not platform firefighting.
• Cross-platform parity as a standing requirement. Android and iOS now agree on coordinate units and on permission-denied semantics (RecognitionFailed::CAMERA_PERMISSION_DENIED), and both present full-screen so users can't swipe away without a result event. A PM can write one acceptance criterion and have it hold on both platforms — a real reduction in QA and support load.
• Layout helpers as the parsing strategy. Layout::rows() and Layout::valueBeside() are unit-agnostic, so "label to the right of the label" extraction (totals, dates, names on forms) is the recommended path. This is a product-level decision worth recording: build extraction on relational geometry, not hardcoded pixel assumptions.
• Scoping decisions this release forces, and which you should own explicitly:
  • Retention: captured images live in a plugin cache folder and are pruned on the next capture/scan (each survives ≥1 minute). "Keep a copy of the receipt" is therefore a product feature you must specify — copy $path to your own storage — not something you get for free.
  • Concurrency: one capture()/scan() at a time; a second call fails fast with BUSY. Design flows as single-shot, and surface a friendly retry rather than assuming queued scans.
  • Fidelity ceiling: images are downscaled to 4096 px longest side, with EXIF orientation applied, and boxes refer to that image. Small print on a 108 MP photo is a real risk — worth a device-matrix spike before promising accuracy on dense documents.
• Permissions and store review are de-risked. iOS NSCameraUsageDescription ships in the manifest and Android launches are guarded, so no app-side Info.plist edits and no crash-on-prompt. That removes a recurring App Store rejection cause and a class of 1-star reviews.
• Privacy posture you can put in a policy document. Android no longer writes to MediaStore (the gallery-empty-file bug is gone) and temp files are deleted on cancel/failure. "Photos never appear in the user's gallery and never leave the device" is a claim you can make.

When to Consider This Package

Adopt when most of these hold:

• You are building a NativePHP mobile app on Laravel and want camera OCR without Swift/Kotlin.
• Text extraction is unstructured — you need the words and their positions, then you do your own interpretation. That is exactly what this returns.
• Your UI is Inertia + Vue/React and can use the shipped JS library (recognize(), capture(), scan(), rows(), event listeners) with TypeScript types.
• You need single-shot capture: one photo, one page, one result.
• Android 21+ / iOS 13+ is an acceptable floor for your user base.
• Privacy or per-scan cost is a deciding factor — regulated data, offline use, or volume where cloud OCR unit economics fail.
• You want the native integration testable in CI via the facade and FakeBridge macros.

Look elsewhere, or plan to wrap another service, when:

• You need structured extraction — line items, tables, key-value normalization, handwriting, or multi-language quality tiers. Generic platform OCR gives you boxes; you'll add a parser or a cloud/LLM step, and should budget for it.
• You need multi-page batch scanning, queued/concurrent captures, or a library of past scans. The cache-folder pruning and BUSY semantics make this a build, not a config.
• You need barcodes, QR, MRZ, or document edge detection/cropping — not in scope here.
• You are web-only or need a desktop target; this is a mobile NativePHP plugin.
• You depend on raw iOS 0–1 box fractions. This release changes them to pixels of the upright image with a top-left origin, matching Android. Code built on Layout::rows()/valueBeside() is unaffected; anything that read fractions directly must divide by width/height (now on TextRecognized, nullable from older native code). Treat this as a breaking change for early adopters and audit before upgrading — it is the one item in this release that needs a migration note, not just a changelog entry.
• You cannot tolerate fixed minimum OS versions or a manifest you don't control (iOS usage description is declared for you; if you need a custom string for review, verify you can override it).

How to Pitch It (Stakeholders)

To executives: This is the 1.0 of our on-device text recognition capability, and it changes the economics of our scanning features. It is MIT-licensed and does the hard, expensive part — camera, permissions, orientation, memory, temp files, parity across iOS and Android — inside the Laravel codebase we already staff. There is no per-scan cost and no image ever leaves the device, which is both a margin story and a compliance story we can put in front of customers. The v1.0 marker matters for planning: the platform risk that makes scanning demos fail on stage — permission crashes on older Android, out-of-memory on modern 50–108 MP cameras, iOS reporting a denial as a user cancel — is fixed and covered by tests. We can commit to scanning features on the roadmap without a native hiring plan.

To engineering: Adopt it, and read two things before you start. First, iOS boxes are now pixels of the upright image with a top-left origin, matching Android — if any prototype parsed raw 0–1 fractions, that code needs a one-line divide by the new width/height on TextRecognized, which are optional and null from older native code so existing handlers still compile. Second, build on Layout::rows() and Layout::valueBeside(); they are unit-agnostic and immunize you against future coordinate changes — that's the migration-proof seam. Beyond that, the release closes real defects: Android capture() no longer touches MediaStore (no more SecurityException on 8/9, no stray empty gallery file; photos go through the core FileProvider), downscaled decode with retry-smaller on OutOfMemoryError, commitNowAllowingStateLoss() for calls during activity teardown, temp files deleted on cancel/failure, camera presented full-screen on iOS so no swipe-away without a result. The constraints to design around: one capture/scan at a time (RecognitionFailed::BUSY — handle it, don't retry blindly), images are pruned from the plugin cache on the next capture (copy $path immediately if you need to keep it), and inputs are downscaled to 4096 px so boxes refer to that image — spike accuracy on dense documents before committing to one. Error handling is now a single taxonomy on both platforms: check isPermissionDenied() and isBusy() rather than string-matching, and the whole surface is testable in CI through the facade and FakeBridge macros. Floors are Android 21 and iOS 13.