DEV Community: Hamdy ELbatal

CoreWatch: A Laravel-Native Dashboard for Server Health and Operations

Hamdy ELbatal — Mon, 12 Oct 2026 16:21:46 +0000

Most Laravel applications eventually need a way to answer a few operational questions: Is the server under pressure? Is the scheduler still running? What is filling the logs? Did a queue or cache operation fail?

There are excellent tools for answering those questions, but they often mean setting up another service, dashboard, or agent. For smaller deployments, I wanted a more direct option: a Laravel package that puts a useful operational view inside the application that already runs the project.

That idea became CoreWatch.

What CoreWatch does

CoreWatch adds a dashboard at /corewatch and a set of Laravel-native tools for:

CPU, memory, disk, uptime, and host information
Application checks for the database, cache, queue, and environment
Recent log entries, read backwards in chunks
Configured service actions, such as restarting Laravel queue workers
Health checks and optional Slack or Telegram alerts
Health and Prometheus endpoints for external monitoring

The package supports PHP 8.2 and Laravel 11, 12, and 13. Its exact operating-system metrics depend on the host: on Linux it reads /proc where available and uses command-based fallbacks for some values. It is not intended to replace a full observability stack for a high-scale system.

Keep it inside the Laravel app

Install the package with Composer and publish its configuration:

composer require hamzi/corewatch
php artisan corewatch:install

The dashboard is available at /corewatch. CoreWatch also exposes its functionality through a facade, so application code can use metrics without making an HTTP request to its own server:

use Hamzi\CoreWatch\Facades\CoreWatch;

$cpu = CoreWatch::cpu();
$ram = CoreWatch::ram();
$disk = CoreWatch::disk();
$health = CoreWatch::health();

That makes the package useful beyond its built-in page. For example, an application can place a small health summary inside an existing admin panel or use the health result in a custom command.

Avoid loading an entire log file

One implementation detail I cared about was log inspection. A naive log viewer reads a file into memory and then slices out the latest lines. That approach becomes unreliable as the file grows.

CoreWatch seeks to the end of the configured file and reads backwards in 64 KB chunks until it has enough matching lines for the requested page. Memory use therefore does not grow with the total size of the log file. It still depends on the requested page and the size of individual log entries, so this is bounded reading rather than a claim of constant memory in every possible case.

Log sources are selected by configured keys. A request does not get to provide an arbitrary filesystem path. That lets an application choose which logs the dashboard can expose.

Operational controls need boundaries

A dashboard that can run server commands is a security feature only if its limits are clear. CoreWatch accepts a service key, looks it up in package configuration, and runs only the corresponding configured command. The request cannot submit a shell command directly. Potentially disruptive shell actions are disabled by default.

The dashboard and API use Laravel's auth middleware by default. For production, authentication is only the first step: an application should also restrict access to administrators using a gate or its own authorization middleware. For example, an app with an isAdmin() method could configure a gate in its service provider:

config([
    'corewatch.gate' => fn ($request) => $request->user()?->isAdmin() === true,
]);

Health and Prometheus endpoints are private by default as well. They can be exposed deliberately for an external monitor, but that choice should be paired with suitable network or proxy restrictions. Operational endpoints can reveal useful details about an application and its host.

A layered package structure

The code separates Laravel's HTTP and console entry points from the work they trigger:

src/
├── Contracts/       Interfaces for metrics, logs, and notifications
├── Domain/          Health rules and diagnostic logic
├── Application/     Actions that coordinate use cases
├── Infrastructure/  Host metrics, repositories, shell, notifications
├── Http/            Controllers, middleware, and requests
└── Console/         Artisan commands

This is not architecture for architecture's sake. It gives the package places to isolate system access, health decisions, and Laravel integration. It also means that tests can exercise actions and domain rules without relying on a live server for every scenario.

The package includes commands for scheduled health checks and scheduler heartbeats:

