Download the PHP package devxisas/qr-studio without Composer

devxisas/qr-studio

A modern QR code studio for Laravel. Inspired by and built upon the foundation of simplesoftwareio/simple-qrcode, this package brings full PHP 8.2+ type safety, enum-based APIs, new data types (vCard, MeCard, Calendar Events), a Blade directive, a response macro, a toDataUri() helper, an Artisan command, and the HasQrCode Eloquent trait — while keeping the same familiar fluent interface.

[!NOTE] Migrating from simplesoftwareio/simple-qrcode? See the migration guide at the bottom of this page.

Requirements

Installation

The service provider is registered automatically via Laravel's package auto-discovery.

PNG generation uses ext-imagick when available, and falls back to ext-gd (installed by default on most servers) when Imagick is not installed. Note: the GD fallback does not support gradients.

To install Imagick for best PNG quality:

Basic Usage

Use the QrCode facade anywhere in your application:

In a Blade template:

Configuration

Publish the config file to set package-wide defaults:

This creates config/qr-studio.php:

These defaults are applied to every QR code generated through the QrCode facade, the @qrcode Blade directive, and the response()->qrcode() macro. Per-call options always take precedence over config defaults.

Note: style, eye, color, gradient, and eyeColor are always per-call — they are not configurable globally as they are visual choices that vary per use case.

Formats

Three output formats are supported. You can pass a string or the Format enum.

PNG and the GD fallback: PNG generation uses ext-imagick when available. When Imagick is not installed the package falls back to ext-gd. The GD fallback works for most use cases, but gradients are not supported under GD — use Imagick if you need gradient PNGs.

Size & Margin

Error Correction

Higher levels allow the QR code to be read even when partially obscured (e.g. with a logo overlay).

Module Styles

Eye Styles

Colors

Foreground & background

Per-eye colors

Each of the three finder eyes (0, 1, 2) can have independent inner and outer colors.

Gradients

Note: Gradients require ext-imagick. They are not supported when falling back to ext-gd.

Image Merging (Logo overlay)

Requires PNG format and ErrorCorrection::High (H) for reliable scanning.

The second argument is the percentage of the QR code the image should occupy (default 0.2).

Data URI (toDataUri)

Generates a base64-encoded data URI — ideal for embedding QR codes in emails, PDFs, or anywhere external URLs are unavailable.

In Blade:

Blade Directive

A @qrcode directive is registered automatically.

When no format argument is passed, the directive reads qr-studio.format from config (default svg). When no size argument is passed, the <img> width/height uses qr-studio.size from config.

SVG output is echoed directly as HTML. PNG and EPS output is wrapped in an <img src="data:..."> tag automatically so no raw binary reaches the browser.

Response Macro

Stream a QR code directly as an HTTP response with the correct Content-Type header.

When size is not passed, the macro uses qr-studio.size from config. The X-Content-Type-Options: nosniff header is always set automatically.

Artisan Command

Generate QR codes from the command line.

Data Types

All data types return an HtmlString just like generate() and follow the same fluent interface.

URL / Plain text

Email

Phone number

SMS

Geo location

WiFi

Bitcoin

vCard 3.0

MeCard (iOS / Android)

Calendar Event (iCal)

Accepts ISO 8601 strings, Unix timestamps, or any DateTimeInterface.

WhatsApp

Generates a wa.me deep-link QR code. Scanning it opens WhatsApp with the number pre-filled and, when a message is provided, the text pre-typed in the message box.

The phone number is normalised to digits only — international format is required (+503 → 503).

Themes

Apply a complete visual preset — colors, gradient, module style, and eye style — with a single call. Any option chained after theme() overrides the preset.

Note: Themes that use dot or round modules automatically set errorCorrection('H') to ensure scannability.

saveToDisk()

Save any QR code directly to a Laravel filesystem disk (local, S3, public, etc.).

Path resolution: when $filename contains no /, the path from config is prepended automatically ('qr.png' → 'qrcodes/qr.png'). Pass a full relative path to override this.

Configure the defaults in config/qr-studio.php:

HasQrCode models also get saveQrCodeToDisk():

HasQrCode Trait

Add QR code generation directly to any Eloquent model. The trait is flexible: return a plain string for URL / text QR codes, or return an array and override qrCodeType() for structured data types (MeCard, vCard, WiFi, etc.).

URL / plain-text model

In Blade:

Structured data types

Return an array from qrCodeData() and override qrCodeType() to match the generator's data type method:

Supported qrCodeType() return values (must match a generator magic method):

Trait API

Combining Options

Options are fully composable via fluent chaining:

API Reference

Complete reference for all public methods on QrCodeGenerator (accessed via the QrCode facade).

generate()

Signature: generate(string $text, ?string $filename = null): HtmlString|string|null

