README

A simple and easy-to-use QR Code generator for Laravel, based on the bacon/bacon-qr-code library.

Note: This is version 2.x.

Version 2.x is the current stable release, requiring PHP 8.2+ and Laravel 11+.
Version 1.x is the LTS/Maintenance version. If you need Laravel 10 support or PHP 8.1, please use version 1.x.
Version 2.x drops compatibility with simplesoftwareio/simple-qrcode to provide a more streamlined API.
📚 Upgrading? Check out the Upgrade Guide.

Requirements

PHP 8.2 or higher
Laravel 11.0 or higher
ext-imagick extension (optional, but recommended for better performance). If imagick is not available, the package will automatically fallback to using gd for PNG and WebP generation.

📦 Installation

composer require linkxtr/laravel-qrcode

The package uses Laravel's package auto-discovery, so the service provider and facade are registered automatically.

⚙️ Configuration

Optionally publish the config file to customise the package-wide defaults:

php artisan vendor:publish --tag=qrcode-config

This creates config/qrcode.php where you can set global defaults for every QR code generated by the QrCode facade or the <x-qr-code> component:

return [
    'format'           => 'svg',   // svg | png | eps | webp
    'size'             => 200,
    'margin'           => 4,
    'error_correction' => 'H',     // L | M | Q | H
    'encoding'         => 'UTF-8',
    'color'            => [0, 0, 0],             // [R, G, B, A] — alpha: 0-100 (optional)
    'background_color' => [255, 255, 255],       // [R, G, B, A] — alpha: 0-100 (optional)
];

Note: Config-driven defaults automatically apply when resolving the QrCode facade, using the <x-qr-code> Blade component, or type-hinting Linkxtr\QrCode\Generator through Laravel's service container. If you manually construct an instance via new Generator(), you will get the hardcoded package defaults unless you pass the config array manually.

Basic Usage in Blade Templates

The <x-qr-code> component is automatically available after installation.

<!-- Display QR code -->
<x-qr-code data="Hello World!" />

<!-- Display QR code with options -->
<x-qr-code
    data="https://example.com"
    size="200"
    color="#ff0000"
    margin="1"
/>

In Controllers

use Linkxtr\LaravelQrCode\Facades\QrCode;

public function generate()
{
    // Return as SVG response
    return QrCode::generate('QR Code Content');

    // Or save to file
    QrCode::generate('Content', storage_path('app/qrcodes/qr.svg'));

    // Or get as string
    $svg = QrCode::generate('Content');
}

✨ Features

🎨 Enhanced Customization

// Colors and styling
QrCode::size(300)
    ->color(255, 0, 0)
    ->backgroundColor(255, 255, 255)
    ->style('dot')
    ->eye('circle')
    ->generate('Styled QR Code');

// Error correction
QrCode::errorCorrection('H')->generate('Important Data');

// Merge images
QrCode::merge('path/to/logo.png')->generate('With Logo');

📱 Multiple Data Types

// URLs
QrCode::generate('https://example.com');

// Emails
QrCode::email('to@example.com', 'Subject', 'Body');

// Phone numbers
QrCode::phoneNumber('+1234567890');

// SMS
QrCode::SMS('+1234567890', 'Message body');

// WiFi
QrCode::wiFi([
    'ssid' => 'Network',
    'encryption' => 'WPA', // Supported: WEP, WPA, WPA2, nopass
    'password' => 'Password'
]);

// Geolocation
QrCode::geo(37.7749, -122.4194);

// BTC
QrCode::btc(['btcaddress', 0.0034, ['label' => 'label', 'message' => 'message', 'returnAddress' => 'https://www.returnaddress.com']]);

// Ethereum (amount in ETH)
QrCode::ethereum('0x742d35Cc6634C0532925a3b8D2b2CE1e5bfb043d', 1.5);
// vCard
QrCode::vCard([
    'name' => 'John Doe',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email' => 'john@example.com',
    'phone' => '+1234567890',
    'company' => 'Tech Corp',
    'title' => 'Developer',
    'url' => 'https://example.com'
]);

// Calendar Event
use Carbon\Carbon;

QrCode::calendar([
    'summary' => 'Laracon US',
    'description' => 'The official Laravel conference.',
    'location' => 'New York, NY',
    'start' => Carbon::create(2024, 8, 27, 9, 0, 0),
    'end' => Carbon::create(2024, 8, 28, 17, 0, 0),
]);

// WhatsApp
QrCode::WhatsApp(['number' => '+1234567890', 'message' => 'Hello from Laravel!']);

// Telegram
QrCode::telegram('username');

🔧 Advanced Usage

All Available Methods

