PHPackages joke-php/avatar - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. joke-php/avatar ActiveLibrary[Utility & Helpers](/categories/utility) joke-php/avatar =============== Module for the Joke framework for generating avatars based on nickname 1.3.4(1mo ago)00MITPHPPHP ^8.5 Since Jun 4Pushed 1mo agoCompare [ Source](https://github.com/joke-php/avatar)[ Packagist](https://packagist.org/packages/joke-php/avatar)[ RSS](/packages/joke-php-avatar/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)Dependencies (6)Versions (10)Used By (0) Joke Avatar =========== [](#joke-avatar) Библиотека для генерации квадратных PNG-аватаров на основе никнейма для PHP-фреймворка [Joke](https://github.com/joke-php/joke). Возможности ----------- [](#возможности) - Генерация квадратных PNG-аватаров на основе никнейма - 6 встроенных тем оформления: `default`, `dark`, `warm`, `nature`, `ocean`, `sunset` - Декоративные квадраты на аватаре (случайное количество, размер и цвет) - Отображение первых двух символов никнейма - Кэширование сгенерированных аватаров в `var/cache/avatars/` - Поддержка TrueType-шрифтов с автоматическим поиском системных шрифтов - Проверка доступной памяти перед генерацией больших изображений - PSR-4 автозагрузка, строгая типизация (`strict_types=1`), PER-CS3 Требования ---------- [](#требования) - PHP ^8.5 - PHP-расширение `ext-gd` - Фреймворк `joke-php/joke` ^1.3 Установка --------- [](#установка) ``` composer require joke-php/avatar ``` Использование ------------- [](#использование) ### 1. Регистрация сервис-провайдера [](#1-регистрация-сервис-провайдера) Добавьте `AvatarProvider` в файл `bootstrap/kernel.php`: ``` use Vasoft\JokeAvatar\AvatarProvider; $config->addProvider(AvatarProvider::class); ``` ### 2. Конфигурация (опционально) [](#2-конфигурация-опционально) Создайте файл `config/avatar.php` для настройки размера и тем: ``` use Vasoft\JokeAvatar\AvatarConfig; return [ AvatarConfig::class => static function () use ($env): AvatarConfig { return (new AvatarConfig()) ->setSize(200) ->setThemes([ 'default' => [ 'background_colors' => ['#3498db', '#2980b9', '#1abc9c', '#16a085'], 'text_color' => '#ffffff', 'decorative_colors' => ['#2ecc71', '#e74c3c', '#f39c12', '#9b59b6'], 'decorative_min' => 3, 'decorative_max' => 6, 'decorative_size_min' => 20, 'decorative_size_max' => 60, ], // ... другие темы ]); }, ]; ``` ### 3. Генерация аватара в контроллере [](#3-генерация-аватара-в-контроллере) ``` use Vasoft\JokeAvatar\AvatarGenerator; use Vasoft\JokeAvatar\Http\Response\ImageResponse; class AvatarController { public function __construct( private readonly AvatarGenerator $generator, ) {} public function __invoke(string $nickname): ImageResponse { $path = $this->generator->generate($nickname, 'dark'); return (new ImageResponse())->load($path); } } ``` ### 4. Маршрут [](#4-маршрут) ``` $router->get('/avatar/{nickname}', AvatarController::class, 'avatar.generate'); ``` Структура модуля ---------------- [](#структура-модуля) ``` src/ ├── AvatarConfig.php # Конфигурация (размер, темы) ├── AvatarException.php # Базовое исключение ├── AvatarGenerationException.php # Исключение при ошибках GD ├── AvatarGenerator.php # Бизнес-логика генерации ├── AvatarProvider.php # Сервис-провайдер ├── SeededRandom.php # Детерминированный PRNG ├── ThemeConfig.php # Value Object темы оформления ├── Controller/ │ ├── AvatarController.php # Контроллер генерации аватара │ └── HealthController.php # Healthcheck для Docker └── Http/Response/ └── ImageResponse.php # HTTP-ответ с PNG docker/ ├── Dockerfile # Мультистейдж сборка для микросервиса ├── docker-compose.yml # Docker Compose для запуска └── entrypoint.sh # Точка входа контейнера ``` Темы оформления --------------- [](#темы-оформления) Каждая тема содержит: ПараметрОписание`background_colors`Массив цветов фона (выбирается случайно)`text_color`Цвет текста`decorative_colors`Массив цветов декоративных квадратов`decorative_min`Минимальное количество квадратов`decorative_max`Максимальное количество квадратов`decorative_size_min`Минимальный размер квадрата (px)`decorative_size_max`Максимальный размер квадрата (px)Кэширование ----------- [](#кэширование) Сгенерированные аватары кэшируются в директории `var/cache/avatars/`. Ключ кэша — MD5-хеш от комбинации никнейма и темы. При повторном запросе возвращается сохранённый файл. Исключения ---------- [](#исключения) - `AvatarException` — базовое исключение модуля (наследует `JokeException`) - `AvatarGenerationException` — ошибка при работе с GD (наследует `AvatarException`) Docker ------ [](#docker) Модуль можно запустить как самостоятельный микросервис через Docker. ### Требования [](#требования-1) - Docker Engine 24+ - Docker Compose v2+ ### Запуск [](#запуск) ``` docker compose -f docker/docker-compose.yml up -d ``` После запуска сервис доступен на `http://localhost:8000`. > **Важно:** При использовании флага `-f` Docker Compose **не подхватывает** `docker-compose.override.yml` автоматически. Если вы создали override-файл, указывайте его явно через дополнительный флаг `-f`: > > ``` > docker compose -f docker/docker-compose.yml -f docker-compose.override.yml up -d > ``` ### Примеры запросов [](#примеры-запросов) ``` # Сгенерировать аватар для Alice curl -o alice.png http://localhost:8000/avatar/Alice # Сгенерировать аватар для Bob в тёмной теме curl -o bob.png "http://localhost:8000/avatar/Bob?theme=dark" # Проверить работоспособность curl http://localhost:8000/health ``` > **Для браузера:** Откройте `http://localhost:8000/avatar/Alice` — сервер вернёт PNG-изображение. Встроенный PHP-сервер может не устанавливать корректный Content-Type для некоторых браузеров, поэтому изображение может отображаться не во всех браузерах. Для гарантированного результата используйте `curl -o avatar.png http://localhost:8000/avatar/Alice`. ### Смена порта [](#смена-порта) Если порт 8000 занят, укажите другой через `docker-compose.override.yml` в корне проекта: ``` # docker-compose.override.yml services: avatar: ports: - "8080:8000" ``` Запуск с override-файлом: ``` docker compose -f docker/docker-compose.yml -f docker-compose.override.yml up -d ``` После этого сервис будет доступен на `http://localhost:8080`. ### Привязка домена [](#привязка-домена) Для доступа по доменному имени используйте reverse proxy (например, Nginx): ``` server { listen 80; server_name avatar.example.com; location / { proxy_pass http://localhost:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } ``` Либо укажите домен в `docker-compose.override.yml` через сети: ``` # docker-compose.override.yml services: avatar: networks: - proxy networks: proxy: external: true ``` ### Остановка [](#остановка) ``` docker compose -f docker/docker-compose.yml down ``` ### Особенности [](#особенности) - Мультистейдж сборка: финальный образ содержит только runtime-зависимости - Кэш аватаров сохраняется в Docker volume `avatar-cache` - HEALTHCHECK через эндпоинт `/health` - Запуск от непривилегированного пользователя `avatar` - Для production рекомендуется использовать Nginx в качестве reverse proxy Тестовое приложение ------------------- [](#тестовое-приложение) В репозитории доступно тестовое приложение для локальной проверки: ``` composer run dev ``` После запуска откройте в браузере: - `http://localhost:8000/avatar/Alice` - `http://localhost:8000/avatar/Bob?theme=dark` - `http://localhost:8000/avatar/Charlie?theme=ocean` Разработка ---------- [](#разработка) ``` # Запуск тестов composer run test # Запуск dev-сервера composer run dev # Запуск через Docker docker compose -f docker/docker-compose.yml up ``` Генерация кода -------------- [](#генерация-кода) Весь исходный код данного модуля полностью создан AI-агентом **SourceCraft Code Assistant** (на базе Claude 3.5 Sonnet) в рамках проекта [Joke](https://github.com/joke-php/joke). - **Архитектура и планирование**: AI-агент в режиме Architect - **Реализация**: AI-агент в режиме Code - **Отладка и тестирование**: AI-агент в режиме Debug - **Оркестрация сложных задач**: AI-агент в режиме Orchestrator Генерация выполнялась в среде разработки VS Code с использованием Roo Code (расширение для AI-ассистированной разработки). Человек выступал в роли ревьюера и постановщика задач. Лицензия -------- [](#лицензия) MIT ### Health Score 41 — FairBetter than 87% of packages Maintenance90 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity57 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 9 Last Release 50d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/ce4dfd67b12e198becd71253723d0c83044cb4689b735f2fd4eee4ac191c41ec?d=identicon)[Voral](/maintainers/Voral) --- Top Contributors [![Voral](https://avatars.githubusercontent.com/u/327165?v=4)](https://github.com/Voral "Voral (54 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/joke-php-avatar/health.svg) ``` [![Health](https://phpackages.com/badges/joke-php-avatar/health.svg)](https://phpackages.com/packages/joke-php-avatar) ``` ### Alternatives [flarum/nicknames Allow users to set nicknames. 11314.5k11](/packages/flarum-nicknames)[azuracast/nowplaying A lightweight PHP adapter for viewing the current now playing data in Icecast and SHOUTcast 1/2. A part of the AzuraCast software suite. 3046.7k3](/packages/azuracast-nowplaying) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)