Description: Generates the QR code for the given text. When $filename is provided the output is written to that path and null is returned. Without a filename, an HtmlString is returned (or a plain string outside of Laravel). Calls reset() automatically after execution, so all per-call options are cleared.

Parameters:

Exceptions: WriterException if the underlying BaconQrCode writer fails.

Example:

toDataUri()

Signature: toDataUri(string $text): string

Description: Generates the QR code and returns a base64-encoded data URI. Ideal for embedding in emails, PDFs, or any context where external URLs are blocked. Calls reset() automatically after execution.

• SVG format returns data:image/svg+xml;base64,...
• PNG format returns data:image/png;base64,...

Parameters:

Exceptions: WriterException if the underlying writer fails.

Example:

format()

Signature: format(Format|string $format): static

Description: Sets the output format. Accepts a Format enum (recommended) or the strings 'svg', 'eps', or 'png'.

Parameters:

Exceptions: InvalidArgumentException if a string other than svg, eps, or png is passed.

Example:

size()

Signature: size(int $pixels): static

Description: Sets the width and height of the generated QR code in pixels. Minimum value is 1.

Parameters:

Exceptions: InvalidArgumentException if $pixels is less than 1.

Example:

margin()

Signature: margin(int $margin): static

Description: Sets the quiet zone (whitespace border) around the QR code. Minimum value is 0.

Parameters:

Exceptions: InvalidArgumentException if $margin is negative.

Example:

encoding()

Signature: encoding(string $encoding): static

Description: Sets the character encoding used when encoding the text. The value is converted to uppercase internally. Defaults to UTF-8.

Parameters:

Example:

errorCorrection()

Signature: errorCorrection(ErrorCorrection|string $errorCorrection): static

Description: Sets the error correction level. Higher levels allow the code to be read even when partially obscured (e.g. with a logo). Accepts an ErrorCorrection enum or the strings 'L', 'M', 'Q', 'H'.

Parameters:

Exceptions: InvalidArgumentException if a string other than L, M, Q, or H is passed.

Example:

style()

Signature: style(Style|string $style, float $size = 0.5): static

Description: Sets the module (dot) rendering style. Accepts a Style enum or the strings 'square', 'dot', or 'round'. The $size parameter controls the fill ratio of each module and must be strictly between 0 and 1.

Important: dot and round styles render all pixels as dots, including the three finder-pattern eyes. Without an explicit eye() call the finder squares disappear and scanners fail to orient the code. Always combine style('dot', ...) or style('round', ...) with ->eye('square') or ->eye('circle').

Parameters:

Exceptions: InvalidArgumentException if an invalid style string is passed, or if $size is >= 1 or <= 0.

Example:

eye()

Signature: eye(EyeStyle|string $style): static

Description: Sets the finder-eye (corner square) rendering style. Accepts an EyeStyle enum or the strings 'square', 'circle', or 'pointy'.

Required when using style('dot') or style('round') to ensure the finder pattern remains recognizable to scanners.

Parameters:

Exceptions: InvalidArgumentException if a string other than square, circle, or pointy is passed.

Example:

color()

Signature: color(int $red, int $green, int $blue, ?int $alpha = null): static

Description: Sets the foreground color of the QR code modules. Alpha channel is optional: 0 = fully opaque, 127 = fully transparent.

Parameters:

Example:

backgroundColor()

Signature: backgroundColor(int $red, int $green, int $blue, ?int $alpha = null): static

Description: Sets the background color of the QR code. Alpha channel follows the same convention as color(): 0 = fully opaque, 127 = fully transparent.

Parameters:

Example:

eyeColor()

Signature: eyeColor(int $eyeNumber, int $innerRed, int $innerGreen, int $innerBlue, int $outerRed = 0, int $outerGreen = 0, int $outerBlue = 0): static

Description: Sets the color of one of the three finder eyes independently. $eyeNumber is 0, 1, or 2. Each eye has an inner color (the center dot) and an outer color (the surrounding frame). When only inner colors are provided, outer defaults to black (0, 0, 0).

Parameters:

Exceptions: InvalidArgumentException if $eyeNumber is not 0, 1, or 2.

Example:

gradient()

Signature: gradient(int $startR, int $startG, int $startB, int $endR, int $endG, int $endB, GradientType|string $type): static

Description: Applies a gradient fill to the QR code foreground modules. The gradient runs from the start color to the end color according to the specified type. Only works with SVG format or PNG with ext-imagick installed. Passing a GradientType enum is recommended; strings are accepted for compatibility.

Parameters:

Exceptions: InvalidArgumentException if an invalid gradient type string is passed. RuntimeException at render time if PNG format is used without ext-imagick.

Example:

theme()

Signature: theme(Theme|string $theme): static

Description: Applies a built-in visual preset to the QR code. The preset configures colors, gradient, module style, and eye style in a single call. Any method chained after theme() overrides the corresponding preset value.