use Illuminate\Support\Facades\Schedule;

Schedule::command('corewatch:heartbeat')->everyMinute();
Schedule::command('corewatch:check-health')->everyFiveMinutes();

It also includes corewatch:doctor to inspect common environment and integration issues, plus corewatch:test-alert to check alert delivery.

Where the project is going

CoreWatch is a practical tool for Laravel teams that want basic operational visibility close to the application. It favors an installable package, Laravel's existing scheduler and authorization mechanisms, and a small number of explicit integration points.

It does not collect historical time series or replace dedicated monitoring systems. For that, use a proper metrics store and alerting stack. CoreWatch is most useful for the everyday checks that otherwise require opening several tools or logging into a server.

The project is open source, and feedback is welcome: hamdyelbatal122/CoreWatch on GitHub.

If you try it in a Laravel application, I would especially like to hear which operational checks save you the most time and what should be configurable before anything else.

Building Local RAG Workflows in Laravel with NativeRAG

Hamdy ELbatal — Mon, 12 Oct 2026 16:12:31 +0000

AI features are becoming normal in web applications, but a lot of teams still hesitate when the first step requires sending private application data to an external API.

That is the problem NativeRAG tries to solve for Laravel developers.

NativeRAG is a Laravel package for building small to medium retrieval-augmented generation workflows using local models through Ollama or LM Studio. It gives you chat completions, embeddings, vector search, streaming responses, model indexing, and conversation persistence without needing a separate vector database to get started.

The goal is simple: keep the Laravel developer experience familiar while making local AI workflows easier to wire into a real application.

Why Local RAG?

Retrieval-augmented generation usually has a few moving parts:

a chat model
an embedding model
document chunking
vector storage
similarity search
prompt construction
conversation history

In many setups, those pieces quickly turn into multiple services. That can be the right architecture at scale, but it is not always what you want on day one.

Sometimes you just need to index Eloquent models, search relevant chunks, and ask a local model a question using that context.

NativeRAG keeps those pieces inside Laravel as much as possible.

What NativeRAG Provides

The package currently supports:

Ollama and LM Studio drivers
chat completions
embedding generation
server-sent event streaming
database-backed embedding storage
SQLite and PHP-side cosine similarity search
Eloquent model indexing through an Embeddable trait
persistent conversations
count-based and token-based history pruning
optional encrypted message storage
Artisan commands for indexing and health checks

It is not trying to replace a dedicated vector database for every use case. Instead, it gives Laravel applications a practical starting point for local RAG features.

Installation

Install the package with Composer:

composer require hamzi/nativerag

Then publish the configuration and migrations:

php artisan vendor:publish --tag="nativerag-config"
php artisan vendor:publish --tag="nativerag-migrations"
php artisan migrate

The package stores embeddings and conversations in your application database.

Configuration

You can use Ollama as the default driver:

NATIVE_RAG_DRIVER=ollama

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_CHAT_MODEL=llama3
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

Or LM Studio:

NATIVE_RAG_DRIVER=lmstudio

LMSTUDIO_BASE_URL=http://localhost:1234
LMSTUDIO_CHAT_MODEL=meta-llama-3-8b-instruct
LMSTUDIO_EMBEDDING_MODEL=nomic-embed-text

You can also tune chunking and search behavior:

NATIVE_RAG_CHUNK_SIZE=1000
NATIVE_RAG_CHUNK_OVERLAP=200
NATIVE_RAG_MIN_SCORE=0.35

Chat Completions

The simplest use case is sending messages to a local chat model:

use Hamzi\NativeRag\Facades\NativeRag;

$response = NativeRag::chat([
    [
        'role' => 'system',
        'content' => 'You are a concise Laravel assistant.',
    ],
    [
        'role' => 'user',
        'content' => 'Explain service containers in simple terms.',
    ],
]);

echo $response->content;

