sobi-labs/frameflow

A lightweight, human-readable protocol for streaming payloads with metadata and integrity checks.

v0.1 2026-04-16 09:27 UTC

Requires

• php: >=8.4

MIT

• Marco Schnorrer

README

A lightweight, human-readable streaming protocol for PHP 8.4+

FrameFlow is designed for developers who need a robust way to stream data (payloads) accompanied by rich metadata. It bridges the gap between simple line-based logs and complex binary formats. It's built for speed, integrity, and absolute simplicity.

Key Features

• Human Readable: Inspect your stream with a simple text editor.
• Robust Integrity: Automatic sha256 checksums and Payload-Length headers for every frame.
• Modern PHP 8.4: Fully utilizes Property Hooks and Asymmetric Visibility for maximum performance and clean code.
• Zero Dependencies: No vendor bloat. Just pure, high-performance PHP.
• Time-Ordered: Built-in RFC 9562 compliant UUIDv7 for natural sorting of messages.

The Protocol Structure

Each FrameFlow message consists of a global Header and one or more Frames.

--- FrameFlow-1.0 ---
Trace-Id: 000069d3-c5d9-7bb4-c757-48eb16eac000
Timestamp: 2026-04-09T22:40:25+00:00
Charset: utf-8
Version: 1
Checksum: sha256
Environment: Production
---

--- Frame ---
Id: 69d8017e8e6f2
Type: message
Payload-Length: 12
Checksum: f48... (sha256)
Payload:
Hello World!
---

Quick Start

Installation

composer require sobi-labs/frameflow

Basic Usage

use FrameFlow\Message;
use FrameFlow\Encoder;

// 1. Create a message with global metadata
$message = Message::make();
$message->header->meta->add('Environment', 'Production');

// 2. Add frames (can be simple strings or Frame objects)
$message->add("This is the first part of my data.");
$message->add("And here is more content...");

$id = uniqid();
$frame = new Message\Frame($message->header, $id, 'notification', new Message\Meta([
    "Content-Type" => "text/html; charset=utf-8",
    "Action" => "ShowAlert",
]));
$frame->payload = "<div>At least an HTML content</div>";
$message->add($frame);

// 3. Encode to streamable string
echo Encoder::encode($message);

Output

--- FrameFlow-1.0 ---
Trace-Id: 019d7423-cb85-714c-8f49-a58077393a47
Timestamp: 2026-04-09T21:26:36+00:00
Charset: utf-8
Version: 1
Checksum: sha256
Environment: Production
---

--- Frame ---
Id: 69d8198c287f2
Payload-Length: 34
Checksum: b6ed69fd1e91020ca3e251f91d8bdc07e60c5f8426aba34b06a502e5bfe13ae1
Payload:
This is the first part of my data.
---

--- Frame ---
Id: 69d8198c28805
Payload-Length: 27
Checksum: 3aabc50a531c0c9251c8419ce676c953395fd576ed6b9720503232a14198d6ad
Payload:
And here is more content...
---

--- Frame ---
Id: 69d8198c28808
Content-Type: text/html; charset=utf-8
Action: ShowAlert
Payload-Length: 35
Checksum: d32792d07b545c96fdefa95cd014ba79f4f4617131d0f9d632ad8d144754ca86
Payload:
<div>At least an HTML content</div>
---

Advanced Concepts

Property Hooks & Metadata

FrameFlow uses PHP 8.4 property hooks. This means size and checksum are calculated on-the-fly only when needed, ensuring your data is always consistent without manual updates.

$frame = $message->get($id);
echo $frame->size;     // Returns byte length
echo $frame->checksum; // Returns current hash of payload

Metadata Escaping

FrameFlow automatically handles multi-line metadata by escaping line breaks (\n, \r) during encoding. This ensures the protocol structure remains intact even with complex meta-information.

Specification Highlights

1. Delimiters: Blocks are separated by ---.
2. Metadata: Key-Value pairs followed by a colon and a space.
3. Payloads: Prefixed by Payload-Length to allow safe binary data transmission.
4. IDs: Every frame has an ID. If not provided, FrameFlow generates sequential IDs for you.

License

The MIT License (MIT). Please see License File for more information.

Roadmap

The vision for FrameFlow is to provide a seamless, transparent way to stream data and metadata. Below is our strategic path forward:

Phase 1: Core & PHP Ecosystem (Current)

• Base data structures (Message, Frame, Meta)
• RFC 9562 compliant UUIDv7 integration (Zero-Dependency)
• PHP 8.4 high-performance Encoder
• Next: High-performance PHP Decoder (Streaming Parser)
• Comprehensive PHPUnit test suite (Aiming for 100% code coverage)
• Static analysis integration (PHPStan/Psalm)

Phase 2: Cross-Language Support

• JavaScript/TypeScript Client: A browser-compatible decoder for fetch() and WebStreams API.
• Cross-Platform Specs: Formalization of the FrameFlow specification for third-party implementations.
• Go/Rust Ports: High-performance implementations for microservice environments.

Phase 3: Advanced Features

• Binary Frames: Optimized handling for raw binary data to minimize encoding overhead.
• Compression: Optional frame-level compression (e.g., zstd, gzip).
• Encryption: Native support for AEAD (Authenticated Encryption with Associated Data) at the frame level.

Built with ☕ and ❤️ for the modern PHP ecosystem.