llms.txt

# OpenFGA PHP SDK - LLM Knowledge Base

This document contains comprehensive information about the OpenFGA PHP SDK for AI assistants and language models. It includes complete guides, API documentation references, and examples to help implement fine-grained authorization in PHP applications.

**Repository:** https://github.com/evansims/openfga-php  
**Documentation Wiki:** https://github.com/evansims/openfga-php/wiki  
**OpenFGA Documentation:** https://openfga.dev/docs  

## Key Information for AI Assistants

- **Language:** PHP 8.3+
- **Package Name:** `evansims/openfga-php`
- **Installation:** `composer require evansims/openfga-php`
- **Purpose:** Fine-grained authorization and relationship-based access control
- **Architecture:** Result pattern for error handling, PSR-7/17/18 HTTP standards
- **Testing:** `composer test` (unit, integration, contract tests)
- **Documentation Generation:** `composer docs:api`

## Complete Guides and Documentation


### SDK Overview and Quick Start

<div align="center">
  <p><a href="https://openfga.dev"><img src="https://raw.githubusercontent.com/evansims/openfga-php/main/.github/openfga.png" width="100" /></a></p>

  <h1>OpenFGA PHP SDK</h1>

  <p>Stop writing authorization logic. Start asking questions.</p>

  <p><code>composer require evansims/openfga-php</code></p>
</div>

<p><br /></p>

##### Getting Started

Build your authorization integration

