SpiceDB PHP

https://github.com/linkorb/spicedb-php
Admin
SpiceDB PHP is a PHP client library for the Authzed SpiceDB permissions database, used to write...
Tokens:81,226
Snippets:504
Trust Score:7.5
Update:3 days ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/linkorb/spicedb-php/blob/main/README.md

Install the spicedb-php package using Composer.

```shell
composer require linkorb/spicedb-php
```

--------------------------------

### expandPermission() usage example

Source: https://github.com/linkorb/spicedb-php

Shows how to call expandPermission to retrieve the expansion tree. The example accesses leaf subjects from the tree root.

```php
use LinkORB\Authzed\Dto\Consistency;
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\Request\PermissionExpand as PermissionExpandRequest;

$result = $client->expandPermission(new PermissionExpandRequest(
    new Consistency(true),
    new ObjectReference('blog/post', 'mypost'),
    'writer'
));

$leafSubjects = $result->getTreeRoot()->getLeaf()->getSubjects();
```

--------------------------------

### Run tests with PHP on host

Source: https://github.com/linkorb/spicedb-php/blob/main/README.md

Run the integration tests using PHPUnit with PHP installed on the host.

```shell
phpunit -c ./phpunit.xml --testsuite 'Integration' ./tests/
```

--------------------------------

### SpiceDB constructor example with serializer wiring

Source: https://github.com/linkorb/spicedb-php

Example of constructing SpiceDB with a Symfony Serializer configured with ArrayDenormalizer, UnwrappingDenormalizer, ObjectNormalizer, JsonEncoder, and JsonLinesDecoder. UnwrappingDenormalizer is required for nested error envelopes; JsonLinesDecoder is required for jsonl streaming methods.

```php
<?php

use LinkORB\Authzed\Serializer\JsonLinesDecoder;
use LinkORB\Authzed\SpiceDB;
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
use Symfony\Component\Serializer\Encoder\JsonEncoder;
use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Normalizer\UnwrappingDenormalizer;
use Symfony\Component\Serializer\Serializer;

$client = new SpiceDB(
    new Serializer(
        [new ArrayDenormalizer(), new UnwrappingDenormalizer(), new ObjectNormalizer(null, null, null, new ReflectionExtractor())],
        [new JsonEncoder(), new JsonLinesDecoder()]
    ),
    HttpClient::create(),
    getenv('SPICEDB_HOST'),
    getenv('SPICEDB_API_KEY')
);
```

--------------------------------

### showResourcesPermission() usage example

Source: https://github.com/linkorb/spicedb-php

Shows how to call showResourcesPermission with a consistency token from a write response. Iterates over returned items, printing resource object IDs when no error is present.

```php
use LinkORB\Authzed\Dto\Consistency;
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\Request\LookupResource as LookupResourceRequest;
use LinkORB\Authzed\Dto\SubjectReference;

$items = $client->showResourcesPermission(new LookupResourceRequest(
    new Consistency(null, $writeResponse->getWrittenAt()),
    'blog/post',
    'writer',
    new SubjectReference(new ObjectReference('blog/user', 'john'))
));

foreach ($items as $item) {
    if ($item->getError() === null) {
        echo $item->getResult()->getResourceObjectId();
    }
}
```

--------------------------------

### Write schema request

Source: https://github.com/linkorb/spicedb-php/blob/main/README.md

Example of writing a schema using the writeSchema method with a Schema DTO.

```php
$client->writeSchema(new \LinkORB\Authzed\Dto\Request\Schema(
    'definition blog/post {
           relation reader: blog/user
           relation writer: blog/user
           permission read = reader + writer
           permission write = writer
    }
    
    definition blog/user {}'
));
```

--------------------------------

### Usage example for showSubjectsPermission()

Source: https://github.com/linkorb/spicedb-php

Shows how to call showSubjectsPermission() with a LookupSubjectRequest containing consistency, subject type, permission name, and resource. The returned array elements provide getResult() with lookedUpAt and subjectObjectId, and getError().

```php
use LinkORB\Authzed\Dto\Consistency;
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\Request\LookupSubject as LookupSubjectRequest;

$subjects = $client->showSubjectsPermission(new LookupSubjectRequest(
    new Consistency(null, $writeResponse->getWrittenAt()),
    'blog/user',
    'write',
    new ObjectReference('blog/post', 'mypost-to-show-subject')
));

echo $subjects[0]->getResult()->getSubjectObjectId();
```

--------------------------------

### checkPermission() usage example

Source: https://github.com/linkorb/spicedb-php

Shows how to call checkPermission with a fully consistent request, including caveat context. The response's getPermissionship() can be compared against PERMISSIONSHIP_HAS_PERMISSION to determine access.

```php
use LinkORB\Authzed\Dto\Consistency;
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\Request\PermissionCheck as PermissionCheckRequest;
use LinkORB\Authzed\Dto\Request\Schema as SchemaRequest;
use LinkORB\Authzed\Dto\SubjectReference;

$client->writeSchema(new SchemaRequest('...'));

$result = $client->checkPermission(new PermissionCheckRequest(
    new Consistency(null, null, null, true),                 // fully consistent
    new ObjectReference('blog/post', 'mypost'),
    'writer',
    new SubjectReference(new ObjectReference('blog/user', 'john')),
    ['second_parameter' => 'hello world']                    // caveat context
));

if ($result->getPermissionship() === PermissionCheckResponse::PERMISSIONSHIP_HAS_PERMISSION) {
    // allowed
}
```

--------------------------------

### Composer installation and autoload configuration for linkorb/spicedb-php

Source: https://github.com/linkorb/spicedb-php

Defines the required package version and PSR-4 autoload mapping for the LinkORB\Authzed namespace to the src/ directory. Use this in composer.json to install the library.

