QR Code

https://github.com/endroid/qr-code
Admin
QR Code is a PHP library that helps generate QR codes in various formats including PNG, WebP, SVG,...
Tokens:89,762
Snippets:623
Trust Score:9.6
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example — reading all properties

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/QrCode.md

Example demonstrating how to read all properties from a QrCode instance.

```APIDOC
## Example — reading all properties

### Description
Example demonstrating how to read all properties from a QrCode instance.

### Code
```php
$qrCode = new QrCode('Data', size: 200, margin: 4);

printf("data=%s size=%d margin=%d\n",
    $qrCode->getData(),
    $qrCode->getSize(),
    $qrCode->getMargin()
);
// data=Data size=200 margin=4
```
```

--------------------------------

### Example - working with any result

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Results.md

Shows how to build a QR code with PngWriter and use the result to output directly, save to a file, or get a data URI for an <img> tag.

```php
use Endroid\QrCode\Builder\Builder;
use Endroid\QrCode\Writer\PngWriter;

$result = (new Builder(writer: new PngWriter(), data: 'Hello'))->build();

// Direct output
header('Content-Type: '.$result->getMimeType());
echo $result->getString();

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

// Inline data URI for <img> tags
$dataUri = $result->getDataUri();
```

--------------------------------

### Example — working with any result

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Results.md

Example demonstrating how to use a result object to output, save, or generate a data URI.

```APIDOC
## Example — working with any result

### Description
Example showing how to use a result object to output directly, save to a file, or generate an inline data URI.

### Code
```php
use Endroid\QrCode\Builder\Builder;
use Endroid\QrCode\Writer\PngWriter;

$result = (new Builder(writer: new PngWriter(), data: 'Hello'))->build();

// Direct output
header('Content-Type: '.$result->getMimeType());
echo $result->getString();

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

// Inline data URI for <img> tags
$dataUri = $result->getDataUri();
```
```

--------------------------------

### Example — iterating blocks

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Matrix.md

Example demonstrating how to iterate over all blocks in the matrix and count dark modules.

```APIDOC
## Example — iterating blocks

### Description
Example demonstrating how to iterate over all blocks in the matrix and count dark modules.

### Code
```php
use Endroid\QrCode\Bacon\MatrixFactory;
use Endroid\QrCode\QrCode;

$matrix = (new MatrixFactory())->create(new QrCode('Data'));

$darkCount = 0;
for ($row = 0; $row < $matrix->getBlockCount(); ++$row) {
    for ($column = 0; $column < $matrix->getBlockCount(); ++$column) {
        $darkCount += $matrix->getBlockValue($row, $column);
    }
}
echo "dark modules: $darkCount";
```
```

--------------------------------

### Example — using the trait in a custom writer

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/WriterInterfaces.md

Shows how to create a custom writer by using the GdTrait and delegating the write method to writeGd. Includes a usage example with a new QrCode.

```php
use Endroid\QrCode\Label\LabelInterface;
use Endroid\QrCode\Logo\LogoInterface;
use Endroid\QrCode\QrCodeInterface;
use Endroid\QrCode\Writer\GdTrait;
use Endroid\QrCode\Writer\Result\GdResult;
use Endroid\QrCode\Writer\ValidatingWriterInterface;
use Endroid\QrCode\Writer\WriterInterface;

final readonly class MyGdWriter implements WriterInterface, ValidatingWriterInterface
{
    use GdTrait;

    public function write(QrCodeInterface $qrCode, ?LogoInterface $logo = null, ?LabelInterface $label = null, array $options = []): GdResult
    {
        return $this->writeGd($qrCode, $logo, $label, $options);
    }
}

$result = (new MyGdWriter())->write(new \Endroid\QrCode\QrCode('Hello'));
```

--------------------------------

### Install endroid/qr-code with Composer

Source: https://github.com/endroid/qr-code/blob/main/README.md

Installs the library via Composer. Requires the GD extension to be enabled and configured for image generation.

```bash
 composer require endroid/qr-code

```

--------------------------------

### Example — reading all properties

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/QrCode.md

Creates a QrCode instance with size 200 and margin 4, then prints the data, size, and margin. The output is shown in the comment.

```php
$qrCode = new QrCode('Data', size: 200, margin: 4);

printf("data=%s size=%d margin=%d\n",
    $qrCode->getData(),
    $qrCode->getSize(),
    $qrCode->getMargin()
);
// data=Data size=200 margin=4
```

--------------------------------

### Basic PngWriter example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/PngWriter.md

Creates a PngWriter, writes a QR code, and outputs the PNG image.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PngWriter;

$writer = new PngWriter();
$result = $writer->write(new QrCode('Life is too short to be generating QR codes'));

