API Services TupleServiceInterface - evansims/openfga-php GitHub Wiki

Service interface for managing OpenFGA relationship tuples. This service provides business-focused operations for working with relationship tuples, which represent the core relationships in your authorization model. Tuples define who has what relationship to which objects, forming the foundation of your permission system. ## Core Operations The service supports tuple management with enhanced functionality: - Write tuples with validation and duplicate filtering - Read tuples with flexible filtering and pagination - Delete tuples safely with existence checking - Track tuple changes over time for auditing ## Batch Operations For high-throughput scenarios, the service provides: - Batch writes for multiple tuples in a single operation - Transaction support for atomicity guarantees - Automatic chunking to respect API limits - Duplicate filtering to optimize performance ## Usage Example php $tupleService = new TupleService($tupleRepository); Write a single tuple $result = $tupleService->write( $store, 'user:anne', 'reader', 'document:budget-2024' ); Read tuples with filters $tuples = $tupleService->read( $store, user: 'user:anne', relation: 'reader' )->unwrap(); Write multiple tuples $batch = $tupleService->writeBatch($store, $tupleKeys)->unwrap();

OpenFGA\Services

View source code

• TupleService (implementation)

public function delete(
    StoreInterface|string $store,
    string $user,
    string $relation,
    string $object,
    bool $confirmExists = false,
): FailureInterface|SuccessInterface

Delete a single relationship tuple. Removes the specified relationship, with optional existence checking to provide better error messages when the tuple doesn't exist.

View source

FailureInterface | SuccessInterface — Success if deleted, or Failure with error details

public function deleteBatch(
    StoreInterface|string $store,
    TupleKeysInterface $tupleKeys,
    bool $transactional = true,
    bool $confirmExists = false,
): FailureInterface|SuccessInterface

Delete multiple relationship tuples in a batch operation. Efficiently removes multiple tuples, with automatic chunking and optional existence checking for better error reporting.

View source

FailureInterface | SuccessInterface — Success if all deleted, or Failure with error details

public function exists(
    StoreInterface|string $store,
    string $user,
    string $relation,
    string $object,
): FailureInterface|SuccessInterface

Check if a specific tuple exists in the store. Efficiently verifies tuple existence without retrieving all matching tuples. Useful for validation before operations or conditional logic.

View source

FailureInterface | SuccessInterface — Success with true/false, or Failure with error details

public function getStatistics(StoreInterface|string $store): FailureInterface|SuccessInterface

Get statistics about tuples in the store. Provides insights into the tuple distribution and counts by type and relation, useful for monitoring and capacity planning.

View source

FailureInterface | SuccessInterface — Success with statistics array, or Failure with error details

public function listChanges(
    StoreInterface|string $store,
    string|null $type = NULL,
    DateTimeImmutable|null $startTime = NULL,
    string|null $continuationToken = NULL,
    int|null $pageSize = NULL,
): FailureInterface|SuccessInterface

List changes to tuples over time for auditing purposes. Retrieves a chronological log of tuple changes (writes and deletes) within the specified time range, useful for compliance and debugging.

View source

FailureInterface | SuccessInterface — Success with changes collection, or Failure with error details

public function read(
    StoreInterface|string $store,
    TupleKeyInterface|null $tupleKey = NULL,
    string|null $continuationToken = NULL,
    int|null $pageSize = NULL,
    Consistency|null $consistency = NULL,
): FailureInterface|SuccessInterface

Read relationship tuples with optional filtering. Retrieves tuples matching the specified criteria, with automatic pagination handling for large result sets.

View source

FailureInterface | SuccessInterface — Success with tuples collection, or Failure with error details

public function write(
    StoreInterface|string $store,
    string $user,
    string $relation,
    string $object,
): FailureInterface|SuccessInterface

Write a single relationship tuple. Creates a relationship between a user and an object with the specified relation. This is the most common operation for establishing permissions.

View source

FailureInterface | SuccessInterface — Success if written, or Failure with error details

public function writeBatch(
    StoreInterface|string $store,
    AuthorizationModelInterface|string $model,
    TupleKeysInterface|null $writes = NULL,
    TupleKeysInterface|null $deletes = NULL,
    bool $transactional = true,
    int $maxParallelRequests = 1,
    int $maxTuplesPerChunk = 100,
    int $maxRetries = 0,
    float $retryDelaySeconds = 1.0,
    bool $stopOnFirstError = false,
): FailureInterface|SuccessInterface

Write multiple relationship tuples in a batch operation. Efficiently writes multiple tuples, with automatic chunking to respect API limits and optional duplicate filtering for performance optimization.

View source

FailureInterface | SuccessInterface — Success if all written, or Failure with error details