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 customize 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'             => 400,
    'margin'           => 4,
    'error_correction' => 'M',     // 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\QrCode\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');
}

Via Artisan CLI

You can generate QR codes directly from the command line using the qr:generate Artisan command. This is useful for quickly creating QR codes or integrating generation into shell scripts.

Interactive Mode

Run the command without arguments to enter an interactive mode that guides you through the options:

php artisan qr:generate

Non-Interactive Mode

You can provide the data and options directly to bypass the interactive prompts:

php artisan qr:generate "https://example.com" \
  --output=public/qr.svg \
  --format=svg \
  --size=500 \
  --color=255,0,0 \
  --errorCorrection=H

Note on Naming Conventions: The CLI command uses camelCase for its flags (e.g., --errorCorrection, --backgroundColor) to match common shell practices, whereas the config/qrcode.php file uses snake_case keys (e.g., error_correction, background_color). When translating your configuration to CLI commands, ensure you convert snake_case values to camelCase.

Available Options:

data: (Argument) The data/payload to encode.
-O, --output: The file path to save the QR code (e.g., public/qr.svg). If omitted, the raw output is printed to the console.
-F, --format: Output format (svg, png, webp, eps). Default: svg.
-S, --size: Size in pixels. Default: 400.
-C, --color: Foreground color as comma-separated RGB or RGBA, where the optional alpha is an integer from 0–100 (e.g., 255,0,0 or 255,0,0,50). Default: 0,0,0.
-B, --backgroundColor: Background color as comma-separated RGB or RGBA, where the optional alpha is an integer from 0–100 (e.g., 255,255,255 or 255,255,255,50). Default: 255,255,255.
-E, --errorCorrection: Error correction level (L, M, Q, H). Default: M.
-M, --margin: Margin around the QR code. Default: 4.

✨ 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::CalendarEvent([
    '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.

🧩 Custom Data Types (Macros)

While this package provides many built-in data types (WiFi, vCard, BTC), your application likely has its own specific data structures. Using Laravel's Macroable trait, you can define your own custom QR code payloads without extending classes or waiting for package updates.

This keeps your controllers clean, ensures DRY (Don't Repeat Yourself) principles, and standardizes QR generation across your application.

Register the Macro Define your macro in the boot method of your AppServiceProvider. You can either return a plain string (which will automatically be converted into a QR code) or call $this->generate() if you want to apply default styles inside the macro.

use Linkxtr\QrCode\Facades\QrCode;

public function boot(): void
{
    // Example 1: Return a string payload (Automatically encoded)
    QrCode::macro('Spotify', function (string $uri) {
        return 'spotify:track:' . $uri;
    });

    // Example 2: Return pre-styled generation for an internal company asset
    QrCode::macro('AssetTag', function (string $serialNumber) {
        $payload = json_encode(['type' => 'hardware', 'sn' => $serialNumber]);

        return $this->size(300)->margin(2)->generate($payload);
    });
}

Use it Anywhere Once registered, your macros are available seamlessly on the Facade:

// Generates a Spotify URI QR code
echo QrCode::Spotify('4uLU6hMCjMI75M1A2tKUQC');

// Generates a pre-styled 300px JSON asset tag
echo QrCode::AssetTag('SN-99812-X');

💡 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');

Advanced Color Models & Composite Eyes

Customize QR codes with CMYK color mode and composite eyes (separate styling for outer and inner eye patterns):

QrCode::size(300)
    ->cmyk()
    ->color(100, 50, 0, 10)
    ->backgroundColor(0, 0, 0, 0)
    ->eye('circle')
    ->internalEye('square') // Style the inner eye pattern separately
    ->generate('Advanced 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($c1, $c2, $c3, $c4 = null) - Set foreground color. In RGB mode: ($red, $green, $blue, $alpha). In CMYK mode: ($cyan, $magenta, $yellow, $black). Default: RGB
backgroundColor($c1, $c2, $c3, $c4 = null) - Set background color. Same parameter meaning as color()
cmyk() - Switch to CMYK color model (0-100 scale for each component)
rgb() - Switch to RGB color model (0-255 scale). This is the default mode
gray($gray, $backgroundGray = null) - Set grayscale colors (0=black, 100=white). If $backgroundGray is null, uses white (100)
style($style) - Set style (dot, square, round)
eye($style) - Set eye style (circle, square, pointy)
internalEye($style) - Set internal eye style (circle, square, pointy) for composite eyes
gradient($startRed, $startGreen, $startBlue, $endRed, $endGreen, $endBlue, $type) - Set gradient color (RGB mode only)
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
CalendarEvent($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