Forem: Hamdy ELbatal

PortFlow: Bridging Laravel with Serial Hardware, IoT Sensors & Thermal Printers

Hamdy ELbatal — Mon, 04 May 2026 23:26:33 +0000

PortFlow: Bridging Laravel with the Physical World — Serial Hardware, IoT Sensors & Thermal Printers

How to connect barcodes scanners, RFID readers, fingerprint modules, thermal printers, RS-232 scales, and Arduino/ESP32 microcontrollers to a Laravel application — through a clean, driver-based architecture and the browser's Web Serial API.

Most Laravel packages live entirely in software. They deal with HTTP, databases, queues, and caches — all safely inside the machine.

PortFlow does not.

It bridges the gap between physical hardware and Laravel's event system and Eloquent database, turning raw serial bytes into typed, routable value objects that your application can consume like any other event — with full PHPStan level 8 type safety, test coverage, and production-grade security hardening.

If you've ever tried to integrate a USB barcode scanner, an RS-232 industrial scale, or an ESP32 microcontroller with a Laravel application and ended up with a mess of raw socket code and hard-to-test conditionals — this article is for you.

The Problem: Hardware is Hard to Integrate with Web Frameworks

Serial devices — printers, sensors, scanners, microcontrollers — speak in bytes, not JSON. They use protocols designed decades before REST APIs existed: raw delimited strings, binary packets with checksums, ESC/POS command sequences, RS-232 semicolon-delimited records.

Bridging that world with Laravel typically means:

Raw fopen() / stream_socket_client() calls sprinkled across controllers
No abstraction — the protocol is baked into the business logic
No testability — you can't unit test a class that opens /dev/ttyUSB0
No type safety — parsed data is array<string, mixed> at best, a raw string at worst
No event routing — you have to wire the parsed data to your domain manually

PortFlow solves all of this with a layered architecture and a single clean interface.

Architecture: Clean Layers, Zero Coupling

PortFlow follows Clean Architecture. The domain has zero knowledge of Laravel infrastructure, HTTP, or serial ports. This makes every layer independently testable.

Browser (Web Serial API)
       │
       │  POST /portflow/ingest  { driver: "raw-json", chunk: "...", context: {...} }
       ▼
IngestController
       │
       ▼
PortFlowManager → DriverRegistry → SerialDriver::parseInbound()
       │
       ▼
SerialFrame[]  ──→  MessageRouter
                         │
                    ┌────┴─────┐
                    │          │
               Dispatch    Persist to
               Laravel    Eloquent
               Event      Model

The source tree maps directly onto the layers:

src/
├── Domain/                       ← Pure PHP, zero Laravel dependencies
│   ├── Contracts/
│   │   ├── SerialDriver.php      ← Interface all drivers implement
│   │   └── SerialEvent.php       ← Marker interface for domain events
│   ├── DTO/
│   │   └── SerialFrame.php       ← Immutable value object: parsed frame
│   └── Services/
│       └── IoTFrameBuffer.php    ← Byte-stream accumulation
│
├── Application/                  ← Orchestration, no I/O
│   ├── Jobs/
│   │   └── RouteSerialFrameJob.php
│   └── Services/
│       ├── DriverRegistry.php
│       ├── HardwareMessageService.php
│       └── MessageRouter.php
│
├── Infrastructure/               ← All Laravel-specific code
│   ├── Drivers/                  ← Six built-in drivers
│   ├── Http/Controllers/
│   ├── Livewire/
│   └── Printing/
│
└── Console/Commands/

Installation

composer require hamzi/portflow

Publish the config:

php artisan vendor:publish --tag=portflow-config

Publish the JavaScript bridge:

php artisan vendor:publish --tag=portflow-assets

That's it. No database migrations, no required environment variables — just a config file and an optional JS asset.

The Web Serial Bridge

The key insight behind PortFlow is delegating the raw serial I/O to the browser's Web Serial API, which runs in Chrome/Edge 89+. The JavaScript bridge reads bytes from the serial port and forwards them to your Laravel backend in small chunks.

<!-- Include the bridge -->
<script src="{{ asset('vendor/portflow/portflow-serial.js') }}"></script>

<!-- Drop the Livewire component -->
<livewire:portflow-connector
  :baud-rate="115200"
  driver="raw-json"
  :auto-connect-on-load="true"
  :context="['device' => 'station-a']"
/>

