Download the PHP package hamzi/portflow without Composer

PortFlow

Neural bridge for Laravel × Hardware. Connect thermal printers, IoT sensors, RS-232 scales, barcode scanners, and any serial device to your Laravel application — all through a clean, driver-based architecture and the browser's Web Serial API.

Contents

• What is PortFlow?
• Architecture
• Requirements
• Installation
• Quick Start
• Available Drivers
  • RAW / JSON (ESP32, Arduino, IoT)
  • Barcode Line Driver (USB/TTL Scanners)
  • RFID ASCII Driver (STX/ETX Readers)
  • Fingerprint Packet Driver (Binary UART)
  • ESC/POS (Thermal Printers)
  • RS-232 (Scales, Legacy Devices)
• Creating a Custom Driver
• Web Serial Integration
  • Backend Direct Serial Mode
  • Auto-Reconnect
  • Browser Compatibility
• Hardware → Events & Eloquent
  • Queue-Based Routing
• Thermal Printing Engine
• IoT Frame Buffering
  • Buffer Persistence Across Requests
• Blade & Livewire Components
• Security
• Configuration Reference
• Testing
• Contributing
• License

What is PortFlow?

Most Laravel packages live entirely in software. PortFlow does not.

It bridges physical hardware (printers, scales, sensors, microcontrollers) with Laravel's event system and database, translating raw serial bytes into typed, routable SerialFrame DTOs that your application can consume like any other event.

Architecture

PortFlow follows Clean Architecture — domain logic is completely isolated from infrastructure:

Requirements

Browser support for Web Serial API: Chrome 89+, Edge 89+. Not supported in Firefox or Safari.

Installation

Publish the config file:

Publish the JavaScript bridge (optional):

Publish driver stubs (optional — for customising the make:driver template):

Quick Start

1. Add the JS bridge to your layout:

2. Drop in the Livewire connector component:

The connector now bootstraps sensible defaults from config/portflow.php automatically, including the ingest URL, default driver, and baud rate. Override them from Blade when needed instead of rendering a select box for the end user.

If :baud-rate is explicitly passed in Blade, PortFlow gives it priority over remembered localStorage values.

Useful Blade props:

When auto-connect-on-load is enabled, PortFlow asks the browser for already-authorized serial devices with navigator.serial.getPorts() and reconnects automatically after reload when permission still exists.

3. Listen for hardware events in your application:

Register the listener in AppServiceProvider::boot():

Available Drivers

RAW / JSON Driver

Use case: ESP32, Arduino, MQTT-to-serial bridges, custom IoT sensors.

The driver accumulates bytes into an IoTFrameBuffer and emits complete JSON frames when a newline delimiter is detected. Invalid JSON is forwarded as { "raw": "..." } so data is never silently dropped.

Inbound frame from an ESP32:

Mapping it to a Laravel event:

ESC/POS Driver

Use case: Thermal receipt printers and USB barcode scanners (which behave like keyboards).

The ESC/POS driver handles both directions:

• Inbound — scanner sends a barcode string that becomes a SerialFrame.
• Outbound — PortFlow::encode('escpos', ['text' => $line]) returns bytes to send to the printer.

Printing a Blade template:

Building ESC/POS bytes manually:

Available EscPosBuilder methods:

RS-232 Driver

Use case: Industrial scales, label printers, and legacy serial devices using semicolon-delimited records.

Example record:

Parsed into:

Encoding outbound commands:

Creating a Custom Driver

Using the Artisan Generator

Then register it in your config:

Manually Implementing the Interface

Implement Hamzi\PortFlow\Domain\Contracts\SerialDriver and, for type safety, also implement SerialEvent on any event classes you create:

Register in AppServiceProvider or config:

Defining a Typed Domain Event

Events that do not implement SerialEvent will still be dispatched, but a Log::warning will be emitted to encourage type safety.

Web Serial Integration

portflow-serial.js provides a thin wrapper around the Web Serial API that POSTs incoming chunks to Laravel automatically.

Constructor options:

Window events:

Auto-Reconnect

When a serial connection drops unexpectedly, the bridge automatically attempts to reconnect using exponential back-off (2 s, 4 s, 8 s, …) up to maxRetries attempts. This is enabled by default and requires no configuration.

Backend Direct Serial Mode