This keeps the API close to common chat message formats while still using Laravel's facade and manager patterns under the hood.

Indexing Eloquent Models

One of the most useful parts of the package is the Embeddable trait.

You can make a model searchable by implementing EmbeddableContract and returning the text that should be embedded:

namespace App\Models;

use Hamzi\NativeRag\Contracts\EmbeddableContract;
use Hamzi\NativeRag\Traits\Embeddable;
use Illuminate\Database\Eloquent\Model;

class Article extends Model implements EmbeddableContract
{
    use Embeddable;

    public function toEmbeddableString(): string
    {
        return "Title: {$this->title}\n\nContent: {$this->content}";
    }
}

When the model is saved, NativeRAG can chunk the text, generate embeddings, and store them in the embeddings table.

This is especially useful for documentation, knowledge bases, product content, internal notes, support articles, and other text-heavy records.

Searching Indexed Content

Once content is indexed, you can search using either a plain text query or a precomputed embedding vector:

use Hamzi\NativeRag\Facades\NativeRag;

$results = NativeRag::search(
    query: 'How do I run database migrations?',
    limit: 5,
    minScore: 0.4,
);

foreach ($results as $chunk) {
    echo $chunk->chunk_content;
}

For many Laravel applications, this is enough to start building contextual AI features without introducing more infrastructure.

Building A RAG Prompt

A common flow looks like this:

Receive a user question.
Search indexed chunks.
Combine the matching chunks into context.
Send the context and question to the model.

Example:

use Hamzi\NativeRag\Facades\NativeRag;
use Hamzi\NativeRag\Services\PromptCompiler;

$question = 'How can users reset their password?';

$chunks = NativeRag::search($question, limit: 4);

$context = $chunks
    ->pluck('chunk_content')
    ->implode("\n\n---\n\n");

$prompt = app(PromptCompiler::class)->buildRagPrompt(
    systemInstruction: 'Answer using only the provided context.',
    context: $context,
    query: $question,
);

$response = NativeRag::chat([
    ['role' => 'user', 'content' => $prompt],
]);

echo $response->content;

This pattern is intentionally straightforward. You can replace the prompt, filtering, scoring threshold, or context formatting based on your application's needs.

Streaming Responses

For UI experiences, waiting for a full response can feel slow. NativeRAG supports streaming through server-sent events:

use Hamzi\NativeRag\Facades\NativeRag;
use Illuminate\Support\Facades\Route;

Route::post('/ai/stream', function () {
    return NativeRag::stream([
        [
            'role' => 'user',
            'content' => request('message'),
        ],
    ]);
});

That makes it easier to build chat interfaces with Livewire, Alpine.js, Vue, React, or any frontend that can consume an event stream.

Conversation Memory

NativeRAG also includes conversation models for persistent chat history:

use Hamzi\NativeRag\Models\NativeRagConversation;

$conversation = NativeRagConversation::create([
    'name' => 'Support session',
]);

$conversation->addSystemMessage('You are a helpful support assistant.');

$reply = $conversation->ask('How do I publish the config file?');

echo $reply->content;

The conversation stores user and assistant messages, then sends the current history to the selected driver.

History can be pruned by message count or an approximate token budget. System messages can also be preserved so the assistant keeps its instructions.

Queueing Embedding Sync

Embedding generation can take time, especially when indexing larger records. NativeRAG can dispatch embedding sync to Laravel queues:

NATIVE_RAG_QUEUE_INDEXING=true
NATIVE_RAG_QUEUE_CONNECTION=redis
NATIVE_RAG_QUEUE_NAME=default

That lets normal application requests stay responsive while workers handle chunking and embedding generation in the background.

Privacy And Tradeoffs

Running models locally gives you more control over where prompts, documents, and embeddings live. That is useful for internal tools and privacy-sensitive applications.

But local RAG also has tradeoffs:

local models need enough CPU, GPU, and memory
embedding quality depends on the selected model
database-backed vector search is convenient, but not a replacement for specialized vector infrastructure at high scale
prompt design still matters
evaluation is still your responsibility

The package gives you the Laravel plumbing. You still need to choose good models, test outputs, and decide what quality bar makes sense for your product.

Where This Package Fits

NativeRAG is a good fit when you want to:

prototype AI features inside an existing Laravel app
build internal assistants over application data
index Eloquent models without standing up another service
keep model calls local through Ollama or LM Studio
experiment with RAG before committing to heavier infrastructure

It may not be the right fit if you already need distributed vector indexing, advanced ranking pipelines, or large-scale retrieval over millions of chunks.

Final Thoughts

What I like about this approach is that it keeps the first version boring in the best way.

You install a Laravel package, publish config and migrations, add a trait to a model, and start searching your own data. The architecture can evolve later, but the early developer experience stays simple.

For many teams, that is exactly the right place to start.

Repository:

https://github.com/hamdyelbatal122/nativerag

Package:

composer require hamzi/nativerag

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. 🚀

DEV Community: Hamdy ELbatal

CoreWatch: A Laravel-Native Dashboard for Server Health and Operations

What CoreWatch does

Keep it inside the Laravel app

Avoid loading an entire log file

Operational controls need boundaries

A layered package structure

Where the project is going

Building Local RAG Workflows in Laravel with NativeRAG

Why Local RAG?

What NativeRAG Provides

Installation

Configuration

Chat Completions

Indexing Eloquent Models

Searching Indexed Content

Building A RAG Prompt

Streaming Responses

Conversation Memory

Queueing Embedding Sync

Privacy And Tradeoffs

Where This Package Fits

Final Thoughts

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

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

The Problem: Hardware is Hard to Integrate with Web Frameworks

Architecture: Clean Layers, Zero Coupling

Installation

The Web Serial Bridge

Six Built-in Drivers

1. Raw / JSON Driver — ESP32 & Arduino

2. Barcode Line Driver — USB/TTL Scanners

3. RFID ASCII Driver — STX/ETX Readers

4. Fingerprint Packet Driver — Binary UART Modules

5. ESC/POS Driver — Thermal Printers

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

Hardware → Laravel Events (The Magic)

Queue-Based Routing

IoT Frame Buffering: Handling Fragmented Streams

Backend Serial Mode: portflow:listen

Creating a Custom Driver

Security Hardening (v0.6.0)

1. Context Key Whitelisting (Injection Prevention)

2. Reverse-Proxy Safe Rate Limiting

3. Boot-Time Configuration Validation

4. Device Path Validation

Testing: From 19 to 86 Tests

Unit Tests — Every Driver

Integration Tests — End-to-End

Blade & Livewire Components

Status Badge

Connector Component

Alpine.js Integration

Supported Devices (Non-Exhaustive)

Requirements

Quick Reference: The Facade

Getting Started Today

Final Thoughts

Vaultic: WebAuthn Authentication for Laravel – The Death of Passwords

Vaultic: WebAuthn Authentication for Laravel

The Death of Passwords is Here

Why Should You Care About Passkeys?

The Problem with Passwords

Why Passkeys Win

What is Vaultic?

Feature Checklist

⚡ Quick Start: Passkeys in 5 Minutes

Step 1️⃣: Install

Step 2️⃣: Publish Assets & Migrate

Step 3️⃣: Add Button to Your Login

Step 4️⃣: 🎉 Done!

🏗️ Architecture: How It Works

💼 Real-World Example: Multi-Guard Setup

🎁 Key Features Deep Dive

1️⃣ Passkey Management Panel

2️⃣ Activity Logging & Security Events

3️⃣ Rate Limiting (Built-In)

4️⃣ Fallback Authentication

5️⃣ Custom WebAuthn Verifier

🔌 API Endpoints for Custom UIs

Backend Serial Mode: `portflow:listen`