Or use the bridge directly with JavaScript:

const bridge = new PortFlowBridge({
  ingestUrl: '{{ route("portflow.ingest") }}',
  driver:    'raw-json',
  baudRate:  115200,
  csrfToken: document.querySelector('meta[name="csrf-token"]').content,
  autoReconnect: true,
  maxRetries: 5,
});

document.getElementById('connect').addEventListener('click', () => bridge.connect());

The bridge supports auto-reconnect with exponential back-off (2 s → 4 s → 8 s → …), localStorage baud rate persistence, Alpine.js bindings, and real-time window events for every status change.

Six Built-in Drivers

Each driver implements a single interface:

interface SerialDriver
{
    public function name(): string;
    public function configure(array $options = []): void;

    /** @return array<int, SerialFrame> */
    public function parseInbound(string $chunk, array $context = []): array;

    public function encodeOutbound(array|string $payload): string;
}

1. Raw / JSON Driver — ESP32 & Arduino

The most flexible driver. Accumulates bytes in an IoTFrameBuffer and emits complete SerialFrame objects when a newline delimiter arrives. Invalid JSON is never silently dropped — it's forwarded as {"raw": "..."} so you can decide how to handle it.

// Incoming from an ESP32:
{ "type": "barcode.scan", "barcode": "4006381333931" }
{ "type": "temperature", "celsius": 22.4, "humidity": 61 }

Configure in config/portflow.php:

'default_driver' => 'raw-json',

'driver_options' => [
    'raw-json' => [
        'delimiter' => "\n",
        'max_bytes'  => 16384,
    ],
],

'mappings' => [
    [
        'driver'              => 'raw-json',
        'payload_field'       => 'type',
        'equals'              => 'barcode.scan',
        'event'               => \App\Events\ProductScanned::class,
        'event_payload_field' => 'barcode',
    ],
    [
        'driver'  => 'raw-json',
        'payload_field' => 'type',
        'equals'  => 'temperature',
        'model'   => \App\Models\SensorReading::class,
    ],
],

2. Barcode Line Driver — USB/TTL Scanners

USB barcode scanners in HID keyboard mode or TTL mode emit a barcode string followed by CR, LF, or CR+LF. This driver strips terminators, filters empty lines, and emits one SerialFrame per barcode.

'driver_options' => [
    'barcode-line' => [
        'delimiter' => "\n",
        'prefix'    => null,    // strip a leading prefix if present
    ],
],

Inbound SerialFrame::$payload:

[
    'barcode'  => '4006381333931',
    'raw'      => "4006381333931\n",
    'driver'   => 'barcode-line',
    'scanned_at' => '2026-05-05T14:23:11+00:00',
]

3. RFID ASCII Driver — STX/ETX Readers

Standard ASCII RFID readers wrap tag IDs in STX (0x02) / ETX (0x03) delimiters. The driver buffers incomplete frames across multiple chunks (essential for real TCP/serial fragmentation), uppercases tag IDs by default, and discards empty tags automatically.

'driver_options' => [
    'rfid-ascii' => [
        'stx'       => "\x02",
        'etx'       => "\x03",
        'uppercase' => true,
    ],
],

Parsed SerialFrame::$payload:

[
    'tag_id'  => 'E2801160600002044E35A000',
    'raw'     => "\x02E2801160600002044E35A000\x03",
    'driver'  => 'rfid-ascii',
]

4. Fingerprint Packet Driver — Binary UART Modules

Binary fingerprint modules (e.g., R305, FPM10A) send structured binary packets over UART. This is the most complex driver — it parses a multi-byte packet header, validates the checksum, and returns typed frames for command, acknowledgement, data, and end-of-data packet types.

Packet layout:
┌──────────┬──────────┬──────────┬────────────────┬──────────┬──────────────┐
│ Start(2) │ Type(1)  │ Len(2)   │ Payload(Len-2) │ Chk(2)  │              │
└──────────┴──────────┴──────────┴────────────────┴──────────┴──────────────┘

Checksum mismatches are logged with Log::warning including the raw hex for debugging. Payload bytes are base64-encoded for binary-safe cache storage across chunks.

'driver_options' => [
    'fingerprint-packet' => [
        'start_code' => 0xEF01,
    ],
],

5. ESC/POS Driver — Thermal Printers

The ESC/POS driver handles both directions:

Inbound (USB barcode scanner as keyboard input):

