tonsoo/php-qr-code

A library for generating qr-codes in various formats and configurations

v0.1.0 2026-07-20 23:27 UTC

Requires

• php: ^8.1
• bacon/bacon-qr-code: ^3.1
• kaareln/php-svg-path-data: ^1.0

Requires (Dev)

• phpunit/phpunit: ^10.5

Suggests

• ext-gd: Required for PNG, JPEG and WebP rendering.

MIT

• Alysson

Published on Packagist.org on 2026-07-20 23:33 UTC

README

A QR code styling and rendering library for PHP.

tonsoo/php-qr-code separates QR encoding from styling and rendering so the package can focus on how a QR code looks: module shapes, finder styling, logo placement, SVG output, and raster output.

Status

Current focus:

• Matrix encoding through bacon/bacon-qr-code
• Styling through QRCode, ModuleStyle, EyeStyle, and Logo
• SVG output with vector-native shape rendering
• PNG/JPEG/WebP output through GD
• Center logo support with safety validation
• CLI example under examples/cli.php

Installation

composer require php-qr-code

For raster output you also need GD:

sudo apt install php-gd

Quick Start

Helper API

<?php

use Tonsoo\QrCode\Styling\ModuleStyle;

$svg = qrCode('https://example.com')
    ->size(640)
    ->margin(32)
    ->foreground('#5a1f14')
    ->modules(ModuleStyle::classyRounded(1.0))
    ->toSvg();

Factory API

<?php

use Tonsoo\QrCode\ErrorCorrection;
use Tonsoo\QrCode\QRCodeFactory;
use Tonsoo\QrCode\Styling\EyeStyle;
use Tonsoo\QrCode\Styling\ModuleStyle;

$qrCode = (new QRCodeFactory())
    ->errorCorrection(ErrorCorrection::High)
    ->make('https://example.com')
    ->size(768)
    ->background('#ffffff')
    ->modules(
        ModuleStyle::classyRounded(1.0)
            ->color('#670908')
    )
    ->eyes(
        EyeStyle::square()
            ->outerColor('#4e0201')
            ->innerColor('#4e0201')
    );

$qrCode->save('qr.svg');
$qrCode->save('qr.png');

Public API

Creation

• qrCode(string $data): QRCode
• QRCodeFactory::create(string $data): QRCode
• (new QRCodeFactory())->make(string $data): QRCode
• QRCode::fromMatrix(MatrixInterface $matrix, ErrorCorrection $errorCorrection = ErrorCorrection::Medium): QRCode

QRCode styling

• ->size(int $pixels)
• ->margin(int $pixels)
• ->background(string $color)
• ->foreground(string $color)
• ->modules(ModuleStyle $style)
• ->eyes(EyeStyle $style)
• ->eyePupils(ModuleStyle $style)
• ->style(ModuleType $type, ModuleStyle $style)
• ->logo(Logo $logo)

Output

• ->toSvg()
• ->toPng()
• ->toJpeg()
• ->toWebp()
• ->save(string $path)
• ->render(RendererInterface $renderer)

Shapes

Built-in module shapes:

• ModuleStyle::square()
• ModuleStyle::circle()
• ModuleStyle::rounded(float $roundness = 0.35)
• ModuleStyle::classyRounded(float $roundness = 0.85)
• ModuleStyle::diamond()
• ModuleStyle::custom(Closure $callback, ?ShapeSafety $safety = null, string $name = 'custom')

classy-rounded is neighbor-aware and is intended to approximate the popular QR styling variants used by tools such as Mini QR / qr-code-styling.

Custom shapes

Custom shapes receive a ShapeContext and return a vector Path.

<?php

use Tonsoo\QrCode\Geometry\Path;
use Tonsoo\QrCode\Shapes\ShapeContext;
use Tonsoo\QrCode\Shapes\ShapeSafety;
use Tonsoo\QrCode\Styling\ModuleStyle;

$style = ModuleStyle::custom(
    callback: function (ShapeContext $context): Path {
        $x = $context->x;
        $y = $context->y;
        $s = $context->size;

        return new Path("M{$x} {$y}h{$s}v{$s}h-{$s}z");
    },
    safety: new ShapeSafety(minimumCoverageRatio: 0.7, supportsRasterRendering: false),
    name: 'my-shape',
);

Logos

Logos are placed in the center of the QR code and reserve a clean exclusion area behind them.

<?php

use Tonsoo\QrCode\Styling\Logo;

$logo = Logo::fromPath('logo.svg')
    ->size(0.16)
    ->padding(18)
    ->background('#ffffff');

SVG logo handling

SvgRenderer supports four logo modes through SvgLogoMode:

• SvgLogoMode::Auto
• SvgLogoMode::Path
• SvgLogoMode::DataUri
• SvgLogoMode::InlineSvg

Auto is the default. SVG files are normally inlined as nested SVG so the final output stays vector-native.

Error Correction

The package uses the four QR standard levels:

• ErrorCorrection::Low
• ErrorCorrection::Medium
• ErrorCorrection::Quartile
• ErrorCorrection::High

Higher correction improves resilience but there is no level above High in the QR standard.

CLI Example

The repository ships with a minimal CLI in examples/cli.php.

php examples/cli.php \
  --data="https://example.com" \
  --output="qr.svg" \
  --modules-shape="classy-rounded" \
  --modules-roundness=1.0 \
  --foreground="#670908"

Logo example:

php examples/cli.php \
  --data="https://example.com" \
  --output="qr.svg" \
  --error-correction=H \
  --modules-shape="classy-rounded" \
  --modules-roundness=1.0 \
  --logo="./logo.svg" \
  --logo-size=0.16 \
  --logo-padding=18 \
  --svg-logo-mode="inline-svg"

Show all options:

php examples/cli.php --help

Architecture

The package is split into a few layers:

• Encoding/: QR matrix generation adapters
• Matrix/: matrix abstraction
• Layout/: classifies dark modules into finder/data/timing/alignment types
• Shapes/ and Geometry/: shape logic and reusable vector geometry
• Styling/: expressive styling objects used by the public API
• Rendering/: SVG and GD renderers
• Validation/: safety checks such as logo coverage validation

Automated Tests

The repository uses PHPUnit.

Run all tests:

composer test

or directly:

vendor/bin/phpunit --configuration phpunit.xml

Covered areas currently include:

• matrix validation
• logo placement helpers
• SVG renderer basics
• logo safety validation
• enum-backed renderer options

Notes

• SVG rendering is the primary path for advanced styling.
• Raster rendering currently supports the core built-in shapes and depends on GD.
• Large logos or aggressive padding are intentionally rejected when they are likely to make the QR unreadable.