Upgrade Guide: Laravel QR Code v1.x to v3.x Migration

Complete upgrade instructions for moving from linkxtr/laravel-qrcode v1.x to v3.x, including breaking changes, required code updates, and rollback steps.

Version 3.x is a significant release that upgrades the underlying bacon/bacon-qr-code library from v2 to v3, hardens the API with strict types, and drops legacy compatibility layers. Most applications need only a few targeted changes to upgrade cleanly.

Laravel 10 users: v3.x requires Laravel 12+ and PHP 8.2+. If you are on Laravel 10 or PHP 8.1, stay on v1.x — it receives maintenance fixes and is the supported path for those environments.

System Requirements

Requirement	v1.x	v2.x	v3.x
PHP	8.1+	8.2+	8.2+
Laravel	10+	11+	12+
ext-gd	Required	Optional	Optional
ext-imagick	Optional	Optional	Optional (recommended)
Composer	2.x	2.x	2.x

Breaking Changes

Review every item below before running the upgrade command. Most changes affect only a small number of call sites.

1. PHP and Laravel version requirements raised

The minimum PHP version is now 8.2 and the minimum Laravel version is 12.0, matching the requirements of bacon/bacon-qr-code v3.

If your composer.json pins PHP or Laravel to an older constraint, update it first:

"require": {
    "php": "^8.2",
    "laravel/framework": "^12.0"
}

2. Direct use of upstream library classes (advanced)

This item only applies if your application imports classes from the BaconQrCode library directly — for example, in a custom renderer or a low-level integration. If you only use the QrCode facade, the Blade component, or constructor injection, you are not affected and can skip this item.

The underlying bacon/bacon-qr-code library reorganized several namespaces between its v2 and v3 releases. Notable changes include:

Old class	New class
BaconQrCode\Writer	BaconQrCode\Writer\Writer
BaconQrCode\Common\ErrorCorrectionLevel	Constants updated — see the bacon/bacon-qr-code releases

3. color() and backgroundColor() now require integers

Both methods now enforce integer arguments (0–255 for RGB, 0–100 for CMYK and alpha). Passing strings throws a type error.

// ❌ v1.x — strings were silently accepted
QrCode::color('255', '0', '0');

// ✅ v3.x — integers required
QrCode::color(255, 0, 0);

Search your codebase for calls to ->color( and ->backgroundColor( and confirm all arguments are integer literals or variables typed as int.

4. simplesoftwareio/simple-qrcode compatibility dropped

v3.x removed the compatibility layer that allowed the QrCode facade to act as a drop-in replacement for simplesoftwareio/simple-qrcode. If you migrated from that package and relied on any method signatures that do not exist in linkxtr/laravel-qrcode’s own API, you will need to update those call sites to use the new API.

Check the API reference in the README for the current method signatures.

5. Strict data validation — InvalidArgumentException on bad input

In v1.x, passing malformed data to type methods (such as a bad phone number or an incomplete WiFi config) could silently generate a corrupted QR code. In v3.x, all data types validate their inputs strictly and throw InvalidArgumentException on failure.

Wrap any call that accepts dynamic user input in a try/catch:

use Linkxtr\QrCode\Contracts\QrCodeExceptionInterface;

try {
    $qr = QrCode::WiFi([
        'ssid'       => $request->ssid,
        'encryption' => $request->encryption,
        'password'   => $request->password,
    ]);
} catch (QrCodeExceptionInterface $e) {
    // Return validation error to the user
    return back()->withErrors(['wifi' => $e->getMessage()]);
}

6. Config defaults changed in v2.4.x

Starting in v2.4.0, the package ships with updated defaults to better reflect modern usage:

Key	v1.x / pre-2.4 default	v2.4.x+ / v3.x+ default
format	png	svg
size	200	400
error_correction	H	M

If your application relied on the previous defaults and you have not published the config file, you may notice changes in QR code output after upgrading. Publish the config and set these values explicitly to lock in your preferred defaults.

Upgrade Steps

1. Update the package constraint

   Run the following command in your project root:

   composer require linkxtr/laravel-qrcode:^3.0
   

   Composer will pull in the latest v3.x release along with bacon/bacon-qr-code v3.

2. Update color() and backgroundColor() calls

   Find every call to ->color( and ->backgroundColor( in your application and confirm each argument is an integer:

   // Before
   QrCode::color('255', '0', '0')->generate('Hello');
   
   // After
   QrCode::color(255, 0, 0)->generate('Hello');
   

   A quick search command to locate these calls:

   grep -rn "->color\|->backgroundColor" app/ resources/
   
3. Publish and review the config file

   If you have not already published the config, do so now:

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

   This creates config/qrcode.php. Open it and explicitly set format, size, and error_correction to match what your application expects, so you are never affected by future default changes:

   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],
       'background_color' => [255, 255, 255],
   ];
   
4. Wrap dynamic inputs in try/catch

   Identify every place where user-supplied data flows into a data-type method (WiFi, Email, PhoneNumber, SMS, VCard, etc.) and add InvalidArgumentException handling:

   use InvalidArgumentException;
   use Linkxtr\QrCode\Facades\QrCode;
   
   try {
       $qr = QrCode::PhoneNumber($request->input('phone'));
   } catch (InvalidArgumentException $e) {
       return response()->json(['error' => $e->getMessage()], 422);
   }
   
5. Clear cached config and views

   php artisan config:clear
   php artisan view:clear
   

Rollback Instructions

If you need to revert to v1.x, run:

composer require linkxtr/laravel-qrcode:^1.0

Then clear the cache again:

php artisan config:clear
php artisan view:clear

If you published config/qrcode.php during the v3.x migration and changed values, review the config after rolling back — the v1.x config schema may differ from v3.x.