header('Content-Type: '.$result->getMimeType()); // image/png
echo $result->getString();
```

--------------------------------

### Basic QrCode creation example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/QrCode.md

Creates a QrCode instance with named arguments for all parameters, using UTF-8 encoding, high error correction, and custom colors.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Encoding\Encoding;
use Endroid\QrCode\ErrorCorrectionLevel;
use Endroid\QrCode\Color\Color;

$qrCode = new QrCode(
    data: 'https://example.com',
    encoding: new Encoding('UTF-8'),
    errorCorrectionLevel: ErrorCorrectionLevel::High,
    size: 300,
    margin: 10,
    foregroundColor: new Color(0, 0, 0),
    backgroundColor: new Color(255, 255, 255)
);
```

--------------------------------

### WebPWriter error handling example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/GifAndWebPWriter.md

Example of handling the exception thrown when the GD installation lacks WebP support. The exception message is 'WebP support is not available in your GD installation'.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\WebPWriter;

$writer = new WebPWriter();
$result = $writer->write(new QrCode('Hello'));

try {
    echo $result->getString();
} catch (\Exception $exception) {
    // "WebP support is not available in your GD installation"
    // when the GD build lacks WebP support
    error_log($exception->getMessage());
}
```

--------------------------------

### OpenSans usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Label.md

Shows how to create a Builder with a label text and an OpenSans font of size 20.

```php
use Endroid\QrCode\Label\Font\OpenSans;
use Endroid\QrCode\Builder\Builder;

$builder = new Builder(labelText: 'Hello', labelFont: new OpenSans(20));
```

--------------------------------

### Font usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Label.md

Creates a Font instance with a valid path and size, then demonstrates the exception thrown for an invalid path.

```php
use Endroid\QrCode\Label\Font\Font;

$font = new Font('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', 24);

try {
    new Font('/does/not/exist.ttf');
} catch (\Exception $e) {
    // "Invalid font path "/does/not/exist.ttf""
}
```

--------------------------------

### Catching Exceptions

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/errors.md

Example of how to catch exceptions thrown by the Builder when building a QR code.

```APIDOC
## Catching Exceptions

### Description
This example demonstrates how to catch exceptions thrown by the Builder when building a QR code, including ValidationException and BlockSizeTooSmallException.

### Code Example
php
use Endroid\QrCode\Builder\Builder;
use Endroid\QrCode\Exception\BlockSizeTooSmallException;
use Endroid\QrCode\Exception\ValidationException;

$builder = new Builder(data: 'https://example.com', validateResult: true);

try {
    $result = $builder->build();
} catch (ValidationException $exception) {
    // Validation failed: unsupported writer, missing decoder package,
    // or decoded data mismatch
} catch (BlockSizeTooSmallException $exception) {
    // Too much data for the requested size
} catch (\Exception $exception) {
    // Any other failure (GD missing, invalid logo, invalid font, ...)
}


### Exceptions
- **ValidationException** - Thrown when validation fails (unsupported writer, missing decoder package, or decoded data mismatch).
- **BlockSizeTooSmallException** - Thrown when there is too much data for the requested size.
- **\Exception** - Any other failure (GD missing, invalid logo, invalid font, etc.).
```

--------------------------------

### GifWriter usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/GifAndWebPWriter.md

Example of using GifWriter to render a QR code as a GIF and output it with the correct content type.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\GifWriter;

$writer = new GifWriter();
$result = $writer->write(new QrCode('Hello'));

header('Content-Type: '.$result->getMimeType()); // image/gif
echo $result->getString();
```

--------------------------------

### WebPWriter basic usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/GifAndWebPWriter.md

Example of using WebPWriter to render a QR code as a WebP image with a quality setting of 80.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\WebPWriter;

$writer = new WebPWriter();
$result = $writer->write(new QrCode('Hello'), options: [
    WebPWriter::WRITER_OPTION_QUALITY => 80,
]);

header('Content-Type: '.$result->getMimeType()); // image/webp
echo $result->getString();
```

--------------------------------

### ConsoleWriter usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/OtherWriters.md

Example of using ConsoleWriter to render a QR code and output the ANSI-colored string for terminal display.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\ConsoleWriter;

$result = (new ConsoleWriter())->write(new QrCode('Hello'));
echo $result->getString(); // ANSI-colored QR code for the terminal
```

--------------------------------

### Basic Logo usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Logo.md

Creates a Logo instance with a local PNG file, resizing to width 50 and enabling punchout background. This is a typical usage for GD-based writers.

```php
use Endroid\QrCode\Logo\Logo;

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

--------------------------------

### BinaryWriter usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/OtherWriters.md

Example of using BinaryWriter to render a QR code as a plain-text binary matrix. The result string contains rows of 1s and 0s separated by newlines.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\BinaryWriter;

$result = (new BinaryWriter())->write(new QrCode('Hello'));
echo $result->getString();
// 1010101...
// 0110010...
```

--------------------------------

### PdfWriter basic example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/PdfWriter.md