// Size and format
QrCode::size(250)->format('png')->generate('Content');

// Colors with RGB
QrCode::color(255, 0, 0)->generate('Red QR');

// Background color
QrCode::backgroundColor(255, 255, 0)->generate('Yellow background');

// Margin
QrCode::margin(2)->generate('With margin');

// Encoding
QrCode::encoding('UTF-8')->generate('Unicode content');

// Gradient colors
QrCode::gradient(0, 0, 255, 255, 0, 0, 'vertical')->generate('Gradient');

Error Correction Levels

L - 7% of data bytes can be restored
M - 15% of data bytes can be restored
Q - 25% of data bytes can be restored
H - 30% of data bytes can be restored (default)

QrCode::errorCorrection('H')->generate('High error correction');

Image Merging

Image merging is supported for PNG, WebP, and SVG formats.

// Merge with logo
QrCode::format('png')->merge('path/to/logo.png', 0.3, true)->generate('With Logo');

// Merge with SVG
QrCode::format('svg')->merge('path/to/logo.png', 0.3, true)->generate('With Logo');

Note: Image merge is not supported for EPS format.

💡 Common Examples

Generate QR for Website

QrCode::size(200)
    ->generate('https://your-website.com');

QR Code with Logo

QrCode::size(300)
    ->merge(public_path('logo.png'), 0.3, true)
    ->generate('QR with logo');

Colorful QR Code

QrCode::size(300)
    ->color(58, 94, 255)
    ->backgroundColor(255, 255, 255)
    ->generate('Colorful QR');

WiFi QR Code

QrCode::wiFi([
    'ssid' => 'MyWiFi',
    'encryption' => 'WPA', // Supported: WEP, WPA, WPA2, nopass
    'password' => 'my-password'
]);

Warning: WEP encryption is deprecated and insecure. It is supported only for legacy compatibility. It is strongly recommended to use WPA or WPA2 instead.

Styled QR Code

QrCode::size(250)
    ->color(255, 0, 0)
    ->style('dot')
    ->eye('circle')
    ->margin(1)
    ->generate('Styled QR Code');

🤝 Contributing & 🗺️ Roadmap

Version 2 Roadmap

For a detailed and up-to-date look at what's planned for Version 2, please check out our ROADMAP.md file.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Request Features

Have an idea? Open an issue with your feature request!

🐛 Troubleshooting

Common Issues

QR code not displaying in blade:

When using the facade directly, make sure to use unescaped output:

{!! QrCode::generate('Content') !!}  ✅
{{ QrCode::generate('Content') }}     ❌

Alternatively, use the much simpler Blade component:

<x-qr-code data="Content" /> ✅

File permission errors:

// Ensure directory exists and is writable
QrCode::generate('Content', storage_path('app/qrcodes/qr.svg'));

Large QR codes:

// For large content, use higher error correction
QrCode::size(400)
    ->errorCorrection('H')
    ->generate('Very long content...');

📚 API Reference

Core Methods

generate($text, $filename = null) - Generate QR code
size($size) - Set size in pixels
color($red, $green, $blue, $alpha = null) - Set QR color (alpha 0-100)
backgroundColor($red, $green, $blue, $alpha = null) - Set background color (alpha 0-100)
style($style) - Set style (dot, square, round)
eye($style) - Set eye style (circle, square)
gradient($startRed, $startGreen, $startBlue, $endRed, $endGreen, $endBlue, $type) - Set gradient color
format($format) - Set format (svg, png, eps, webp)
margin($margin) - Set margin size
errorCorrection($level) - Set error correction level (L, M, Q, H)
encoding($encoding) - Set character encoding
merge($image, $percentage, $absolute) - Merge image/logo

Data Type Methods

email($to, $subject, $body) - Generate email QR
phoneNumber($phone) - Generate phone QR
SMS($phone, $message) - Generate SMS QR
geo($lat, $lng) - Generate location QR
wiFi($config) - Generate WiFi QR
btc($config) - Generate BTC QR
ethereum($address, $amount = null) - Generate Ethereum QR (amount in ETH)
vCard($config) - Generate vCard QR
calendar($config) - Generate Calendar Event QR
WhatsApp($params) - Generate WhatsApp QR (array with number and optional message)
telegram($username) - Generate Telegram QR

📄 License

This package is open-sourced software licensed under the MIT license.

🙏 Acknowledgments

Based on the original work by simplesoftwareio/simple-qrcode
Built upon bacon/bacon-qr-code
Maintained by khaled-sadek and contributors

Need help? Open an issue • Found a bug? Report it

⭐ If you find this repository useful, please consider starring it.

linkxtr / laravel-qrcode

Maintainers

Package info

Statistics

Security