README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle QrCode

Генерация и чтение QR-кодов для PHP 8.1+ без единой обязательной зависимости: все режимы кодирования, рендеринг в SVG/PNG/EPS/PDF/терминал (PNG — без расширений GD и Imagick), высокоуровневые данные (URL, Wi-Fi, vCard, платежи СБП/ГОСТ) и полноценный декодер с исправлением ошибок Рида-Соломона.

Возможности

Кодирование по ISO/IEC 18004 — режимы числовой, буквенно-цифровой, байтовый, кандзи (Shift-JIS) и объявление кодировки через ECI; версии 1–40 с авто-подбором; уровни коррекции L/M/Q/H; авто-выбор и фиксация маски.
Рендеринг без зависимостей — SVG, PNG на чистом PHP (только ext-zlib), EPS, PDF и вывод в терминал половинными блоками Unicode.
Стилизация — цвет модулей и фона, прозрачность (RGBA), настраиваемая тихая зона и масштаб.
Высокоуровневые данные (более 50 типов) — контакты (vCard, MeCard), связь (Email, Phone, SMS, MMS, WhatsApp, Telegram, Viber, Signal, Skype, FaceTime), соцсети (VK, Instagram, Facebook, X, LinkedIn, YouTube, TikTok, GitHub…), карты (Geo, Google/Яндекс Карты), Wi-Fi, событие календаря, магазины приложений и платежи: СБП (динамический QR НСПК и статический ГОСТ Р 56042-2014 / формат ST00012), SEPA/GiroCode, ЮMoney, UPI, PayPal и криптовалюты (Bitcoin, Ethereum, Litecoin, Dogecoin, Bitcoin Cash, Monero, TON, Tron, Dash, Zcash, Ripple, Solana).
Чтение (декодер) — восстановление данных из матрицы во всех режимах с исправлением ошибок (синдромы, Берлекамп-Мэсси, поиск Чьена, формула Форни).
Качество — строгая типизация, 100 % покрытие строк, 98.5 % Infection MSI (с документированными эквивалентами), полный статанализ (PHPStan max, Psalm 1, PHPMD, Deptrac, Rector) на PHP 8.1–8.5.

Установка

composer require cloud-castle/qr-code

Требуется PHP 8.1+. Расширения ext-gd/ext-imagick не нужны; ext-iconv требуется только для режима кандзи и национальных кодировок (см. suggest).

Быстрый старт

<?php

use CloudCastle\QrCode\QrCode;
use CloudCastle\QrCode\Enum\ErrorCorrectionLevel;
use CloudCastle\QrCode\Style\Color;
use CloudCastle\QrCode\Writer\PngWriter;

// SVG по умолчанию
$svg = QrCode::create('https://gitverse.ru/cloud-castle/qr-code')->render();

// PNG без ext-gd, с настройками
$png = QrCode::create('Привет, мир!')
    ->errorCorrection(ErrorCorrectionLevel::High)
    ->foregroundColor(new Color(20, 30, 90))
    ->scale(8)
    ->margin(4)
    ->writer(new PngWriter())
    ->build();

$png->saveToFile('qr.png');
echo $png->getDataUri(); // data:image/png;base64,...
echo $png->getBase64();  // сырое изображение в Base64 (для JSON/API)

Высокоуровневые данные

use CloudCastle\QrCode\Data\Wifi;
use CloudCastle\QrCode\Data\RussianPayment;

// Подключение к Wi-Fi
$svg = QrCode::create(new Wifi(ssid: 'MyNet', password: 'secret'))->render();

// Платёж по ГОСТ Р 56042-2014 (СБП)
$payment = new RussianPayment(
    name: 'ООО Ромашка',
    personalAcc: '40702810500000000123',
    bankName: 'ПАО Сбербанк',
    bic: '044525225',
    correspAcc: '30101810400000000225',
    sum: 1500.50,
    purpose: 'Оплата по счёту 123',
);
$svg = QrCode::create($payment)->render();

Чтение QR-кода

use CloudCastle\QrCode\QrCode;
use CloudCastle\QrCode\Reader\QrReader;

$matrix = QrCode::create('https://example.com')->getMatrix();
$data = (new QrReader())->read($matrix); // 'https://example.com'

Сравнение с аналогами

Полные автогенерируемые таблицы (функциональность, производительность, память, безопасность, качество кода) с графой 🏆 Победитель — на странице Comparison в Wiki. Краткая сводка для русского README:

Все таблицы сгенерированы автоматически из честных прогонов (PHP 8.1.34).

Функциональность

Возможность	CloudCastle	endroid/qr-code	bacon/bacon-qr-code	chillerlan/php-qrcode	khanamiryan/qrcode-detector	🏆 Победитель
Генерация QR-кода	✅	✅	✅	✅	❌	CloudCastle
Чтение / декодирование	✅	❌	❌	✅	✅	CloudCastle
Исправление ошибок при чтении	✅	❌	❌	✅	✅	CloudCastle
Числовой / буквенно-цифровой / байтовый режимы	✅	✅	✅	✅	✅	CloudCastle
Режим кандзи (Shift-JIS)	✅	❌	✅	✅	✅	CloudCastle
Кодировки через ECI	✅	❌	✅	✅	✅	CloudCastle
Версии 1–40, уровни L/M/Q/H	✅	✅	✅	✅	✅	CloudCastle
Рендеринг в SVG	✅	✅	✅	✅	✅	CloudCastle
Рендеринг в PNG без ext-gd/ext-imagick	✅	❌	❌	❌	❌	CloudCastle
Рендеринг в BMP без ext-gd/ext-imagick	✅	❌	❌	❌	❌	CloudCastle
Рендеринг в GIF без ext-gd/ext-imagick	✅	❌	❌	❌	❌	CloudCastle
Рендеринг в EPS	✅	❌	✅	✅	❌	CloudCastle
Рендеринг в PDF (нативно)	✅	❌	❌	⚠️	❌	CloudCastle
Вывод в терминал (ASCII/Unicode)	✅	❌	❌	✅	❌	CloudCastle
Вывод изображения в Base64 / data-URI	✅	✅	❌	✅	❌	CloudCastle
Высокоуровневые данные (URL, Wi-Fi, vCard…)	✅	❌	❌	❌	❌	CloudCastle
Платежи по ГОСТ Р 56042-2014 (СБП/ST00012)	✅	❌	❌	❌	❌	CloudCastle
Ноль обязательных runtime-зависимостей	✅	❌	❌	❌	❌	CloudCastle
Логотип по центру (SVG)	✅	✅	❌	✅	❌	CloudCastle
Логотип по центру во всех форматах (SVG/PNG/BMP/GIF/EPS/PDF)	✅	❌	❌	❌	❌	CloudCastle