// Scanner sends: "4006381333931\n"
// → SerialFrame with payload['barcode'] = '4006381333931'

Outbound (print a Blade template as ESC/POS bytes):

$bytes = PortFlow::print('receipts.order', ['order' => $order]);
// Returns ESC/POS byte string — send to printer via Web Serial

Build ESC/POS bytes with the fluent builder:

use Hamzi\PortFlow\Infrastructure\Printing\EscPosBuilder;

$bytes = (new EscPosBuilder)
    ->align('center')
    ->bold()
    ->text('ACME STORE')
    ->bold(false)
    ->divider()
    ->align('left')
    ->text('Item 1 ................. $9.99')
    ->text('Item 2 ................. $4.50')
    ->divider()
    ->bold()
    ->text('TOTAL ................. $14.49')
    ->bold(false)
    ->feed(3)
    ->cut()
    ->bytes();

Method	ESC/POS command	Description
`text(string $v)`	—	Append a line
`bold(bool $on)`	`ESC E n`	Toggle bold
`underline(bool $on)`	`ESC - n`	Toggle underline
`align(string)`	`ESC a n`	`left`, `center`, `right`
`divider(int $w)`	—	Dash separator
`feed(int $lines)`	`LF`	Blank lines
`cut(bool $partial)`	`GS V`	Paper cut

6. RS-232 Driver — Industrial Scales & Legacy Devices

Industrial scales and legacy serial devices often emit semicolon-delimited ASCII records. The RS-232 driver parses these and exposes both the raw string and the split segments.

// Device emits:
12.500;kg;SCALE-A1

// SerialFrame::$payload:
[
    'weight'   => '12.500',
    'unit'     => 'kg',
    'segments' => ['12.500', 'kg', 'SCALE-A1'],
    'raw'      => '12.500;kg;SCALE-A1',
]

Encode outbound commands (e.g., send a TARE command):

PortFlow::encode('rs232', ['TARE', '0', 'RESET']);
// → "TARE,0,RESET\n"

Hardware → Laravel Events (The Magic)

Once frames are parsed, MessageRouter maps them to domain events and Eloquent models using the portflow.mappings config:

// config/portflow.php
'mappings' => [
    [
        'driver'              => 'barcode-line',
        'event'               => \App\Events\ProductScanned::class,
        'event_payload_field' => 'barcode',
    ],
    [
        'driver' => 'rfid-ascii',
        'event'  => \App\Events\AccessCardSwiped::class,
        'event_payload_field' => 'tag_id',
    ],
    [
        'driver' => 'raw-json',
        'model'  => \App\Models\SensorReading::class,
    ],
],

Your listener looks exactly like any other Laravel event listener:

class HandleBarcodeScan
{
    public function handle(ProductScanned $event): void
    {
        $product = Product::where('barcode', $event->frame->payload['barcode'])->firstOrFail();
        $product->increment('scan_count');
        broadcast(new ProductDisplayed($product));
    }
}

Queue-Based Routing

High-throughput hardware (RS-232 at 921600 baud, streaming sensors) can overwhelm synchronous routing. Enable queue routing with one config line:

'queue_routing' => true,
'queue_connection' => 'redis',
'queue_name'       => 'hardware',

Frames are dispatched to RouteSerialFrameJob and processed asynchronously. Rate limiting is built in — default 60 requests/minute per IP + authenticated user, configurable in portflow.ingest_rate_limit.

IoT Frame Buffering: Handling Fragmented Streams

Serial bytes don't arrive in neat JSON objects. A 64-byte JSON frame might arrive as three 22-byte chunks depending on timing, baud rate, and OS buffering. IoTFrameBuffer solves this transparently:

Chunk 1: '{"type":"bar'
Chunk 2: 'code.scan","b'
Chunk 3: 'arcode":"400638"}\n'
         └──────────── emitted as SerialFrame ──────────────┘

The buffer persists across requests using Laravel Cache (keyed by context.session_id), so even a single JSON frame split across multiple HTTP requests from the Web Serial bridge is assembled correctly.

// config/portflow.php
'driver_options' => [
    'raw-json' => [
        'max_bytes' => 16384,   // rolling ceiling — prevents unbounded growth
    ],
],

Backend Serial Mode: `portflow:listen`

For server-side integration (Linux services, kiosks, headless stations), PortFlow provides a backend Artisan listener that reads from real serial ports and feeds frames through the same ingest pipeline:

# Basic
php artisan portflow:listen /dev/ttyUSB0 --driver=barcode-line --baud=115200

# Full UART parameters
php artisan portflow:listen /dev/ttyUSB1 \
  --driver=rfid-ascii \
  --baud=9600 \
  --parity=none \
  --data-bits=8 \
  --stop-bits=1 \
  --flow-control=none \
  --context='{"station":"gate-a"}'

# Debug mode — shows raw payload in the console
php artisan portflow:listen /dev/ttyUSB0 \
  --driver=raw-json \
  --baud=921600 \
  --show-data=1 \
  --show-data-format=json

Device path validation ensures only legitimate TTY nodes are used (/dev/ttyXxx, /dev/serial/by-id/*, /dev/serial/by-path/*) — path traversal via writable /dev/shm/ or similar paths is rejected at the validation layer.

Creating a Custom Driver

Generate the boilerplate with Artisan:

php artisan portflow:make-driver MyScale
# creates app/SerialDrivers/MyScaleDriver.php

The generated stub implements SerialDriver. Fill in parseInbound() and encodeOutbound():

final class MyScaleDriver implements SerialDriver
{
    public function name(): string { return 'my-scale'; }

    public function configure(array $options = []): void { }

    public function encodeOutbound(array|string $payload): string
    {
        return is_string($payload) ? $payload : implode(',', (array) $payload)."\n";
    }

    /** @return array<int, SerialFrame> */
    public function parseInbound(string $chunk, array $context = []): array
    {
        $weight = trim($chunk);
        if ($weight === '') {
            return [];
        }

        return [SerialFrame::now($this->name(), ['weight' => $weight], $context)];
    }
}

'drivers' => [
    'my-scale' => \App\SerialDrivers\MyScaleDriver::class,
],

Define a typed domain event by implementing SerialEvent:

use Hamzi\PortFlow\Domain\Contracts\SerialEvent;

final class WeightReceived implements SerialEvent
{
    public function __construct(
        public readonly string $value,
        public readonly array  $context = [],
    ) {}
}

The SerialEvent marker interface is enforced at routing time. Events that don't implement it are rejected with Log::error and routing is skipped — preventing silent data loss from misconfigured mappings.

Security Hardening (v0.6.0)

Security was a primary concern in the latest release. Here's what was hardened:

1. Context Key Whitelisting (Injection Prevention)

The ingest endpoint previously accepted any keys in the context JSON object, making it possible to inject arbitrary data into the frame context that could reach Eloquent fill() calls.

// Now: only these keys are accepted. Unknown keys → 422 Unprocessable Entity.
'context' => ['nullable', 'array:session_id,source,device,baud_rate,device_name'],
'context.session_id'  => ['sometimes', 'string', 'max:128'],
'context.source'      => ['sometimes', 'string', 'max:64'],
'context.device'      => ['sometimes', 'string', 'max:128'],
'context.baud_rate'   => ['sometimes', 'integer'],
'context.device_name' => ['sometimes', 'string', 'max:128'],

2. Reverse-Proxy Safe Rate Limiting

The default Laravel IP-based rate limit is trivially bypassed behind a proxy. PortFlow's rate limiter combines the client IP with the authenticated user ID:

RateLimiter::for('portflow', function (Request $request) {
    $by = $request->ip();

    if ($request->user() !== null) {
        $by .= '-'.$request->user()->getAuthIdentifier();
    }

    return Limit::perMinute((int) config('portflow.ingest_rate_limit', 60))->by($by);
});

3. Boot-Time Configuration Validation

Misconfigured drivers (wrong class name, missing interface) now throw immediately at application boot — not silently at the first request, which could happen in production:

// In PortFlowServiceProvider::boot()
private function validateConfiguration(): void
{
    foreach ($drivers as $name => $class) {
        if (! class_exists($class)) {
            throw PortFlowException::invalidDriver($name, "class [{$class}] does not exist");
        }
        if (! is_a($class, SerialDriver::class, true)) {
            throw PortFlowException::invalidDriver($name, "class [{$class}] must implement SerialDriver");
        }
    }

    foreach ($mappings as $index => $mapping) {
        if (isset($mapping['event']) && ! class_exists($mapping['event'])) {
            throw PortFlowException::invalidConfiguration(
                "mappings[{$index}].event class [{$mapping['event']}] does not exist"
            );
        }
    }
}