Basic usage: creates a PdfWriter, writes a QR code, and outputs the PDF with the correct MIME type.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PdfWriter;

$writer = new PdfWriter();
$result = $writer->write(new QrCode('https://example.com'));

header('Content-Type: '.$result->getMimeType()); // application/pdf
echo $result->getString();
```

--------------------------------

### EpsWriter usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/OtherWriters.md

Example of using EpsWriter to generate an EPS QR code and output it with the correct MIME type.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\EpsWriter;

$result = (new EpsWriter())->write(new QrCode('Hello'));
header('Content-Type: '.$result->getMimeType()); // image/eps
echo $result->getString();
```

--------------------------------

### Margin usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Label.md

Creates a Margin instance with top=0, right=10, bottom=10, left=10 and echoes the bottom margin, which outputs 10.

```php
use Endroid\QrCode\Label\Margin\Margin;

$margin = new Margin(top: 0, right: 10, bottom: 10, left: 10);
echo $margin->getBottom(); // 10
```

--------------------------------

### Error handling with SvgResult

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Results.md

Example showing how to write an SVG QR code, post-process the XML, and handle exceptions from getString().

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\SvgWriter;
use Endroid\QrCode\Writer\Result\SvgResult;

$result = (new SvgWriter())->write(new QrCode('Hello'));

if ($result instanceof SvgResult) {
    // Post-process the DOM before serializing
    $result->getXml()->addAttribute('data-source', 'endroid/qr-code');
}

try {
    $string = $result->getString();
} catch (\Exception $exception) {
    // "Could not save SVG XML to string"
    error_log($exception->getMessage());
}
```

--------------------------------

### Full configuration with Builder and SvgWriter

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/configuration.md

Full configuration example for the Endroid QR Code library using the Builder class with an SvgWriter. It sets writer options, encoding, error correction, size, margin, colors, label, and logo. The build() method returns the result.

```php
use Endroid\QrCode\Builder\Builder;
use Endroid\QrCode\Color\Color;
use Endroid\QrCode\Encoding\Encoding;
use Endroid\QrCode\ErrorCorrectionLevel;
use Endroid\QrCode\Label\Font\OpenSans;
use Endroid\QrCode\Label\LabelAlignment;
use Endroid\QrCode\RoundBlockSizeMode;
use Endroid\QrCode\Writer\SvgWriter;

$builder = new Builder(
    writer: new SvgWriter(),
    writerOptions: [
        SvgWriter::WRITER_OPTION_EXCLUDE_XML_DECLARATION => true,
        SvgWriter::WRITER_OPTION_COMPACT => false,
    ],
    validateResult: false,
    data: 'Custom QR code contents',
    encoding: new Encoding('ISO-8859-1'),
    errorCorrectionLevel: ErrorCorrectionLevel::High,
    size: 300,
    margin: 10,
    roundBlockSizeMode: RoundBlockSizeMode::None,
    foregroundColor: new Color(0, 0, 0),
    backgroundColor: new Color(255, 255, 255),
    labelText: 'This is the label',
    labelFont: new OpenSans(20),
    labelAlignment: LabelAlignment::Center,
    logoPath: __DIR__.'/assets/bender.png',
    logoResizeToWidth: 50,
);

$result = $builder->build();
```

--------------------------------

### BuilderRegistry usage example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Builder.md

Shows how to register builders for PNG and SVG writers, retrieve the SVG builder to generate a QR code, and handle the exception thrown when requesting an unregistered builder (e.g., 'pdf').

```php
use Endroid\QrCode\Builder\Builder;
use Endroid\QrCode\Builder\BuilderRegistry;
use Endroid\QrCode\Writer\PngWriter;
use Endroid\QrCode\Writer\SvgWriter;

$registry = new BuilderRegistry();
$registry->set('png', new Builder(writer: new PngWriter()));
$registry->set('svg', new Builder(writer: new SvgWriter()));

$svgResult = $registry->get('svg')->build(data: 'Hello');

try {
    $registry->get('pdf'); // \Exception: Builder with name "pdf" not available from registry
} catch (\Exception $e) {
    error_log($e->getMessage());
}
```

--------------------------------

### BuilderRegistryInterface with set and get methods

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/types.md

Defines a registry for named BuilderInterface instances. Implemented by Endroid\QrCode\Builder\BuilderRegistry.

```php
interface BuilderRegistryInterface
{
    public function set(string $name, BuilderInterface $builder): void;

    public function get(string $name): BuilderInterface;
}

```

--------------------------------

### DebugWriter usage example with Builder

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/OtherWriters.md

Example of using DebugWriter with the Builder to generate a debug dump. The output shows the data, encoding, error correction level, size, and other parameters.

```php
use Endroid\QrCode\Builder\Builder;
use Endroid\QrCode\Writer\DebugWriter;

$result = (new Builder(writer: new DebugWriter(), data: 'Hello', size: 200))
    ->build();