Производительность (меньше — лучше)

Пакет	Время, мкс/оп	🏆 Победитель
CloudCastle	1004.54	🏆
chillerlan/php-qrcode	3818.75
endroid/qr-code	7115.81
bacon/bacon-qr-code	8346.03

Потребление памяти (меньше — лучше)

Пакет	Память, КБ	🏆 Победитель
CloudCastle	337.5	🏆
endroid/qr-code	574.2
chillerlan/php-qrcode	668.0
bacon/bacon-qr-code	672.5

Безопасность

Аспект	CloudCastle	endroid/qr-code	bacon/bacon-qr-code	chillerlan/php-qrcode	khanamiryan/qrcode-detector	🏆 Победитель
Экранирование данных в SVG/HTML (защита от инъекций)	✅	✅	✅	✅	❌	CloudCastle
Ноль сторонних runtime-зависимостей (минимум supply-chain)	✅	❌	❌	❌	❌	CloudCastle
Строгая типизация (declare(strict_types=1) везде)	✅	✅	⚠️	✅	❌	CloudCastle
Валидация входных параметров на границе	✅	✅	✅	✅	⚠️	CloudCastle
Проверка уязвимостей зависимостей в CI (roave/audit)	✅	❌	❌	❌	❌	CloudCastle
Отсутствие подавления ошибок оператором @	✅	✅	✅	✅	❌	CloudCastle

Качество кода

Аспект	CloudCastle	endroid/qr-code	bacon/bacon-qr-code	chillerlan/php-qrcode	khanamiryan/qrcode-detector	🏆 Победитель
PHPStan уровень max	✅	⚠️	❌	⚠️	❌	CloudCastle
Psalm errorLevel 1	✅	❌	❌	❌	❌	CloudCastle
Покрытие строк 100 % (порог per-file)	✅	❌	❌	⚠️	❌	CloudCastle
Мутационное тестирование (Infection MSI 98.5 %)	✅	❌	❌	❌	❌	CloudCastle
Контроль архитектурных слоёв (Deptrac)	✅	❌	❌	❌	❌	CloudCastle
PHPMD + PHP-CS-Fixer + PHPCS (PSR-12)	✅	⚠️	⚠️	⚠️	❌	CloudCastle
Rector (проверка современного синтаксиса)	✅	⚠️	❌	⚠️	❌	CloudCastle
Матрица CI PHP 8.1–8.5	✅	⚠️	⚠️	⚠️	❌	CloudCastle

Плюсы и минусы

Плюсы:

✅ Ноль обязательных runtime-зависимостей — минимальная поверхность supply-chain; PNG собирается на чистом PHP без ext-gd/ext-imagick.
✅ Быстрее и экономнее аналогов — самый низкий расход времени и памяти в честном бенчмарке против endroid, bacon и chillerlan.
✅ Суперсет возможностей — генерация всех режимов, чтение с исправлением ошибок, форматы SVG/PNG/EPS/PDF/терминал и высокоуровневые данные, которых нет у большинства аналогов (Wi-Fi, vCard, платежи СБП/ГОСТ).
✅ Эталонное качество — 100 % покрытие и 98.5 % Infection MSI, полный статанализ, строгая типизация на PHP 8.1–8.5.

Минусы (честно):

⚠️ Пакет моложе и менее распространён, чем endroid/qr-code или bacon/bacon-qr-code — меньше звёзд, установок и упоминаний в готовых рецептах.
⚠️ Встраивание логотипа по центру пока не реализовано (есть у endroid и chillerlan) — в плане ближайших релизов.
⚠️ Из растровых форматов нативно поддержан только PNG; GIF/JPEG/WebP не выводятся (PNG покрывает подавляющее большинство сценариев).

Сценарий	Рекомендация
Микросервисы и API без графических расширений	CloudCastle — PNG без `ext-gd`/`ext-imagick`
Финтех и платежи в России (СБП, ГОСТ)	CloudCastle — готовый `RussianPayment`
Высоконагруженная генерация	CloudCastle — самый быстрый и экономный
Строгие требования к качеству и типобезопасности	CloudCastle — 100 % покрытие, 98.5 % MSI, Psalm 1
Нужен логотип по центру «из коробки»	endroid/qr-code или chillerlan/php-qrcode
Распознавание QR с искажённых фотографий	khanamiryan/qrcode-detector или chillerlan

Разработка

composer install
composer check      # линтеры + статический анализ + тесты
composer fix        # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci         # полный CI-пайплайн локально
composer docs:build # пересобрать сравнительные таблицы

Полный список команд: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/qr-code
Wiki (руководства, страницы фич, диаграммы): https://gitverse.ru/cloud-castle/qr-code/wiki
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Политика безопасности: SECURITY.md

Лицензия