```json
{
  "require": { "linkorb/spicedb-php": "^2.0" },
  "autoload": { "psr-4": { "LinkORB\\Authzed\\": "src" } }
}
```

--------------------------------

### writeRelationship() usage example

Source: https://github.com/linkorb/spicedb-php

Creates a relationship between a blog post and a user with the 'writer' relation using OPERATION_CREATE. The returned ZedToken can be used with Consistency::atLeastAsFresh for read-after-write.

```php
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\Relationship;
use LinkORB\Authzed\Dto\RelationshipUpdate;
use LinkORB\Authzed\Dto\Request\RelationshipWrite as RelationshipWriteRequest;
use LinkORB\Authzed\Dto\SubjectReference;

$relationship = new Relationship(
    new ObjectReference('blog/post', 'mypost'),
    'writer',
    new SubjectReference(new ObjectReference('blog/user', 'john'))
);

$response = $client->writeRelationship(new RelationshipWriteRequest([
    new RelationshipUpdate(RelationshipUpdate::OPERATION_CREATE, $relationship)
]));

$writtenAt = $response->getWrittenAt(); // use in Consistency::atLeastAsFresh
```

--------------------------------

### readSchema() usage example

Source: https://github.com/linkorb/spicedb-php

Calls readSchema() on a client and prints the schema text. The returned schema string is whitespace-normalized by the server.

```php
$schema = $client->readSchema();
echo $schema->getSchemaText();
```

--------------------------------

### Consuming watch() stream

Source: https://github.com/linkorb/spicedb-php

Example of iterating over the watch() generator. Each yielded Watch object provides getResult() with updates and changesThrough, and getError() for partial errors. Empty chunks yield a keep-alive heartbeat with no updates.

```php
use LinkORB\Authzed\Dto\Request\Watch as WatchRequest;
use LinkORB\Authzed\Dto\RelationshipUpdate;

$watchRequest = new WatchRequest(['blog/post']);

foreach ($client->watch($watchRequest, 0.2) as $reply) {
    if ($reply->getError() !== null) {
        continue; // partial error line
    }
    foreach ($reply->getResult()->getUpdates() as $update) {
        echo $update->getOperation(); // OPERATION_CREATE / TOUCH / DELETE
        echo $update->getRelationship()->getRelation();
    }
    if ($reply->getResult()->getChangesThrough() !== null) {
        echo $reply->getResult()->getChangesThrough()->getToken();
    }
}
```

--------------------------------

### Inject ConnectorInterface into a service

Source: https://github.com/linkorb/spicedb-php

Shows a typical dependency injection of the ConnectorInterface into a service class. The constructor promotes the interface, and the example uses the checkPermission method with a PermissionCheckRequest to verify a user's permission on a post. The method returns a boolean based on the permissionship response.

```php
use LinkORB\Authzed\ConnectorInterface;

final class BlogService
{
    public function __construct(private ConnectorInterface $authzed) {}

    public function userCanWrite(string $userId, string $postId): bool
    {
        return $this->authzed->checkPermission(
            new PermissionCheckRequest(
                null,
                new ObjectReference('blog/post', $postId),
                'writer',
                new SubjectReference(new ObjectReference('blog/user', $userId))
            )
        )->getPermissionship() === PermissionCheckResponse::PERMISSIONSHIP_HAS_PERMISSION;
    }
}
```

--------------------------------

### readRelationship() usage example

Source: https://github.com/linkorb/spicedb-php

Reads relationships for a blog/post filter using a consistency token. After a delete, the server terminates the stream with an empty body, indicated by null relationship and error in the result.

```php
use LinkORB\Authzed\Dto\Consistency;
use LinkORB\Authzed\Dto\RelationshipFilter;
use LinkORB\Authzed\Dto\Request\RelationshipRead as RelationshipReadRequest;

$result = $client->readRelationship(new RelationshipReadRequest(
    new Consistency(null, $writtenAt),
    new RelationshipFilter('blog/post')
));

// After a delete, the server terminates the stream with an empty body:
if ($result[0]->getResult()->getRelationship() === null && $result[0]->getError() === null) {
    // end of stream — no more relationships match
}
```

--------------------------------

### deleteRelationship() usage example

Source: https://github.com/linkorb/spicedb-php

Deletes all relationships of a specific post by providing a RelationshipFilter with the resource type and ID. The response provides a deletedAt ZedToken.

```php
use LinkORB\Authzed\Dto\RelationshipFilter;
use LinkORB\Authzed\Dto\Request\RelationshipDeletion as RelationshipDeletionRequest;

$response = $client->deleteRelationship(new RelationshipDeletionRequest(
    new RelationshipFilter('blog/post', 'mypost') // delete all relationships of post "mypost"
));
```

--------------------------------

### Catching SpiceDBServerException

Source: https://github.com/linkorb/spicedb-php

Example of catching SpiceDBServerException when calling checkPermission. The exception's getCode() and getMessage() mirror the Error DTO's values, and getError() provides access to the full error details.

```php
use LinkORB\Authzed\Exception\SpiceDBServerException;
use LinkORB\Authzed\Dto\Request\PermissionCheck as PermissionCheckRequest;
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\SubjectReference;

try {
    $client->checkPermission(new PermissionCheckRequest(
        null,
        new ObjectReference('blog/post', 'mypost'),
        'writer',
        new SubjectReference(new ObjectReference('not-exist', 'john'))
    ));
} catch (SpiceDBServerException $e) {
    $error = $e->getError();
    echo $e->getCode();             // e.g. 3
    echo $e->getMessage();          // e.g. "...failed validation..."
    echo $error->getCode();         // same as $e->getCode()
    echo $error->getMessage();      // same as $e->getMessage()
    var_dump($error->getDetails());
}
```

