# PHP UDB SDK ACME Billing Example
Standalone PHP project using an arbitrary `acme.billing.v1` proto package.
This example does not require a UDB source checkout. It uses:
- the PHP SDK package from GitHub
- `buf` for generated project models
- UDB CLI from a GitHub Release, or the UDB broker/CLI image through local Docker Compose
## Project Files
| `proto/` | The ACME Billing proto used by both UDB and Buf |
| `gen/` | Generated PHP protobuf models |
| `db_ops/` | Generated by UDB CLI from `proto/`; committed so the example shows the migration output |
| `docker-compose.yml` | Local Postgres, Redis, Qdrant, MinIO, and UDB broker |
| `scripts/` | Project commands that call UDB as an external CLI/image |
| `acme_billing.php` | PHP SDK smoke client using generated `Product` |
## Generate
Use Docker for the UDB CLI:
```powershell
.\scripts\generate.ps1 -Runner docker
```
Or use a GitHub Release CLI binary:
```powershell
$env:UDB_RUNNER = "release"
.\scripts\generate.ps1
```
This runs `buf generate`, installs Composer dependencies, then asks UDB to
generate `db_ops/` from `proto/`. If no local UDB binary is configured, the
Docker runner downloads the latest GitHub Release CLI asset and executes it
inside Compose.
Before the first public UDB release exists, the default
`releases/latest/download/...` URL will 404. For local pre-release testing,
point the scripts at a binary you already built or downloaded:
```powershell
cargo build --release --bin udb-proto-parser
$env:UDB_CLI = "E:\Projects\udb\target\release\udb-proto-parser.exe"
.\scripts\generate.ps1 -Runner auto
```
For Docker-based pre-release testing, expose a real URL to the Linux binary with
`UDB_CLI_URL`. A Windows path cannot be executed inside the Linux Compose
container.
## Start Broker
```powershell
.\scripts\serve.ps1
.\scripts\bootstrap.ps1 -Runner docker
```
The compose stack provides Postgres, Redis, Qdrant, MinIO, and the UDB broker.
## Run Client
PHP needs the `grpc` extension enabled for live RPC calls.
```powershell
$env:UDB_TARGET = "127.0.0.1:50051"
php acme_billing.php
```
The client performs relational create/read/update/delete, vector upsert/search,
and object put/read/presign checks against the local broker.
Docker smoke runs PHP with prebuilt gRPC/protobuf extensions:
```powershell
docker compose --profile smoke run --rm --build smoke
```
For operation-level timings:
```powershell
docker compose --profile smoke run --rm --no-deps -e UDB_SHOW_TIMINGS=true smoke php84 acme_billing.php
```
Performance notes:
- Keep one `UdbClient` per long-lived worker/service container and call
`$client->warmup($metadata)` before user traffic when possible.
- The smoke script is correctness-heavy: it performs extra selects after writes
and touches Postgres, Qdrant, and MinIO. Application flows should avoid
verification reads they do not need.
- For local benchmarks, the compose broker sets `UDB_RATE_LIMIT_ENABLED=false`
to avoid measuring Redis rate-limit overhead. Leave rate limiting enabled in
production unless another gateway enforces it.
- Use batch or transaction RPCs for many records instead of issuing one PHP
process/RPC per row.
## Checks
```powershell
buf lint
composer validate --no-check-publish
php -l acme_billing.php
```