echo $result->getString();
// Data: Hello
// Encoding: UTF-8
// Error Correction Level: Endroid\QrCode\ErrorCorrectionLevel
// Size: 200
// ...
```

--------------------------------

### PdfWriter options and error handling example

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/PdfWriter.md

Advanced usage with options and error handling. Shows how to set unit, offsets, and link, and how to draw into an existing FPDF document. Catches exceptions for missing FPDF or alpha channel issues.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PdfWriter;

$writer = new PdfWriter();

try {
    $result = $writer->write(
        qrCode: new QrCode('https://example.com'),
        options: [
            PdfWriter::WRITER_OPTION_UNIT => 'mm',
            PdfWriter::WRITER_OPTION_X => 10,
            PdfWriter::WRITER_OPTION_Y => 10,
            PdfWriter::WRITER_OPTION_LINK => 'https://example.com',
        ]
    );

    // Draw into an existing multi-page document
    $fpdf = new \FPDF();
    $fpdf->AddPage();
    $result2 = $writer->write(new QrCode('Page 2'), options: [
        PdfWriter::WRITER_OPTION_PDF => $fpdf,
        PdfWriter::WRITER_OPTION_Y => 100,
    ]);
} catch (\Exception $exception) {
    // e.g. "Unable to find FPDF: check your installation" (setasign/fpdf not installed)
    // or "PDF Writer does not support alpha channels" (colors with alpha > 0)
    error_log($exception->getMessage());
}
```

--------------------------------

### Example — validation error handling

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/WriterInterfaces.md

Demonstrates catching ValidationException when validating a PNG writer's result. The exception message indicates either a missing package or a data mismatch.

```php
use Endroid\QrCode\Exception\ValidationException;
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PngWriter;

$writer = new PngWriter();
$qrCode = new QrCode('Life is too short to be generating QR codes');
$result = $writer->write($qrCode);

try {
    $writer->validateResult($result, 'Life is too short to be generating QR codes');
} catch (ValidationException $exception) {
    // "Please install "khanamiryan/qrcode-detector-decoder" or disable image validation"
    // or "The validation reader read "..." instead of "...". Adjust your parameters..."
    error_log($exception->getMessage());
}
```

--------------------------------

### Error handling example for LogoImageData::createForLogo

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/ImageData.md

Shows how to catch exceptions when creating logo data from invalid paths. The first try block demonstrates the 'Could not read logo image data from path' exception, and the second demonstrates the 'Logo path is not an image' exception.

```php
use Endroid\QrCode\ImageData\LogoImageData;
use Endroid\QrCode\Logo\Logo;

try {
    LogoImageData::createForLogo(new Logo('/my/invalid/path.png'));
} catch (\Exception $exception) {
    // "Could not read logo image data from path "/my/invalid/path.png": ..."
    error_log($exception->getMessage());
}

try {
    LogoImageData::createForLogo(new Logo(__DIR__.'/QrCodeTest.php'));
} catch (\Exception $exception) {
    // "Logo path is not an image"
    error_log($exception->getMessage());
}
```

--------------------------------

### Using ErrorCorrectionLevel in QrCode

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Enums.md

Shows how to create a QrCode with a specific error correction level and access the backing value. The example uses High, but any case can be used. The output is the string 'high'.

```php
use Endroid\QrCode\ErrorCorrectionLevel;
use Endroid\QrCode\QrCode;

$qrCode = new QrCode(
    data: 'https://example.com',
    errorCorrectionLevel: ErrorCorrectionLevel::High
);

echo ErrorCorrectionLevel::High->value; // "high"
```

--------------------------------

### Usage with a writer and error handling

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Color.md

Creates a QrCode with custom foreground and background colors, writes it with PngWriter, and outputs the data URI. Catches exceptions like missing GD extension.

```php
use Endroid\QrCode\Color\Color;
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PngWriter;

$qrCode = new QrCode(
    data: 'https://example.com',
    foregroundColor: new Color(20, 40, 90),
    backgroundColor: new Color(255, 255, 255, 0) // fully opaque white
);

$writer = new PngWriter();
try {
    $result = $writer->write($qrCode);
    echo $result->getDataUri(); // data:image/png;base64,...
} catch (\Exception $exception) {
    // e.g. "Unable to generate image: please check if the GD extension is enabled..."
    error_log($exception->getMessage());
}
```

--------------------------------

### Basic usage of MatrixFactory

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Bacon.md

Creates a MatrixFactory instance and uses it to create a matrix from a QrCode with data 'Hello'. Outputs the block count and outer size.

```php
use Endroid\QrCode\Bacon\MatrixFactory;
use Endroid\QrCode\QrCode;

$matrixFactory = new MatrixFactory();
$matrix = $matrixFactory->create(new QrCode('Hello'));

echo $matrix->getBlockCount();   // e.g. 25
echo $matrix->getOuterSize();    // size + 2 * margin
```