4. Device Path Validation

The portflow:listen command validates device paths with a strict allowlist regex:

private function isValidDevicePath(string $device): bool
{
    // Linux/macOS: only real TTY nodes and stable symlinks
    if (str_starts_with($device, '/dev/')) {
        return (bool) preg_match(
            '#^/dev/(tty[A-Za-z0-9]+|serial/by-id/[A-Za-z0-9._-]+|serial/by-path/[A-Za-z0-9._:-]+)$#',
            $device
        );
    }
    // Windows: COM1–COM256 and extended \\.\COMx paths
    return (bool) preg_match('/^(COM[1-9]\d{0,2}|\\\\\\\\\\.\\\\COM[1-9]\d{0,2})$/i', $device);
}

Testing: From 19 to 86 Tests

The v0.6.0 release added comprehensive test coverage that was previously missing.

Unit Tests — Every Driver

// tests/Unit/BarcodeLineDriverTest.php
it('strips CR LF terminators', function () {
    $driver = new BarcodeLineDriver;
    $frames = $driver->parseInbound("4006381333931\r\n");

    expect($frames)->toHaveCount(1)
        ->and($frames[0]->payload['barcode'])->toBe('4006381333931');
});

it('handles multiple barcodes in one chunk', function () {
    $driver = new BarcodeLineDriver;
    $frames = $driver->parseInbound("CODE1\nCODE2\nCODE3\n");

    expect($frames)->toHaveCount(3);
});

Integration Tests — End-to-End

// tests/Feature/FrameRoutingIntegrationTest.php
it('routes a raw-json frame to a Laravel event', function () {
    Event::fake([ProductScanned::class]);

    $response = $this->postJson('/portflow/ingest', [
        'driver' => 'raw-json',
        'chunk'  => json_encode(['type' => 'barcode.scan', 'barcode' => 'TEST123'])."\n",
    ]);

    $response->assertOk();
    Event::assertDispatched(ProductScanned::class, fn ($e) => $e->frame->payload['barcode'] === 'TEST123');
});

it('rejects unknown context keys with 422', function () {
    $this->postJson('/portflow/ingest', [
        'driver'  => 'raw-json',
        'chunk'   => '{}',
        'context' => ['arbitrary_key' => 'injection_value'],
    ])->assertUnprocessable();
});

it('assembles a fragmented JSON frame across two requests', function () {
    $sessionId = 'test-buffer-123';

    $this->postJson('/portflow/ingest', [
        'driver'  => 'raw-json',
        'chunk'   => '{"type":"barcode.scan","bar',
        'context' => ['session_id' => $sessionId],
    ])->assertOk();

    $this->postJson('/portflow/ingest', [
        'driver'  => 'raw-json',
        'chunk'   => 'code":"4006381333931"}'."\n",
        'context' => ['session_id' => $sessionId],
    ])->assertOk();
    // Buffer assembled across two HTTP requests ✓
});

Test results: 86 tests, 172 assertions, PHPStan level 8 — 0 errors.

Blade & Livewire Components

Status Badge

<livewire:portflow-status />

Displays driver name, connection status, and frame count. Updates in real time via Livewire events.

Connector Component

<livewire:portflow-connector
  :baud-rate="115200"
  driver="barcode-line"
  :auto-connect-on-load="true"
  :filters="[['usbVendorId' => 6790]]"
  browser-chunk-event="scanner-frame"
/>

Handles the full connect/disconnect/reconnect lifecycle. Emits Livewire events on every frame so you can respond with #[On('scanner-frame')] in any Livewire component.

Alpine.js Integration

<div x-data="portflowConnector()" x-init="init()">
  <button @click="connect()" :disabled="connecting">
    <span x-text="connected ? 'Connected' : 'Connect Device'"></span>
  </button>
  <span x-show="retryCount > 0" x-text="'Reconnecting… attempt ' + retryCount"></span>
</div>

Supported Devices (Non-Exhaustive)

Category	Devices / Modules
Microcontrollers	ESP32, ESP8266, Arduino (Uno, Mega, Nano), Raspberry Pi (serial UART)
Barcode Scanners	Any USB HID / TTL scanner (Honeywell, Zebra, Datalogic, generic)
RFID Readers	STX/ETX ASCII readers (EM4100, MIFARE ASCII mode)
Fingerprint	R305, FPM10A, AS608, any binary-UART module
Thermal Printers	Any ESC/POS compatible printer (Epson TM-series, Bixolon, Star, Sewoo, generic USB)
Scales / Weighing	RS-232 industrial scales (Mettler Toledo, Sartorius, Adam Equipment)
Legacy/Industrial	Any RS-232 / RS-485 device with ASCII output