--------------------------------

### Run tests with Docker

Source: https://github.com/linkorb/spicedb-php/blob/main/README.md

Run the test suite using Docker.

```shell
make run-test
```

--------------------------------

### Initializing a client with environment variables (README pattern)

Source: https://github.com/linkorb/spicedb-php

Constructs a SpiceDB client using the serializer, a default HTTP client, and the SPICEDB_HOST and SPICEDB_API_KEY environment variables.

```php
new SpiceDB($serializer, HttpClient::create(), getenv('SPICEDB_HOST'), getenv('SPICEDB_API_KEY'));
```

--------------------------------

### Initialize SpiceDB client with pure PHP

Source: https://github.com/linkorb/spicedb-php/blob/main/README.md

Instantiate a new SpiceDB client with required dependencies: symfony/serializer and symfony/http-client. Uses environment variables SPICEDB_HOST and SPICEDB_API_KEY.

```php
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
use Symfony\Component\Serializer\Encoder\JsonEncoder;
use LinkORB\Authzed\Serializer\JsonLinesDecoder;
use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
use Symfony\Component\Serializer\Normalizer\UnwrappingDenormalizer;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Serializer;

new SpiceDB(
    new Serializer(
        [new ArrayDenormalizer(), new UnwrappingDenormalizer(), new ObjectNormalizer(null, null, null, new ReflectionExtractor())],
        [new JsonEncoder(), new JsonLinesDecoder()]
    ),
    HttpClient::create(),
    getenv('SPICEDB_HOST'),
    getenv('SPICEDB_API_KEY')
);
```

--------------------------------

### expandPermission() method signature

Source: https://github.com/linkorb/spicedb-php

Declares the expandPermission method that POSTs to /v1/permissions/expand and returns a PermissionExpandResponse. Throws SpiceDBServerException on HTTP status >= 400.

```php
public function expandPermission(PermissionExpandRequest $request): PermissionExpandResponse
```

--------------------------------

### Constructor

Source: https://github.com/linkorb/spicedb-php

Constructs a new SpiceDB client instance with the required serializer, HTTP client, base URI, and API key. The client wraps the HTTP client with fixed per-request options including base URI, Accept header, Authorization header, and HTTP version.

```APIDOC
## Constructor

### Description
Constructs a new SpiceDB client instance.

### Method
Constructor

### Signature
```php
public function __construct(
    SerializerInterface $serializer,
    HttpClientInterface $httpClient,
    string $baseUri,
    string $apiKey
)
```

### Parameters
- **$serializer** (SerializerInterface) - Required - Serializer used to serialize request DTOs (format `json`) and deserialize response DTOs (formats `json` and `jsonl`). Must be configured with `JsonEncoder`, `JsonLinesDecoder` and normalizers.
- **$httpClient** (HttpClientInterface) - Required - Symfony HTTP client, typically `HttpClient::create()`.
- **$baseUri** (string) - Required - SpiceDB HTTP endpoint base URI, e.g. `https://grpc.authzed.com` or `http://localhost:8443`.
- **$apiKey** (string) - Required - Pre-shared key / API token sent as `Authorization: Bearer <key>`.

### Throws
Nothing at construction time.

### Request Example
```php
<?php

use LinkORB\Authzed\Serializer\JsonLinesDecoder;
use LinkORB\Authzed\SpiceDB;
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
use Symfony\Component\Serializer\Encoder\JsonEncoder;
use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
use Symfony\Component\Serializer\Normalizer\UnwrappingDenormalizer;
use Symfony\Component\Serializer\Serializer;

$client = new SpiceDB(
    new Serializer(
        [new ArrayDenormalizer(), new UnwrappingDenormalizer(), new ObjectNormalizer(null, null, null, new ReflectionExtractor())],
        [new JsonEncoder(), new JsonLinesDecoder()]
    ),
    HttpClient::create(),
    getenv('SPICEDB_HOST'),
    getenv('SPICEDB_API_KEY')
);
```
```

--------------------------------

### SpiceDB constructor with HTTP client options

Source: https://github.com/linkorb/spicedb-php

Wraps the raw HTTP client with fixed per-request options: base URI, Accept header, Bearer authorization, and HTTP/2.0. Every request is an HTTP/2 POST with a JSON body and Bearer header.

```php
$this->httpClient = $httpClient->withOptions(
    [
        'base_uri' => $baseUri,
        'headers' => [
            'Accept' => 'application/json',
            'Authorization' => 'Bearer ' . $apiKey,
        ],
        'http_version' => '2.0',
    ]
);
```

--------------------------------

### POST /v1/watch

Source: https://github.com/linkorb/spicedb-php

Starts a long-lived watch stream for relationship changes. The client method is SpiceDB::watch(). The request body is a serialized Dto\Request\Watch. The response is a stream of Watch objects, decoded from JSON chunks.

```APIDOC
## [POST] /v1/watch

### Description
Starts a long-lived watch stream for relationship changes. The client method is `SpiceDB::watch()`. The request body is a serialized `Dto\Request\Watch`. The response is a stream of `Watch` objects, decoded from JSON chunks.

### Method
POST

### Endpoint
/v1/watch

### Parameters
#### Request Body
- **optionalObjectTypes** (array of string) - Optional - Only watch these object types
- **optionalStartCursor** (Dto\ZedToken) - Optional - Resume from this cursor

### Response
#### Success Response (200)
- **result** (Dto\Response\WatchResponse) - `{updates: Dto\RelationshipUpdate[], changesThrough: Dto\ZedToken}`
- **error** (Dto\Response\Error) - Per-chunk error, if any