--------------------------------

### Create Matrix via MatrixFactory

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Matrix.md

Creates a Matrix via Bacon\MatrixFactory from a QrCode and prints block count, block size, and outer size. Requires the Endroid QR Code library.

```php
use Endroid\QrCode\Bacon\MatrixFactory;
use Endroid\QrCode\QrCode;

$matrixFactory = new MatrixFactory();
$matrix = $matrixFactory->create(new QrCode('Hello'));

printf("blocks: %d, block size: %.2f, outer: %d\n",
    $matrix->getBlockCount(),
    $matrix->getBlockSize(),
    $matrix->getOuterSize()
);
```

--------------------------------

### Example of ErrorCorrectionLevelConverter

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Bacon.md

Converts ErrorCorrectionLevel::High to BaconErrorCorrectionLevel::valueOf('H') and checks equality.

```php
use BaconQrCode\Common\ErrorCorrectionLevel as BaconErrorCorrectionLevel;
use Endroid\QrCode\Bacon\ErrorCorrectionLevelConverter;
use Endroid\QrCode\ErrorCorrectionLevel;

$baconLevel = ErrorCorrectionLevelConverter::convertToBaconErrorCorrectionLevel(ErrorCorrectionLevel::High);
// $baconLevel === BaconErrorCorrectionLevel::valueOf('H')
```

--------------------------------

### PdfWriter::write

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/PdfWriter.md

Documentation for the PdfWriter::write method, including parameters, options, return type, exceptions, and usage examples.

```APIDOC
## PdfWriter::write

### Description
Renders a QR code into a PDF document using the FPDF library. The writer either creates a new FPDF document or draws into a user-supplied `\FPDF` instance.

### Method
`write`

### Signature
```php
public function write(QrCodeInterface $qrCode, ?LogoInterface $logo = null, ?LabelInterface $label = null, array $options = []): ResultInterface
```

### Parameters
- **qrCode** (`QrCodeInterface`) - Required - The QR code to render.
- **logo** (`?LogoInterface`) - Optional - Optional logo, placed via `FPDF::Image()`.
- **label** (`?LabelInterface`) - Optional - Optional label; reserves 30 units of vertical space and renders centered text.
- **options** (`array<string, mixed>`) - Optional - See options below.

### Options
- **unit** (`string`) - Default `'mm'` - PDF measure unit; must be one of `mm`, `pt`, `cm`, `in`.
- **fpdf** (`\FPDF`) - Default `new \FPDF('P', $unit, [$matrix->getOuterSize(), $matrix->getOuterSize() + $labelSpace])` - Existing FPDF document to draw into; a new document with an added page is created when omitted.
- **x** (`float`/`int`) - Default `0` - Horizontal offset of the QR code within the page.
- **y** (`float`/`int`) - Default `0` - Vertical offset of the QR code within the page.
- **link** (`string`) - Optional - URL or identifier returned by `FPDF::AddLink()`; makes the QR code area clickable via `FPDF::Link()`.

### Return Type
`ResultInterface` — concretely a `PdfResult`, MIME type `application/pdf`.

### Throws
- `\Exception` - `'PDF Measure unit should be one of [mm, pt, cm, in]'` when `unit` is not allowed.
- `\Exception` - `'Unable to find FPDF: check your installation'` when class `\FPDF` does not exist.
- `\Exception` - `'PDF Writer does not support alpha channels'` when foreground or background alpha > 0.
- `\Exception` - `'pdf option must be an instance of FPDF'` when `fpdf` option is not an `\FPDF`.
- `\Exception` - `'Unable to read image size for logo "%s"'` when `getimagesize()` fails on the logo path.

### Example — basic
```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PdfWriter;

$writer = new PdfWriter();
$result = $writer->write(new QrCode('https://example.com'));

header('Content-Type: '.$result->getMimeType()); // application/pdf
echo $result->getString();
```

### Example — options and error handling
```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PdfWriter;

$writer = new PdfWriter();

try {
    $result = $writer->write(
        qrCode: new QrCode('https://example.com'),
        options: [
            PdfWriter::WRITER_OPTION_UNIT => 'mm',
            PdfWriter::WRITER_OPTION_X => 10,
            PdfWriter::WRITER_OPTION_Y => 10,
            PdfWriter::WRITER_OPTION_LINK => 'https://example.com',
        ]
    );

    // Draw into an existing multi-page document
    $fpdf = new \FPDF();
    $fpdf->AddPage();
    $result2 = $writer->write(new QrCode('Page 2'), options: [
        PdfWriter::WRITER_OPTION_PDF => $fpdf,
        PdfWriter::WRITER_OPTION_Y => 100,
    ]);
} catch (\Exception $exception) {
    // e.g. "Unable to find FPDF: check your installation" (setasign/fpdf not installed)
    // or "PDF Writer does not support alpha channels" (colors with alpha > 0)
    error_log($exception->getMessage());
}
```
```

