search

endroid / qr-code

QR Code Generator
https://endroid.nl
MIT License
4.45k stars 726 forks source link
data-uri factory php qrcode reader twig-extension

readme

QR Code

By endroid

Latest Stable Version Build Status Total Downloads Monthly Downloads License

This library helps you generate QR codes in a jiffy. Makes use of bacon/bacon-qr-code to generate the matrix and khanamiryan/qrcode-detector-decoder for validating generated QR codes. Further extended with Twig extensions, generation routes, a factory and a Symfony bundle for easy installation and configuration. Different writers are provided to generate the QR code as PNG, SVG, EPS or in binary format.

Sponsored by

Blackfire.io

Installation

Use Composer to install the library. Also make sure you have enabled and configured the GD extension if you want to generate images.

 composer require endroid/qr-code

Usage: using the builder

use Endroid\QrCode\Builder\Builder;
use Endroid\QrCode\Encoding\Encoding;
use Endroid\QrCode\ErrorCorrectionLevel;
use Endroid\QrCode\Label\LabelAlignment;
use Endroid\QrCode\Label\Font\OpenSans;
use Endroid\QrCode\RoundBlockSizeMode;
use Endroid\QrCode\Writer\PngWriter;

$builder = new Builder(
    writer: new PngWriter(),
    writerOptions: [],
    validateResult: false,
    data: 'Custom QR code contents',
    encoding: new Encoding('UTF-8'),
    errorCorrectionLevel: ErrorCorrectionLevel::High,
    size: 300,
    margin: 10,
    roundBlockSizeMode: RoundBlockSizeMode::Margin,
    logoPath: __DIR__.'/assets/symfony.png',
    logoResizeToWidth: 50,
    logoPunchoutBackground: true,
    labelText: 'This is the label',
    labelFont: new OpenSans(20),
    labelAlignment: LabelAlignment::Center
);

$result = $builder->build();

Usage: without using the builder

use Endroid\QrCode\Color\Color;
use Endroid\QrCode\Encoding\Encoding;
use Endroid\QrCode\ErrorCorrectionLevel;
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Label\Label;
use Endroid\QrCode\Logo\Logo;
use Endroid\QrCode\RoundBlockSizeMode;
use Endroid\QrCode\Writer\PngWriter;
use Endroid\QrCode\Writer\ValidationException;

$writer = new PngWriter();

// Create QR code
$qrCode = new QrCode(
    data: 'Life is too short to be generating QR codes',
    encoding: new Encoding('UTF-8'),
    errorCorrectionLevel: ErrorCorrectionLevel::Low,
    size: 300,
    margin: 10,
    roundBlockSizeMode: RoundBlockSizeMode::Margin,
    foregroundColor: new Color(0, 0, 0),
    backgroundColor: new Color(255, 255, 255)
);

// Create generic logo
$logo = new Logo(
    path: __DIR__.'/assets/symfony.png',
    resizeToWidth: 50,
    punchoutBackground: true
);

// Create generic label
$label = new Label(
    text: 'Label',
    textColor: new Color(255, 0, 0)
);

$result = $writer->write($qrCode, $logo, $label);

// Validate the result
$writer->validateResult($result, 'Life is too short to be generating QR codes');

Usage: working with results


// Directly output the QR code
header('Content-Type: '.$result->getMimeType());
echo $result->getString();

// Save it to a file
$result->saveToFile(__DIR__.'/qrcode.png');

// Generate a data URI to include image data inline (i.e. inside an <img> tag)
$dataUri = $result->getDataUri();

QR Code

Writer options

Some writers provide writer options. Each available writer option is can be found as a constant prefixed with WRITEROPTION in the writer class.

You can provide any writer options like this.

use Endroid\QrCode\Writer\SvgWriter;

$builder = new Builder(
    writer: new SvgWriter(),
    writerOptions: [
        SvgWriter::WRITER_OPTION_EXCLUDE_XML_DECLARATION => true
    ]
);

Encoding

If you use a barcode scanner you can have some troubles while reading the generated QR codes. Depending on the encoding you chose you will have an extra amount of data corresponding to the ECI block. Some barcode scanner are not programmed to interpret this block of information. To ensure a maximum compatibility you can use the ISO-8859-1 encoding that is the default encoding used by barcode scanners (if your character set supports it, i.e. no Chinese characters are present).

Round block size mode

By default block sizes are rounded to guarantee sharp images and improve readability. However some other rounding variants are available.

Readability

The readability of a QR code is primarily determined by the size, the input length, the error correction level and any possible logo over the image so you can tweak these parameters if you are looking for optimal results. You can also check $qrCode->getRoundBlockSize() value to see if block dimensions are rounded so that the image is more sharp and readable. Please note that rounding block size can result in additional padding to compensate for the rounding difference. And finally the encoding (default UTF-8 to support large character sets) can be set to ISO-8859-1 if possible to improve readability.

Validating the generated QR code

If you need to be extra sure the QR code you generated is readable and contains the exact data you requested you can enable the validation reader, which is disabled by default. You can do this either via the builder or directly on any writer that supports validation. See the examples above.

Please note that validation affects performance so only use it in case of problems.

Symfony integration

The endroid/qr-code-bundle integrates the QR code library in Symfony for an even better experience.

Read the bundle documentation for more information.

Versioning

Version numbers follow the MAJOR.MINOR.PATCH scheme. Backwards compatibility breaking changes will be kept to a minimum but be aware that these can occur. Lock your dependencies for production and test your code when upgrading.

License

This bundle is under the MIT license. For the full copyright and license information please view the LICENSE file that was distributed with this source code.