### Notes
- The response is a long-lived stream consumed via `httpClient->stream($response, $abortIdleTimeout)`.
- Each non-empty chunk is decoded as `json` into `Dto\Response\Watch`; each empty chunk (keep-alive) becomes `new WatchResponse(new WatchResponseResult())`.
- Successful stream yields `Watch` objects until the connection closes or until `$abortIdleTimeout` (seconds) elapses with no data — the resulting Symfony `TimeoutException` ends the generator silently (by design).
- `4xx` response: a `ClientException` is caught, the error body is decoded into `WatchResponse`, and `SpiceDBServerException` is thrown from the generator (e.g. `value does not match regex pattern` for an unknown type).
- Auth: same `Bearer <apiKey>` header as all other routes.
```

--------------------------------

### showResourcesPermission() method signature

Source: https://github.com/linkorb/spicedb-php

Declares the showResourcesPermission method that POSTs to /v1/permissions/resources and returns an array of LookupResourceResponse objects. Throws SpiceDBServerException on HTTP status >= 400.

```php
public function showResourcesPermission(LookupResourceRequest $request): array
```

--------------------------------

### expandPermission()

Source: https://github.com/linkorb/spicedb-php

Expands a permission tree to show all subjects and relationships that grant access. POSTs to /v1/permissions/expand and deserializes the response into a PermissionExpandResponse.

```APIDOC
## POST /v1/permissions/expand

### Description
Expands a permission tree to show all subjects and relationships that grant access.

### Method
POST

### Endpoint
/v1/permissions/expand

### Parameters
#### Request Body
- **$request** (LinkORB\Authzed\Dto\Request\PermissionExpand) - Required - Consistency, resource, permission name

### Response
#### Success Response (200)
- **PermissionExpandResponse** - `getExpandedAt(): ?ZedToken` and `getTreeRoot(): ?PermissionsRelationshipTree` (the expansion tree of intermediate/leaf subject sets).

### Request Example
```php
use LinkORB\Authzed\Dto\Consistency;
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\Request\PermissionExpand as PermissionExpandRequest;

$result = $client->expandPermission(new PermissionExpandRequest(
    new Consistency(true),
    new ObjectReference('blog/post', 'mypost'),
    'writer'
));

$leafSubjects = $result->getTreeRoot()->getLeaf()->getSubjects();
```

### Error Handling
Throws `SpiceDBServerException` when the HTTP status is `>= 400`.
```

--------------------------------

### SpiceDB::showResourcesPermission()

Source: https://github.com/linkorb/spicedb-php

Shows resources for a permission in SpiceDB. Accepts a Dto\Request\LookupResource object and returns an array of Dto\Response\LookupResource objects.

```APIDOC
## SpiceDB::showResourcesPermission()

### Description
Shows resources for a permission in SpiceDB.

### Method
showResourcesPermission

### Parameters
#### Request Body
- **Dto\Request\LookupResource** (object) - Required - The lookup resource request object.

### Response
#### Success Response
- **Dto\Response\LookupResource[]** - An array of lookup resource response objects.
```

--------------------------------

### showResourcesPermission()

Source: https://github.com/linkorb/spicedb-php

Lists all resources of a given type on which a subject has a specific permission. POSTs to /v1/permissions/resources and deserializes the JSON-lines response body into an array of LookupResourceResponse.

```APIDOC
## POST /v1/permissions/resources

### Description
Lists all resources of a given type on which a subject has a specific permission.

### Method
POST

### Endpoint
/v1/permissions/resources

### Parameters
#### Request Body
- **$request** (LinkORB\Authzed\Dto\Request\LookupResource) - Required - Consistency, resource object type, permission name, subject

### Response
#### Success Response (200)
- **array** of `LookupResourceResponse` - Each element wraps `getResult(): ?LookupResourceDto` (which carries `lookedUpAt` + `resourceObjectId`) and `getError(): ?Error`.

### Request Example
```php
use LinkORB\Authzed\Dto\Consistency;
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\Request\LookupResource as LookupResourceRequest;
use LinkORB\Authzed\Dto\SubjectReference;

$items = $client->showResourcesPermission(new LookupResourceRequest(
    new Consistency(null, $writeResponse->getWrittenAt()),
    'blog/post',
    'writer',
    new SubjectReference(new ObjectReference('blog/user', 'john'))
));

foreach ($items as $item) {
    if ($item->getError() === null) {
        echo $item->getResult()->getResourceObjectId();
    }
}
```

### Error Handling
Throws `SpiceDBServerException` when the HTTP status is `>= 400`.
```

--------------------------------

### SpiceDB::expandPermission()

Source: https://github.com/linkorb/spicedb-php

Expands a permission in SpiceDB. Accepts a Dto\Request\PermissionExpand object and returns a Dto\Response\PermissionExpand object.

```APIDOC
## SpiceDB::expandPermission()

### Description
Expands a permission in SpiceDB.

### Method
expandPermission

### Parameters
#### Request Body
- **Dto\Request\PermissionExpand** (object) - Required - The permission expand request object.

### Response
#### Success Response
- **Dto\Response\PermissionExpand** - The permission expand response object.
```

--------------------------------

### writeSchema() method signature

Source: https://github.com/linkorb/spicedb-php

Declares the public method signature for writing a schema. Takes a SchemaRequest object and returns void.

```php
public function writeSchema(SchemaRequest $request): void
```

--------------------------------

### writeSchema(SchemaRequest $request): void

Source: https://github.com/linkorb/spicedb-php

Writes a new schema to SpiceDB. Takes a SchemaRequest object and returns no value.

```APIDOC
## writeSchema(SchemaRequest $request): void

### Description
Writes a new schema to SpiceDB.

### Method
writeSchema

