Download the PHP package wtsvk/evitadb-php-client without Composer

evitadb-php-client

PHP gRPC client for EvitaDB — generated stubs + a thin session-based wrapper for managing read/write sessions.

Installation

System requirements:

• PHP 8.5+
• ext-grpc (pecl install grpc)
• ext-protobuf (pecl install protobuf)

Usage

The client has two layers: EvitaDbConnection for server-level operations, and EvitaDbClient for catalog-scoped data access.

Quick start

Connection + catalog split

For Laravel apps, register singletons in your AppServiceProvider:

Transactions

All data access goes through writeTransaction() and readTransaction(). Each call opens one gRPC session for the duration of the callable, giving you a consistent snapshot for reads and one server-side transaction for writes.

getEntity() throws EvitaDbEntityNotFoundException if the entity is missing; use findEntity() if null is an acceptable outcome.

Rollback semantics

EvitaDB's gRPC Close() RPC has no rollback flag — calling it always commits. The PHP client therefore handles the two paths differently:

• Normal return: session is closed via Close() with the configured commit behavior (commits server-side).
• Exception inside the callable: the session is intentionally orphaned (no Close() is sent). The EvitaDB server's session timeout will discard the buffered transaction, giving you a deferred-but-real rollback. The exception propagates out of writeTransaction() unchanged.
• Deterministic rollback: pass dryRun: true — the server discards all changes on close regardless of outcome.

Commit behavior

Control how long the gRPC close call blocks before returning:

EntityFetch — control what content is returned

By default the server returns identity-only entities (no attributes, prices, or references). Pass an EntityFetch to ask for specific content. Pass EntityFetch::all() for everything.

QueryBuilder — filtering and ordering

Testing your application

The package ships with EvitaDbMockClient and MockEvitaDbConnection for unit-testing application code:

The mock auto-assigns primary keys for upsertEntity() (start with $client->nextPrimaryKey = 1000 to mimic existing data). Strict mode: any call without a matching stub throws — fail loud, not silent. See tests/Unit/Testing/EvitaDbMockClientTest.php for full API examples.

EvitaDB version compatibility

This package follows independent semver. The targeted EvitaDB version is recorded in composer.json extra.evitadb-version. Wrapper-only fixes/refactors bump the package version (patch or minor) without changing the EvitaDB target — they don't get a row here.

Each row in the matrix below marks the first package version that introduced support for the listed EvitaDB version. Every later package release until the next row keeps the same EvitaDB target.

For a specific EvitaDB version, pin the package version that matches (e.g. ^0.2 if you target EvitaDB 2026.1.8).

Architecture

• src/EvitaDbConnectionInterface.php / src/EvitaDbConnection.php — server-level operations (isHealthy, defineCatalog, getCatalogNames, deleteCatalog) and factory for catalog-scoped clients via catalog().
• src/EvitaDbClientInterface.php / src/EvitaDbClient.php — catalog-scoped gRPC client with a transaction-only public surface: writeTransaction() and readTransaction(). The catalog is bound at construction. Session management, commit behavior, and rollback-on-exception (session orphaning) are all handled internally.
• src/EntityFetch.php — mutable fluent builder for specifying what entity content to return (attributes, prices, references, etc.). Construct fresh per query.
• src/QueryBuilder.php — mutable fluent builder producing EvitaQL GrpcQueryRequest messages. Supports filtering, ordering, pagination, and custom EntityFetch.
• src/Transaction/ — ReadTransactionContext and WriteTransactionContext interfaces consumers receive inside readTransaction() / writeTransaction() callables. Concrete implementations: ReadOnlySessionScopedContext (read-only) and ReadWriteSessionScopedContext (read + write), both backed by one EvitaDB session and sharing read code via the SessionScopedReads trait.
• src/SessionCommitBehavior.php — enum controlling how long the close call blocks (WaitForConflictResolution, WaitForLogPersistence, WaitForChangesVisible).
• src/SortDirection.php — enum for query ordering (Asc, Desc).
• src/GrpcStatus.php — typed readonly value object wrapping the stdClass returned by gRPC wait(). Used by Connection, Client, and the session-scoped context implementations to render uniform error messages.
• src/Testing/ — EvitaDbMockClient, MockEvitaDbConnection, mock context classes (MockReadOnlySessionScopedContext, MockReadWriteSessionScopedContext), and supporting DTOs for unit-testing consumer applications without a live EvitaDB.
• src/Exception/ — custom exception hierarchy. The client throws on errors instead of logging — your app handles them.
• src/Protocol/ — auto-generated PHP classes from EvitaDB .proto definitions. Do not edit manually.
• proto/ — committed .proto source files synced from the EvitaDB Docker image.

Maintenance scripts

• scripts/sync-protos.sh — pulls .proto files from the pinned EvitaDB image and applies the PHP namespace patches. Run when bumping EvitaDB version.
• scripts/build-proto.sh — runs protoc + grpc_php_plugin to regenerate src/Protocol/* from proto/*.

GitHub Actions automates this via auto-update-evitadb.yml (daily cron) which detects new EvitaDB releases and opens a PR with regenerated stubs.

License

Apache 2.0. See LICENSE.

EvitaDB itself is licensed under the Business Source License 1.1, converting to Apache 2.0 on 2027-01-01. The .proto files in this package are interface definitions extracted from the EvitaDB JAR — derivative work that should be permissible under BSL's "make non-production use" + "modify" grants for an interop client. Consult EvitaDB's LICENSE for authoritative terms.