--------------------------------

### build

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Builder.md

Renders a QR code using the configured writer and options, with optional per-call overrides for all QR code, label, and logo settings. Returns a ResultInterface instance representing the generated QR code.

```APIDOC
## build

### Description
Renders a QR code using the configured writer and options, with optional per-call overrides for all QR code, label, and logo settings. Returns a ResultInterface instance representing the generated QR code.

### Method
build

### Signature
```php
public function build(
    ?WriterInterface $writer = null,
    ?array $writerOptions = null,
    ?bool $validateResult = null,
    // QrCode options
    ?string $data = null,
    ?EncodingInterface $encoding = null,
    ?ErrorCorrectionLevel $errorCorrectionLevel = null,
    ?int $size = null,
    ?int $margin = null,
    ?RoundBlockSizeMode $roundBlockSizeMode = null,
    ?ColorInterface $foregroundColor = null,
    ?ColorInterface $backgroundColor = null,
    // Label options
    ?string $labelText = null,
    ?FontInterface $labelFont = null,
    ?LabelAlignment $labelAlignment = null,
    ?MarginInterface $labelMargin = null,
    ?ColorInterface $labelTextColor = null,
    // Logo options
    ?string $logoPath = null,
    ?int $logoResizeToWidth = null,
    ?int $logoResizeToHeight = null,
    ?bool $logoPunchoutBackground = null,
): ResultInterface
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `writer` | `?WriterInterface` | no | `null` (constructor value) | Writer override for this call |
| `writerOptions` | `?array<mixed>` | no | `null` (constructor value) | Writer options override |
| `validateResult` | `?bool` | no | `null` (constructor value) | Validation override |
| `data` | `?string` | no | `null` (constructor value) | Payload override |
| `encoding` | `?EncodingInterface` | no | `null` (constructor value) | Encoding override |
| `errorCorrectionLevel` | `?ErrorCorrectionLevel` | no | `null` (constructor value) | ECL override |
| `size` | `?int` | no | `null` (constructor value) | Size override |
| `margin` | `?int` | no | `null` (constructor value) | Margin override |
| `roundBlockSizeMode` | `?RoundBlockSizeMode` | no | `null` (constructor value) | Rounding mode override |
| `foregroundColor` | `?ColorInterface` | no | `null` (constructor value) | Foreground override |
| `backgroundColor` | `?ColorInterface` | no | `null` (constructor value) | Background override |
| `labelText` | `?string` | no | `null` (constructor value) | Label text override |
| `labelFont` | `?FontInterface` | no | `null` (constructor value) | Label font override |
| `labelAlignment` | `?LabelAlignment` | no | `null` (constructor value) | Label alignment override |
| `labelMargin` | `?MarginInterface` | no | `null` (constructor value) | Label margin override |
| `labelTextColor` | `?ColorInterface` | no | `null` (constructor value) | Label color override |
| `logoPath` | `?string` | no | `null` (constructor value) | Logo path override |
| `logoResizeToWidth` | `?int` | no | `null` (constructor value) | Logo width override |
| `logoResizeToHeight` | `?int` | no | `null` (constructor value) | Logo height override |
| `logoPunchoutBackground` | `?bool` | no | `null` (constructor value) | Logo punchout override |

### Return Type
`ResultInterface` — the render result produced by the writer (see [Results.md](Results.md)). The concrete class depends on the writer: `PngResult` for `PngWriter`, `SvgResult` for `SvgWriter`, etc.

### Throws

| Error | Condition |
|-------|-----------|
| `ValidationException` | `validateResult` is `true` and the constructor-configured writer does not implement `ValidatingWriterInterface` |
| `ValidationException` | `validateResult` is `true` and the decoded result does not match the input data |
| `BlockSizeTooSmallException` | QR code matrix cannot fit in the requested size |
| `\Exception` | Writer failures (e.g. GD extension missing, invalid logo path, PDF unit invalid) |

### Behavior Notes
- If `validateResult` is `true` and the configured writer is not a `ValidatingWriterInterface`, `ValidationException::createForUnsupportedWriter(get_class($this->writer))` is thrown — note this check uses the *constructor-configured* writer, not the per-call override.
- A label is created when `$this->labelText || $labelText` is truthy; a logo when `$this->logoPath || $logoPath` is truthy.
- After writing, if `validateResult` is `true` and the writer implements `ValidatingWriterInterface`, `$writer->validateResult($result, $qrCode->getData())` is invoked.
```

--------------------------------

### Minimal QrCode creation with error handling

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/QrCode.md

Creates a QrCode with only the required data argument, then attempts to build the matrix. Catches BlockSizeTooSmallException when data is too large for the size, and retries with a larger size.

```php
use Endroid\QrCode\QrCode;
use Endroid\QrCode\Bacon\MatrixFactory;
use Endroid\QrCode\Exception\BlockSizeTooSmallException;