### Parameters
#### Request Body
- **$request** (SchemaRequest) - Required - The schema to write.

### Response
#### Success Response
No return value.
```

--------------------------------

### checkPermission() method signature

Source: https://github.com/linkorb/spicedb-php

Declares the checkPermission method that POSTs to /v1/permissions/check and returns a PermissionCheckResponse. Throws SpiceDBServerException on HTTP status >= 400.

```php
public function checkPermission(PermissionCheckRequest $request): PermissionCheckResponse
```

--------------------------------

### showSubjectsPermission() method signature

Source: https://github.com/linkorb/spicedb-php

Declares the public method that POSTs to /v1/permissions/subjects and deserializes the JSON-lines response into an array of LookupSubject DTOs. Throws SpiceDBServerException when the HTTP status is >= 400.

```php
public function showSubjectsPermission(LookupSubjectRequest $request): array
```

--------------------------------

### SpiceDB constructor signature

Source: https://github.com/linkorb/spicedb-php

Constructor signature for the SpiceDB client. Requires a serializer, HTTP client, base URI, and API key. Throws nothing at construction time.

```php
public function __construct(
    SerializerInterface $serializer,
    HttpClientInterface $httpClient,
    string $baseUri,
    string $apiKey
)
```

--------------------------------

### Environment variables declared in phpunit.xml.dist

Source: https://github.com/linkorb/spicedb-php

Declares SPICEDB_HOST and SPICEDB_API_KEY with force="true" for the test suite. Defaults are http://spicedb:8443 and somerandomkeyhere respectively.

```xml
<env name="SPICEDB_HOST" value="http://spicedb:8443" force="true" />
<env name="SPICEDB_API_KEY" value="somerandomkeyhere" force="true" />
```

--------------------------------

### SpiceDB::writeSchema()

Source: https://github.com/linkorb/spicedb-php

Writes a schema to SpiceDB. Accepts a Dto\Request\Schema object and returns void.

```APIDOC
## SpiceDB::writeSchema()

### Description
Writes a schema to SpiceDB.

### Method
writeSchema

### Parameters
#### Request Body
- **Dto\Request\Schema** (object) - Required - The schema request object.

### Response
#### Success Response
- **void** - No return value.
```

--------------------------------

### POST /v1/permissions/expand

Source: https://github.com/linkorb/spicedb-php

Expands the permission tree for a given resource and permission. The request body contains the resource and permission details.

```APIDOC
## [POST] /v1/permissions/expand

### Description
Expands the permission tree for a given resource and permission. The request body contains the resource and permission details.

### Method
POST

### Endpoint
/v1/permissions/expand

### Parameters
#### Request Body
- **resource** (object) - Required - The resource to expand.
- **permission** (string) - Required - The permission to expand.

### Response
#### Success Response (2xx/3xx)
- **tree** (object) - The expanded permission tree.

```

--------------------------------

### expandPermission(PermissionExpandRequest $request): PermissionExpandResponse

Source: https://github.com/linkorb/spicedb-php

Expands a permission tree for a given permission. This method corresponds to the POST /v1/permissions/expand endpoint.

```APIDOC
## expandPermission(PermissionExpandRequest $request): PermissionExpandResponse

### Description
Expands a permission tree for a given permission. This method corresponds to the POST /v1/permissions/expand endpoint.

### Method
POST

### Endpoint
/v1/permissions/expand

### Parameters
#### Request Body
- **$request** (LinkORB\Authzed\Dto\Request\PermissionExpand) - Required - Expansion query.

### Response
#### Success Response (200)
- **PermissionExpand** (LinkORB\Authzed\Dto\Response\PermissionExpand) - The expanded permission tree.
```

--------------------------------

### expandPermission(PermissionExpandRequest $request): PermissionExpandResponse

Source: https://github.com/linkorb/spicedb-php

Expands a permission to show the full set of subjects and relationships that grant it. Returns a PermissionExpandResponse.

```APIDOC
## expandPermission(PermissionExpandRequest $request): PermissionExpandResponse

### Description
Expands a permission to show the full set of subjects and relationships that grant it.

### Method
expandPermission

### Parameters
#### Request Body
- **$request** (PermissionExpandRequest) - Required - The permission expansion request.

### Response
#### Success Response
- **PermissionExpandResponse** - The expanded permission tree.
```

--------------------------------

### writeSchema()

Source: https://github.com/linkorb/spicedb-php

Writes a new schema to SpiceDB. It serializes the request to JSON and POSTs it to /v1/schema/write, returning nothing on success.

```APIDOC
## writeSchema()

### Description
Writes a new schema to SpiceDB. It serializes the request to JSON and POSTs it to `/v1/schema/write`, returning nothing on success.

### Method
POST

### Endpoint
`/v1/schema/write`

### Parameters
#### Request Body
- **$request** (SchemaRequest) - Required - The schema text to install.

### Response
#### Success Response
- **void** - No return value on success.

### Request Example
```json
{
  "schema": "definition blog/post { relation reader: blog/user relation writer: blog/user permission read = reader + writer permission write = writer } definition blog/user {}"
}
```
```

--------------------------------

### Relationship

Source: https://github.com/linkorb/spicedb-php

A single relationship tuple.

```APIDOC
## Relationship

### Description
A single relationship tuple.

### Constructor
```php
public function __construct(
    ObjectReference $resource = null,
    string $relation = null,
    SubjectReference $subject = null
)
```

