> ## Documentation Index
> Fetch the complete documentation index at: https://laravel-qrcode.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from simple-qrcode to Laravel QR Code

> Step-by-step guide to migrate from simplesoftwareio/simple-qrcode or endroid/qr-code to linkxtr/laravel-qrcode — with side-by-side code comparisons and feature matrix.

If your application currently relies on `simplesoftwareio/simple-qrcode`, you are likely running into maintenance and compatibility concerns on modern PHP and Laravel versions. The `simple-qrcode` package has remained unmaintained since February 2021 and has not been tested or updated for PHP 8.2+ or modern Laravel releases, relies on mutable builder instances, and lacks modern vector styling features.

`linkxtr/laravel-qrcode` is engineered as a modern, high-performance replacement. It maintains drop-in API compatibility for common generation calls while providing immutable builder safety, a native Blade component, an interactive Artisan CLI, WebP support, custom eye shapes, and 100% decode-verified scannability.

## Feature comparison

| Feature | `linkxtr/laravel-qrcode` | `simplesoftwareio/simple-qrcode` | `endroid/qr-code` |
| :- | :- | :- | :- |
| **Laravel 12+ and 13+ support** | Full support | Untested (unmaintained since Laravel 8) | Needs manual wrapper |
| **PHP 8.2, 8.3 & 8.4** | Full strict-types support | Untested / unmaintained | Supported |
| **Active maintenance** | Yes | Abandoned (Feb 2021) | Yes (standalone PHP) |
| **Fluent syntax** | `QrCode::size(300)->generate()` | `QrCode::size(300)->generate()` | Verbose builder objects |
| **Immutable builder** | Yes (zero side-effects) | No (mutable instance bugs) | Yes |
| **Blade component** | `<x-qr-code data="..." />` | None | None |
| **Artisan CLI** | `php artisan qr:generate` | None | None |
| **Vector default** | SVG (zero PHP extensions) | SVG | SVG |
| **Raster formats** | PNG, WebP, EPS | PNG, EPS | PNG, WebP |
| **Eye shape customization** | Square, circle, pointy | Square, circle | Square only |
| **Per-eye colors** | Yes (all 3 corners) | Yes | No |
| **Gradients** | 5 directions (RGB) | 5 directions | No |
| **Center logo merge** | SVG, PNG, WebP, EPS | PNG only (requires Imagick) | Layered logo object |
| **Controller response** | Built-in `Responsable` | Manual header setup | PSR-7 response helper |
| **Built-in caching** | `QrCode::cache(3600)` | No | Cache decorators |

## Migrating in three steps

**1. Swap Composer dependencies**

Remove the unmaintained package and install `linkxtr/laravel-qrcode`:

```bash theme={null}
composer remove simplesoftwareio/simple-qrcode
composer require linkxtr/laravel-qrcode
```

Laravel automatically registers the `QrCode` facade and `<x-qr-code>` Blade component.

**2. Publish configuration**

Publish the configuration file to customize global defaults:

```bash theme={null}
php artisan vendor:publish --tag=qrcode-config
```

This creates `config/qrcode.php` with default format, size, margin, colors, error correction, and cache settings.

**3. Update facade imports**

Update your facade namespace imports across your codebase.

```php theme={null}
// Before (simple-qrcode)
use SimpleSoftwareIO\QrCode\Facades\QrCode;

// After (linkxtr/laravel-qrcode)
use Linkxtr\QrCode\Facades\QrCode;
```

If your application used global facade aliases without imports, the `QrCode` alias resolves directly to `Linkxtr\QrCode\Facades\QrCode`.

## Side-by-side code comparison

### Basic generation

The core fluent API is identical. While most existing calls work unchanged, calls that omit `size()` and `margin()` use package defaults of 400 px and four quiet-zone modules instead of the legacy 100 px and zero margin. To retain the legacy output dimensions and layout, explicitly set `size(100)` and `margin(0)`.

```php Laravel QR Code (New) theme={null}
use Linkxtr\QrCode\Facades\QrCode;

// Returns a QrCodeResult (implements Stringable, Htmlable, Responsable)
$svg = QrCode::size(300)->generate('https://laravel-qrcode.mintlify.app');
```

```php simple-qrcode (Legacy) theme={null}
use SimpleSoftwareIO\QrCode\Facades\QrCode;

// Returned raw string or generator
$svg = QrCode::size(300)->generate('https://example.com');
```

