Plugin Marketplace

nativephp/mobile-scanner

QR code and barcode scanner plugin for NativePHP Mobile - supports multiple barcode formats with continuous scanning

Scanner Plugin for NativePHP Mobile#

Barcode and QR code scanning plugin for NativePHP Mobile applications.

Overview#

The Scanner API provides cross-platform barcode and QR code scanning capabilities through a native camera interface.

Installation#

Copied!
composer require nativephp/mobile-scanner

Usage#

PHP (Livewire/Blade)#

Copied!
use Native\Mobile\Facades\Scanner;
use Native\Mobile\Events\Scanner\CodeScanned;
 
// Open scanner
Scanner::scan();
 
// Listen for scan results
#[OnNative(CodeScanned::class)]
public function handleScan($data, $format, $id = null)
{
    Dialog::toast("Scanned: {$data}");
}

JavaScript (Vue/React/Inertia)#

Copied!
import { Scanner, On, Off, Events } from '#nativephp';
 
// Open scanner
await Scanner.scan();
 
// Listen for scan results
const handleScan = (payload) => {
    const { data, format, id } = payload;
    console.log(`Scanned: ${data}`);
};
 
On(Events.Scanner.CodeScanned, handleScan);

Configuration Methods#

prompt(string $prompt)#

Set custom prompt text displayed on the scanner screen.

Copied!
Scanner::scan()->prompt('Scan product barcode');
Copied!
await Scanner.scan()
    .prompt('Scan product barcode');

continuous(bool $continuous = true)#

Keep scanner open to scan multiple codes. Default is false (closes after first scan).

Copied!
Scanner::scan()->continuous(true);
Copied!
await Scanner.scan()
    .continuous(true);

formats(array $formats)#

Specify which barcode formats to scan. Default is ['qr'].

Available formats: qr, ean13, ean8, code128, code39, upca, upce, all

Copied!
Scanner::scan()->formats(['qr', 'ean13', 'code128']);
Copied!
await Scanner.scan()
    .formats(['qr', 'ean13', 'code128']);

id(string $id)#

Set a unique identifier for the scan session. Useful for handling different scan contexts.

Copied!
Scanner::scan()->id('checkout-scanner');
Copied!
await Scanner.scan()
    .id('checkout-scanner');

Combined Example#

Copied!
Scanner::scan()
    ->prompt('Scan your ticket')
    ->continuous(true)
    ->formats(['qr', 'ean13'])
    ->id('ticket-scanner');
Copied!
await Scanner.scan()
    .prompt('Scan your ticket')
    .continuous(true)
    .formats(['qr', 'ean13'])
    .id('ticket-scanner');

Events#

CodeScanned#

Fired when a barcode is successfully scanned.

Properties:

  • string $data - The decoded barcode data
  • string $format - The barcode format
  • string|null $id - The scan session ID (if set)

PHP

Copied!
use Native\Mobile\Attributes\OnNative;
use Native\Mobile\Events\Scanner\CodeScanned;
 
#[OnNative(CodeScanned::class)]
public function handleScan($data, $format, $id = null)
{
    if ($id === 'product-scanner') {
        $this->addProduct($data);
    }
}

Vue

Copied!
import { On, Off, Events } from '#nativephp';
import { onMounted, onUnmounted } from 'vue';
 
const handleScan = (payload) => {
    const { data, format, id } = payload;
 
    if (id === 'product-scanner') {
        addProduct(data);
    }
};
 
onMounted(() => {
    On(Events.Scanner.CodeScanned, handleScan);
});
 
onUnmounted(() => {
    Off(Events.Scanner.CodeScanned, handleScan);
});

React

Copied!
import { On, Off, Events } from '#nativephp';
import { useEffect } from 'react';
 
const handleScan = (payload) => {
    const { data, format, id } = payload;
 
    if (id === 'product-scanner') {
        addProduct(data);
    }
};
 
useEffect(() => {
    On(Events.Scanner.CodeScanned, handleScan);
 
    return () => {
        Off(Events.Scanner.CodeScanned, handleScan);
    };
}, []);

Testing#

The plugin extends the NativePHP testing suite with scanner-specific helpers, so your app tests can assert scan activity without knowing any bridge internals:

Copied!
use Native\Mobile\Testing\Native;
 
it('opens the scanner with the checkout prompt', function () {
    Native::test(CheckoutScreen::class)
        ->tap('Scan barcode')
        ->assertScanRequested('Scan product barcode');
});
 
it('does not open the scanner until the button is tapped', function () {
    Native::test(CheckoutScreen::class)
        ->assertNothingScanned();
});

Helpers#

  • assertScanRequested(?string $prompt = null) — assert a scan was requested, or one whose prompt exactly matches $prompt when given.
  • assertNothingScanned() — assert no scan was requested.

Scanned codes never arrive as a decoded return value — Scanner::scan() fires the native call and forgets it; the result only reaches your app later as a CodeScanned event. There's nothing to pre-script with a with* helper, so the vocabulary above is assert-only.

The helpers are available on Native::fakeBridge() and chain directly off Native::test(...). They register automatically while running tests (requires a core with a macroable FakeBridge; on older cores they simply don't register).

Platform Support#

  • Android: ML Kit Barcode Scanning (API 21+)
  • iOS: AVFoundation (iOS 13.0+)

Notes#

  • Permissions: You must enable the scanner permission in config/nativephp.php to use the scanner. Camera permissions are then handled automatically, and users will be prompted for permission the first time the scanner is used.