PHPackages                             ikromjon/nativephp-mobile-document-scanner - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. ikromjon/nativephp-mobile-document-scanner

ActiveNativephp-plugin[Utility & Helpers](/categories/utility)

ikromjon/nativephp-mobile-document-scanner
==========================================

Document scanner plugin for NativePHP Mobile - scan documents with edge detection, cropping, and perspective correction using native camera APIs

v1.3.0(2mo ago)42MITPHPPHP ^8.3CI passing

Since Apr 5Pushed 2mo agoCompare

[ Source](https://github.com/Ikromjon1998/nativephp-mobile-document-scanner)[ Packagist](https://packagist.org/packages/ikromjon/nativephp-mobile-document-scanner)[ RSS](/packages/ikromjon-nativephp-mobile-document-scanner/feed)WikiDiscussions main Synced today

READMEChangelog (4)Dependencies (14)Versions (10)Used By (0)

NativePHP Mobile Document Scanner
=================================

[](#nativephp-mobile-document-scanner)

[![Tests](https://github.com/Ikromjon1998/nativephp-mobile-document-scanner/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Ikromjon1998/nativephp-mobile-document-scanner/actions/workflows/tests.yml)[![Total Downloads](https://camo.githubusercontent.com/c8b605001ad412fb570a3b57d88e4b6d60ddc345e95d9ba619f20c00e32dd820/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696b726f6d6a6f6e2f6e61746976657068702d6d6f62696c652d646f63756d656e742d7363616e6e6572)](https://packagist.org/packages/ikromjon/nativephp-mobile-document-scanner)[![License: MIT](https://camo.githubusercontent.com/932abd8e818a25e0f3ab199bbff4a365c89bb280b5667966eef19eab8f82f412/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f496b726f6d6a6f6e313939382f6e61746976657068702d6d6f62696c652d646f63756d656e742d7363616e6e6572)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/9df2e2416021abae33024bf9d964a3cc5e71f942f8a568682481b3054455e854/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e332532422d383839324246)](composer.json)

Scan documents with automatic edge detection, perspective correction, and cropping in your NativePHP Mobile app — powered by native platform APIs.

Quick Start
-----------

[](#quick-start)

```
composer require ikromjon/nativephp-mobile-document-scanner
php artisan native:plugin:register ikromjon/nativephp-mobile-document-scanner
php artisan native:run android  # or ios
```

```
use Ikromjon\DocumentScanner\Facades\DocumentScanner;
use Ikromjon\DocumentScanner\Events\DocumentScanned;
use Native\Mobile\Attributes\OnNative;

// In your Livewire component:
DocumentScanner::scan();

// Handle the result (Livewire method)
#[OnNative(DocumentScanned::class)]
public function onScanned($data)
{
    $paths = $data['paths'];           // ['/path/scan_0.jpg', ...]
    $pageCount = $data['pageCount'];   // 2
}
```

That's it. The scanner opens, the user scans, and you get the file paths back via events. See below for full options and JavaScript usage.

How It Works
------------

[](#how-it-works)

PlatformNative APIFeatures**iOS**VisionKit (`VNDocumentCameraViewController`)Auto edge detection, perspective correction, shadow removal, multi-page**Android**Google ML Kit Document ScannerAuto edge detection, cropping, rotation, multi-page, gallery importNo external API keys or internet required. Camera permission is handled automatically.

Installation
------------

[](#installation)

```
composer require ikromjon/nativephp-mobile-document-scanner
php artisan native:plugin:register ikromjon/nativephp-mobile-document-scanner
```

Build your app (plugin requires a native build):

```
php artisan native:run android
# or
php artisan native:run ios
```

> **Note:** The scanner requires a native build on a real device — it won't work with `php artisan serve`. If you call `scan()` without a native build, you'll see a warning in your Laravel log.

Configuration
-------------

[](#configuration)

Optionally publish the config file:

```
php artisan vendor:publish --tag=document-scanner-config
```

KeyDefaultDescription`default_max_pages``0`Default max pages per scan (0 = unlimited)`max_pages_limit``100`Absolute cap on pages per scan`default_output_format``jpeg`Default output format (`jpeg` or `pdf`)`default_jpeg_quality``90`Default JPEG compression quality (1-100)`storage_directory``scanned-documents`Subdirectory for scanned files`default_gallery_import``false`Allow gallery import (Android only)`default_scanner_mode``full`Scanner mode: `base`, `filter`, `full` (Android only)Usage (PHP)
-----------

[](#usage-php)

### Scan a Document

[](#scan-a-document)

```
use Ikromjon\DocumentScanner\Facades\DocumentScanner;

// Scan with defaults
DocumentScanner::scan();

// Scan with options
DocumentScanner::scan([
    'maxPages' => 3,
    'outputFormat' => 'jpeg',
    'jpegQuality' => 85,
]);

// Scan a single page (e.g. ID card)
DocumentScanner::scan(['maxPages' => 1]);

// Scan to PDF
DocumentScanner::scan(['outputFormat' => 'pdf']);
```

The `scan()` method opens the native scanner UI and returns immediately. Results are delivered asynchronously via events.

### Type-Safe DTO

[](#type-safe-dto)

```
use Ikromjon\DocumentScanner\Data\ScanOptions;
use Ikromjon\DocumentScanner\Enums\OutputFormat;

DocumentScanner::scan(new ScanOptions(
    maxPages: 5,
    outputFormat: OutputFormat::Pdf,
));
```

### Scan Parameters

[](#scan-parameters)

ParameterTypePlatformDescription`maxPages`intBothMax pages to scan (0 = unlimited)`outputFormat`OutputFormat|stringBoth`jpeg` or `pdf``jpegQuality`intBothJPEG quality 1-100 (only for jpeg output)`galleryImport`boolAndroid onlyAllow importing from device gallery`scannerMode`ScannerMode|stringAndroid only`base`, `filter`, or `full`Full Livewire Example
---------------------

[](#full-livewire-example)

A complete component that scans documents and displays the results:

```
use Livewire\Component;
use Native\Mobile\Attributes\OnNative;
use Ikromjon\DocumentScanner\Facades\DocumentScanner;
use Ikromjon\DocumentScanner\Events\DocumentScanned;
use Ikromjon\DocumentScanner\Events\ScanCancelled;
use Ikromjon\DocumentScanner\Events\ScanFailed;

class DocumentScannerComponent extends Component
{
    public array $scannedFiles = [];
    public string $error = '';

    public function scan()
    {
        DocumentScanner::scan(['maxPages' => 5]);
    }

    #[OnNative(DocumentScanned::class)]
    public function onScanned($data)
    {
        $this->scannedFiles = $data['paths'];
    }

    #[OnNative(ScanCancelled::class)]
    public function onCancelled()
    {
        // User dismissed the scanner
    }

    #[OnNative(ScanFailed::class)]
    public function onFailed($data)
    {
        $this->error = $data['error'];
    }
}
```

> **Important:** Use `#[OnNative(...)]` (not `#[On(...)]`) for NativePHP events.

Listening to Events (Laravel)
-----------------------------

[](#listening-to-events-laravel)

```
use Ikromjon\DocumentScanner\Events\DocumentScanned;

class HandleDocumentScanned
{
    public function handle(DocumentScanned $event): void
    {
        // $event->paths — array of file paths
        // $event->pageCount — number of pages scanned
        // $event->outputFormat — 'jpeg' or 'pdf'
    }
}
```

Usage (JavaScript)
------------------

[](#usage-javascript)

```
import {
  scan,
  imagesToPdf,
  pdfToImages,
  Events,
} from "../../vendor/ikromjon/nativephp-mobile-document-scanner/resources/js/index.js";
import { On } from "#nativephp";

// Open scanner
await scan({ maxPages: 3, outputFormat: "jpeg", jpegQuality: 90 });

// Listen for results
On(Events.DocumentScanned, (payload) => {
  console.log("Scanned:", payload.paths, payload.pageCount);
});

On(Events.ScanCancelled, () => {
  console.log("Cancelled");
});

On(Events.ScanFailed, (payload) => {
  console.error("Failed:", payload.error);
});

// Combine images into PDF
const result = await imagesToPdf(["/path/scan_0.jpg", "/path/scan_1.jpg"]);
console.log("PDF:", result.path);

// Extract thumbnails from PDF
const thumbs = await pdfToImages("/path/scan.pdf", 80);
console.log("Pages:", thumbs.paths);
```

Events
------

[](#events)

EventPayloadWhen`DocumentScanned``paths`, `pageCount`, `outputFormat`Scanning completed successfully`ScanCancelled`—User cancelled the scanner`ScanFailed``error`An error occurred`PdfCreated``path``imagesToPdf()` completedScanned Files
-------------

[](#scanned-files)

Scanned files are saved to the app's internal storage under the configured `storage_directory` (default: `scanned-documents`). File paths returned in the `DocumentScanned` event are absolute paths on the device.

- **JPEG output:** one file per page (e.g. `scan_0.jpg`, `scan_1.jpg`)
- **PDF output:** a single multi-page PDF file
- Files persist until the app is uninstalled or you delete them manually

### Which format to use?

[](#which-format-to-use)

**JPEG (default)** is the better choice for most apps. You get individual files per page, which means you can show page previews, let users view/delete specific pages, and convert to PDF later on your own terms (e.g. with [fpdf](https://packagist.org/packages/setasign/fpdf)). You also control file size via `jpegQuality`.

**PDF** is useful when you need a single file immediately and don't need to display or manipulate individual pages. Note that the native scanner produces the PDF directly — you can't extract page previews from it without a separate library.

See [Smart Docs](https://github.com/Ikromjon1998/smart-docs) for an example that scans as JPEG by default and converts to PDF on demand.

Required Permissions
--------------------

[](#required-permissions)

**Android:** `CAMERA` — declared automatically via `nativephp.json`. ML Kit handles the scanner UI internally.

**iOS:** VisionKit requests camera access at runtime. Your app's `Info.plist` must include an `NSCameraUsageDescription` string — NativePHP sets a default, but you should customize it for your app store submission (e.g. "This app uses the camera to scan documents").

No API keys or internet required.

Demo App
--------

[](#demo-app)

See [Smart Docs](https://github.com/Ikromjon1998/smart-docs) — a full NativePHP mobile app that uses this plugin for document scanning.

Documentation
-------------

[](#documentation)

- [Installation](docs/installation.md) — requirements, setup steps, verification
- [Configuration](docs/configuration.md) — all config options explained
- [Usage with Livewire](docs/livewire.md) — Livewire components and event handling
- [Usage with JavaScript](docs/javascript.md) — Inertia Vue/React integration
- [API Reference](docs/api-reference.md) — events, DTOs, enums, validation, contracts

JPEG-to-PDF Conversion
----------------------

[](#jpeg-to-pdf-conversion)

Combine scanned JPEG pages into a single PDF on-device — no extra PHP library needed:

```
use Ikromjon\DocumentScanner\Facades\DocumentScanner;
use Ikromjon\DocumentScanner\Events\PdfCreated;
use Native\Mobile\Attributes\OnNative;

// Combine images into a PDF
$result = DocumentScanner::imagesToPdf([
    '/path/scan_0.jpg',
    '/path/scan_1.jpg',
]);
$pdfPath = $result['path']; // '/path/combined_1712345678.pdf'

// Listen for completion
#[OnNative(PdfCreated::class)]
public function onPdfCreated($data)
{
    $pdfPath = $data['path'];
}
```

Works with any JPEG files, not just scanned documents.

PDF Page Thumbnails
-------------------

[](#pdf-page-thumbnails)

Extract page previews from a PDF — useful when you scan as PDF but need page-level previews:

```
$result = DocumentScanner::pdfToImages('/path/scan.pdf', quality: 80);
$pagePaths = $result['paths']; // ['/path/page_0.jpg', '/path/page_1.jpg']
```

Planned Features
----------------

[](#planned-features)

- **File management** — list, delete, and clean up scanned files via the plugin API
- **Image post-processing** — grayscale, contrast, rotation on scanned images

See [ROADMAP.md](ROADMAP.md) for full details and status.

Testing
-------

[](#testing)

```
composer test
composer analyse
```

Requirements
------------

[](#requirements)

- PHP 8.3+
- NativePHP Mobile v3+
- iOS 13+ / Android API 21+

License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance84

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

4

Last Release

86d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e842ce53c5da80b37318566ca16f298f971b9494b1c7afea5f9ae0b65d208e01?d=identicon)[Ikromjon1998](/maintainers/Ikromjon1998)

---

Top Contributors

[![Ikromjon1998](https://avatars.githubusercontent.com/u/57859849?v=4)](https://github.com/Ikromjon1998 "Ikromjon1998 (39 commits)")

---

Tags

laravelmobileOCRscannernativephpdocument-scannervisionkit

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ikromjon-nativephp-mobile-document-scanner/health.svg)

```
[![Health](https://phpackages.com/badges/ikromjon-nativephp-mobile-document-scanner/health.svg)](https://phpackages.com/packages/ikromjon-nativephp-mobile-document-scanner)
```

###  Alternatives

[jenssegers/agent

Desktop/mobile user agent parser with support for Laravel, based on Mobiledetect

4.8k72.3M513](/packages/jenssegers-agent)[nativephp/mobile-starter

The skeleton application for NativePHP for Mobile.

192.5k](/packages/nativephp-mobile-starter)[al-saloul/agent

Desktop/mobile user agent parser with support for Laravel, based on Mobiledetect

1516.6k1](/packages/al-saloul-agent)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)