### Properties
| Property | Getter / Setter | Type | Required | Description |
|----------|-----------------|------|----------|-------------|
| `resource` | `getResource(): ?ObjectReference` / `setResource(?ObjectReference): self` | `ObjectReference` | no | The resource side of the tuple |
| `relation` | `getRelation(): ?string` / `setRelation(?string): self` | `string` | no | Relation name |
| `subject` | `getSubject(): ?SubjectReference` / `setSubject(?SubjectReference): self` | `SubjectReference` | no | The subject side of the tuple |
```

--------------------------------

### POST /v1/permissions/resources

Source: https://github.com/linkorb/spicedb-php

Shows resources for a permission. The request body is a `Dto\Request\LookupResource` object and the response is decoded as JSONL into an array of `Dto\Response\LookupResource` objects.

```APIDOC
## POST /v1/permissions/resources

### Description
Shows resources for a permission.

### Method
POST

### Endpoint
/v1/permissions/resources

### Parameters
#### Request Body
- **Dto\Request\LookupResource** (object) - Required - The lookup resource request.

### Response
#### Success Response (200)
- **Dto\Response\LookupResource[]** (array) - List of resources.
```

--------------------------------

### SpiceDB::showSubjectsPermission()

Source: https://github.com/linkorb/spicedb-php

Shows subjects for a permission in SpiceDB. Accepts a Dto\Request\LookupSubject object and returns an array of Dto\Response\LookupSubject objects.

```APIDOC
## SpiceDB::showSubjectsPermission()

### Description
Shows subjects for a permission in SpiceDB.

### Method
showSubjectsPermission

### Parameters
#### Request Body
- **Dto\Request\LookupSubject** (object) - Required - The lookup subject request object.

### Response
#### Success Response
- **Dto\Response\LookupSubject[]** - An array of lookup subject response objects.
```

--------------------------------

### LookupResource constructor

Source: https://github.com/linkorb/spicedb-php

Constructor for the LookupResource request DTO, representing the JSON body of SpiceDB::showResourcesPermission() (POST /v1/permissions/resources). All parameters are optional and default to null.

```php
public function __construct(
    Consistency $consistency = null,
    string $resourceObjectType = null,
    string $permission = null,
    SubjectReference $subject = null
)
```

--------------------------------

### PermissionUpdate constants and constructor

Source: https://github.com/linkorb/spicedb-php

Defines the PERMISSIONSHIP_* constants and constructor for PermissionUpdate, which describes a permission change from the watch-resources stream. All properties are optional.

```php
public const PERMISSIONSHIP_UNSPECIFIED = 'PERMISSIONSHIP_UNSPECIFIED';
public const PERMISSIONSHIP_NO_PERMISSION = 'PERMISSIONSHIP_NO_PERMISSION';
public const PERMISSIONSHIP_HAS_PERMISSION = 'PERMISSIONSHIP_HAS_PERMISSION';
public const PERMISSIONSHIP_CONDITIONAL_PERMISSION = 'PERMISSIONSHIP_CONDITIONAL_PERMISSION';

public function __construct(
    SubjectReference $subject = null,
    ObjectReference $resource = null,
    string $relation = null,
    string $updatedPermission = null
)
```

--------------------------------

### readSchema() method signature

Source: https://github.com/linkorb/spicedb-php

Declares the public method signature for reading the current schema. Takes no arguments and returns a SchemaResponse object.

```php
public function readSchema(): SchemaResponse
```

--------------------------------

### checkPermission()

Source: https://github.com/linkorb/spicedb-php

Checks whether a subject has a specific permission on a resource. POSTs to /v1/permissions/check and deserializes the response into a PermissionCheckResponse.

```APIDOC
## POST /v1/permissions/check

### Description
Checks whether a subject has a specific permission on a resource.

### Method
POST

### Endpoint
/v1/permissions/check

### Parameters
#### Request Body
- **$request** (LinkORB\Authzed\Dto\Request\PermissionCheck) - Required - Consistency, resource, permission name, subject, and optional caveat context map

### Response
#### Success Response (200)
- **PermissionCheckResponse** - Exposes `getCheckedAt(): ?ZedToken`, `getPermissionship(): ?string` (one of the `PERMISSIONSHIP_*` constants) and `getPartialCaveatInfo(): ?array` (map of missing caveat context fields).

### Request Example
```php
use LinkORB\Authzed\Dto\Consistency;
use LinkORB\Authzed\Dto\ObjectReference;
use LinkORB\Authzed\Dto\Request\PermissionCheck as PermissionCheckRequest;
use LinkORB\Authzed\Dto\Request\Schema as SchemaRequest;
use LinkORB\Authzed\Dto\SubjectReference;

$client->writeSchema(new SchemaRequest('...'));

$result = $client->checkPermission(new PermissionCheckRequest(
    new Consistency(null, null, null, true),                 // fully consistent
    new ObjectReference('blog/post', 'mypost'),
    'writer',
    new SubjectReference(new ObjectReference('blog/user', 'john')),
    ['second_parameter' => 'hello world']                    // caveat context
));

if ($result->getPermissionship() === PermissionCheckResponse::PERMISSIONSHIP_HAS_PERMISSION) {
    // allowed
}
```

### Error Handling
Throws `SpiceDBServerException` when the HTTP status is `>= 400` (e.g. subject/resource type fails schema validation; message contains `failed validation`).
```

--------------------------------

### writeRelationship() method signature

Source: https://github.com/linkorb/spicedb-php

Signature for writing relationships. POSTs to /v1/relationships/write and returns a RelationshipWriteResponse. Throws SpiceDBServerException on HTTP status >= 400.

```php
public function writeRelationship(RelationshipWriteRequest $request): RelationshipWriteResponse
```

--------------------------------

### POST /v1/permissions/expand

Source: https://github.com/linkorb/spicedb-php

Expands a permission tree for a given resource and permission. This endpoint returns the computed permission tree along with the token at which it was computed.

```APIDOC
## POST /v1/permissions/expand