Requirements

Dependency	Version
PHP	^8.2
Laravel	^11.0 \| ^12.0 \| ^13.0
Livewire	^3.0
Browser (Web Serial)	Chrome 89+ / Edge 89+

Quick Reference: The Facade

use Hamzi\PortFlow\Facades\PortFlow;

// Parse inbound bytes with a driver
$frames = PortFlow::ingest('barcode-line', $rawChunk, $context);

// Encode outbound data
$bytes = PortFlow::encode('escpos', ['text' => 'Hello, printer!']);

// Render a Blade view as ESC/POS bytes
$bytes = PortFlow::print('receipts.order', compact('order'));

// Health check
$status = PortFlow::health();
// → ['default_driver' => 'raw-json', 'registered_drivers' => ['raw-json', 'barcode-line', ...]]

Getting Started Today

# Install
composer require hamzi/portflow

# Publish config
php artisan vendor:publish --tag=portflow-config

# Publish JS bridge
php artisan vendor:publish --tag=portflow-assets

# Generate a custom driver
php artisan portflow:make-driver MyDevice

# Test from a real serial port
php artisan portflow:listen /dev/ttyUSB0 --driver=raw-json --baud=115200 --show-data=1

GitHub: github.com/hamdyelbatal122/PortFlow
Packagist: packagist.org/packages/hamzi/portflow
License: MIT

Final Thoughts

PortFlow was built to close a real gap in the Laravel ecosystem. Hardware integration shouldn't require you to abandon Laravel's clean architecture, event system, and testability. With PortFlow, a barcode scan from a $15 USB scanner flows through the same event-driven pipeline as any other domain event in your application — typed, routable, testable, and secure.

If you're building a POS system, a warehouse scanning app, an access control panel, a smart factory dashboard, or any application that needs to talk to physical hardware — I'd love to hear what you're building.

Contributions are welcome. See CONTRIBUTING.md for the branching strategy, commit convention, and PR guidelines.

Published under MIT License — built with PHP 8.2, Laravel 11/12/13, and a lot of serial port debugging.

Tags: laravel php iot hardware serial-port barcode rfid thermal-printer clean-architecture open-source

Vaultic: WebAuthn Authentication for Laravel – The Death of Passwords

Hamdy ELbatal — Sun, 03 May 2026 05:55:51 +0000

Vaultic: WebAuthn Authentication for Laravel

The Death of Passwords is Here

** Passwords are dead.**

We all know it. You know it. Your users know it. Yet here we are in 2026, still storing password hashes like it's 2016.

The future is passwordless. And it's not coming—it's already here.

But implementing WebAuthn (FIDO2) is a nightmare: challenges, assertions, public-key cryptography, browser compatibility... the complexity is overwhelming.

Until now.

Meet Vaultic: a production-ready WebAuthn/Passkeys package for Laravel that makes passwordless authentication as simple as installing a composer package.

Face ID. Touch ID. Windows Hello. Security Keys.

All working in your Laravel app. Today.

Why Should You Care About Passkeys?

The Problem with Passwords

Issue	Impact
🔓 Phishing	Users fall for fake login prompts
🔑 Reuse	Same password across 100 sites
💥 Breaches	33 billion passwords leaked in 2024
📞 Support Cost	Password resets waste admin time
😤 UX Pain	Users hate remembering passwords

Why Passkeys Win

🛡️  Phishing-proof      → Keys locked to YOUR domain only
📱  Biometric-first     → Face ID, Touch ID, Windows Hello
⚡  Lightning fast       → Tap instead of typing
🔐  Cryptographically   → FIDO2 standard (unbreakable)
    secure
🌍  Universal support   → All modern browsers, all platforms

The result?

Companies switching to passkeys report:

📉 50% fewer password reset tickets
⚡ 90% faster login experience
🚫 ~0% phishing attacks (keys can't be stolen)
😊 Higher user satisfaction

What is Vaultic?

Vaultic is a Laravel package that abstracts away all the WebAuthn complexity. Think of it as the Rails framework for passkeys—you don't write boilerplate, you just ship.

Feature Checklist

Feature	Status
🎯 Multi-guard support (web + API)	✅
📱 Stateful + stateless flows	✅
🎨 Pre-built Blade components	✅
📊 Activity tracking (last login, IP, device)	✅
🔄 Fallback authentication	✅
🚀 Laravel Sanctum integration	✅
⚙️ Zero configuration needed	✅
🔧 Custom WebAuthn verifier	✅
📚 Comprehensive tests	✅
🏆 Battle-tested (19+ releases)	✅

⚡ Quick Start: Passkeys in 5 Minutes

Step 1️⃣: Install

composer require hamzi/vaultic

Step 2️⃣: Publish Assets & Migrate

php artisan vendor:publish --provider="Hamzi\\Vaultic\\VaulticServiceProvider" --tag=vaultic-config
php artisan vendor:publish --provider="Hamzi\\Vaultic\\VaulticServiceProvider" --tag=vaultic-migrations
php artisan vendor:publish --provider="Hamzi\\Vaultic\\VaulticServiceProvider" --tag=vaultic-views
php artisan migrate

Step 3️⃣: Add Button to Your Login

Blade:

<x-vaultic::passkey-button size="md" :full-width="true" />

Step 4️⃣: 🎉 Done!

Your users can now register and log in with:

👤 Face ID
👆 Touch ID
🪟 Windows Hello
🔑 Security Keys

That's it. No WebAuthn knowledge required.

🏗️ Architecture: How It Works

Vaultic uses a clean, layered architecture:

┌─────────────────────────────────┐
│  HTTP Layer                     │
│  (Controllers + Middleware)     │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│  Service Layer                  │
│  (WebAuthn Orchestration)       │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│  Repository Layer               │
│  (Passkey Persistence)          │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│  Eloquent Models                │
│  (Database)                     │
└─────────────────────────────────┘

Clean separation of concerns. Easy to test. Easy to extend.

💼 Real-World Example: Multi-Guard Setup

Your app has both a web UI (Blade) and an API (Sanctum). Vaultic handles both with one package:

// config/vaultic.php
'auth' => [
    'guards' => [
        // 🌐 Web Login
        'web' => [
            'guard' => 'web',
            'provider_model' => App\Models\User::class,
            'identifier_column' => 'email',
        ],
        // 📱 API Auth
        'api' => [
            'guard' => 'sanctum',
            'provider_model' => App\Models\User::class,
            'identifier_column' => 'email',
            'token_issuer' => Hamzi\Vaultic\Services\SanctumApiTokenIssuer::class,
        ],
    ],
],

The flow:

🌐 Web user → taps passkey button → gets session → redirects to dashboard
📱 Mobile client → sends public key → gets Sanctum token → calls API

Both use the same passkey database. No duplication. No complexity.

🎁 Key Features Deep Dive

1️⃣ Passkey Management Panel

Let users manage their own passkeys:

<x-vaultic::passkey-panel />

Users see:

📋 List of linked authenticators (iPhone, Yubikey, Windows Hello, etc.)
🕐 Last used timestamp
🌍 Last used IP address
🗑️ One-click delete for lost devices

Transparency = Trust.

2️⃣ Activity Logging & Security Events

Listen to security events:

Event::listen(PasskeyAuthenticated::class, function ($event) {
    Log::info('User authenticated with passkey', [
        'user_id' => $event->user->id,
        'ip' => request()->ip(),
        'device' => $event->passkey->metadata,
    ]);
});

Events available:

✅ PasskeyRegistered — New key added
✅ PasskeyAuthenticated — User logged in
❌ AuthenticationFailed — Attack detected

3️⃣ Rate Limiting (Built-In)

Protection against brute force attacks:

'rate_limit' => [
    'attempts' => 10,
    'decay_seconds' => 60,
],

After 10 failed attempts → locked out for 60 seconds.

4️⃣ Fallback Authentication

If passkey fails (lost device, browser doesn't support):

'fallback' => [
    'driver' => 'password', // or 'otp' or custom
],

Users can fall back to password or recovery codes.

5️⃣ Custom WebAuthn Verifier

Use your own FIDO2 library (Duo, Yubico, etc.):

$this->app->bind(
    Hamzi\Vaultic\Contracts\WebAuthnVerifier::class,
    App\Security\CustomWebAuthnVerifier::class
);

No vendor lock-in. Total flexibility.

🔌 API Endpoints for Custom UIs

Vaultic exposes clean JSON endpoints:

📝 Registration
  POST /passkeys/register/options      → Get challenge
  POST /passkeys/register              → Save passkey

🔓 Authentication
  POST /passkeys/authenticate/options  → Get challenge
  POST /passkeys/authenticate          → Log in & get token

🗑️ Management
  DELETE /passkeys/{passkey}           → Remove passkey

All JSON responses. Build custom UIs with:

⚛️ React / Vue / Svelte
📱 Native iOS / Android
🤖 Headless systems
🌐 Custom frontends

🌍 Browser & Device Support

Vaultic works everywhere:

Platform Authenticators

🍎 iOS/macOS: Face ID, Touch ID
🪟 Windows: Windows Hello (face, fingerprint, PIN)
🐧 Linux: Fingerprint readers

Cross-Device Auth

📱 Phone as Security Key: Via Bluetooth (tap on your iPhone to unlock your Mac)

Hardware Keys

🔑 Yubikey, Google Titan, Ledger (USB/NFC/BLE)

Vaultic is configured to prefer discoverable credentials, meaning:

No username entry needed
Browser handles biometric prompt
Seamless UX on all devices

📦 Browser Compatibility

Browser	WebAuthn Support
✅ Chrome 67+	Full support
✅ Firefox 60+	Full support
✅ Safari 13+	Full support
✅ Edge 18+	Full support
✅ Opera 54+	Full support

Bottom line: If your users are on modern browsers (which they are), passkeys work everywhere.

🚀 Deployment Checklist

Before shipping to production:

✅ APP_URL is correct (WebAuthn is domain-locked)
✅ CACHE_DRIVER configured (file, Redis, etc.)
✅ Trusted proxies set (if behind load balancer)
✅ composer test passes
✅ Tested on real devices
✅ Event listeners configured
✅ Fallback auth tested
✅ Security.md policy in place

📊 Real Impact Numbers

Companies that switched to passkeys:

Metric	Impact
📞 Support tickets	⬇️ 50% fewer
⚡ Login speed	⬇️ 90% faster
🔓 Phishing attacks	⬇️ ~0%
😊 User satisfaction	⬆️ Significantly higher
🔐 Security incidents	⬇️ Nearly zero

❓ FAQ: Your Questions Answered

Q: "What if a user loses their device?"

A: Vaultic supports fallback auth. Configure:

'fallback' => ['driver' => 'password'],

Lost device? Fall back to password or recovery codes.

Q: "Will my users actually use passkeys?"

A: Yes. When users see a biometric login option, they prefer it. No friction = instant adoption.

Q: "Is it production-ready?"

A: 100%. Vaultic has 19+ releases, comprehensive tests, and follows Laravel standards (CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md).

Q: "Can I keep passwords alongside passkeys?"

A: Yes. Passkeys are optional, not forced. You can:

Offer passkeys as an option
Keep password login alongside
Gradually migrate users
Monitor adoption via events

Q: "What about old browsers?"

A: Use fallback auth. Gracefully degrade to passwords if WebAuthn not supported.

Q: "How does this affect my auth flow?"

A: Minimal changes. Vaultic integrates seamlessly with Laravel's auth system.

🎯 The Future is Passwordless

Timeline:

2023: Apple, Google, Microsoft announce passkey support
2024: Enterprise adoption accelerates
2025: Passkeys become mainstream
2026: Passwords are legacy (where we are now)

Your Laravel app doesn't need to wait for the future—you can move to passwordless authentication today.

🚀 Getting Started (3 Steps)

1. Read the Documentation

👉 github.com/hamdyelbatal122/vaultic

2. Install the Package

composer require hamzi/vaultic

3. Add a Button

<x-vaultic::passkey-button />

That's it. Users can register and log in with passkeys.

💚 Support Vaultic

If Vaultic helps your project:

⭐ Star the repo: github.com/hamdyelbatal122/vaultic
💬 Share your experience: Tweet us or comment below
🐛 Report issues: Help us improve
📖 Contribute docs: Better docs = more users
💰 Sponsor: GitHub Sponsors

Open source thrives on community support. Every star, every issue, every contribution matters.

🤝 Join the Passwordless Future

The password era is ending. Passkeys are the future.

Vaultic makes the transition seamless.

📚 Further Reading

Questions? Drop them in the comments below. 👇

Share this post if you found it helpful. 🚀