README

📱 Aicrion QRCode

A modern, professional PHP 8.2+ library to generate and read QR codes from multiple sources and in multiple formats.

📖 Full Documentation

✨ Features

• 🧱 Modern architecture — interfaces, immutable value objects, enums, readonly properties (PHP 8.2+)
• 🖼️ Multiple output formats — PNG, SVG, EPS, WEBP
• 📥 Multiple input sources for reading — file path, binary string, Base64, URL, GD image, stream resource
• 🎨 Full customization — size, margin, colors, error correction level, embedded logo, caption label
• 📇 Structured payloads — WiFi, Contact (vCard), Phone, SMS, Email, Geo location, Calendar events, URLs, with automatic type detection when reading
• 🌈 Colored QR codes — generate and reliably read back QR codes with fully custom foreground/background colors
• 🧪 Fully tested — unit and feature tests with PHPUnit
• 📦 Zero-config Composer install — sane, production-ready defaults out of the box
• 🧯 Rich exception hierarchy — precise, catchable error types for every failure mode

📦 Installation

Requires PHP 8.2+ and the gd extension.

composer require aicrion/qrcode

🚀 Quick Start

Generate a QR Code

use Aicrion\QRCode\QRCode;

$qr = QRCode::make();

// Save directly to a file
$qr->generateToFile('https://github.com/aicrion/qrcode-php', __DIR__ . '/qrcode.png');

// Get raw bytes
$bytes = $qr->generate('Hello World');

// Get a data URI (ideal for <img src="...">)
$uri = $qr->generateDataUri('Hello World');

Read a QR Code

use Aicrion\QRCode\QRCode;

$qr = QRCode::make();

$result = $qr->readFromPath(__DIR__ . '/qrcode.png');

echo $result->content; // decoded text

Or let the library auto-detect the source type:

$qr->read(__DIR__ . '/qrcode.png');      // file path
$qr->read('https://example.com/qr.png'); // URL
$qr->read($base64DataUri);               // Base64 data URI
$qr->read($binaryImageString);           // raw binary

🎨 Customization

use Aicrion\QRCode\Enums\{OutputFormat, ErrorCorrectionLevel};
use Aicrion\QRCode\ValueObjects\{QRCodeOptions, Color};

$options = (new QRCodeOptions())
    ->withSize(600)
    ->withFormat(OutputFormat::SVG)
    ->withColors(Color::fromHex('#0f172a'), Color::white())
    ->withErrorCorrection(ErrorCorrectionLevel::HIGH)
    ->withLogo(__DIR__ . '/assets/logo.png', sizeRatio: 22);

$svg = QRCode::make()->generate('https://aicrion.dev', $options);

📚 Supported Formats & Sources

🇮🇷 Persian / Farsi & Unicode Support

Full UTF-8 support out of the box — Persian, Arabic, Chinese, emoji, etc.

$qr->generateToFile('سلام دنیا! این یک کد کیوآر فارسی است.', __DIR__ . '/farsi-qr.png');

$result = $qr->readFromPath(__DIR__ . '/farsi-qr.png');
echo $result->content; // سلام دنیا! این یک کد کیوآر فارسی است.

📇 Structured QR Codes (WiFi, Contact, Phone, etc.)

use Aicrion\QRCode\Enums\WifiEncryption;

$qr->generateWifi(ssid: 'MyNetwork', password: 'secret123', encryption: WifiEncryption::WPA);
$qr->generateContact(firstName: 'Hadi', lastName: 'Akbarzadeh', phone: '+989120000000', email: 'hadi@elatel.ir');
$qr->generatePhone('+989120000000');
$qr->generateSms('+989120000000', 'Hello!');
$qr->generateEmail('hello@aicrion.dev', 'Subject', 'Body');
$qr->generateGeo(35.6892, 51.3890);
$qr->generateUrl('https://github.com/aicrion/qrcode-php');

Reading automatically detects and parses the payload type:

$result = $qr->readFromPath(__DIR__ . '/wifi.png');

echo $result->type->value; // "wifi"
print_r($result->parsed);  // ['ssid' => 'MyNetwork', 'password' => 'secret123', ...]

See the Structured Payloads documentation for the full list of supported types.

🌈 Colored QR Codes

use Aicrion\QRCode\ValueObjects\{QRCodeOptions, Color};

$options = (new QRCodeOptions())->withColors(Color::fromHex('#0f172a'), Color::fromHex('#f8fafc'));

$qr->generateToFile('https://aicrion.dev', __DIR__ . '/branded-qr.png', $options);

// Reading colored QR codes works exactly like black & white ones
$result = $qr->readFromPath(__DIR__ . '/branded-qr.png');
echo $result->content;

🧯 Exception Handling

All exceptions extend Aicrion\QRCode\Exceptions\QRCodeException:

use Aicrion\QRCode\Exceptions\QRCodeException;

try {
    $result = QRCode::make()->readFromPath('/missing/file.png');
} catch (QRCodeException $e) {
    // Handles InvalidSourceException, DecodingException, GenerationException, etc.
    logger()->error($e->getMessage());
}

🧪 Testing

composer install
composer test

📖 Documentation

Full documentation, including the complete API reference, is available at:

https://aicrion.github.io/qrcode-php/

Table of contents: Installation · Quick Start · Generating QR Codes · Reading QR Codes · Structured Payloads · Colors & Styling · Configuration Options · Exception Handling · Examples · API Reference · Contributing · Changelog

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

1. Fork the repository
2. Create a feature branch
3. Run composer test and composer stan
4. Submit your pull request

📜 License

Created with ❤️ by Aicrion. Licensed under the MIT License. Free to use, modify, and distribute!