### Description
Expands a permission tree for a given resource and permission. This endpoint returns the computed permission tree along with the token at which it was computed.

### Method
POST

### Endpoint
/v1/permissions/expand

### Parameters
#### Request Body
- **consistency** (Dto\Consistency) - Optional - Read consistency
- **resource** (Dto\ObjectReference) - Required (per server validation) - {objectType, objectId}
- **permission** (string) - Required (per server validation) - Permission name

### Response
#### Success Response (200)
- **expandedAt** (Dto\ZedToken) - Token at which the tree was computed
- **treeRoot** (Dto\PermissionsRelationshipTree) - Root node: intermediate (Dto\AlgebraicSubjectSet) or leaf (Dto\DirectSubjectSet), plus expandedObject/expandedRelation

### Status Codes
- `< 400` success
- `>= 400` → SpiceDBServerException
```

--------------------------------

### watch()

Source: https://github.com/linkorb/spicedb-php

Streams relationship updates from the SpiceDB Watch API. It POSTs to /v1/watch and yields Watch objects, handling timeouts and server errors.

```APIDOC
## [POST] /v1/watch

### Description
Streams relationship updates from the SpiceDB Watch API. It POSTs to /v1/watch and yields Watch objects, handling timeouts and server errors.

### Method
POST

### Endpoint
/v1/watch

### Parameters
#### Request Body
- **$request** (LinkORB\Authzed\Dto\Request\Watch) - Required - Optional object types filter and optional start cursor (ZedToken)
- **$abortIdleTimeout** (float) - Required - Idle timeout in seconds; when the stream produces no data for this long, the generator exits via the TimeoutException catch

### Response
#### Success Response (200)
- **Watch** (LinkORB\Authzed\Dto\Response\Watch) - Yields Watch objects with getResult() and getError()

### Request Example
```php
use LinkORB\Authzed\Dto\Request\Watch as WatchRequest;
use LinkORB\Authzed\Dto\RelationshipUpdate;

$watchRequest = new WatchRequest(['blog/post']);

foreach ($client->watch($watchRequest, 0.2) as $reply) {
    if ($reply->getError() !== null) {
        continue; // partial error line
    }
    foreach ($reply->getResult()->getUpdates() as $update) {
        echo $update->getOperation(); // OPERATION_CREATE / TOUCH / DELETE
        echo $update->getRelationship()->getRelation();
    }
    if ($reply->getResult()->getChangesThrough() !== null) {
        echo $reply->getResult()->getChangesThrough()->getToken();
    }
}
```

### Error Handling Example
```php
use LinkORB\Authzed\Exception\SpiceDBServerException;

try {
    iterator_to_array($client->watch(new WatchRequest(['not-found-error']), 0.1));
} catch (SpiceDBServerException $e) {
    echo $e->getError()->getCode();    // e.g. 3
    echo $e->getError()->getMessage(); // e.g. "value does not match regex pattern"
}
```
```

--------------------------------

### Consistency

Source: https://github.com/linkorb/spicedb-php

Selects the consistency model for a read request. It is a one-of style structure: only one strategy should be populated per request.

```APIDOC
## Consistency

### Description
Selects the consistency model for a read request. It is a one-of style structure: only one strategy should be populated per request.

### Constructor
```php
public function __construct(
    bool $minimizeLatency = null,
    ZedToken $atLeastAsFresh = null,
    ZedToken $atExactSnapshot = null,
    bool $fullyConsistent = null
)
```

### Properties
- `minimizeLatency` (bool) - Optional - Prefer lowest-latency (possibly stale) result
- `atLeastAsFresh` (ZedToken) - Optional - Read at least as fresh as the given token (read-after-write)
- `atExactSnapshot` (ZedToken) - Optional - Read at the exact snapshot identified by the token
- `fullyConsistent` (bool) - Optional - Fully consistent read

### Methods
- `isMinimizeLatency(): ?bool` - Getter for `minimizeLatency`
- `setMinimizeLatency(?bool): self` - Setter for `minimizeLatency`
- `getAtLeastAsFresh(): ?ZedToken` - Getter for `atLeastAsFresh`
- `setAtLeastAsFresh(?ZedToken): self` - Setter for `atLeastAsFresh`
- `getAtExactSnapshot(): ?ZedToken` - Getter for `atExactSnapshot`
- `setAtExactSnapshot(?ZedToken): self` - Setter for `atExactSnapshot`
- `isFullyConsistent(): ?bool` - Getter for `fullyConsistent`
- `setFullyConsistent(?bool): self` - Setter for `fullyConsistent`
```

--------------------------------

### SpiceDB::checkPermission()

Source: https://github.com/linkorb/spicedb-php

Checks a permission in SpiceDB. Accepts a Dto\Request\PermissionCheck object and returns a Dto\Response\PermissionCheck object.

```APIDOC
## SpiceDB::checkPermission()

### Description
Checks a permission in SpiceDB.

### Method
checkPermission

### Parameters
#### Request Body
- **Dto\Request\PermissionCheck** (object) - Required - The permission check request object.

### Response
#### Success Response
- **Dto\Response\PermissionCheck** - The permission check response object.
```

--------------------------------

### LookupResource::__construct

Source: https://github.com/linkorb/spicedb-php

Creates a LookupResource DTO representing one JSON-lines entry of SpiceDB::showResourcesPermission().

```APIDOC
## LookupResource::__construct

### Description
Creates a LookupResource DTO representing one JSON-lines entry of SpiceDB::showResourcesPermission().

### Method
Constructor

### Signature
```php
public function __construct(LookupResourceDto $result = null, Error $error = null)
```

### Parameters
- **result** (LookupResourceDto) - Optional - The found resource (`lookedUpAt`, `resourceObjectId`)
- **error** (Error) - Optional - Per-line error, if any

