Imager Client

Клиентская библиотека микросервиса Imager для четырёх языков — Python, PHP, TypeScript и Go — с идентичным поведением на всех платформах. Строит пути и URL ассетов (превью, размеры, форматы, retina) и вызывает админ-методы генерации/удаления.

Для работы нужен настроенный и запущенный микросервис Imager.

Основной репозиторий: GitVerse · Зеркало: GitHub

Документация: RU / EN

• Python — пакет на PyPI
• PHP — пакет на Packagist
  • Twig — пакет на Packagist
• TypeScript (клиент + сервер) — пакет на npm
  • Vue — пакет на npm
  • React — пакет на npm
• Go — модуль на pkg.go.dev

Почему Imager Client

• Один API — четыре языка. Все реализации дают побайтово идентичный JSON-результат на едином наборе golden-тестов: можно строить URL на бэкенде (PHP, Python, Go, Node) и на фронтенде (TS) без расхождений.
• Zero-dependency. Ни одного внешнего пакета: только стандартная библиотека каждого языка (urllib, curl, fetch, net/http).
• Мгновенно. Клиентские методы — чистые функции конкатенации строк: без HTTP, без валидации, без исключений. Генерация миллиона ассетов — практически мгновенно.
• Безопасные секреты. В TypeScript админ-методы вынесены в отдельный серверный импорт imager-client/server: токен физически не может попасть в браузерный бандл.
• Гибкие параметры. Сегмент размера можно передавать строкой, объектом или массивом; dpr — числом или строкой; формат — одним или списком.

Установка

Фреймворк-компоненты

Тонкие обёртки над ядром для популярных фреймворков: вся логика (сегменты, dpr, форматы, srcset) — в ядре, компоненты нормализуют алиасы props (src→source, preset→segment, width/height→сегмент) и рендерят нативные узлы фреймворка.

Пакеты самодостаточны: ядро встроено в бандл, imager-client — опциональный peerDependency (нужен только для своего инстанса, например ImagerServer с админ-методами).

// React: глобальная инициализация
ImagerPlugin.install({ baseURL: "...", format: "webp", dpr: 2 });

<ImagerAssets src="/test.png" width={200} height={200} dpr={2} format="webp" alt="Фото" />

// Vue: глобальная инициализация через app.use
createApp(App).use(ImagerPlugin, { baseURL: "...", format: "webp", dpr: 2 }).mount("#app");

{# Twig: расширение с imager-сервисом #}
{{ imager_assets('/test.png', {preset: 'thumb', format: 'webp', alt: 'Фото'})|raw }}

Quick Start

Python

from imager import Imager

imager = Imager({"baseURL": "https://imgs.example.com/images/", "format": "webp"})

asset = imager.GetAsset("/test.gif", {"width": 200, "height": 200}, "gif", 2)
url = imager.GetAssetPath("/test.gif", "200x200", "webp")
# https://imgs.example.com/images/test-gif/200x200.webp

PHP

use imagerClient\Imager;

$imager = new Imager(["baseURL" => "https://imgs.example.com/images/", "format" => "webp"]);

$asset = $imager->GetAsset("/test.gif", ["width" => 200, "height" => 200], "gif", 2);
$url = $imager->GetAssetPath("/test.gif", "200x200", "webp");
// https://imgs.example.com/images/test-gif/200x200.webp

TypeScript

// Клиент (браузер) — без admin-методов и токена
import { Imager } from "imager-client";

const imager = new Imager({ baseURL: "https://imgs.example.com/images/", format: "webp" });
const asset = imager.GetAsset("/test.gif", { width: 200, height: 200 }, "gif", 2);
const url = imager.GetAssetPath("/test.gif", "200x200", "webp");
// https://imgs.example.com/images/test-gif/200x200.webp

// Сервер (Node) — только здесь доступны админ-методы
import { ImagerServer } from "imager-client/server";

const server = new ImagerServer({
    baseURL: "https://imgs.example.com/images/",
    token: "secret",
    adminURL: "https://imager.example.com",
});
await server.AdminGenerate("/test.gif", true);

Go

import imager "gitverse.ru/pkg-ru/imager-client/src/imager-go"

i := imager.New(imager.Options{
    BaseURL: "https://imgs.example.com/images/",
    Format:  "webp",
})

asset := i.GetAsset("/test.gif", imager.Size{Width: 200, Height: 200}, "gif", 2)
url := i.GetAssetPath("/test.gif", "200x200", "webp")
// https://imgs.example.com/images/test-gif/200x200.webp

Параметры методов

segment — четыре формы записи

"thumb"                       # строка как есть: именованный пресет
"200x200" | "200x" | "x200"   # строка-размер
{"width": 200, "height": 200} # объект; оба поля необязательны
[200, 200]                    # массив [width, height]; оба обязательны
— не задан                    # → "x"

format / formats — строка или список

"webp"                    # один формат
["webp", "gif"]           # список (для GetAssets)
— не задан                # → настройки imager (format / formats) → формат исходника

dpr — число или строка

2        # варианты без суффикса и @2
"3"      # строка-цифра: без суффикса, @2, @3
1        # один вариант с полем dpr: 1
0        # dpr не используется
> 3      # трактуется как 3
— не задан # → настройки imager (dpr)

Примеры разных вариантов вызова

imager.GetAsset("/test.gif")                       # минимальный: сегмент "x", формат исходника
imager.GetAsset("/test.gif", "thumb")              # именованный пресет
imager.GetAsset("/test.gif", {"width": 200})       # объект: только ширина → "200x"
imager.GetAsset("/test.gif", [200, 200])           # массив → "200x200"
imager.GetAsset("/test.gif", "200x200", "webp")    # + формат
imager.GetAsset("/test.gif", "200x200", "webp", 2) # + dpr (варианты без суффикса и @2)

imager.GetAssets("/test.gif", ["200x200", "x400"], ["webp", "gif"], "2")  # 4 ассета
imager.AdminGenerate("/test.gif", True)                   # по source
imager.AdminGenerate(asset)                               # по AssetType
imager.AdminDelete(["/path/a.webp", "/path/b.webp"])      # список готовых путей

Полное описание всех вариантов, структуры AssetType, MIME-таблица и правила формирования URL — в языковых доках: Python, PHP, TypeScript, Go.

Тесты

Единые golden-кейсы в test/fixture.json: все 4 языка дают побайтово идентичный JSON-результат для каждого кейса. Нормализация props фреймворк-компонентов — в test/fixture-components.json.

make test

или по языкам:

python test/test.py
php test/test.php
npm test
go run test/test.go

Фреймворк-пакеты:

make test-react test-vue test-twig

© 2025 Алтухов Владислав Владимирович