Available themes: ocean, sunset, forest, midnight, coral (use the Theme enum or a plain string).

Parameters:

Exceptions: InvalidArgumentException if an unrecognised theme name is passed.

Example:

saveToDisk()

Signature: saveToDisk(string $text, string $filename, ?string $disk = null): string

Description: Generates the QR code and persists it to a Laravel filesystem disk. Returns the storage path where the file was written. Calls reset() automatically after execution.

• When $filename contains no /, the configured path from config('qr-studio.path') is prepended automatically.
• When $disk is null, the configured disk from config('qr-studio.disk') is used.
• The file extension in $filename determines nothing — use format() to control the output format.

Parameters:

Returns: string — the storage path where the file was saved.

Exceptions: WriterException if the QR writer fails. RuntimeException if the disk cannot write.

Example:

merge()

Signature: merge(string $filepath, float $percentage = 0.2, bool $absolute = false): static

Description: Overlays an image (e.g. a logo) centered over the QR code. Only applies when using PNG format — silently has no effect for SVG or EPS. $percentage is the fraction of the QR code's width that the image should occupy (0.0–1.0). When $absolute is false and $filepath does not start with /, the path is prepended with base_path(). Use errorCorrection('H') to ensure the code remains scannable after the overlay.

Parameters:

Exceptions: InvalidArgumentException if the file cannot be read.

Example:

mergeString()

Signature: mergeString(string $content, float $percentage = 0.2): static

Description: Same as merge() but accepts the raw binary content of the image directly instead of a file path. Useful when the image has already been loaded into memory (e.g. fetched via HTTP). Only applies when using PNG format.

Parameters:

Example:

Limitations & Known Issues

1. Dot/Round style without eye() — code will not scan

DotsModule and RoundnessModule in BaconQrCode render every pixel as a dot, including the three finder-pattern eyes. Without those recognizable squares, scanners cannot determine the orientation of the code and will fail to read it, even though the QR data is valid.

Rule: always call ->eye('square') or ->eye('circle') whenever you use style('dot', ...) or style('round', ...).

2. PNG gradient without ext-imagick throws RuntimeException

Gradient rendering for PNG requires Imagick. When only GD is available (the fallback path), calling ->gradient() before generating a PNG throws a RuntimeException at render time — not at configuration time.

Solutions:

• Install ext-imagick for full PNG gradient support.
• Use SVG format instead — gradients always work in SVG with no extra extension required.

3. merge() / mergeString() is PNG-only

Logo overlay is performed using bitmap compositing and silently has no effect when the output format is SVG or EPS. No error is thrown and no warning is emitted — the image just does not appear.

Always combine merge() with format('png') and errorCorrection('H') (H provides 30% redundancy, which compensates for the area covered by the logo).

4. Gradient without eyeColor() may produce low-contrast finder eyes

When eyeColor() is not set, finder eyes inherit the gradient fill. If the gradient produces a light color at the eye positions and the background is also light, the eye borders become invisible and scanners fail.

Solution: Use eyeColor() on all three eyes with high-contrast colors whenever using a gradient.

5. style() size must be strictly less than 1.0

The $size parameter in style('dot', $size) must be in the range (0, 1). Passing 1.0 or any value >= 1 throws an InvalidArgumentException immediately. Values close to 1.0 also produce nearly solid modules with no visible gap between them.

Recommended range: 0.5 to 0.7.

6. Low error correction with dot/round modules reduces scan reliability

Error correction levels L (7%) or M (15%) combined with dot or round modules often produce codes that real-world scanners refuse. The reduced per-module fill area leaves very little redundancy to compensate for noise, printing imperfections, or screen glare.

Always use errorCorrection('H') when using dot or round module styles.

7. EPS format has no browser preview

EPS (Encapsulated PostScript) is a valid vector format understood by print software (Illustrator, InDesign, macOS Preview), but browsers cannot render it inline. Using an EPS data URI in an <img> tag will display nothing.

EPS is intended for print pipelines. Use response()->qrcode('...', Format::Eps) to stream it from a route, or write it to a file with generate($text, $path). For web display, use SVG.

8. State resets automatically after generate() and toDataUri()

Every call to generate() or toDataUri() triggers an internal reset(), clearing all per-call options (format, size, style, colors, etc.) and returning the instance to config defaults. Do not split configuration across multiple statements expecting state to persist:

Enum Reference

All enums are backed enums so they work alongside their string equivalents.

Testing

Migrating from simplesoftwareio/simple-qrcode

This package was built as a modernized continuation of simple-qrcode. The core fluent API is identical, so most projects require only minor changes.

Installation

Facade

That's usually the only change needed. All existing method calls (generate, size, format, color, style, eye, gradient, merge, etc.) work identically.

What's new

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT — see LICENSE.