Laravel QR Code Environment Variables Configuration Guide

Configure QR code defaults via .env without publishing the config file — covers every supported environment variable and color format.

Every option in config/qrcode.php reads from a corresponding environment variable, so you can control package-wide defaults through your .env file without publishing or editing any PHP config. This is ideal for twelve-factor apps, containerized deployments, and multi-environment setups where each environment needs different QR code settings.

All supported environment variables

Add any of the following entries to your .env file. Omitting a variable leaves the built-in default in effect.

.env

# ─── Output format ────────────────────────────────────────────────────────────
# Accepted: svg | png | webp | eps
# Default:  svg
QR_CODE_FORMAT=svg

# ─── Dimensions ───────────────────────────────────────────────────────────────
# Size in pixels (integer)
# Default: 400
QR_CODE_SIZE=400

# Quiet-zone margin in module units (integer)
# Default: 4
QR_CODE_MARGIN=4

# ─── Colors ───────────────────────────────────────────────────────────────────
# Foreground color
# Accepted formats: "R,G,B" | "R,G,B,A" | "#RRGGBB"  (alpha 0–100)
# Default: 0,0,0  (black)
QR_CODE_COLOR="0,0,0"

# Background color — same formats as QR_CODE_COLOR
# Default: 255,255,255  (white)
QR_CODE_BACKGROUND_COLOR="255,255,255"

# ─── Error correction ─────────────────────────────────────────────────────────
# Accepted: L | M | Q | H
# Default:  M
QR_CODE_ERROR_CORRECTION=M

# ─── Encoding ─────────────────────────────────────────────────────────────────
# Default: UTF-8
QR_CODE_ENCODING=UTF-8

# ─── Rendering backend ────────────────────────────────────────────────────────
# Force GD even when Imagick is installed (true | false)
# Default: false
QR_CODE_FORCE_GD=false

Variable reference

QR_CODE_FORMAT · string · default: "svg"

Sets the default image format for every generated QR code.

Value	Notes
svg	Vector format. Scales perfectly at any size. No image extension needed.
png	Raster — requires GD or Imagick
webp	Modern raster — requires GD or Imagick
eps	Vector format for print. Image merging is not supported.

QR_CODE_FORMAT=png

QR_CODE_SIZE · integer · default: "400"

Sets the default pixel dimensions of the generated QR code. For svg and eps this controls the viewBox size; for png and webp it sets the actual pixel dimensions.

QR_CODE_SIZE=300

QR_CODE_MARGIN · integer · default: "4"

Sets the default quiet zone (blank border) around the QR code in module units. The QR code specification recommends a minimum of 4 for reliable scanning.

QR_CODE_MARGIN=2

QR_CODE_COLOR · string · default: "0,0,0"

Sets the default foreground (module) color. Three formats are accepted:

Format	Example value
RGB comma-separated	0,0,0
RGBA comma-separated (alpha 0–100)	0,0,0,100
Hex	#000000

# Deep blue modules
QR_CODE_COLOR=30,64,175

# Red modules with full opacity
QR_CODE_COLOR=255,0,0,100

# Hex shorthand
QR_CODE_COLOR=#1E40AF

QR_CODE_BACKGROUND_COLOR · string · default: "255,255,255"

Sets the default background color. Accepts the same three formats as QR_CODE_COLOR.

# Transparent background (PNG/WebP only)
# Alpha 0 = fully transparent
QR_CODE_BACKGROUND_COLOR=255,255,255,0

# Light gray background
QR_CODE_BACKGROUND_COLOR=243,244,246

QR_CODE_ERROR_CORRECTION · string · default: "M"

Sets the default Reed-Solomon error correction level.

Value	Recovery capacity	When to use
L	~7 %	Clean digital displays
M	~15 %	General purpose (default)
Q	~25 %	Printed materials
H	~30 %	Codes with an embedded logo

# Increase to H when merging a logo into the QR code
QR_CODE_ERROR_CORRECTION=H

QR_CODE_ENCODING · string · default: "UTF-8"

Sets the default character encoding applied to the data payload before it is encoded. Only change this if you need a specific non-Unicode encoding supported by the underlying bacon/bacon-qr-code library.

QR_CODE_ENCODING=UTF-8

QR_CODE_FORCE_GD · boolean · default: "false"

When set to true, the package skips Imagick and renders raster images using PHP’s GD extension, even when Imagick is available. Use this when your server installs Imagick but restricts it via security policies.

QR_CODE_FORCE_GD=true

GD produces lower-quality raster output and lacks some color features available in Imagick. Keep this false in production unless you have a specific compatibility requirement.

Environment-specific examples

Use different defaults for local development vs. production without changing any PHP code:

.env (local)

QR_CODE_FORMAT=svg
QR_CODE_SIZE=200
QR_CODE_COLOR=107,114,128
QR_CODE_ERROR_CORRECTION=L

QR_CODE_FORMAT=png
QR_CODE_SIZE=400
QR_CODE_COLOR=0,0,0
QR_CODE_ERROR_CORRECTION=H
QR_CODE_FORCE_GD=false

Color format reference

The QR_CODE_COLOR and QR_CODE_BACKGROUND_COLOR variables accept three interchangeable string formats. Choose whichever fits your workflow:

Format	.env value	PHP config equivalent
RGB CSV	"255,0,0"	[255, 0, 0]
RGBA CSV (alpha 0–100)	"255,0,0,100"	[255, 0, 0, 100]
Hex	"#FF0000"	—

When using PHP arrays directly in config/qrcode.php (after publishing the config), you can also write:

'color' => [255, 0, 0],           // RGB
'color' => [255, 0, 0, 50],       // RGBA — 50% opacity

Environment variables are read by config/qrcode.php at boot time. You do not need to publish the config file to use env vars. The unpublished config that ships with the package already calls env('QR_CODE_*', ...) for every option. Publishing the config only adds the ability to set PHP array values (such as [R, G, B]) directly in PHP, which is not possible in a .env file.