memran/marwa-envelop

Transport-agnostic message envelope with fluent builder for Kafka/WebSocket/etc.

v1.0.0 2025-08-08 10:15 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

README

Transport-agnostic, structured message wrapper for PHP — ideal for Kafka, WebSocket, MQTT, log pipelines, or chat protocols.

🚀 Features

• 📦 PSR-compliant and lazy-loaded
• 💬 Works with strings, arrays, files, and links
• 🔐 Optional HMAC signing with TTL expiry
• 🔁 Compress/gzip for efficient transport
• 🔗 Attachments and file linking
• 🧱 Chainable message builder syntax
• 🧪 Ready for WebSocket, Kafka, SQS, Laravel Queue, MQTT, etc.

📸 Screenshot

Message structure as decoded from Envelop JSON:

{
  "id": "2dd0faca-499a-42de-a274-a458b12dc1cf",
  "type": "chat.message",
  "sender": "user:123",
  "receiver": "user:456",
  "body": "Hello World!",
  "headers": {
    "x-room": "demo"
  },
  "signature": "..."
}

📦 Installation

composer require memran/marwa-envelop

🛠 Usage Example

✉️ Build and Send Message

use Marwa\Envelop\EnvelopBuilder;

$msg = EnvelopBuilder::start()
    ->type('chat.message')
    ->sender('user:123')
    ->receiver('user:456')
    ->header('x-room', 'demo')
    ->body('Hello world!')
    ->ttl(60)
    ->sign('super-secret-key')
    ->build();

// Send over Kafka, WebSocket, etc.
$wire = $msg->toJson();

📬 Decode and Read Message

use Marwa\Envelop\Envelop;

$received = Envelop::fromJson($wire);

if ($received->isExpired()) {
    throw new \Exception("Message expired");
}

if (!$received->checkSignature('super-secret-key')) {
    throw new \Exception("Invalid signature");
}

echo $received->body; // "Hello world!"

📁 Attach File

$msg = EnvelopBuilder::start()
    ->type('chat.file')
    ->sender('u:1')
    ->receiver('u:2')
    ->attach('/path/to/image.jpg')
    ->build();

🔗 Link to Remote File

$msg = EnvelopBuilder::start()
    ->type('file.link')
    ->sender('u:1')
    ->receiver('u:2')
    ->link('https://example.com/my.pdf', [
        'name' => 'My Document',
        'size' => '2MB'
    ])
    ->build();

🧩 Ideal Use Cases

• WhatsApp-style chat systems
• Kafka or MQTT message brokers
• WebSocket messaging with TTL
• Distributed logging pipelines
• Task queues with metadata (e.g. Laravel, Symfony)

🔖 Stable Releases

Version	Notes
v1.0.0	Initial stable release 🚀

📝 License

MIT © Mohammad Emran

🧠 Keywords

• kafka
• websocket
• envelope
• message structure
• event-driven
• php builder
• logging
• transport agnostic
• HMAC
• json message
• file attachment
• laravel queue