README

A PHP client library for the Kitsu / Zou production tracker API. Based on the gazu python library.

Requirements

PHP 8.1+
Guzzle HTTP 7.x (installed automatically via Composer)

Installation

composer require fuitad/gazelle

Quick Start

use Gazelle\Gazelle;

$gazelle = new Gazelle('https://your-kitsu-server.example.com/api');

// Authenticate
$gazelle->logIn('user@example.com', 'password');

// List all open projects
$projects = $gazelle->project->allOpenProjects();

// Get all shots for a project
$shots = $gazelle->shot->allShotsForProject($projects[0]);

// Log out
$gazelle->logOut();

Modules

Every module is accessible as a public property on the Gazelle instance.

Property	Description
`$gazelle->asset`	Assets, asset types, asset instances
`$gazelle->shot`	Shots, sequences, episodes
`$gazelle->scene`	Scenes, asset instances, camera instances
`$gazelle->task`	Tasks, task types, task statuses, comments
`$gazelle->project`	Projects, project settings, team management
`$gazelle->person`	People, departments, avatars
`$gazelle->user`	Current-user-scoped queries
`$gazelle->files`	Output files, working files, preview files, softwares
`$gazelle->casting`	Shot / asset / episode casting
`$gazelle->edit`	Edits
`$gazelle->entity`	Generic entities and entity types
`$gazelle->studio`	Studios
`$gazelle->sync`	Event feed, project export / import
`$gazelle->playlist`	Playlists
`$gazelle->concept`	Concepts
`$gazelle->context`	Admin/user-context-aware convenience wrappers

Model Parameters

All methods that accept a model (project, shot, asset, etc.) accept either:

A UUID string: '550e8400-e29b-41d4-a716-446655440000'
An associative array with at least an 'id' key: ['id' => '550e8400-...', 'name' => 'My Project']

This means you can pass model arrays directly from previous API calls.

Authentication

// Password login
$tokens = $gazelle->logIn('user@example.com', 'password');

// MFA (TOTP)
$tokens = $gazelle->logIn('user@example.com', 'password', totp: '123456');

// Use an existing token
$gazelle->setToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');

// Or with refresh token
$gazelle->setToken([
    'access_token'  => 'eyJ...',
    'refresh_token' => 'eyJ...',
]);

// Refresh the access token manually
$gazelle->refreshAccessToken();

// Log out
$gazelle->logOut();

See docs/authentication.md for the full reference.

Configuration

$gazelle = new Gazelle(
    host: 'https://kitsu.example.com/api',
    sslVerify: true,                          // Verify SSL certificates
    useRefreshToken: true,                    // Auto-refresh on token expiry
    callbackNotAuthenticated: function($client, $path) {
        // Called when a 401 is received.
        // Return true to retry the request, false to throw NotAuthenticatedException.
        return false;
    },
);

// Change host at runtime
$gazelle->setHost('https://other-kitsu.example.com/api');

// Check connectivity
$gazelle->hostIsUp();    // bool
$gazelle->hostIsValid(); // bool (checks /api endpoint responds)

Exceptions

All exceptions live under Gazelle\Exception\.

Exception	HTTP status	Meaning
`AuthFailedException`	—	Login credentials rejected
`NotAuthenticatedException`	401 / 422	Not authenticated
`NotAllowedException`	403	Insufficient permissions
`RouteNotFoundException`	404	Endpoint not found
`MethodNotAllowedException`	405	Wrong HTTP method
`ParameterException`	400	Bad request / missing field
`TooBigFileException`	413	Upload too large
`ServerErrorException`	500 / 502	Server-side error
`UploadFailedException`	—	File upload rejected
`DownloadFileException`	—	File download failed
`FileDoesntExistException`	—	Local file not found before upload
`TaskStatusNotFoundException`	—	Task status ID not in the server list
`TaskMustBeAnArrayException`	—	Task passed as string where array required

Documentation

Testing

composer install
./vendor/bin/phpunit

Related Projects

gazu — Official Python client (this library mirrors its API)
zou — The Kitsu back-end
Kitsu — The production tracker UI

License

MIT

fuitad / gazelle

Maintainers

Package info

Statistics

Security