From 80fa48d8cb7dfb384730f830517fd283916f1680 Mon Sep 17 00:00:00 2001 From: khaled-sadek <65240054+khaled-sadek@users.noreply.github.com> Date: Tue, 27 Oct 2026 20:00:39 +0300 Subject: [PATCH 1/2] docs: visual overhaul with 35+ real QR assets, bug fixes, and simple-qrcode migration guide --- advanced/migrating-from-simple-qrcode.mdx | 238 ++++++++++++++++++ configuration/config-file.mdx | 6 +- configuration/environment-variables.mdx | 37 ++- customization/colors.mdx | 38 +++ customization/image-merge.mdx | 13 + customization/styling.mdx | 45 ++++ docs.json | 7 +- images/colors/complete-color-example.svg | 2 + images/colors/eye-colors-three.svg | 2 + images/colors/gradient-diagonal.svg | 2 + images/colors/gradient-horizontal.svg | 2 + images/colors/gradient-inverse-diagonal.svg | 2 + images/colors/gradient-radial.svg | 2 + images/colors/gradient-vertical.svg | 2 + images/colors/grayscale.svg | 2 + images/colors/rgb-red.svg | 2 + images/colors/rgba-semi-transparent.svg | 2 + images/merge/merged-branded-complete.svg | 1 + images/merge/merged-logo-20.svg | 1 + images/merge/merged-logo-30.svg | 1 + images/showcase/classic-blue.svg | 2 + images/showcase/dot-circle.svg | 2 + images/showcase/gradient-diagonal.svg | 2 + images/showcase/gradient-radial.svg | 2 + images/showcase/logo-merged.svg | 1 + images/showcase/multi-eye-colors.svg | 2 + images/styling/eye-circle.svg | 2 + images/styling/eye-pointy.svg | 2 + images/styling/eye-square.svg | 2 + images/styling/internal-eye-circle-pointy.svg | 2 + images/styling/internal-eye-square-circle.svg | 2 + images/styling/margin-0.svg | 2 + images/styling/margin-2.svg | 2 + images/styling/margin-6.svg | 2 + images/styling/style-dot.svg | 2 + images/styling/style-round.svg | 2 + images/styling/style-square.svg | 2 + images/usage/blade-custom-eyes.svg | 2 + images/usage/blade-dot-circle.svg | 2 + images/usage/blade-gradient.svg | 2 + images/usage/blade-hex-blue.svg | 2 + images/usage/blade-minimal.svg | 2 + images/usage/cli-interactive-terminal.svg | 63 +++++ images/usage/logo-merged.svg | 1 + index.mdx | 29 ++- usage/artisan-cli.mdx | 4 + usage/blade-component.mdx | 31 ++- usage/facade.mdx | 60 +++-- 48 files changed, 610 insertions(+), 28 deletions(-) create mode 100644 advanced/migrating-from-simple-qrcode.mdx create mode 100644 images/colors/complete-color-example.svg create mode 100644 images/colors/eye-colors-three.svg create mode 100644 images/colors/gradient-diagonal.svg create mode 100644 images/colors/gradient-horizontal.svg create mode 100644 images/colors/gradient-inverse-diagonal.svg create mode 100644 images/colors/gradient-radial.svg create mode 100644 images/colors/gradient-vertical.svg create mode 100644 images/colors/grayscale.svg create mode 100644 images/colors/rgb-red.svg create mode 100644 images/colors/rgba-semi-transparent.svg create mode 100644 images/merge/merged-branded-complete.svg create mode 100644 images/merge/merged-logo-20.svg create mode 100644 images/merge/merged-logo-30.svg create mode 100644 images/showcase/classic-blue.svg create mode 100644 images/showcase/dot-circle.svg create mode 100644 images/showcase/gradient-diagonal.svg create mode 100644 images/showcase/gradient-radial.svg create mode 100644 images/showcase/logo-merged.svg create mode 100644 images/showcase/multi-eye-colors.svg create mode 100644 images/styling/eye-circle.svg create mode 100644 images/styling/eye-pointy.svg create mode 100644 images/styling/eye-square.svg create mode 100644 images/styling/internal-eye-circle-pointy.svg create mode 100644 images/styling/internal-eye-square-circle.svg create mode 100644 images/styling/margin-0.svg create mode 100644 images/styling/margin-2.svg create mode 100644 images/styling/margin-6.svg create mode 100644 images/styling/style-dot.svg create mode 100644 images/styling/style-round.svg create mode 100644 images/styling/style-square.svg create mode 100644 images/usage/blade-custom-eyes.svg create mode 100644 images/usage/blade-dot-circle.svg create mode 100644 images/usage/blade-gradient.svg create mode 100644 images/usage/blade-hex-blue.svg create mode 100644 images/usage/blade-minimal.svg create mode 100644 images/usage/cli-interactive-terminal.svg create mode 100644 images/usage/logo-merged.svg diff --git a/advanced/migrating-from-simple-qrcode.mdx b/advanced/migrating-from-simple-qrcode.mdx new file mode 100644 index 0000000..b2b5bf5 --- /dev/null +++ b/advanced/migrating-from-simple-qrcode.mdx @@ -0,0 +1,238 @@ +--- +title: "Migrating from simple-qrcode to Laravel QR Code" +sidebarTitle: "Migrating from simple-qrcode" +description: "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 compatibility barriers on modern PHP and Laravel versions. The `simple-qrcode` package has remained unmaintained since February 2021, lacks support for PHP 8.2+ and Laravel 12+, 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 | Abandoned (max Laravel 8) | Needs manual wrapper | +| **PHP 8.2, 8.3 & 8.4** | Full strict-types support | Incompatible | 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** | `` | 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 only | Square only | +| **Per-eye colors** | Yes (all 3 corners) | No | No | +| **Gradients** | 5 directions (RGB) | Linear only | 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 + + + + Remove the unmaintained package and install `linkxtr/laravel-qrcode`: + + ```bash + composer remove simplesoftwareio/simple-qrcode + composer require linkxtr/laravel-qrcode + ``` + + Laravel automatically registers the `QrCode` facade and `` Blade component. + + + + Publish the configuration file to customize global defaults: + + ```bash + php artisan vendor:publish --tag=qrcode-config + ``` + + This creates `config/qrcode.php` with default format, size, margin, colors, error correction, and cache settings. + + + + Update your facade namespace imports across your codebase. + + ```php + // 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. Your existing calls continue to work without changes. + + +```php Laravel QR Code (New) +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) +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 values, but `linkxtr/laravel-qrcode` adds support for alpha channels and hex strings. + + +```php Laravel QR Code (New) +// Clean RGB color chaining +QrCode::size(300) + ->color(30, 64, 175) + ->backgroundColor(255, 255, 255) + ->generate('https://example.com'); + +// Supports hex colors directly +QrCode::size(300) + ->color(30, 64, 175, 50) // 50% opacity + ->generate('https://example.com'); +``` + +```php simple-qrcode (Legacy) +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) +QrCode::size(400) + ->errorCorrection('H') + ->style('dot') + ->eye('circle') + ->merge(public_path('logo.png'), 0.25) + ->generate('https://example.com'); +``` + +```php simple-qrcode (Legacy) +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) +// 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) +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 +$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 + +``` + +### 3. Interactive Artisan CLI +Generate QR codes in terminals, build steps, and deployments: + +```bash +# 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 +// 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 +public function show(): QrCodeResult +{ + return QrCode::size(300)->generate('https://example.com'); +} +``` + + + + Get started with installation and your first QR code. + + + Learn how to drop the Blade component into your templates. + + diff --git a/configuration/config-file.mdx b/configuration/config-file.mdx index 6687a34..9808c05 100644 --- a/configuration/config-file.mdx +++ b/configuration/config-file.mdx @@ -120,11 +120,13 @@ return [ | Cache Configuration |-------------------------------------------------------------------------- | - | Controls whether generated QR codes are cached and their TTL in minutes. + | Controls whether generated QR codes are cached, their TTL in seconds, + | and the cache store to use. | */ 'cache_enabled' => env('QR_CODE_CACHE_ENABLED', false), - 'cache_ttl' => env('QR_CODE_CACHE_TTL', 1440), + 'cache_ttl' => (int) (env('QR_CODE_CACHE_TTL') ?? 86400), + 'cache_store' => env('QR_CODE_CACHE_STORE', null), ]; ``` diff --git a/configuration/environment-variables.mdx b/configuration/environment-variables.mdx index 8acf4de..83042b2 100644 --- a/configuration/environment-variables.mdx +++ b/configuration/environment-variables.mdx @@ -54,9 +54,13 @@ QR_CODE_FORCE_GD=false # Default: false QR_CODE_CACHE_ENABLED=false -# Cache Time-To-Live in minutes -# Default: 1440 -QR_CODE_CACHE_TTL=1440 +# Cache Time-To-Live in seconds (e.g. 86400 = 24 hours) +# Default: 86400 +QR_CODE_CACHE_TTL=86400 + +# Cache store to use (null uses default cache store; e.g. redis, memcached) +# Default: null +QR_CODE_CACHE_STORE= ``` ## Variable reference @@ -169,6 +173,33 @@ QR_CODE_FORCE_GD=true + + Enables or disables automatic caching of generated QR code results. When enabled, identical requests reuse cached output to eliminate duplicate rendering overhead. + +```ini +QR_CODE_CACHE_ENABLED=true +``` + + + + Sets the cache time-to-live **in seconds**. The default is 86400 seconds (24 hours). + +```ini +# Cache for 1 hour (3600 seconds) +QR_CODE_CACHE_TTL=3600 +``` + + + + Specifies the cache store to use for storing cached QR codes (e.g. `redis`, `memcached`, `database`, or `file`). When set to `null` or omitted, the package uses your default Laravel cache repository defined in `config/cache.php`. + +```ini +# Use dedicated Redis cache store +QR_CODE_CACHE_STORE=redis +``` + + + ## Environment-specific examples Use different defaults for local development vs. production without changing any PHP code: diff --git a/customization/colors.mdx b/customization/colors.mdx index 57b9e30..b83b886 100644 --- a/customization/colors.mdx +++ b/customization/colors.mdx @@ -19,6 +19,10 @@ QrCode::color(220, 38, 38) ->generate('https://example.com'); ``` + + RGB red QR code + + ### RGB with Alpha Add a fourth argument to include an **alpha (transparency) channel**. The scale is **0–100**, where `0` is fully opaque and `100` is fully transparent. @@ -36,6 +40,10 @@ QrCode::color(220, 38, 38, 50) representation automatically. + + RGBA semi-transparent QR code + + ## CMYK Switch to CMYK mode by calling `cmyk()` before `color()`. All four channel values use a **0–100** scale (percentage). @@ -78,6 +86,10 @@ QrCode::gray(0)->generate('https://example.com'); - **First argument** — foreground shade (0 = black, 100 = white). - **Second argument** — background shade. Defaults to `100` (white) when omitted. + + Grayscale QR code + + ## Gradients Apply a two-color gradient to the QR code foreground with `gradient()`. Provide start and end colors as RGB arrays or hex strings, then choose a direction. @@ -111,6 +123,24 @@ QrCode::gradient([255, 165, 0], [255, 0, 128], 'diagonal') `cmyk()` is not supported. + + + Vertical gradient QR code + + + Horizontal gradient QR code + + + Diagonal gradient QR code + + + Inverse diagonal gradient QR code + + + Radial gradient QR code + + + ## Per-Eye Color Overrides Override the color of any individual eye with `eyeColor()`. Each QR code has three positional eyes indexed `0`, `1`, and `2`. @@ -140,6 +170,10 @@ QrCode::eyeColor(0, [220, 38, 38])->generate('https://example.com'); without Imagick. + + Per-eye colors QR code + + ## Complete Color Example Chain color options with style and format options to build a fully branded QR code. @@ -159,6 +193,10 @@ $qr = QrCode::format('png') ->generate('https://example.com'); ``` + + Complete color example QR code + + Set module shape, eye style, size, margin, and output format. diff --git a/customization/image-merge.mdx b/customization/image-merge.mdx index b7bf62e..49eef02 100644 --- a/customization/image-merge.mdx +++ b/customization/image-merge.mdx @@ -87,6 +87,15 @@ QrCode::format('png') logo. + + + 20% logo merge QR code + + + 30% logo merge QR code + + + ## Save to a File Pass a second argument to `generate()` to write the result directly to disk. @@ -155,6 +164,10 @@ $qr = QrCode::format('png') // {!! $qr !!} ``` + + Complete branded QR code with merged logo + + Control module shape, eye style, size, margin, and format. diff --git a/customization/styling.mdx b/customization/styling.mdx index 07d6154..c0cfcd6 100644 --- a/customization/styling.mdx +++ b/customization/styling.mdx @@ -35,6 +35,18 @@ QrCode::style('square')->generate('https://example.com'); equivalent. + + + Square modules QR code + + + Circular dot modules QR code + + + Rounded modules QR code + + + ## Eye Style The three large **positional squares** in the corners of every QR code are called eyes. Use `eye()` to set their outer shape. @@ -53,6 +65,18 @@ QrCode::style('dot')->eye('circle')->generate('https://example.com'); QrCode::style('round')->eye('pointy')->generate('https://example.com'); ``` + + + Square eyes QR code + + + Circle eyes QR code + + + Pointy eyes QR code + + + ## Internal (Composite) Eye Style Each positional eye is made of two parts: an outer frame and an inner marker. By default both share the same style set by `eye()`. Call `internalEye()` to style the **inner marker** independently, giving you composite eyes. @@ -70,6 +94,15 @@ QrCode::style('dot')->eye('circle')->internalEye('pointy')->generate('https://ex and `'pointy'`. + + + Square outer with circle inner eye QR code + + + Circle outer with pointy inner eye QR code + + + ## Size and Margin Control the pixel dimensions and quiet zone around the code with `size()` and `margin()`. @@ -85,6 +118,18 @@ QrCode::size(500)->margin(6)->generate('https://example.com'); - **`size(int $size)`** — Total width and height in pixels. Default: `400`. - **`margin(int $margin)`** — Quiet-zone thickness in modules. Default: `4`. + + + Margin 0 QR code + + + Margin 2 QR code + + + Margin 6 QR code + + + ## Output Format Use `format()` to choose the image format of the generated QR code. diff --git a/docs.json b/docs.json index e5477d9..e928ed1 100644 --- a/docs.json +++ b/docs.json @@ -27,7 +27,11 @@ "groups": [ { "group": "Get Started", - "pages": ["introduction", "installation", "quickstart"] + "pages": [ + "introduction", + "installation", + "quickstart" + ] }, { "group": "Usage", @@ -67,6 +71,7 @@ "pages": [ "advanced/macros", "advanced/upgrade-guide", + "advanced/migrating-from-simple-qrcode", "advanced/troubleshooting" ] } diff --git a/images/colors/complete-color-example.svg b/images/colors/complete-color-example.svg new file mode 100644 index 0000000..a0cf992 --- /dev/null +++ b/images/colors/complete-color-example.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/eye-colors-three.svg b/images/colors/eye-colors-three.svg new file mode 100644 index 0000000..388a8ee --- /dev/null +++ b/images/colors/eye-colors-three.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/gradient-diagonal.svg b/images/colors/gradient-diagonal.svg new file mode 100644 index 0000000..d16ca81 --- /dev/null +++ b/images/colors/gradient-diagonal.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/gradient-horizontal.svg b/images/colors/gradient-horizontal.svg new file mode 100644 index 0000000..7151802 --- /dev/null +++ b/images/colors/gradient-horizontal.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/gradient-inverse-diagonal.svg b/images/colors/gradient-inverse-diagonal.svg new file mode 100644 index 0000000..be5dec0 --- /dev/null +++ b/images/colors/gradient-inverse-diagonal.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/gradient-radial.svg b/images/colors/gradient-radial.svg new file mode 100644 index 0000000..f92e817 --- /dev/null +++ b/images/colors/gradient-radial.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/gradient-vertical.svg b/images/colors/gradient-vertical.svg new file mode 100644 index 0000000..bbb3ec2 --- /dev/null +++ b/images/colors/gradient-vertical.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/grayscale.svg b/images/colors/grayscale.svg new file mode 100644 index 0000000..fda959f --- /dev/null +++ b/images/colors/grayscale.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/rgb-red.svg b/images/colors/rgb-red.svg new file mode 100644 index 0000000..a819e4c --- /dev/null +++ b/images/colors/rgb-red.svg @@ -0,0 +1,2 @@ + + diff --git a/images/colors/rgba-semi-transparent.svg b/images/colors/rgba-semi-transparent.svg new file mode 100644 index 0000000..6a8b5bf --- /dev/null +++ b/images/colors/rgba-semi-transparent.svg @@ -0,0 +1,2 @@ + + diff --git a/images/merge/merged-branded-complete.svg b/images/merge/merged-branded-complete.svg new file mode 100644 index 0000000..fd3d65a --- /dev/null +++ b/images/merge/merged-branded-complete.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/merge/merged-logo-20.svg b/images/merge/merged-logo-20.svg new file mode 100644 index 0000000..0cf0cb4 --- /dev/null +++ b/images/merge/merged-logo-20.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/merge/merged-logo-30.svg b/images/merge/merged-logo-30.svg new file mode 100644 index 0000000..d2e18e5 --- /dev/null +++ b/images/merge/merged-logo-30.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/showcase/classic-blue.svg b/images/showcase/classic-blue.svg new file mode 100644 index 0000000..26b6f8c --- /dev/null +++ b/images/showcase/classic-blue.svg @@ -0,0 +1,2 @@ + + diff --git a/images/showcase/dot-circle.svg b/images/showcase/dot-circle.svg new file mode 100644 index 0000000..26dd902 --- /dev/null +++ b/images/showcase/dot-circle.svg @@ -0,0 +1,2 @@ + + diff --git a/images/showcase/gradient-diagonal.svg b/images/showcase/gradient-diagonal.svg new file mode 100644 index 0000000..660d63c --- /dev/null +++ b/images/showcase/gradient-diagonal.svg @@ -0,0 +1,2 @@ + + diff --git a/images/showcase/gradient-radial.svg b/images/showcase/gradient-radial.svg new file mode 100644 index 0000000..5036e58 --- /dev/null +++ b/images/showcase/gradient-radial.svg @@ -0,0 +1,2 @@ + + diff --git a/images/showcase/logo-merged.svg b/images/showcase/logo-merged.svg new file mode 100644 index 0000000..6d8683f --- /dev/null +++ b/images/showcase/logo-merged.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/showcase/multi-eye-colors.svg b/images/showcase/multi-eye-colors.svg new file mode 100644 index 0000000..e7b0bcc --- /dev/null +++ b/images/showcase/multi-eye-colors.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/eye-circle.svg b/images/styling/eye-circle.svg new file mode 100644 index 0000000..d203979 --- /dev/null +++ b/images/styling/eye-circle.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/eye-pointy.svg b/images/styling/eye-pointy.svg new file mode 100644 index 0000000..e29fd69 --- /dev/null +++ b/images/styling/eye-pointy.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/eye-square.svg b/images/styling/eye-square.svg new file mode 100644 index 0000000..2cf3cce --- /dev/null +++ b/images/styling/eye-square.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/internal-eye-circle-pointy.svg b/images/styling/internal-eye-circle-pointy.svg new file mode 100644 index 0000000..d203979 --- /dev/null +++ b/images/styling/internal-eye-circle-pointy.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/internal-eye-square-circle.svg b/images/styling/internal-eye-square-circle.svg new file mode 100644 index 0000000..d25e9c2 --- /dev/null +++ b/images/styling/internal-eye-square-circle.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/margin-0.svg b/images/styling/margin-0.svg new file mode 100644 index 0000000..054f577 --- /dev/null +++ b/images/styling/margin-0.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/margin-2.svg b/images/styling/margin-2.svg new file mode 100644 index 0000000..54ee230 --- /dev/null +++ b/images/styling/margin-2.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/margin-6.svg b/images/styling/margin-6.svg new file mode 100644 index 0000000..0db7f5f --- /dev/null +++ b/images/styling/margin-6.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/style-dot.svg b/images/styling/style-dot.svg new file mode 100644 index 0000000..84c1e41 --- /dev/null +++ b/images/styling/style-dot.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/style-round.svg b/images/styling/style-round.svg new file mode 100644 index 0000000..63de7d0 --- /dev/null +++ b/images/styling/style-round.svg @@ -0,0 +1,2 @@ + + diff --git a/images/styling/style-square.svg b/images/styling/style-square.svg new file mode 100644 index 0000000..4b4191b --- /dev/null +++ b/images/styling/style-square.svg @@ -0,0 +1,2 @@ + + diff --git a/images/usage/blade-custom-eyes.svg b/images/usage/blade-custom-eyes.svg new file mode 100644 index 0000000..e1d5090 --- /dev/null +++ b/images/usage/blade-custom-eyes.svg @@ -0,0 +1,2 @@ + + diff --git a/images/usage/blade-dot-circle.svg b/images/usage/blade-dot-circle.svg new file mode 100644 index 0000000..7bbed0d --- /dev/null +++ b/images/usage/blade-dot-circle.svg @@ -0,0 +1,2 @@ + + diff --git a/images/usage/blade-gradient.svg b/images/usage/blade-gradient.svg new file mode 100644 index 0000000..bbb3ec2 --- /dev/null +++ b/images/usage/blade-gradient.svg @@ -0,0 +1,2 @@ + + diff --git a/images/usage/blade-hex-blue.svg b/images/usage/blade-hex-blue.svg new file mode 100644 index 0000000..1b8c516 --- /dev/null +++ b/images/usage/blade-hex-blue.svg @@ -0,0 +1,2 @@ + + diff --git a/images/usage/blade-minimal.svg b/images/usage/blade-minimal.svg new file mode 100644 index 0000000..adcbbc8 --- /dev/null +++ b/images/usage/blade-minimal.svg @@ -0,0 +1,2 @@ + + diff --git a/images/usage/cli-interactive-terminal.svg b/images/usage/cli-interactive-terminal.svg new file mode 100644 index 0000000..09a375b --- /dev/null +++ b/images/usage/cli-interactive-terminal.svg @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + Terminal — php artisan qr:generate + + + + + + $ + php artisan qr:generate + + + + ┌ What text or URL should be encoded in the QR code? + │ https://laravel-qrcode.mintlify.app + │ + + + ┌ Where should the generated file be saved? (Leave blank to print to console) + │ storage/app/qrcodes/docs-badge.svg + │ + + + ┌ Which format should be generated? + │ ● svg (default vector format) + │ ○ png + │ ○ webp + │ ○ eps + │ + + + ┌ Do you want to configure advanced options? (Size, Colors, Margin...) + │ Yes + │ + + + + ✔ QR Code generated successfully! + Saved to: storage/app/qrcodes/docs-badge.svg (400×400 px, format: svg) + + \ No newline at end of file diff --git a/images/usage/logo-merged.svg b/images/usage/logo-merged.svg new file mode 100644 index 0000000..6d8683f --- /dev/null +++ b/images/usage/logo-merged.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.mdx b/index.mdx index 2a10abd..1a27d4b 100644 --- a/index.mdx +++ b/index.mdx @@ -24,7 +24,32 @@ Laravel QR Code is a modern QR code generation package for Laravel 12+ and PHP 8 -## Get Started in Three Steps +## Visual showcase + +Explore real vector QR codes generated directly by the package with custom shapes, gradients, multi-eye colors, and embedded logos: + + + + Classic blue QR code + + + Dots with circle eyes QR code + + + Diagonal gradient QR code + + + Radial gradient QR code + + + Multi-eye colors QR code + + + Logo merged QR code + + + +## Get started in three steps @@ -48,7 +73,7 @@ Laravel QR Code is a modern QR code generation package for Laravel 12+ and PHP 8 ```blade Blade Component - + ``` ```php Facade diff --git a/usage/artisan-cli.mdx b/usage/artisan-cli.mdx index 1eff700..14e9b04 100644 --- a/usage/artisan-cli.mdx +++ b/usage/artisan-cli.mdx @@ -27,6 +27,10 @@ The prompt sequence: fields interactively. + + Interactive CLI terminal prompt preview + + ## Non-interactive mode Pass the payload as a positional argument and use flags to set every option. This mode is designed for scripting — it skips all prompts and exits immediately with a success or failure code. diff --git a/usage/blade-component.mdx b/usage/blade-component.mdx index c645db1..f07cc25 100644 --- a/usage/blade-component.mdx +++ b/usage/blade-component.mdx @@ -23,7 +23,7 @@ The `` Blade component is the simplest way to display QR codes direct ``` -This renders an inline SVG QR code at the default size of 100 px. No PHP imports or extra configuration needed — the component is auto-registered by the package's service provider. +This renders an inline SVG QR code. When size and margin are omitted, the component automatically inherits dimensions from `config/qrcode.php` (default size of 400 px and quiet zone margin of 4 modules). No PHP imports or extra configuration needed — the component is auto-registered by the package's service provider. ## Available props @@ -32,8 +32,8 @@ This renders an inline SVG QR code at the default size of 100 px. No PHP imports plain text, a phone number, etc. - - Width and height of the QR code in pixels. + + Width and height of the QR code in pixels. When omitted or `null`, the component automatically inherits `size` from `config/qrcode.php` (package default `400`). @@ -50,8 +50,8 @@ This renders an inline SVG QR code at the default size of 100 px. No PHP imports Background color. Accepts the same formats as `color`. - - Quiet-zone margin around the QR code. + + Quiet-zone margin around the QR code in module units. When omitted or `null`, the component automatically inherits `margin` from `config/qrcode.php` (package default `4` quiet-zone modules). @@ -201,6 +201,27 @@ Both the `` text and `aria-label` value run through Laravel's `__()` help </CodeGroup> +<CardGroup cols={3}> + <Frame caption="Minimal default"> + <img src="/images/usage/blade-minimal.svg" alt="Minimal Blade component QR code" /> + </Frame> + <Frame caption="Hex color (#0066cc)"> + <img src="/images/usage/blade-hex-blue.svg" alt="Hex color Blade QR code" /> + </Frame> + <Frame caption="Dot style & circle eyes"> + <img src="/images/usage/blade-dot-circle.svg" alt="Dot style and circle eyes Blade QR code" /> + </Frame> + <Frame caption="Vertical gradient"> + <img src="/images/usage/blade-gradient.svg" alt="Vertical gradient Blade QR code" /> + </Frame> + <Frame caption="Custom eye colors"> + <img src="/images/usage/blade-custom-eyes.svg" alt="Custom eye colors Blade QR code" /> + </Frame> + <Frame caption="Logo overlay (Error correction H)"> + <img src="/images/usage/logo-merged.svg" alt="Merged logo Blade QR code" /> + </Frame> +</CardGroup> + ## Passing extra HTML attributes Because `<x-qr-code>` is a standard Blade component, you can pass arbitrary HTML attributes. They are merged onto the root `<svg>` or `<img>` element, so you can add CSS classes, `id` attributes, inline styles, and data attributes freely: diff --git a/usage/facade.mdx b/usage/facade.mdx index 221b4b0..ea3865b 100644 --- a/usage/facade.mdx +++ b/usage/facade.mdx @@ -192,36 +192,41 @@ $eps = (string) QrCode::format('eps')->generate('https://example.com'); ## Returning a QR code from a controller +`QrCodeResult` implements Laravel's `Responsable` interface. You can return the result object directly from any controller method, and Laravel automatically invokes `toResponse()` to return an HTTP 200 response with the correct `Content-Type` header (such as `image/svg+xml` or `image/png`). + <Tabs> - <Tab title="SVG response"> + <Tab title="Automatic Responsable"> ```php - use Illuminate\Http\Response; use Linkxtr\QrCode\Facades\QrCode; + use Linkxtr\QrCode\Support\QrCodeResult; - public function show(): Response + public function show(): QrCodeResult { - $svg = (string) QrCode::size(300)->generate('https://example.com'); - - return response($svg, 200) - ->header('Content-Type', 'image/svg+xml'); + // Returns HTTP 200 with automatic Content-Type: image/svg+xml + return QrCode::size(300)->generate('https://example.com'); } ``` - </Tab> - <Tab title="PNG response"> + <Tab title="Custom headers & HTTP caching"> ```php + use Illuminate\Http\Request; use Illuminate\Http\Response; use Linkxtr\QrCode\Facades\QrCode; - public function show(): Response + public function show(Request $request): Response { - $png = (string) QrCode::size(300)->format('png')->generate('https://example.com'); + $result = QrCode::size(300)->generate('https://example.com'); + $etag = md5((string) $result); + + if ($request->header('If-None-Match') === $etag) { + return response('', 304); + } - return response($png, 200) - ->header('Content-Type', 'image/png'); + return $result->toResponse($request) + ->header('ETag', $etag) + ->header('Cache-Control', 'public, max-age=86400, immutable'); } ``` - </Tab> <Tab title="File download"> ```php @@ -239,10 +244,35 @@ $eps = (string) QrCode::format('eps')->generate('https://example.com'); return response()->download($path, 'qrcode.png'); } ``` - </Tab> </Tabs> +## Caching generated QR codes + +Rendering complex vector or raster QR codes with high error correction and merged logos consumes CPU cycles. The `cache()` method caches generated output in your application's cache store, avoiding redundant rendering for identical requests. + +```php +use Carbon\Carbon; +use DateInterval; +use Linkxtr\QrCode\Facades\QrCode; + +// Cache for 3600 seconds (1 hour) +QrCode::cache(3600)->generate('https://example.com'); + +// Cache with a Carbon DateTime instance (e.g., until midnight) +QrCode::cache(Carbon::tomorrow())->generate('https://example.com'); + +// Cache with DateInterval (e.g., 2 hours) +QrCode::cache(new DateInterval('PT2H'))->generate('https://example.com'); + +// Explicitly bypass cache for one-time tokens or dynamic OTPs +QrCode::withoutCache()->generate('https://example.com'); +``` + +<Tip> + Cache keys are generated deterministically from the payload and serialized generator configuration. If you change any parameter (such as size, color, or error correction), the package automatically generates and caches a new QR code. +</Tip> + ## Styled QR code examples <CodeGroup> From 25e9f8c1f4c73cfcdc74f72b20304edb1191f9ab Mon Sep 17 00:00:00 2001 From: khaled sadek <65240054+khaled-sadek@users.noreply.github.com> Date: Sun, 1 Nov 2026 13:55:03 +0200 Subject: [PATCH 2/2] docs: update documentation for migration, colors, blade component, and facade usage --- advanced/migrating-from-simple-qrcode.mdx | 21 ++++++++++++--------- customization/colors.mdx | 10 +++++----- usage/blade-component.mdx | 6 +++--- usage/facade.mdx | 12 +++++------- 4 files changed, 25 insertions(+), 24 deletions(-) diff --git a/advanced/migrating-from-simple-qrcode.mdx b/advanced/migrating-from-simple-qrcode.mdx index b2b5bf5..b50dacd 100644 --- a/advanced/migrating-from-simple-qrcode.mdx +++ b/advanced/migrating-from-simple-qrcode.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Migrating from simple-qrcode" description: "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 compatibility barriers on modern PHP and Laravel versions. The `simple-qrcode` package has remained unmaintained since February 2021, lacks support for PHP 8.2+ and Laravel 12+, relies on mutable builder instances, and lacks modern vector styling features. +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. @@ -12,8 +12,8 @@ If your application currently relies on `simplesoftwareio/simple-qrcode`, you ar | Feature | `linkxtr/laravel-qrcode` | `simplesoftwareio/simple-qrcode` | `endroid/qr-code` | | :--- | :--- | :--- | :--- | -| **Laravel 12+ and 13+ support** | Full support | Abandoned (max Laravel 8) | Needs manual wrapper | -| **PHP 8.2, 8.3 & 8.4** | Full strict-types support | Incompatible | Supported | +| **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 | @@ -21,9 +21,9 @@ If your application currently relies on `simplesoftwareio/simple-qrcode`, you ar | **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 only | Square only | -| **Per-eye colors** | Yes (all 3 corners) | No | No | -| **Gradients** | 5 directions (RGB) | Linear only | No | +| **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 | @@ -71,7 +71,7 @@ If your application currently relies on `simplesoftwareio/simple-qrcode`, you ar ### Basic generation -The core fluent API is identical. Your existing calls continue to work without changes. +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)`. <CodeGroup> ```php Laravel QR Code (New) @@ -91,7 +91,7 @@ $svg = QrCode::size(300)->generate('https://example.com'); ### Colors and background -Both packages support RGB values, but `linkxtr/laravel-qrcode` adds support for alpha channels and hex strings. +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()`. <CodeGroup> ```php Laravel QR Code (New) @@ -101,7 +101,7 @@ QrCode::size(300) ->backgroundColor(255, 255, 255) ->generate('https://example.com'); -// Supports hex colors directly +// RGBA with alpha channel (0–100 scale) QrCode::size(300) ->color(30, 64, 175, 50) // 50% opacity ->generate('https://example.com'); @@ -222,6 +222,9 @@ QrCode::cache(3600)->generate('https://example.com'); Return QR code results directly from your controller methods: ```php +use Linkxtr\QrCode\Facades\QrCode; +use Linkxtr\QrCode\Support\QrCodeResult; + public function show(): QrCodeResult { return QrCode::size(300)->generate('https://example.com'); diff --git a/customization/colors.mdx b/customization/colors.mdx index b83b886..b37b3c2 100644 --- a/customization/colors.mdx +++ b/customization/colors.mdx @@ -25,12 +25,12 @@ QrCode::color(220, 38, 38) ### RGB with Alpha -Add a fourth argument to include an **alpha (transparency) channel**. The scale is **0–100**, where `0` is fully opaque and `100` is fully transparent. +Add a fourth argument to include an **alpha (transparency) channel**. The scale is **0–100**, where `100` is fully opaque and `0` is fully transparent. ```php -// 50 % transparent foreground on a transparent background -QrCode::color(220, 38, 38, 50) - ->backgroundColor(255, 255, 255, 0) +// Semi-transparent blue foreground with alpha channel (60) on light gray background +QrCode::color(30, 64, 175, 60) + ->backgroundColor(241, 245, 249) ->generate('https://example.com'); ``` @@ -77,7 +77,7 @@ Use `gray()` for a one-call shorthand that sets both foreground and (optionally) ```php // Dark gray foreground, light gray background -QrCode::gray(20, 90)->generate('https://example.com'); +QrCode::gray(20, 92)->generate('https://example.com'); // Black foreground, white background (defaults) QrCode::gray(0)->generate('https://example.com'); diff --git a/usage/blade-component.mdx b/usage/blade-component.mdx index f07cc25..19f5746 100644 --- a/usage/blade-component.mdx +++ b/usage/blade-component.mdx @@ -23,7 +23,7 @@ The `<x-qr-code>` Blade component is the simplest way to display QR codes direct <x-qr-code data="https://example.com" /> ``` -This renders an inline SVG QR code. When size and margin are omitted, the component automatically inherits dimensions from `config/qrcode.php` (default size of 400 px and quiet zone margin of 4 modules). No PHP imports or extra configuration needed — the component is auto-registered by the package's service provider. +You render an inline SVG QR code with this Blade component. When you omit `size` and `margin`, the component inherits its dimensions from `config/qrcode.php` (default size of 400 px and quiet zone margin of 4 modules). You do not need PHP imports or extra configuration because the package's service provider registers the component automatically. ## Available props @@ -33,7 +33,7 @@ This renders an inline SVG QR code. When size and margin are omitted, the compon </ParamField> <ParamField path="size" type="int | null" default="null"> - Width and height of the QR code in pixels. When omitted or `null`, the component automatically inherits `size` from `config/qrcode.php` (package default `400`). + Width and height of the QR code in pixels. When you omit `size` or pass `null`, the component inherits `size` from `config/qrcode.php` (package default `400`). </ParamField> <ParamField path="format" type="string" default="svg"> @@ -51,7 +51,7 @@ This renders an inline SVG QR code. When size and margin are omitted, the compon </ParamField> <ParamField path="margin" type="int | null" default="null"> - Quiet-zone margin around the QR code in module units. When omitted or `null`, the component automatically inherits `margin` from `config/qrcode.php` (package default `4` quiet-zone modules). + Quiet-zone margin around the QR code in module units. When you omit `margin` or pass `null`, the component inherits `margin` from `config/qrcode.php` (package default `4` quiet-zone modules). </ParamField> <ParamField path="style" type="string"> diff --git a/usage/facade.mdx b/usage/facade.mdx index ea3865b..a1c26df 100644 --- a/usage/facade.mdx +++ b/usage/facade.mdx @@ -216,15 +216,13 @@ $eps = (string) QrCode::format('eps')->generate('https://example.com'); public function show(Request $request): Response { $result = QrCode::size(300)->generate('https://example.com'); - $etag = md5((string) $result); - if ($request->header('If-None-Match') === $etag) { - return response('', 304); - } + $response = $result->toResponse($request); + $response->setEtag(md5((string) $result)); + $response->header('Cache-Control', 'public, max-age=86400, immutable'); + $response->isNotModified($request); - return $result->toResponse($request) - ->header('ETag', $etag) - ->header('Cache-Control', 'public, max-age=86400, immutable'); + return $response; } ``` </Tab>