- [Introduction](https://github.com/evansims/openfga-php/wiki/Introduction)<br />
  Start here to get your first authorization check working.
- [Installation](https://github.com/evansims/openfga-php/wiki/Installation)<br />
  Install the SDK and set up required dependencies for your environment.
- [Authentication](https://github.com/evansims/openfga-php/wiki/Authentication)<br />
  Set up authentication for production environments and managed services.

##### Essentials

Learn the core concepts and patterns

- [Stores](https://github.com/evansims/openfga-php/wiki/Stores)<br />
  Manage authorization stores for multi-tenant applications and environment separation.
- [Authorization Models](https://github.com/evansims/openfga-php/wiki/Models)<br />
  Learn how to define your permission rules using OpenFGA's intuitive DSL.
- [Relationship Tuples](https://github.com/evansims/openfga-php/wiki/Tuples)<br />
  Understand how to grant and revoke specific permissions between users and resources.
- [Permission Queries](https://github.com/evansims/openfga-php/wiki/Queries)<br />
  Master the four types of queries: check permissions, list objects, find users, and expand relationships.
- [Assertions](https://github.com/evansims/openfga-php/wiki/Assertions)<br />
  Define test cases to verify your authorization model.

##### Features

Explore advanced features and patterns

- [Helper Functions](https://github.com/evansims/openfga-php/wiki/Helpers)<br />
  Simplify your code with convenient helper functions for common authorization operations.
- [Concurrency](https://github.com/evansims/openfga-php/wiki/Concurrency)<br />
  Leveraging the SDK's powerful concurrency features to improve performance when working with large-scale authorization operations.
- [Exceptions](https://github.com/evansims/openfga-php/wiki/Exceptions)<br />
  Handling errors and exceptions in your authorization system.
- [Integration](https://github.com/evansims/openfga-php/wiki/Integration)<br />
  Integrating OpenFGA with your existing systems and frameworks.
- [Observability](https://github.com/evansims/openfga-php/wiki/Observability)<br />
  Essential tracing and metrics to monitor your authorization system, including advanced event-driven telemetry and custom monitoring patterns.
- [Results](https://github.com/evansims/openfga-php/wiki/Results)<br />
  Building robust applications with proper response handling using the SDK's Result pattern.


## API Reference Documentation

Complete API documentation is available in the GitHub wiki. Here's the organized structure with direct links:

### Core Classes

- [Main OpenFGA client with all operations](https://github.com/evansims/openfga-php/wiki/API-Client)
- [Client interface definition](https://github.com/evansims/openfga-php/wiki/API-ClientInterface)
- [DSL to authorization model transformer](https://github.com/evansims/openfga-php/wiki/API-Transformer)
- [Transformer interface](https://github.com/evansims/openfga-php/wiki/API-TransformerInterface)
- [Internationalization messages](https://github.com/evansims/openfga-php/wiki/API-Messages)

### Authentication

- [Base authentication interface](https://github.com/evansims/openfga-php/wiki/API-Authentication-AuthenticationInterface)
- [Pre-shared key authentication](https://github.com/evansims/openfga-php/wiki/API-Authentication-TokenAuthentication)
- [OAuth 2.0 client credentials](https://github.com/evansims/openfga-php/wiki/API-Authentication-ClientCredentialAuthentication)
- [OAuth access token management](https://github.com/evansims/openfga-php/wiki/API-Authentication-AccessToken)
- [Access token interface](https://github.com/evansims/openfga-php/wiki/API-Authentication-AccessTokenInterface)

### Models and Data Structures

- [Store model for data isolation](https://github.com/evansims/openfga-php/wiki/API-Models-Store)
- [Store interface](https://github.com/evansims/openfga-php/wiki/API-Models-StoreInterface)
- [Authorization model with type definitions](https://github.com/evansims/openfga-php/wiki/API-Models-AuthorizationModel)
- [Authorization model interface](https://github.com/evansims/openfga-php/wiki/API-Models-AuthorizationModelInterface)
- [Relationship tuple key (user, relation, object)](https://github.com/evansims/openfga-php/wiki/API-Models-TupleKey)
- [Tuple key interface](https://github.com/evansims/openfga-php/wiki/API-Models-TupleKeyInterface)
- [Complete relationship tuple with metadata](https://github.com/evansims/openfga-php/wiki/API-Models-Tuple)
- [Tuple interface](https://github.com/evansims/openfga-php/wiki/API-Models-TupleInterface)
- [Type definition with relations](https://github.com/evansims/openfga-php/wiki/API-Models-TypeDefinition)
- [Type definition interface](https://github.com/evansims/openfga-php/wiki/API-Models-TypeDefinitionInterface)
- [Conditional authorization logic](https://github.com/evansims/openfga-php/wiki/API-Models-Condition)
- [Condition interface](https://github.com/evansims/openfga-php/wiki/API-Models-ConditionInterface)

### Collections

- [Collection of tuple keys](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-TupleKeys)
- [Tuple keys collection interface](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-TupleKeysInterface)
- [Collection of tuples](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-Tuples)
- [Tuples collection interface](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-TuplesInterface)
- [Collection of type definitions](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-TypeDefinitions)
- [Type definitions collection interface](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-TypeDefinitionsInterface)
- [Batch check items collection](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-BatchCheckItems)
- [Batch check items interface](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-BatchCheckItemsInterface)
- [Collection of stores](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-Stores)
- [Stores collection interface](https://github.com/evansims/openfga-php/wiki/API-Models-Collections-StoresInterface)

### Enumerations

- [Consistency levels for queries](https://github.com/evansims/openfga-php/wiki/API-Models-Enums-Consistency)
- [Authorization model schema versions](https://github.com/evansims/openfga-php/wiki/API-Models-Enums-SchemaVersion)
- [Tuple write operations (write/delete)](https://github.com/evansims/openfga-php/wiki/API-Models-Enums-TupleOperation)
- [Built-in type names](https://github.com/evansims/openfga-php/wiki/API-Models-Enums-TypeName)

### Requests and Responses

- [Authorization check request](https://github.com/evansims/openfga-php/wiki/API-Requests-CheckRequest)
- [Check request interface](https://github.com/evansims/openfga-php/wiki/API-Requests-CheckRequestInterface)
- [Batch authorization check request](https://github.com/evansims/openfga-php/wiki/API-Requests-BatchCheckRequest)
- [Batch check request interface](https://github.com/evansims/openfga-php/wiki/API-Requests-BatchCheckRequestInterface)
- [Write/delete tuples request](https://github.com/evansims/openfga-php/wiki/API-Requests-WriteTuplesRequest)
- [Write tuples request interface](https://github.com/evansims/openfga-php/wiki/API-Requests-WriteTuplesRequestInterface)
- [Read tuples request](https://github.com/evansims/openfga-php/wiki/API-Requests-ReadTuplesRequest)
- [Read tuples request interface](https://github.com/evansims/openfga-php/wiki/API-Requests-ReadTuplesRequestInterface)
- [Authorization check response](https://github.com/evansims/openfga-php/wiki/API-Responses-CheckResponse)
- [Check response interface](https://github.com/evansims/openfga-php/wiki/API-Responses-CheckResponseInterface)
- [Batch check response](https://github.com/evansims/openfga-php/wiki/API-Responses-BatchCheckResponse)
- [Batch check response interface](https://github.com/evansims/openfga-php/wiki/API-Responses-BatchCheckResponseInterface)

### Results and Error Handling

- [Success result wrapper](https://github.com/evansims/openfga-php/wiki/API-Results-Success)
- [Success interface](https://github.com/evansims/openfga-php/wiki/API-Results-SuccessInterface)
- [Failure result wrapper](https://github.com/evansims/openfga-php/wiki/API-Results-Failure)
- [Failure interface](https://github.com/evansims/openfga-php/wiki/API-Results-FailureInterface)
- [Base result interface](https://github.com/evansims/openfga-php/wiki/API-Results-ResultInterface)

### Exceptions

- [Base client exception](https://github.com/evansims/openfga-php/wiki/API-Exceptions-ClientException)
- [Client throwable interface](https://github.com/evansims/openfga-php/wiki/API-Exceptions-ClientThrowable)
- [Authentication errors](https://github.com/evansims/openfga-php/wiki/API-Exceptions-AuthenticationException)
- [Configuration errors](https://github.com/evansims/openfga-php/wiki/API-Exceptions-ConfigurationException)
- [Network and HTTP errors](https://github.com/evansims/openfga-php/wiki/API-Exceptions-NetworkException)
- [Serialization errors](https://github.com/evansims/openfga-php/wiki/API-Exceptions-SerializationException)

### Network and Infrastructure

- [HTTP request management](https://github.com/evansims/openfga-php/wiki/API-Network-RequestManager)
- [Request manager interface](https://github.com/evansims/openfga-php/wiki/API-Network-RequestManagerInterface)
- [Retry logic with exponential backoff](https://github.com/evansims/openfga-php/wiki/API-Network-RetryHandler)
- [Retry handler interface](https://github.com/evansims/openfga-php/wiki/API-Network-RetryHandlerInterface)
- [Circuit breaker for fault tolerance](https://github.com/evansims/openfga-php/wiki/API-Network-CircuitBreaker)
- [Circuit breaker interface](https://github.com/evansims/openfga-php/wiki/API-Network-CircuitBreakerInterface)
- [Request context and metadata](https://github.com/evansims/openfga-php/wiki/API-Network-RequestContext)
- [Request context interface](https://github.com/evansims/openfga-php/wiki/API-Network-RequestContextInterface)

### Observability and Monitoring

- [Telemetry provider interface](https://github.com/evansims/openfga-php/wiki/API-Observability-TelemetryInterface)
- [OpenTelemetry integration](https://github.com/evansims/openfga-php/wiki/API-Observability-OpenTelemetryProvider)
- [No-op telemetry provider](https://github.com/evansims/openfga-php/wiki/API-Observability-NoOpTelemetryProvider)
- [Telemetry provider factory](https://github.com/evansims/openfga-php/wiki/API-Observability-TelemetryFactory)

### Schema Validation

- [JSON schema definitions](https://github.com/evansims/openfga-php/wiki/API-Schemas-Schema)
- [Schema interface](https://github.com/evansims/openfga-php/wiki/API-Schemas-SchemaInterface)
- [Schema validation logic](https://github.com/evansims/openfga-php/wiki/API-Schemas-SchemaValidator)
- [Schema validator interface](https://github.com/evansims/openfga-php/wiki/API-Schemas-SchemaValidatorInterface)
- [Schema builder for dynamic schemas](https://github.com/evansims/openfga-php/wiki/API-Schemas-SchemaBuilder)
- [Schema builder interface](https://github.com/evansims/openfga-php/wiki/API-Schemas-SchemaBuilderInterface)

### Translation and Internationalization

- [Message translation service](https://github.com/evansims/openfga-php/wiki/API-Translation-Translator)
- [Translator interface](https://github.com/evansims/openfga-php/wiki/API-Translation-TranslatorInterface)
- [YAML parser for translation files](https://github.com/evansims/openfga-php/wiki/API-Translation-YamlParser)

### Framework Integration

- [Laravel service provider](https://github.com/evansims/openfga-php/wiki/API-Integration-ServiceProvider)

## Quick Reference for AI Assistants

### Common Usage Patterns

#### Basic Authorization Check
```php
use OpenFGA\Client;
use OpenFGA\Models\TupleKey;

$client = new Client(url: 'https://api.fga.example');

$result = $client->check(
    store: 'store_123',
    model: 'model_456',
    tupleKey: new TupleKey('user:alice', 'viewer', 'document:readme')
);

if ($result->success()) {
    $allowed = $result->value()->getAllowed();
}
```

#### Batch Authorization Checks
```php
use OpenFGA\Models\Collections\BatchCheckItems;
use OpenFGA\Models\BatchCheckItem;

$checks = new BatchCheckItems([
    new BatchCheckItem(
        tupleKey: new TupleKey('user:alice', 'viewer', 'document:budget'),
        correlationId: 'check-1'
    ),
    new BatchCheckItem(
        tupleKey: new TupleKey('user:bob', 'editor', 'document:budget'),
        correlationId: 'check-2'
    ),
]);

$result = $client->batchCheck(
    store: 'store_123',
    model: 'model_456',
    checks: $checks
);
```

#### DSL Authorization Model
```php
$dsl = '
    model
      schema 1.1

    type user

    type document
      relations
        define owner: [user]
        define editor: [user] or owner
        define viewer: [user] or editor
';

$model = $client->dsl($dsl)->unwrap();
```

#### Writing Relationship Tuples
```php
use OpenFGA\Models\Collections\TupleKeys;

$writes = new TupleKeys([
    new TupleKey('user:alice', 'owner', 'document:budget'),
    new TupleKey('user:bob', 'viewer', 'document:budget'),
]);

$result = $client->writeTuples(
    store: 'store_123',
    model: 'model_456',
    writes: $writes
);
```

#### List Objects a User Can Access
```php
$result = $client->listObjects(
    store: 'store_123',
    model: 'model_456',
    type: 'document',
    relation: 'viewer',
    user: 'user:alice'
);

if ($result->success()) {
    $documents = $result->value()->getObjects();
}
```

### Result Pattern Usage

The SDK uses the Result pattern instead of exceptions for expected failures:

```php
// Handle results with method chaining
$documents = $client->listObjects(...)
    ->success(fn($response) => echo "Found objects!")
    ->failure(fn($error) => echo "Error: " . $error->getMessage())
    ->unwrap(); // Gets value or throws exception

// Handle results with conditionals
$result = $client->check(...);
if ($result->success()) {
    $allowed = $result->value()->getAllowed();
} else {
    $error = $result->error();
    // Handle error
}
```

### Authentication Configuration

#### Pre-shared Key
```php
use OpenFGA\Authentication\TokenAuthentication;

$auth = new TokenAuthentication('your-api-key');
$client = new Client(
    url: 'https://api.fga.example',
    authentication: $auth
);
```

#### OAuth 2.0 Client Credentials
```php
use OpenFGA\Authentication\ClientCredentialAuthentication;

$auth = new ClientCredentialAuthentication(
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    tokenUrl: 'https://auth.fga.example/oauth/token'
);
$client = new Client(
    url: 'https://api.fga.example',
    authentication: $auth
);
```

### Common Commands

- **Install:** `composer require evansims/openfga-php`
- **Run Tests:** `composer test`
- **Generate API Docs:** `composer docs:api`
- **Generate LLMs.txt:** `composer docs:llms`
- **Lint Code:** `composer lint`

### Framework Integration

#### Laravel Service Provider
```php
// In config/app.php
'providers' => [
    OpenFGA\Integration\ServiceProvider::class,
],
```

The service provider registers the OpenFGA client in the container and provides configuration through Laravel's config system.

### Key Architecture Concepts

1. **Result Pattern:** All operations return Success/Failure objects instead of throwing exceptions
2. **Interface-First Design:** Every class implements an interface for testing and flexibility
3. **Type Safety:** Full PHP 8.3+ type hints throughout
4. **PSR Compliance:** Uses PSR-7/17/18 for HTTP handling
5. **Immutable Models:** All data models are immutable value objects
6. **Collection Types:** Type-safe collections for working with multiple objects
7. **Schema Validation:** Built-in JSON schema validation for all API interactions