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.

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\.

Documentation

• Authentication
• Asset
• Shot
• Scene
• Task
• Project
• Person
• User
• Files
• Casting
• Edit
• Entity
• Studio
• Sync
• Playlist
• Concept
• Context

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