### Properties
- **result** (LinkORB\Authzed\Dto\LookupResource) - Optional - The found resource (`lookedUpAt`, `resourceObjectId`). Getter: `getResult(): ?LookupResourceDto`, Setter: `setResult(?LookupResourceDto): self`
- **error** (Error) - Optional - Per-line error, if any. Getter: `getError(): ?Error`, Setter: `setError(?Error): self`
```

--------------------------------

### showResourcesPermission(LookupResourceRequest $request): array

Source: https://github.com/linkorb/spicedb-php

Looks up all resources on which a subject has a given permission. Returns an array of LookupResourceResponse objects.

```APIDOC
## showResourcesPermission(LookupResourceRequest $request): array

### Description
Looks up all resources on which a subject has a given permission.

### Method
showResourcesPermission

### Parameters
#### Request Body
- **$request** (LookupResourceRequest) - Required - The lookup resource request.

### Response
#### Success Response
- **LookupResourceResponse[]** - Array of resources with the permission.
```

--------------------------------

### writeSchema(SchemaRequest $request): void

Source: https://github.com/linkorb/spicedb-php

Writes a schema to the Authzed service. This method corresponds to the POST /v1/schema/write endpoint.

```APIDOC
## writeSchema(SchemaRequest $request): void

### Description
Writes a schema to the Authzed service. This method corresponds to the POST /v1/schema/write endpoint.

### Method
POST

### Endpoint
/v1/schema/write

### Parameters
#### Request Body
- **$request** (LinkORB\Authzed\Dto\Request\Schema) - Required - Schema text to write.

### Response
#### Success Response (200)
No return value.
```

--------------------------------

### watch() method signature

Source: https://github.com/linkorb/spicedb-php

Signature of the watch() method that POSTs to /v1/watch and streams the response. The $abortIdleTimeout parameter controls the idle timeout in seconds; when the stream produces no data for this long, the generator exits via a TimeoutException catch.

```php
public function watch(WatchRequest $request, float $abortIdleTimeout): Generator
```

--------------------------------

### showResourcesPermission(LookupResourceRequest $request): array

Source: https://github.com/linkorb/spicedb-php

Looks up resources that a subject can access for a given permission. This method corresponds to the POST /v1/permissions/resources endpoint.

```APIDOC
## showResourcesPermission(LookupResourceRequest $request): array

### Description
Looks up resources that a subject can access for a given permission. This method corresponds to the POST /v1/permissions/resources endpoint.

### Method
POST

### Endpoint
/v1/permissions/resources

### Parameters
#### Request Body
- **$request** (LinkORB\Authzed\Dto\Request\LookupResource) - Required - Lookup-resources query.

### Response
#### Success Response (200)
- **array** (LinkORB\Authzed\Dto\Response\LookupResource[]) - List of resources the subject can access.
```

--------------------------------

### POST /v1/permissions/resources

Source: https://github.com/linkorb/spicedb-php

Looks up resources for a given subject and permission. This endpoint returns a stream of matching resource IDs along with per-line errors if any.

```APIDOC
## POST /v1/permissions/resources

### Description
Looks up resources for a given subject and permission. This endpoint returns a stream of matching resource IDs along with per-line errors if any.

### Method
POST

### Endpoint
/v1/permissions/resources

### Parameters
#### Request Body
- **consistency** (Dto\Consistency) - Optional - Read consistency
- **resourceObjectType** (string) - Required (per server validation) - e.g. blog/post
- **permission** (string) - Required (per server validation) - Permission name
- **subject** (Dto\SubjectReference) - Required (per server validation) - {object, optionalRelation}

### Response
#### Success Response (200)
- **result** (Dto\LookupResource) - {lookedUpAt: Dto\ZedToken, resourceObjectId: string}
- **error** (Dto\Response\Error) - Per-line error, if any

### Status Codes
- `< 400` success
- `>= 400` → SpiceDBServerException
```

--------------------------------

### Handling per-record errors in showResourcesPermission

Source: https://github.com/linkorb/spicedb-php

Iterate over results from showResourcesPermission() and check each item's getError() for record-level failures. A null error means success; non-null indicates a failure to inspect. This pattern applies to showSubjectsPermission(), readRelationship(), and watch() as well.

```php
foreach ($client->showResourcesPermission($request) as $item) {
    if ($item->getError() !== null) {
        echo $item->getError()->getMessage();
        continue;
    }
    echo $item->getResult()->getResourceObjectId();
}
```

--------------------------------

### Architecture module graph for LinkORB\Authzed namespace

Source: https://github.com/linkorb/spicedb-php

Shows the layered structure of the library: the SpiceDB client, ConnectorInterface, exception, serializer, and DTO value objects. Useful for understanding the code organization.

```text
LinkORB\Authzed
├── SpiceDB                       (class)  — the client, implements ConnectorInterface
├── ConnectorInterface            (interface) — the 10-method contract
├── Exception\SpiceDBServerException  — single custom exception, wraps Dto\Response\Error
├── Serializer\JsonLinesDecoder    — jsonl encoder, powers streamed responses
└── Dto                           — pure value objects (no logic)
    ├── (core 16)                — AlgebraicSubjectSet, Consistency, DirectSubjectSet,
    │                              LookupResource, LookupSubject, ObjectReference,
    │                              PermissionUpdate, PermissionsRelationshipTree,
    │                              Precondition, Relationship, RelationshipFilter,
    │                              RelationshipUpdate, SubjectFilter,
    │                              SubjectFilterRelationFilter, SubjectReference, ZedToken
    ├── Request (11)             — one class per client-call body
    └── Response (14)            — one class (or envelope) per reply
```
Tokens:
Raw