Download the PHP package fahara02/udb-laravel without Composer

UDB Laravel SDK

UDB :: Universal Data Broker
_{gRPC data plane | native control plane | tenant/project scope guard
crate v0.5.21 | protocol v1.0.0}

Laravel client for UDB, a service that lets your app read and write data through one broker instead of connecting directly to every database or storage backend.

Install this package when a Laravel app needs to call a running UDB broker. It gives you a Laravel ServiceProvider, a Udb facade, generated PHP protobuf classes, request middleware, and clear exceptions for gRPC errors.

What is UDB?

UDB stands for Universal Data Broker. Think of it as a data API that sits between your Laravel app and the systems where the data actually lives.

A Laravel app sends a request such as "select patients", "upsert this invoice", or "delete this object". UDB decides where that data lives, applies the broker rules, talks to the right backend, and returns a typed response.

That means the Laravel app does not need to know whether the data is in Postgres, MySQL, SQLite, MongoDB, S3, Redis, Qdrant, or another supported backend. The app only needs the UDB endpoint and the request it wants to send.

What This Package Does

This package makes UDB feel natural inside Laravel:

• composer require fahara02/udb-laravel:^0.5.21
• set UDB_ENDPOINT in .env
• call Udb::select(), Udb::upsert(), or Udb::delete()
• use typed generated PHP classes for requests and responses
• let middleware attach tenant, user, and correlation context automatically
• catch Laravel-friendly exceptions instead of handling raw gRPC status arrays everywhere

Requirements

• PHP 8.1+
• grpc PECL extension — pecl install grpc then add extension=grpc.so to php.ini. The generated stubs extend \Grpc\BaseStub; there is no fallback transport.
• Laravel 10, 11, or 12 (Illuminate Container + HTTP + Routing)
• A running UDB broker reachable from the app

Installation

The service provider is auto-discovered by Laravel. The Udb facade is registered automatically. By default, the package also adds middleware to the web and api route groups so each request can carry tenant and user context into UDB.

The package also installs a version-matched CLI launcher at vendor/bin/udb. Use it from your Laravel project when you need UDB's shared annotation protos:

After that, your app-owned .proto files can import:

Run vendor/bin/udb proto fmt after export or schema edits to keep long UDB field annotations on one line for easier review.

Publish the config file when you need to override defaults:

This drops a documented config/udb.php into your app.

Configuration

For local development, the only required value is usually:

For production, you will normally set TLS, service identity, project, and timeout values too:

The full reference lives in config/udb.php.

UDB_ENDPOINT accepts either a host:port value or a Unix-domain-socket target (unix:///var/run/udb.sock) for a co-located broker sidecar — see Performance below.

Performance

PHP-FPM is shared-nothing: it tears down the worker after every request, so a normal PHP UDB client opens a new gRPC channel per request and re-pays the TCP + TLS + HTTP/2 handshake every time (grpc#15426). That re-handshake is the dominant PHP latency against a gRPC broker.

The fix is to hold a warm channel in a persistent-worker runtime (OpenSwoole / RoadRunner / FrankenPHP) that builds the client once and reuses it across requests, and/or to run a local UDB sidecar reached over a Unix domain socket. See:

• Guide: docs/php-perf.md — why PHP-FPM can't pool a channel, per-runtime setup recipes, keepalive args, and the local sidecar / UDS pattern (incl. the required broker-side UDS bind, a maintainer follow-up).
• Runnable example: examples/persistent-worker/ — a worker that constructs the client once and serves requests on the warm channel (OpenSwoole + RoadRunner + a plain-CLI fallback).

Worker keepalive env (set these for a persistent-worker deployment so the warm channel isn't dropped to IDLE and re-handshaked):

Usage

Read Data

If the call happens during an HTTP request, the middleware will try to attach the current tenant, user, and correlation ID automatically.

Write Data

upsert() returns a MutationResponse.

Delete Data

delete() also returns a MutationResponse.

Idempotency Replay And Read-Your-Writes

A keyed replay-safe mutation the broker deduplicated reports was_duplicate; the write receipt on the response fences a follow-up read (full contract: docs/native-services.md).

Retry contract: a replay-safe mutation is retried on transient errors only when the request carries a non-empty idempotency key — keyless mutations fail closed rather than risk a double apply.

Queue Jobs And Scheduled Commands

Jobs, commands, and schedulers do not have an HTTP request, so pass metadata explicitly:

Storage (upload & download)

The framework-agnostic UdbProject exposes a storage() facade over the generated StorageService. Build it with createUdb() (or UdbProject::connect()), then use the convenience wrappers:

Download — happy path (presigned URL). downloadFile() emits exactly one GetDownloadUrl RPC and returns the typed GetDownloadUrlResponse; the bytes never transit the broker. Hand the URL to the client / browser:

Download — streaming fallback (new in 0.3.6). When the client cannot reach the object store over HTTP (no egress, corporate proxy), pull the raw bytes through the broker with the server-streaming DownloadFile RPC. downloadFileBytes() opens one server-stream and reassembles each DownloadFileChunk.data run in order:

For RPCs without a wrapper, reach the generated stub via $storage->client(). A runnable end-to-end upload-then-download script lives at examples/storage-download.php.

Raw gRPC Stub

For broker RPCs that do not have a convenience method yet, use the generated gRPC stub:

Platform Services (Vault, Metering, Scheduler, …)

Vault, Metering, Scheduler, Search, Webhook, Workflow, Lock, LiveQuery, Config, Backup, and Embedding have no convenience wrappers yet — reach their buf-generated stubs through the generated client's per-service accessors (VaultServiceStub(), MeteringServiceStub(), …), which share one channel, metadata, and TLS configuration:

The per-RPC retry class and idempotency contract are listed in docs/generated/udb-native-contract.json.

Error handling

Per-request context

The shipped UdbContextMiddleware resolves three values from each incoming HTTP request and binds them to the singleton client so subsequent RPC calls inherit them:

Override the resolvers by binding the same container keys in your AppServiceProvider:

Testing

The SDK ships with Pest tests + an Orchestra Testbench base class. For your own app's tests, swap the UdbClient binding for a fake:

Run the SDK's own tests:

Versioning & compatibility

This SDK follows the UDB wire-protocol version — see UDB_PROTOCOL_VERSION in the parent sdk/ directory. Major SDK versions track major broker versions; minor SDK versions add convenience methods and Laravel-idiomatic helpers.

The current wire protocol is 1.0.0.

License

MIT © fahara02