// Only the data argument is required; everything else falls back to defaults
$qrCode = new QrCode('Hello world');

$matrixFactory = new MatrixFactory();
try {
    $matrixFactory->create($qrCode);
} catch (BlockSizeTooSmallException $exception) {
    // "Too much data: increase image dimensions or lower error correction level"
    // Occurs when size / blockCount < 1, typically when data is long and size small.
    $qrCode = new QrCode('Hello world', size: 400);
}
```

--------------------------------

### Basic Color instantiation

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Color.md

Creates opaque black, opaque white, and semi-transparent red Color instances. Alpha 63 gives approximately 50% opacity.

```php
use Endroid\QrCode\Color\Color;

$black = new Color(0, 0, 0);          // opaque black
$white = new Color(255, 255, 255);    // opaque white
$semiTransparentRed = new Color(255, 0, 0, 63); // red at ~50% opacity
```

--------------------------------

### Constructor

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Color.md

Creates a new Color instance with red, green, blue, and optional alpha values. Alpha is on a 0-127 scale where 0 is opaque and 127 is fully transparent.

```APIDOC
## Constructor

### Description
Creates a new Color instance with the specified RGBA values. The alpha channel is optional and defaults to 0 (fully opaque).

### Method
`__construct`

### Parameters
- `red` (int, 0-255) - Required - Red channel value.
- `green` (int, 0-255) - Required - Green channel value.
- `blue` (int, 0-255) - Required - Blue channel value.
- `alpha` (int, 0-127) - Optional - Alpha channel value, 0 = opaque, 127 = fully transparent. Defaults to 0.

### Return Type
A `Color` instance.

### Example
```php
use Endroid\QrCode\Color\Color;

$black = new Color(0, 0, 0);          // opaque black
$white = new Color(255, 255, 255);    // opaque white
$semiTransparentRed = new Color(255, 0, 0, 63); // red at ~50% opacity
```
```

--------------------------------

### Builder::__construct

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Builder.md

Creates a new Builder instance with configurable options for the QR code, label, and logo. All parameters are optional and have sensible defaults.

```APIDOC
## Builder::__construct

### Description
Creates a new Builder instance with configurable options for the QR code, label, and logo. All parameters are optional and have sensible defaults.

### Method
Constructor

### Signature
```php
public function __construct(
    private WriterInterface $writer = new PngWriter(),
    /** @var array<mixed> */
    private array $writerOptions = [],
    private bool $validateResult = false,
    // QrCode options
    private string $data = '',
    private EncodingInterface $encoding = new Encoding('UTF-8'),
    private ErrorCorrectionLevel $errorCorrectionLevel = ErrorCorrectionLevel::Low,
    private int $size = 300,
    private int $margin = 10,
    private RoundBlockSizeMode $roundBlockSizeMode = RoundBlockSizeMode::Margin,
    private ColorInterface $foregroundColor = new Color(0, 0, 0),
    private ColorInterface $backgroundColor = new Color(255, 255, 255),
    // Label options
    private string $labelText = '',
    private FontInterface $labelFont = new Font(__DIR__.'/../../assets/open_sans.ttf', 16),
    private LabelAlignment $labelAlignment = LabelAlignment::Center,
    private MarginInterface $labelMargin = new Margin(0, 10, 10, 10),
    private ColorInterface $labelTextColor = new Color(0, 0, 0),
    // Logo options
    private string $logoPath = '',
    private ?int $logoResizeToWidth = null,
    private ?int $logoResizeToHeight = null,
    private bool $logoPunchoutBackground = false,
)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `writer` | `WriterInterface` | no | `new PngWriter()` | Writer used to render the result |
| `writerOptions` | `array<mixed>` | no | `[]` | Options passed through to the writer (see [configuration.md](../configuration.md)) |
| `validateResult` | `bool` | no | `false` | When `true`, the result is decoded and compared against the input data after writing |
| `data` | `string` | no | `''` | QR code payload |
| `encoding` | `EncodingInterface` | no | `new Encoding('UTF-8')` | Character encoding of the payload |
| `errorCorrectionLevel` | `ErrorCorrectionLevel` | no | `ErrorCorrectionLevel::Low` | Error correction level |
| `size` | `int` | no | `300` | QR code size in pixels (excluding margin) |
| `margin` | `int` | no | `10` | Quiet-zone margin in pixels |
| `roundBlockSizeMode` | `RoundBlockSizeMode` | no | `RoundBlockSizeMode::Margin` | Block rounding mode |
| `foregroundColor` | `ColorInterface` | no | `new Color(0, 0, 0)` | Dark module color |
| `backgroundColor` | `ColorInterface` | no | `new Color(255, 255, 255)` | Light module / background color |
| `labelText` | `string` | no | `''` | Text of the label rendered below the QR code; empty string disables the label |
| `labelFont` | `FontInterface` | no | `new Font(__DIR__.'/../../assets/open_sans.ttf', 16)` | TTF font used for the label (bundled Open Sans, size 16) |
| `labelAlignment` | `LabelAlignment` | no | `LabelAlignment::Center` | Horizontal label alignment |
| `labelMargin` | `MarginInterface` | no | `new Margin(0, 10, 10, 10)` | Label margins (top, right, bottom, left) |
| `labelTextColor` | `ColorInterface` | no | `new Color(0, 0, 0)` | Label text color |
| `logoPath` | `string` | no | `''` | Path or URL of the logo image; empty string disables the logo |
| `logoResizeToWidth` | `?int` | no | `null` | Target logo width in pixels; `null` keeps aspect ratio from source |
| `logoResizeToHeight` | `?int` | no | `null` | Target logo height in pixels; `null` keeps aspect ratio from source |
| `logoPunchoutBackground` | `bool` | no | `false` | When `true`, the area behind the logo is made transparent (GD writers only) |
```

