Download the PHP package wwwision/umadb-php without Composer

UmaDB PHP Extension

PHP bindings for UmaDB event store, built with Rust using ext-php-rs.

UmaDB is a specialist event store for Dynamic Consistency Boundaries (DCB), enabling flexible, query-driven append conditions for implementing business rules without hardcoded aggregate boundaries.

[!NOTE]
See wwwision/dcb-eventstore-umadb for a more convenient and typesafe API

Features

• ✨ Full DCB API - Complete implementation of the Dynamic Consistency Boundaries specification
• 🚀 High Performance - Rust-powered with zero-copy data handling
• 🔒 Type Safe - Leverages PHP 8.0+ type system
• 💪 Sync Client - Blocking operations suitable for traditional PHP applications
• 🎯 Simple API - Read, append, head operations with intuitive builder patterns
• 🔄 Idempotent Appends - UUID-based event deduplication
• 🏷️ Tag-based Filtering - Efficient event queries
• ⚡ Optimistic Concurrency - Position-based conflict detection
• 🧵 Thread Safe (ZTS) - Full support for FrankenPHP and multi-threaded environments

Requirements

• PHP 8.4 or higher
• UmaDB Server running and accessible
• Rust 1.70 or higher (only for building from source)

Installation

Option 1: PIE (Recommended)

Note: Requires Rust 1.70+ and PIE installed. See PIE.md for details.

Option 2: Pre-built Binaries

Download the pre-compiled extension for your platform from the latest release:

Linux (x86_64):

macOS (Intel):

macOS (Apple Silicon):

Verify checksum (optional but recommended):

Option 3: Building from Source

See INSTALL.md for detailed instructions.

Enable the Extension

After installation (any option), add to your php.ini:

Or for CLI only, use:

Verify installation:

Quick Start

API Reference

Client

Constructor

Parameters:

• $url - Server URL (e.g., http://localhost:50051 or https://server:50051)
• $ca_path - Optional path to CA certificate for TLS (self-signed certs)
• $batch_size - Optional batch size hint for reading events (default: server decides)
• $api_key - Optional API key for authentication

Note on Named Arguments: Parameter names use snake_case (not camelCase). When using named arguments, all preceding optional parameters must be provided explicitly (even as null) due to ext-php-rs limitations.

Examples:

read()

Reads events from the event store.

Parameters:

• $query - Optional query to filter events by type and tags
• $start - Starting position (inclusive if forward, exclusive if backward)
• $backwards - Read backwards from start position
• $limit - Maximum number of events to return
• $subscribe - Subscribe to new events (streaming mode)

Returns: Array of SequencedEvent objects

Examples:

append()

Appends events to the event store.

Parameters:

• $events - Array of Event objects to append
• $condition - Optional append condition for consistency enforcement

Returns: Position of the last appended event

Throws: IntegrityException if append condition fails

Examples:

head()

Returns the current head position of the event store, or null if empty.

Example:

Event

Represents an event in the event store.

Properties:

• string $event_type - Event type identifier (read-only)
• string $data - Binary event data (read-only)
• array $tags - Tags for filtering (read-only)
• ?string $uuid - Optional UUID for idempotency (read-only)

Example:

SequencedEvent

Represents an event with its position in the stream.

Properties:

• Event $event - The event object (read-only)
• int $position - Position in the stream (read-only)

Note: This class is returned by read() and cannot be instantiated directly.

Query

A query for filtering events. An event matches if it matches any query item (OR logic).

Parameters:

• $items - Array of QueryItem objects

Example:

QueryItem

A query item specifying event types and tags to match.

Matching Rules:

• Event type must be in $types (or $types is empty/null = match all types)
• All tags in $tags must be present in the event tags (AND logic)

Parameters:

• $types - Array of event type strings to match
• $tags - Array of tag strings that must all be present

Examples:

AppendCondition

Condition for conditional appends, enabling optimistic concurrency control and business rule enforcement.

Parameters:

• $fail_if_events_match - Query that must not match any existing events
• $after - Optional position constraint (fail if events exist after this position)

Examples:

Exception Classes

All exceptions extend PHP's base Exception class and are in the UmaDB\Exception namespace:

• UmaDB\Exception\IntegrityException - Append condition failed
• UmaDB\Exception\TransportException - gRPC/network errors
• UmaDB\Exception\CorruptionException - Data corruption detected
• UmaDB\Exception\IoException - I/O errors
• UmaDB\Exception\UmaDBException - Generic UmaDB error

Example:

Usage Examples

Idempotent Appends

Use UUIDs to make appends idempotent:

Prevent Duplicate Email Registration

Multi-step Workflow Coordination

Query Filtering

Development

Building

Testing

Running Examples

Start UmaDB server:

Run examples:

Architecture

This extension uses ext-php-rs to create Rust-powered PHP extensions with:

• Zero-copy data transfer where possible
• Type-safe FFI between PHP and Rust
• Automatic memory management via reference counting
• Native PHP exception handling
• Thread-safe design for ZTS and FrankenPHP compatibility

The extension wraps the umadb-client Rust crate, providing a synchronous client that internally manages a Tokio runtime for async gRPC operations.

FrankenPHP & Multi-Threading

The extension fully supports FrankenPHP and other multi-threaded PHP environments:

• Built with ZTS (Zend Thread Safety) support enabled
• Thread-safe initialization using Rust's std::sync::Once
• Each client instance is independent and thread-safe
• No global mutable state

When compiled against FrankenPHP's ZTS-enabled PHP, the extension automatically uses thread-safe code paths. No special configuration is needed.

Comparison with Python Bindings

Similar to the Python bindings (umadb package), this PHP extension:

• ✅ Exposes the same DCB API
• ✅ Uses synchronous client only (blocking operations)
• ✅ Pre-collects read results into arrays/lists
• ✅ Provides idiomatic language bindings

Differences:

• PHP extension is compiled and loaded as a native extension
• Python uses PyO3 and Maturin for packaging
• PHP has no async/await (yet), so sync-only is natural

License

Licensed under the MIT License. See LICENSE-MIT for details.

Contributing

Contributions are welcome! Please ensure:

1. Code is formatted: make fmt
2. Clippy passes: make clippy
3. Tests pass: make test and make test-rust
4. Examples run successfully

Links

• UmaDB Main Repository
• DCB Specification
• ext-php-rs Documentation