### Colors and background

Both packages support RGB and alpha channels, where the facade's `color()` accepts integer channels. If you want to use hex strings, you can pass them to the Blade component, configuration files (`config/qrcode.php` and `.env`), or `gradient()`.

```php Laravel QR Code (New) theme={null}
// Clean RGB color chaining
QrCode::size(300)
    ->color(30, 64, 175)
    ->backgroundColor(255, 255, 255)
    ->generate('https://example.com');

// RGBA with alpha channel (0–100 scale)
QrCode::size(300)
    ->color(30, 64, 175, 50) // 50% opacity
    ->generate('https://example.com');
```

```php simple-qrcode (Legacy) theme={null}
QrCode::size(300)
    ->color(30, 64, 175)
    ->backgroundColor(255, 255, 255)
    ->generate('https://example.com');
```

### Logo merge with high error correction

Embedding logos requires error correction level **H** to ensure scannability.

```php Laravel QR Code (New) theme={null}
QrCode::size(400)
    ->errorCorrection('H')
    ->style('dot')
    ->eye('circle')
    ->merge(public_path('logo.png'), 0.25)
    ->generate('https://example.com');
```

```php simple-qrcode (Legacy) theme={null}
QrCode::format('png')
    ->size(400)
    ->errorCorrection('H')
    ->merge(public_path('logo.png'), 0.25, true)
    ->generate('https://example.com');
```

### Structured data types

Helper methods for structured payloads map cleanly:

```php Laravel QR Code (New) theme={null}
// WiFi credentials
QrCode::WiFi([
    'ssid' => 'OfficeWiFi',
    'encryption' => 'WPA2',
    'password' => 'secret123',
]);

// Email
QrCode::Email('team@example.com', 'Subject', 'Body content');

// Phone SMS
QrCode::SMS('+1234567890', 'Hello!');
```

```php simple-qrcode (Legacy) theme={null}
QrCode::wifi([
    'ssid' => 'OfficeWiFi',
    'encryption' => 'WPA',
    'password' => 'secret123',
]);

QrCode::email('team@example.com', 'Subject', 'Body content');

QrCode::sms('+1234567890', 'Hello!');
```

## New features unlocked

Migrating to `linkxtr/laravel-qrcode` provides immediate architectural improvements:

### 1. Immutable builder safety

`simplesoftwareio/simple-qrcode` mutated generator instances in place. If you shared a base generator or resolved it from a singleton container, subsequent calls inherited options set by earlier requests. `linkxtr/laravel-qrcode` clones its internal configuration on every fluent call, preventing cross-request leaks.

```php theme={null}
$base = QrCode::size(300)->color(30, 64, 175);

// Both calls remain completely independent and isolated
$badgeQr = $base->style('dot')->generate('https://example.com/badge');
$cardQr = $base->style('square')->generate('https://example.com/card');
```

### 2. Blade component with automatic accessibility

Render accessible QR codes directly in your Blade views without `{!! !!}` directives:

```blade theme={null}
<x-qr-code
    data="https://laravel-qrcode.mintlify.app"
    size="250"
    style="dot"
    eye="circle"
    color="#1e40af"
/>
```

### 3. Interactive Artisan CLI

Generate QR codes in terminals, build steps, and deployments:

```bash theme={null}
# Interactive guided mode
php artisan qr:generate

# Scripting flag mode
php artisan qr:generate "https://example.com" --output=public/qr.svg --size=500
```

### 4. Built-in caching

Cache rendered QR codes directly using your application cache:

```php theme={null}
// Cache for 3600 seconds (1 hour)
QrCode::cache(3600)->generate('https://example.com');
```

### 5. Controller Responsable support

Return QR code results directly from your controller methods:

```php theme={null}
use Linkxtr\QrCode\Facades\QrCode;
use Linkxtr\QrCode\Support\QrCodeResult;

public function show(): QrCodeResult
{
    return QrCode::size(300)->generate('https://example.com');
}
```

> [card] [Quickstart](https://laravel-qrcode.mintlify.site/quickstart.md)
>
> Get started with installation and your first QR code.

> [card] [Blade Component](https://laravel-qrcode.mintlify.site/usage/blade-component.md)
>
> Learn how to drop the Blade component into your templates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.