momostafas/quotai-sdk

Official PHP client for the Quotai public translation API

dev-main 2026-06-01 01:09 UTC

Requires

• php: ^8.1
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Mohamed Mostafa

• i18n
• translations
• localization
• quotai

README

Official PHP client for the Quotai public translation API.

Pull translations at runtime, resolve individual keys with fallbacks, and push newly extracted strings back to your Quotai project.

Packagist: momostafas/quotai-sdk

Requirements

• PHP 8.1+
• Extensions: curl, json
• A Quotai project API key (qk_…) from quotai.net → Project → Settings → API Key

Install

composer require momostafas/quotai-sdk

Quick start

<?php

require 'vendor/autoload.php';

use Quotai\Environment;
use Quotai\QuotaiClient;

$quotai = new QuotaiClient([
    'apiKey' => getenv('QUOTAI_API_KEY') ?: '',
    'environment' => Environment::Production,
    'locale' => 'en',
]);

$info = $quotai->getProjectInfo();
echo $info['name'], PHP_EOL;

$title = $quotai->getString('home.hero.title', ['fallback' => 'Welcome']);

$messages = $quotai->getMessages(['locale' => 'en']);
// ['home.hero.title' => 'Welcome', ...] — flat map for Laravel, Symfony, etc.

Environment variable

Omit apiKey when QUOTAI_API_KEY is set in the environment:

$quotai = new QuotaiClient(['locale' => 'en']);

Configuration

Option	Description	Default
auth	AuthMode::Header (default) or AuthMode::None for reverse-proxy setups	Header
apiKey	Project API key (qk_…)	getenv('QUOTAI_API_KEY')
expectedProjectId	Validates key matches project; generic error on mismatch	—
environment	Environment::Production | Staging | Development	Production
baseUrl	Override API origin (wins over environment)	—
locale	Default locale for getString / getMessages	Project source language
branch	Branch id (branch_id query param)	Main branch
cacheTTL	In-memory cache TTL (ms); 0 disables	60000
timeout	Request timeout (ms)	15000
status	Filter by translation status (string or list)	—
tags	Filter by tags	—

Built-in base URLs

Environment	URL
Production	https://quotai.net
Staging	https://staging.quotai.net
Development	http://localhost:5001

API

getProjectInfo(): array

Returns project metadata (GET /api/public/project-info).

getMessages(array $options = []): array

Returns a flat key → string map for one locale.

$en = $quotai->getMessages(['locale' => 'en']);
$fr = $quotai->getMessages(['locale' => 'fr', 'branch' => 'branch_id_here']);

getString(string $key, array $options = []): string

Resolves a single key with caching and safe fallbacks.

$text = $quotai->getString('nav.home', [
    'locale' => 'de',
    'fallback' => 'Home',
]);

pushKeys(array $keys, ?string $branch = null): void

Creates new keys on your project (POST /api/public/keys). Existing keys on the same branch are skipped.

$quotai->pushKeys([
    [
        'key' => 'checkout.title',
        'defaultValue' => 'Checkout',
        'context' => 'Payment page heading',
    ],
    [
        'key' => 'checkout.submit',
        'defaultValue' => 'Pay now',
        'tags' => ['checkout'],
    ],
]);

clearCache(): void

Clears the in-memory translation cache.

Framework notes

• Laravel / Symfony: see examples/laravel.md
• Reverse proxy: see examples/reverse-proxy.md

CLI example

QUOTAI_API_KEY=qk_your_key php examples/script.php

Security

• Server-side only for production apps that use an API key (AuthMode::Header, default).
• Never expose qk_… keys or project ids in HTML, JavaScript, or public env vars visible to the browser.
• The SDK does not log secrets and does not put project_id in request URLs. Calling getProjectInfo() still returns project_id in the JSON response — avoid surfacing that to end users.
• Use expectedProjectId for build scripts and backend config validation; mismatch errors stay generic (no raw ids).
• For proxied setups, use AuthMode::None and inject X-API-Key in nginx/Apache/your app middleware.

Development

cd sdk-php
composer install
composer test

License

MIT