Some devices are easier or safer to integrate from the backend (Linux service, kiosk daemon, headless station) rather than browser Web Serial. PortFlow includes an Artisan listener:

Windows example:

Advanced UART parameters:

Show incoming serial payloads in the console while still ingesting frames:

Data preview options:

• --show-data=1 enables payload preview logs.
• --show-data-format=auto|raw|plain|json|hex|base64 controls rendering format.
• --show-data-max=512 limits displayed bytes per chunk to keep logs readable.

Security and hardening notes:

• Device path validation supports /dev/* on Linux/macOS and COMx / \\.\COMx on Windows.
• Use portflow.backend.allowed_devices to allowlist exact/glob device paths.
• Listener configures serial parameters with platform-native tooling (stty on POSIX, mode on Windows).
• Ingest now validates decoded base64 chunk size against max_chunk_bytes.

config/portflow.php backend section:

To disable:

Alpine.js integration (built-in):

Browser Compatibility

The Web Serial API is only available in Chromium-based browsers (Chrome 89+ / Edge 89+). Firefox and Safari do not support it.

Check support in JavaScript:

Check support in Blade (no Alpine required):

The component renders a yellow warning banner with a "Download Chrome" link in Firefox/Safari, and leaves the content untouched in supported browsers.

Customise the message and hide the download link:

Hardware → Events & Eloquent

The mappings config key lets you automatically route frames to Laravel events or Eloquent models without writing controller code.

If a mapping's event or model throws an exception, it is caught and written to Log::error so one bad handler never breaks other mappings or the HTTP response.

Queue-Based Routing

For high-throughput or slow listeners, route frames asynchronously via the queue:

Or in .env:

When enabled, each SerialFrame is dispatched as a RouteSerialFrameJob (3 retries by default) on the configured queue connection. The HTTP response is returned immediately.

Thermal Printing Engine

PortFlow ships a Blade-to-ESC/POS renderer so you can design receipts in familiar Blade syntax:

resources/views/receipts/order.blade.php

In a controller or job:

IoT Frame Buffering

IoTFrameBuffer is a standalone utility that accumulates streaming bytes and emits complete frames when a delimiter is found. Use it independently for any stream protocol:

Buffer Persistence Across Requests

IoT devices may split a JSON packet across multiple HTTP requests. Pass a session_id in the request context and the RawJsonDriver will automatically persist the buffer state in the Laravel cache between requests (5-minute TTL):

JavaScript (add session_id to the context):

Or POST directly from firmware:

A subsequent request with the same session_id will complete and emit the frame:

The backend will emit one complete SerialFrame with { "sensor": "temp", "value": 22.5 }.

Requires a cache driver other than array in production (e.g., redis, database).

Blade & Livewire Components

Blade

portflow-browser-check wraps any slot content and injects a styled warning banner when the browser does not support the Web Serial API. See the Browser Compatibility section for full options.

Livewire

The PortFlowStatus component listens for the portflow-status-updated browser event dispatched by the JS bridge automatically.

Security

Configuration Reference

Barcode Line Driver

Use case: common 1D/2D barcode scanners in serial mode (USB CDC, TTL UART, RS-232 adapters).

Most scanners send ASCII text followed by a line terminator (\r, \n, or both). barcode-line normalizes this into:

Recommended config:

RFID ASCII Driver

Use case: 125kHz serial readers (for example ID-12/ID-20 family) that send framed ASCII.

A common frame format is:

• STX (0x02)
• ASCII tag bytes
• CR + LF
• ETX (0x03)

rfid-ascii parses this safely and emits payload like:

Recommended config:

Fingerprint Packet Driver

Use case: optical/capacitive UART fingerprint modules that speak binary packet protocol (common start code 0xEF01).

Unlike barcode/RFID text streams, fingerprint sensors are binary. PortFlow now supports binary chunks over web ingest using chunk_encoding: base64 automatically in the JS bridge.

fingerprint-packet validates checksums and emits parsed packet metadata:

Recommended config:

Device Patterns Supported Out-of-the-box

Testing

Run with coverage:

Lint & style:

Static analysis:

Contributing

Contributions are welcome. Please:

1. Fork the repository and create a feature branch.
2. Write tests for all new behaviour.
3. Run composer format and composer analyse before submitting.
4. Open a Pull Request with a clear description of the change.

See CONTRIBUTING.md for full guidelines.

License

The MIT License. See LICENSE for details.