--------------------------------

### Pass writer options to Builder for SvgWriter

Source: https://github.com/endroid/qr-code/blob/main/README.md

Provide writer options to the Builder constructor. This example sets the exclude_xml_declaration option for the SVG writer, but the same pattern applies to other writers with their respective options.

```php
use Endroid\QrCode\Writer\SvgWriter;

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

--------------------------------

### Error handling example for line breaks

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/ImageData.md

Shows how to catch the exception thrown when the label text contains a line break (\n). The exception message is 'Label does not support line breaks'.

```php
use Endroid\QrCode\ImageData\LabelImageData;
use Endroid\QrCode\Label\Label;

try {
    LabelImageData::createForLabel(new Label("line1\nline2"));
} catch (\Exception $exception) {
    // "Label does not support line breaks"
    error_log($exception->getMessage());
}
```

--------------------------------

### Logo Constructor

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Logo.md

Creates a new Logo instance with the specified path and optional resize and punchout settings.

```APIDOC
## Logo Constructor

### Description
Creates a new Logo instance with the specified path and optional resize and punchout settings.

### Method
Constructor

### Signature
```php
public function __construct(
    private string $path,
    private ?int $resizeToWidth = null,
    private ?int $resizeToHeight = null,
    private bool $punchoutBackground = false,
)
```

### Parameters
- **path** (string) - Required - Local file path or URL of the logo image (PNG, GIF, JPEG, WebP, or SVG)
- **resizeToWidth** (?int) - Optional - Target width in pixels; null keeps the source width
- **resizeToHeight** (?int) - Optional - Target height in pixels; null keeps the source height
- **punchoutBackground** (bool) - Optional - When true, the background behind the logo is made transparent (GD writers only)

### Notes
- Both resizeToWidth and resizeToHeight set: used as-is.
- Only resizeToWidth set: height = imagesy * width / imagesx (aspect preserved).
- Only resizeToHeight set: width = imagesx * height / imagesy (aspect preserved).
- Neither set: original image dimensions used.
- SVG logos require both resizeToWidth and resizeToHeight explicitly — otherwise \Exception('SVG Logos require an explicitly set resize width and height').

### Example
```php
use Endroid\QrCode\Logo\Logo;

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

--------------------------------

### Catch invalid encoding exception with Encoding

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Encoding.md

Handles invalid encoding errors. Throws an exception if the value is not `'UTF-8'` and either the mbstring extension is missing (message about mbstring) or the value is not in `mb_list_encodings()` (message includes the invalid value). The example logs the exception message.

```php
use Endroid\QrCode\Encoding\Encoding;

try {
    new Encoding('not-a-real-encoding');
} catch (\Exception $exception) {
    // "Invalid encoding "not-a-real-encoding": choose one of ..."
    // (requires ext-mbstring; without it the message is about mbstring)
    error_log($exception->getMessage());
}
```

--------------------------------

### Output, save, or get data URI from QR code result

Source: https://github.com/endroid/qr-code/blob/main/README.md

Use the result object to either output the QR code directly, save it to a file, or generate a data URI for inline embedding. The code assumes $result is available from a previous step.

```php
// 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();
```

--------------------------------

### MatrixFactoryInterface create method

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Matrix.md

Interface for factories that create a MatrixInterface from a QrCodeInterface. Implemented by Endroid\QrCode\Bacon\MatrixFactory.

```php
interface MatrixFactoryInterface
{
    public function create(QrCodeInterface $qrCode): MatrixInterface;
}
```

--------------------------------

### getSize method signature

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/QrCode.md

Returns the requested QR code size in pixels (excluding margin).

```php
public function getSize(): int
```

--------------------------------

### getPath method

Source: https://github.com/endroid/qr-code/blob/main/_autodocs/api-reference/Logo.md

Returns the logo file path or URL.

```php
public function getPath(): string
```
Tokens:
Raw