Chillerlan PHP QR Code

https://github.com/chillerlan/php-qrcode
Admin
Chillerlan PHP QR Code is a PHP library for generating and reading QR Codes, supporting Model 2...
Tokens:192,245
Snippets:1,136
Trust Score:9.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Sphinx dependencies

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Readme.md

Install the required Python packages for building the Sphinx documentation locally.

```bash
pip install sphinx myst-parser sphinx-rtd-theme
```

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

### Install php-qrcode via Composer

Source: https://github.com/chillerlan/php-qrcode/blob/main/README.md

Install the php-qrcode package using Composer in the terminal. This is the standard installation method.

```bash
composer require chillerlan/php-qrcode
```

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

### Class skeleton extending QROutputAbstract

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Starts a custom output class by extending QROutputAbstract and implementing the required methods from QROutputInterface.

```php
class MyCustomOutput extends QROutputAbstract{

	public static function moduleValueIsValid($value):bool{}

	protected function prepareModuleValue($value){}

	protected function getDefaultModuleValue(bool $isDark){}

	public function dump(string $file = null){}

}
```

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

### Import the library and autoloader

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Quickstart.md

Use this to import the main classes and include the autoloader if necessary.

```php
use chillerlan\QRCode\{QRCode, QROptions};

require_once __DIR__.'/../vendor/autoload.php';
```

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

### Install php-qrcode via Composer terminal

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Installation.md

Installs the php-qrcode package using Composer from the terminal. The first command installs the latest version; the second installs a specific tag (4.3.4) or commit hash.

```shell
composer require chillerlan/php-qrcode
```

```shell
composer require chillerlan/php-qrcode:4.3.4
```

```shell
composer require chillerlan/php-qrcode:dev-main#f15b0afe9d4128bf734c3bf1bcffae72bf7b3e53
```

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

### Quickstart: Render QR code from URI

Source: https://github.com/chillerlan/php-qrcode/blob/main/README.md

Encodes an otpauth URI into a QR code image and outputs an HTML img tag. Uses the QRCode class's render method.

```php
$data = 'otpauth://totp/test?secret=B3JX4VCVJDVNXNZ5&issuer=chillerlan.net';

// quick and simple:
echo '<img src="'.(new QRCode)->render($data).'" alt="QR Code" />';
```

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

### Example output of custom QR code render

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Shows the expected output format from the custom output class: section headers with module type name and binary mask, followed by coordinates of modules.

```none
these-modules-are-light (000000000010)

x: 0, y: 0
x: 1, y: 0
x: 2, y: 0
...

here-is-a-dark-module (100000000010)

x: 4, y: 4
x: 5, y: 4
x: 6, y: 4
...
```

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

### Return image resource for post-processing

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Set outputInterface to QRImagick and returnResource to true to get the internal image resource. The example shows retrieving the image blob from the Imagick object.

```php
$options->outputInterface = QRImagick::class;
$options->returnResource  = true;

/** @var Imagick $imagick */
$imagick = $qrcode->render($data);

echo $imagick->getImageBlob();
```

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

### vCard minimal example

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Appendix/URI-Content.md

Minimal vCard 4.0 example for exchanging contact details. Placeholders like <NAME> and <EMAIL> must be replaced with actual values. See RFC 6350 for the full specification.

```none
BEGIN:VCARD
VERSION:4.0
N:<NAME>
FN:<FULL NAME>
GENDER:O
EMAIL;type=(WORK|HOME):<EMAIL>
TEL;type=(WORK|CELL|HOME):<PHONE>
ADR;type=WORK:<LINE1>;<LINE2>;<STREET>;<CITY>;<STATE>;<ZIP>;<COUNTRY>
TZ:<CITY/COUNTRY>
URL:<URL>
PHOTO;JPEG:<LINK>
LOGO;JPEG:<LINK>
NOTE:<TEXT>
CATEGORIES:<LIST>
END:VCARD
```

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

### prepareModuleValue method

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Transforms the validated input value by lowercasing it for use as the final module substitute.

```php
	protected function prepareModuleValue($value):string{
		return strtolower($value);
	}
```

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

### Invoke QROutputInterface manually

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Alternative to QRCode::render(): manually instantiate the custom output class with options and the QR matrix, then call dump() to output or write to a file.

```php
$qrcode            = new QRCode($options);
$qrOutputInterface = new MyCustomOutput($options, $qrcode->getMatrix($data));

//dump the output, which is equivalent to QRCode::render()
$qrOutputInterface->dump();
// render to file
$qrOutputInterface->dump('/path/to/qrcode.svg');
```

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

### composer.json version switch for PHP compatibility

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Installation.md

Allows installing a php-qrcode version compatible with older PHP versions (^7.0 || ^8.0) by specifying multiple version constraints. Test and verify output before deploying such a switch.

```json
{
	"require": {
		"php": "^7.0 || ^8.0",
		"chillerlan/php-qrcode": "^2.0 || ^3.4 || ^4.3 || ^5.0"
	}
}
```

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

### Create your first QR Code

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Quickstart.md

Encodes a URI for a mobile authenticator into a QR code image. The default output is a base64 encoded data URI.

```php
$data   = 'otpauth://totp/test?secret=B3JX4VCVJDVNXNZ5&issuer=chillerlan.net';
$qrcode = new QRCode()->render($data);

// default output is a base64 encoded data URI
printf('<img src="%s" alt="QR Code" />', $qrcode);
```

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

### iCalendar event example

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Appendix/URI-Content.md

iCalendar (vCalendar) example for sharing calendar events, taken from the spatie/icalendar-generator library. Includes a VEVENT with UID, timestamps, and summary. See RFC 5545 for the full specification.

```none
BEGIN:VCALENDAR
VERSION:2.0
PRODID:spatie/icalendar-generator
NAME:Laracon online
X-WR-CALNAME:Laracon online
BEGIN:VEVENT
UID:5ef5c3f64cb2c
DTSTAMP;TZID=UTC:20200626T094630
SUMMARY:Creating calendar feeds
DTSTART:20190306T150000Z
DTEND:20190306T160000Z
DTSTAMP:20190419T135034Z
END:VEVENT
END:VCALENDAR
```

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

### Collect modules per type and render output in dump()

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Initial implementation of the dump() method that manually loops over the matrix to collect modules per M_TYPE and renders section headers with module lists. This version does not use QROutputAbstract::collectModules() and does not handle QROptions::$connectPaths or $drawLightModules.

```php
	public function dump(string $file = null):string{
		$collections = [];

		// loop over the matrix and collect the modules per layer
		foreach($this->matrix->getMatrix() as $y => $row){
			foreach($row as $x => $M_TYPE){
				$collections[$M_TYPE][] = $this->module($x, $y, $M_TYPE);
			}
		}

		// build the final output
		$out = [];

		foreach($collections as $M_TYPE => $collection){
			$name  = ($this->getModuleValue($M_TYPE) ?: $this::LAYERNAMES[$M_TYPE]);
			// the section header
			$out[] = sprintf("%s (%012b)\n", $name, $M_TYPE);
			// the list of modules
			$out[] = sprintf("%s\n", implode("\n", $collection));
		}

		return implode("\n", $out);
	}
```

```php
	protected function moduleTransform(int $x, int $y, int $M_TYPE, int $M_TYPE_LAYER):string{

		if(!$this->drawLightModules && !$this->matrix->isDark($M_TYPE)){
			return '';
		}

		return sprintf('x: %s, y: %s', $x, $y);
	}
```

```php
	public function dump(string $file = null):string{
		$collections = $this->collectModules();

		// build the final output
		$out = [];

		foreach($collections as $M_TYPE => $collection){
			$name  = ($this->getModuleValue($M_TYPE) ?: $this::LAYERNAMES[$M_TYPE]);
			// the section header
			$out[] = sprintf("%s (%012b)\n", $name, $M_TYPE);
			// the list of modules
			$out[] = sprintf("%s\n", implode("\n", $collection));
		}

		return implode("\n", $out);
	}
```

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

### Set QROptions::$outputInterface to custom class

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Configure QROptions to use a custom output class and render a QR code. Sets connectPaths and drawLightModules to true, defines custom module values for QRMatrix::M_DATA and QRMatrix::M_DATA_DARK, then renders and dumps the output.

```php
$options                   = new QROptions;
$options->outputInterface  = MyCustomOutput::class;
$options->connectPaths     = true;
$options->drawLightModules = true;

// our custom module values
$options->moduleValues    = [
	QRMatrix::M_DATA      => 'these-modules-are-light',
	QRMatrix::M_DATA_DARK => 'here-is-a-dark-module',
];

$qrcode = new QRCode($options);
$qrcode->addByteSegment('test');

var_dump($qrcode->render());
```

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

### logoSpaceStartX

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Configuration-settings.md

Sets the optional horizontal start position of the logo space (top left corner).

```APIDOC
## logoSpaceStartX

### Description
Sets the optional horizontal start position of the logo space (top left corner).

### Configuration Option
- **Name**: `logoSpaceStartX`
- **Type**: (not specified)
- **Required**: No
- **Default**: (not specified)

### Usage
Set this option in the `QROptions` class to define the horizontal start position of the logo space.
```

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

### getDefaultModuleValue method

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Returns an empty string as the default for dark and light modules, avoiding exceptions when using LAYERNAMES for non-existing values.

```php
	protected function getDefaultModuleValue(bool $isDark):string{
		return '';
	}
```

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

### Configuration using QROptions

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Quickstart.md

Configures the QR code with QROptions, setting version 7 and outputBase64 false to output raw image instead of base64 data URI. The image type is SVG by default.

```php
$options = new QROptions;
$options->version      = 7;
$options->outputBase64 = false; // output raw image instead of base64 data URI

header('Content-type: image/svg+xml'); // the image type is SVG by default

echo new QRCode($options)->render($data);
```

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

### composer.json with php-qrcode dev-main

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Installation.md

Adds the php-qrcode package to a project via composer.json. Requires PHP ^8.2 and uses the dev-main branch; replace dev-main with a version constraint like ^4.3 for stable releases.

```json
{
	"require": {
		"php": "^8.2",
		"chillerlan/php-qrcode": "dev-main"
	}
}
```

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

### composer.json requirement for php-qrcode

Source: https://github.com/chillerlan/php-qrcode/blob/main/README.md

Example composer.json requiring PHP ^8.4 and chillerlan/php-qrcode with a dev-main commit hash. Replace dev-main with a version constraint like ^6.0 for stable releases.

```json
{
	"require": {
		"php": "^8.4",
		"chillerlan/php-qrcode": "dev-main#<commit_hash>"
	}
}
```

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

### Full custom output class MyCustomOutput

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Complete implementation of a custom output class extending QROutputAbstract. Overrides prepareModuleValue, getDefaultModuleValue, moduleValueIsValid, dump, and moduleTransform to produce a string-based format similar to SVG or EPS.

```php
class MyCustomOutput extends QROutputAbstract{

	protected function prepareModuleValue($value):string{
		return strtolower($value);
	}

	protected function getDefaultModuleValue(bool $isDark):string{
		return '';
	}

	public static function moduleValueIsValid($value):bool{
		return is_string($value) && preg_match('/^[a-z-]+$/i', $value) === 1;
	}

	public function dump(string $file = null):string{
		$collections = $this->collectModules($this->module(...));

		// build the final output
		$out = [];

		foreach($collections as $M_TYPE => $collection){
			$name  = ($this->getModuleValue($M_TYPE) ?: $this::LAYERNAMES[$M_TYPE]);
			// the section header
			$out[] = sprintf("%s (%012b)\n", $name, $M_TYPE);
			// the list of modules
			$out[] = sprintf("%s\n", implode("\n", $collection));
		}

		return implode("\n", $out);
	}

	protected function moduleTransform(int $x, int $y, int $M_TYPE, int $M_TYPE_LAYER):string{

		if(!$this->drawLightModules && !$this->matrix->isDark($M_TYPE)){
			return '';
		}

		return sprintf('x: %s, y: %s', $x, $y);
	}

}
```

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

### logoSpaceStartY

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Configuration-settings.md

Sets the optional vertical start position of the logo space (top left corner).

```APIDOC
## logoSpaceStartY

### Description
Sets the optional vertical start position of the logo space (top left corner).

### Configuration Option
- **Name**: `logoSpaceStartY`
- **Type**: (not specified)
- **Required**: No
- **Default**: (not specified)

### Usage
Set this option in the `QROptions` class to define the vertical start position of the logo space.
```

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

### Render and save EPS file

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QREps.md

Render a QR code with the configured options and save it to a file. The example uses a YouTube URL as data and saves to 'qrcode.eps' in the current directory.

```php
$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
$file = __DIR__.'/qrcode.eps';

new QRCode($options)->render($data, $file);
```

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

### Return ImageInterface instance with returnResource

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRInterventionImage.md

Set returnResource to true to get an Intervention\Image\Interfaces\ImageInterface instance instead of a string. This ignores other output options and allows further manipulation before dumping the output.

```php
$options->returnResource = true;

/** @var \Intervention\Image\Interfaces\ImageInterface $image */
$image = new QRCode($options)->render($data);

// do stuff with the ImageInterface instance...

// ...dump output

header('Content-type: image/png');

echo $image->toPng()->toString();
```

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

### Return Imagick instance with returnResource

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRImagick.md

Set returnResource to true to get an Imagick instance instead of a string. This ignores other output options and allows direct manipulation of the image, such as scaling and format conversion.

```php
$options->returnResource = true;

/** @var \Imagick $imagick */
$imagick = new QRCode($options)->render($data);

// do stuff with the Imagick instance...
$imagick->scaleImage(150, 150, true);
// ...

// ...dump output
$imagick->setImageFormat('png32');

header('Content-type: image/png');

echo $imagick->getImageBlob();
```

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

### moduleValueIsValid method

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Custom-output-interface.md

Validates that the input value is a string containing only letters a-z (case-insensitive) and hyphens.

```php
	public static function moduleValueIsValid($value):bool{
		return is_string($value) && preg_match('/^[a-z-]+$/i', $value) === 1;
	}
```

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

### Using collectModules() and moduleTransform()

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/QROutputAbstract.md

Collects modules into path layers and transforms each module. The moduleTransform() method must be implemented when using the collector. The example returns a formatted string with coordinates and M_TYPE.

```php
class MyOutput extends QROutputAbstract{

	public function dump(string $file = null):string{

		// collect the modules for the path elements
		$paths = $this->collectModules();

		// loop over the paths
		foreach($paths as $M_TYPE_LAYER => &$path){

			if($path === []){
				continue;
			}

			$path = implode($this->options->eol, $path);
		}

		return implode($this->options->eol, $paths);
	}

	// this method must be implemented/overridden if your output class uses the module collector
	protected function moduleTransform(int $x, int $y, int $M_TYPE, int $M_TYPE_LAYER):string{
		return sprintf('%d %d %012b', $x, $y, $M_TYPE);
	}

}
```

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

### Return GdImage instance with returnResource

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRGdImage.md

Set returnResource to true to get a GdImage instance instead of a string. This ignores other output options. Use the instance for further processing and then dump the image.

```php
$options->returnResource = true;

/** @var \GdImage $gdImage */
$gdImage = new QRCode($options)->render($data);

// do stuff with the GdImage instance...
$size = imagesx($gdImage);
// ...

// ...dump output
header('Content-type: image/jpeg');

imagejpeg($gdImage);
imagedestroy($gdImage);
```

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

### Add logo space via options

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Logos.md

Configure a rectangular logo space using QROptions. Either width or height must be given; if only one is provided, the space is square. Start coordinates are optional.

```php
$options->addLogoSpace    = true;

// either width or height must be given, if only one dimension is given, the space is assumed square
$options->logoSpaceWidth  = 9;
$options->logoSpaceHeight = 9;

// the top left corner of the space, both values are optional
$options->logoSpaceStartX = 10;
$options->logoSpaceStartY = 10;
```

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

### Render QR code as JSON string with QRStringJSON

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRStringJSON.md

Configure QROptions with outputType STRING_JSON and jsonFlags, then render data to a JSON string. The example sets the Content-type header to application/json and uses JSON_THROW_ON_ERROR|JSON_UNESCAPED_SLASHES flags.

```php
$options = new QROptions;

$options->outputType = QROutputInterface::STRING_JSON;
$options->jsonFlags  = JSON_THROW_ON_ERROR|JSON_UNESCAPED_SLASHES;

header('Content-type: application/json');

$data   = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';

echo new QRCode($options)->render($data); // -> JSON string
```

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

### Setting module values with validation

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Module-Values.md

Shows how to set module values with user input validation using QRMarkupSVG::moduleValueIsValid(). The example sets a default dark color and sanitizes user input before assigning it to multiple dark module types.

```php
// set an initial value that acts as default
$dark = 'rgba(0, 0, 0, 0.5)';

// try to receive user input
if(QRMarkupSVG::moduleValueIsValid($_GET['qr_dark'])){
	// module values for HTML, SVG and other markup may need special treatment,
	// e.g. only accept hexadecimal values from user input
	// as moduleValueIsValid() just checks for the general syntax
	$dark = sanitize_user_input($_GET['qr_dark']);
}

$options->moduleValues = [
	QRMatrix::M_DATA_DARK      => $dark,
	QRMatrix::M_FINDER_DARK    => $dark,
	QRMatrix::M_ALIGNMENT_DARK => $dark,
	QRMatrix::M_FINDER_DOT     => $dark,
];
```

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

### Render QR code as HTML in a PHP document

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRMarkupHTML.md

Generate the QR code HTML using the configured options and output it within a full HTML document. The example sets the content type to text/html and includes CSS styling for the QR code elements.

```php
<?php

$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
$out  = new QRCode($options)->render($data);

header('Content-type: text/html');

?>
<!DOCTYPE html>
<html lang="none">
<head>
	<meta charset="UTF-8"/>
	<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
	<title>QRCode HTML Example</title>
	<style>
		div.qrcode{
			margin: 1em;
		}

		/* rows */
		div.qrcode > div {
			height: 10px;
		}

		/* modules */
		div.qrcode > div > span {
			display: inline-block;
			width: 10px;
			height: 10px;
		}
	</style>
</head>
<body>
<!-- php poutput -->
<?php echo $out; ?>
</body>
</html>
```

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

### Build Sphinx docs on Windows

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Readme.md

Run the make.bat script in the /docs directory on Windows to generate HTML documentation.

```bash
.\make.bat html
```

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

### Build Sphinx docs on Linux

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Readme.md

Run make html in the /docs directory on Linux to generate HTML documentation.

```bash
make html
```

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

### Run phpDocumentor on Windows

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Readme.md

Execute phpDocumentor with the phpdoc.xml config on Windows.

```bash
c:\path\to\php.exe c:\path\to\phpDocumentor.phar --config=phpdoc.xml
```

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

### Run phpDocumentor on Linux

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Readme.md

Execute phpDocumentor with the phpdoc.xml config on Linux.

```bash
php /path/to/phpDocumentor.phar --config=phpdoc.xml
```

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

### Set and retrieve QROptions properties

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Shows how to set and retrieve values on a QROptions instance. Unknown properties are not created and return null without error.

```php
$options = new QROptions;

// set some values
$options->version = 7;     // property "version" exists
$options->foo     = 'bar'; // property "foo" does not exist (and will not be created)

// retrieve values
var_dump($options->version); // -> 7
var_dump($options->foo);     // -> null (no error will be thrown)
```

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

### Access result data from DecoderResult

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Reading-QRCodes.md

Use the result instance to get the decoded data. You can access the data property or cast the result to string.

```php
$content = $result->data;
// ...or simply cast it to string:
$content = (string)$result;
```

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

### Extend QROptions class for custom settings

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Shows how to extend QROptions to add custom settings for your output module.

```php
class MyCustomOptions extends QROptions{
	protected string $myParam = 'defaultValue';
	// ...
}
```

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

### Set options after QRCode invocation

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Create a QRCode instance with default settings, then set options via setOptions(). Note that modifying the QROptions instance after invocation may cause side effects.

```php
// instance will be invoked with default settings
$qrcode  = new QRCode;

// set options after QRCode invocation
$options = new QROptions;

$qrcode->setOptions($options);
```

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

### Get QRMatrix from DecoderResult and render

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Reading-QRCodes.md

The result instance offers a method that returns a QRMatrix instance populated with the detected settings. You can modify the matrix and render it with a new QRCode instance.

```php
$matrix = $result->getQRMatrix();

// ...matrix modification...

$output = new QRCode($options)->renderMatrix($matrix);

// ...dump output
```

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

### Supply an iterable of options to QROptions constructor

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

The constructor accepts an iterable of key-value pairs. Optional setters are called for each setting if present.

```php
$myOptions = [
	'version'    => 5,
	'outputType' => QROutputInterface::GDIMAGE_PNG,
	'eccLevel'   => EccLevel::M,
];

$options = new QROptions($myOptions);
```

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

### Extend SettingsContainerInterface on-the-fly with anonymous class

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Shows how to create custom options on-the-fly using an anonymous class that extends SettingsContainerAbstract and uses the traits.

```php
$myOptions = [
	'myParam' => 'whatever value',
	// ...
];

$myCustomOptions = new class($myOptions) extends SettingsContainerAbstract{
	use QROptionsTrait, MyCustomOptionsTrait;
};
```

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

### Render a QRMatrix instance

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Obtain a QRMatrix from various sources and render it directly using renderMatrix(). The matrix can come from the current data segments, the QR Code reader, or be manually constructed.

```php
// a matrix from the current data segments
$matrix = $qrcode->getQRMatrix();
// from the QR Code reader
$matrix = $readerResult->getQRMatrix();
// manually invoked
$matrix = (new QRMatrix(new Version(7), new EccLevel(EccLevel::M)))->initFunctionalPatterns();

$output = $qrcode->renderMatrix($matrix);
// save to file
$qrcode->renderMatrix($matrix, '/path/to/qrcode.svg');
```

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

### Base64 URI output (default)

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

By default, render() returns a Base64 encoded data URI, as shown in the comment.

```php
echo $qrcode->render($data); // -> data:image/png;base64,...
```

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

### Supply options directly to QRCode constructor

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

In v6+, you can pass the iterable of option values directly to the QRCode constructor.

```php
$qrCode = new QRCode($myOptions);
```

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

### Previous functionality: get matrix as JSON array

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRStringJSON.md

Equivalent to the old behavior (v5 and earlier) that dumped an array representation of the internal matrix. Retrieves the QRMatrix instance and encodes the matrix as an array of booleans using json_encode.

```php
$matrix = new QRCode($options)->getQRMatrix(); // -> QRMatrix instance

// retrieve the internal matrix as an array of booleans
$json   = json_encode($matrix->getMatrix(true), $jsonFlags);
```

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

### Save and load QROptions to/from JSON

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Shows multiple ways to serialize QROptions to JSON and load them back. Includes toJSON, json_encode, __toString, and fromJSON methods.

```php
$json = $options->toJSON(JSON_THROW_ON_ERROR);
// via JsonSerializable interface
$json = json_encode($options, JSON_THROW_ON_ERROR);
// via __toString()
$json = (string)$options;

$options = new QROptions()->fromJSON($json);
// on an existing instance - properties will be overwriten
$options->fromJSON($json);
```

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

### Set options on existing QROptions instance via fromIterable

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

You can set an iterable of options on an existing QROptions instance using the fromIterable method.

```php
$options->fromIterable($myOptions);
```

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

### Set QRImagick options

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRImagick.md

Configure the QRImagick output with format, quality, colors, and module styles. Set outputInterface to QRImagick::class and adjust imagickFormat, scale, colors, and module values as needed.

```php
$options = new QROptions;

$options->outputInterface     = QRImagick::class;
$options->imagickFormat       = 'webp'; // e.g. png32, jpeg, webp
$options->quality             = 90;
$options->scale               = 20;
$options->bgColor             = '#ccccaa';
$options->imageTransparent    = true;
$options->transparencyColor   = '#ccccaa';
$options->drawLightModules    = true;
$options->drawCircularModules = true;
$options->circleRadius        = 0.4;
$options->keepAsSquare        = [
	QRMatrix::M_FINDER_DARK,
	QRMatrix::M_FINDER_DOT,
	QRMatrix::M_ALIGNMENT_DARK,
];
$options->moduleValues        = [
	QRMatrix::M_FINDER_DARK    => '#A71111', // dark (true)
	QRMatrix::M_FINDER_DOT     => '#A71111', // finder dot, dark (true)
	QRMatrix::M_FINDER         => '#FFBFBF', // light (false)
	QRMatrix::M_ALIGNMENT_DARK => '#A70364',
	QRMatrix::M_ALIGNMENT      => '#FFC9C9',
	QRMatrix::M_VERSION_DARK   => '#650098',
	QRMatrix::M_VERSION        => '#E0B8FF',
];
```

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

### Use SettingsContainerInterface with trait for custom options

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Shows a more flexible approach using the SettingsContainerInterface with a trait. Includes optional magic setters and getters.

```php
trait MyCustomOptionsTrait{
	protected string $myParam = 'defaultValue';
	// ...

	// an optional magic setter, named "set_" + property name
	protected function set_myParam(string $myParam):void{
		$this->myParam = trim($myParam);
	}

	// an optional magic getter, named "get_" + property name
	protected function get_myParam():string{
		return strtoupper($this->myParam);
	}
}

class MyCustomOptions extends SettingsContainerAbstract{
	use QROptionsTrait, MyCustomOptionsTrait;
}

// set the options
$myCustomOptions = new MyCustomOptions;
$myCustomOptions->myParam = 'whatever value';
```

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

### Save QR Code to file via render method parameter

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Pass the file path as the second argument to render() to override the QROptions::$cachefile setting.

```php
$qrcode->render($data, '/path/to/qrcode.svg');
```

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

### Set QRMarkupXML options

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRMarkupXML.md

Configures QROptions for XML output, including disabling base64 encoding, excluding light modules, assigning an XSLT stylesheet, and setting module colors.

```php
$options = new QROptions;

$options->outputInterface  = QRMarkupXML::class;
$options->outputBase64     = false;
// if set to false, the light modules won't be included in the output
$options->drawLightModules = false;

// assign an XSLT stylesheet
$options->xmlStylesheet    = './qrcode.style.xsl';

$options->moduleValues     = [
	QRMatrix::M_FINDER_DARK    => '#A71111', // dark (true)
	QRMatrix::M_FINDER_DOT     => '#A71111', // finder dot, dark (true)
	QRMatrix::M_FINDER         => '#FFBFBF', // light (false)
	QRMatrix::M_ALIGNMENT_DARK => '#A70364',
	QRMatrix::M_ALIGNMENT      => '#FFC9C9',
	QRMatrix::M_VERSION_DARK   => '#650098',
	QRMatrix::M_VERSION        => '#E0B8FF',
];
```

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

### Save QR Code to file using cachefile option

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Set outputBase64 to false and specify a cachefile path to store the QR code output. The render method writes to the file and the path is available in $options->cachefile for use in an HTML img tag.

```php
$options->outputBase64 = false;
$options->cachefile    = '/path/to/qrcode.svg';

$qrcode->render($data);

printf('<img src="%s" alt="QR Code" />', $options->cachefile);
```

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

### Push EPS as file download

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QREps.md

Output the EPS file directly to the browser as a download. Sets the Content-type header to 'application/postscript' and Content-Disposition with filename 'qrcode.eps', then echoes the rendered output.

```php
header('Content-type: application/postscript');
header('Content-Disposition: filename="qrcode.eps"');

echo new QRCode($options)->render($data);

exit;
```

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

### Protected methods: initFPDF() and module()

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRFpdf.md

These protected methods are part of the QRFpdf class. initFPDF() initializes an FPDF instance, and module() renders a single module. They are not directly callable by users but are listed for completeness.

```APIDOC
## Protected methods

### initFPDF()
- **Return**: `FPDF`
- **Description**: Initializes an FPDF instance.

### module(int $x, int $y, int $M_TYPE)
- **Return**: `void`
- **Description**: Renders a single module.
- **Parameters**:
  - **$x** (int) - X coordinate
  - **$y** (int) - Y coordinate
  - **$M_TYPE** (int) - Module type constant
```

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

### Disable Base64 output for direct image output

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Set outputBase64 to false and set the Content-type header to output the raw image data directly.

```php
$options->outputBase64 = false;

header('Content-type: image/png');

echo $qrcode->render($data);
```

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

### Using QRMatrix methods for module state

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/Module-Values.md

Iterates over all modules and demonstrates set(), check(), checkType(), and checkTypeIn() methods for managing and querying module types.

```php
for($y = 0; $y < $this->moduleCount; $y++){ // rows
	for($x = 0; $x < $this->moduleCount; $x++){ // columns
		// sets current module as dark (true) with the M_DATA type
		$this->matrix->set($x, $y, true, QRMatrix::M_DATA);

		// -> true (shortcut for checkType($x, $y, QRMatrix::IS_DARK))
		$this->matrix->check($x, $y);

		// -> true (current module is of type M_DATA)
		$this->matrix->checkType($x, $y, QRMatrix::M_DATA);

		// -> true (current module is of type IS_DARK)
		$this->matrix->checkType($x, $y, QRMatrix::IS_DARK);

		// -> false, type is M_DATA
		$this->matrix->checkTypeIn($x, $y, [QRMatrix::M_FINDER_DARK, QRMatrix::M_ALIGNMENT]);
	}
}
```

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

### Render QR code with QRImagick

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRImagick.md

Generate a QR code using the configured options and output a data URI. The render method returns a base64-encoded image string when outputBase64 is enabled (default).

```php
$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
$out  = new QRCode($options)->render($data); // -> data:image/webp;base64,...

printf('<img alt="%s" src="%s" />', $alt, $out);
```

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

### Create GDLuminanceSource from GdImage instance

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Reading-QRCodes.md

Manually invoke a GDLuminanceSource from a GdImage instance. The static convenience methods fromFile() and fromBlob() are also available.

```php
$gdimage = imagecreatefromstring($imagedata);

$source = new GDLuminanceSource($gdimage, $options);
```

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

### Using saveToFile() and toBase64DataURI()

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/QROutputAbstract.md

Saves output to a file if a path is provided, and optionally converts to a base64 data URI when outputBase64 is enabled. The mime type is not validated.

```php
class MyOutput extends QROutputAbstract{

	public function dump(string $file = null):string{
		$output = 'qrcode data string';

		// save the plain data to file
		$this->saveToFile($output, $file);

		// base64 encoding may be called optionally
		if($this->options->outputBase64){
			$output = $this->toBase64DataURI($output, 'text/plain');
		}

		return $output;
	}

}
```

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

### Configure QRMarkupSVG options for SVG output

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRMarkupSVG.md

Sets QROptions for SVG output with QRMarkupSVG class. Includes version, light module rendering, circular modules, path connection, keep-as-square module types, and a gradient via svgDefs. The svgDefs string embeds a linearGradient and CSS style block for dark/light fills.

```php
$options = new QROptions;

$options->version              = 7;
$options->outputInterface      = QRMarkupSVG::class;
// if set to false, the light modules won't be rendered
$options->drawLightModules     = true;
$options->svgUseFillAttributes = true;
// draw the modules as circles isntead of squares
$options->drawCircularModules  = true;
$options->circleRadius         = 0.4;
// connect paths to avoid render glitches
// @see https://github.com/chillerlan/php-qrcode/issues/57
$options->connectPaths         = true;
// keep modules of these types as square
$options->keepAsSquare         = [
	QRMatrix::M_FINDER_DARK,
	QRMatrix::M_FINDER_DOT,
	QRMatrix::M_ALIGNMENT_DARK,
];
// add a gradient via the <defs> element
// @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs
// @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient
$options->svgDefs             = '
	<linearGradient id="rainbow" x1="1" y2="1">
		<stop stop-color="#e2453c" offset="0"/>
		<stop stop-color="#e07e39" offset="0.2"/>
		<stop stop-color="#e5d667" offset="0.4"/>
		<stop stop-color="#51b95b" offset="0.6"/>
		<stop stop-color="#1e72b7" offset="0.8"/>
		<stop stop-color="#6f5ba7" offset="1"/>
	</linearGradient>
	<style><![CDATA[
		.dark{fill: url(#rainbow);}
		.light{fill: #eee;}
	]]></style>';
```

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

### prepareModuleValue() pseudo implementation

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Customizing/QROutputAbstract.md

Prepares the final replacement value from input. May throw QRCodeOutputException if value is invalid.

```php
class MyOutput extends QROutputAbstract{

	protected function prepareModuleValue(mixed $value):mixed{

		// extended validation to make sure the values are valid for output
		// e.g. examine array values, clamp etc.
		if(!is_valid($value)){
			throw new QRCodeOutputException('invalid module value');
		}

		return $this->modifyValue($value);
	}

}
```

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

### QRCode::setOptions()

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Sets the options instance after QRCode invocation. This method allows you to configure the QRCode instance with a QROptions object after it has been created.

```APIDOC
## QRCode::setOptions()

### Description
Sets the options instance after QRCode invocation. This method allows you to configure the QRCode instance with a QROptions object after it has been created.

### Method
setOptions

### Parameters
- **$options** (QROptions) - Required - The options instance to set.

### Request Example
```php
$qrcode = new QRCode;
$options = new QROptions;
$qrcode->setOptions($options);
```

### Response
No return value.
```

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

### Configure QRStringText options

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRStringText.md

Sets up QROptions for the QRStringText output interface, including ANSI colors and module values for different QR matrix parts.

```php
$options = new QROptions;

$options->outputInterface = QRStringText::class;
$options->eol             = "\n";
// add some space on the line start
$options->textLineStart   = str_repeat(' ', 6);
// default values for unassigned module types
$options->textDark        = QRStringText::ansi8('██', 253);
$options->textLight       = QRStringText::ansi8('░░', 253);
$options->moduleValues    = [
	QRMatrix::M_FINDER_DARK    => QRStringText::ansi8('██', 124),
	QRMatrix::M_FINDER         => QRStringText::ansi8('░░', 124),
	QRMatrix::M_FINDER_DOT     => QRStringText::ansi8('██', 124),
	QRMatrix::M_ALIGNMENT_DARK => QRStringText::ansi8('██', 2),
	QRMatrix::M_ALIGNMENT      => QRStringText::ansi8('░░', 2),
	QRMatrix::M_VERSION_DARK   => QRStringText::ansi8('██', 21),
	QRMatrix::M_VERSION        => QRStringText::ansi8('░░', 21),
];
```

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

### QRCode::render()

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Renders the QR code to an output string or file. This method is used to generate the final QR code output after adding data segments.

```APIDOC
## QRCode::render()

### Description
Renders the QR code to an output string or file. This method is used to generate the final QR code output after adding data segments.

### Method
render

### Parameters
- **$file** (string|null) - Optional - The file path to save the output. If null, the output is returned as a string.

### Request Example
```php
$output = $qrcode->render();
$qrcode->render(null, '/path/to/qrcode.svg');
```

### Response
Returns the rendered output as a string if no file path is provided.
```

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

### Create IMagickLuminanceSource from Imagick instance

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Reading-QRCodes.md

Manually invoke an IMagickLuminanceSource from an Imagick instance. The static convenience methods fromFile() and fromBlob() are also available.

```php
$imagick = new Imagick;
$imagick->readImageBlob($imagedata);

$source = new IMagickLuminanceSource($imagick, $options);
```

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

### QRCode::renderMatrix()

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Usage/Advanced-usage.md

Renders a given QRMatrix instance to an output string or file. This method allows you to render a matrix that was obtained from various sources, such as the current data segments or a QR code reader.

```APIDOC
## QRCode::renderMatrix()

### Description
Renders a given QRMatrix instance to an output string or file. This method allows you to render a matrix that was obtained from various sources, such as the current data segments or a QR code reader.

### Method
renderMatrix

### Parameters
- **$matrix** (QRMatrix) - Required - The matrix to render.
- **$file** (string|null) - Optional - The file path to save the output. If null, the output is returned as a string.

### Request Example
```php
$output = $qrcode->renderMatrix($matrix);
$qrcode->renderMatrix($matrix, '/path/to/qrcode.svg');
```

### Response
Returns the rendered output as a string if no file path is provided.
```

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

### Set QROptions for QRGdImageWEBP output

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRGdImage.md

Configure QROptions for GD image output using QRGdImageWEBP. Sets output interface, quality, scale, background and transparency colors, circular modules, and module values.

```php
$options = new QROptions;

// $outputInterface can be one of the classes listed in `QROutputInterface::MODES`
$options->outputInterface     = QRGdImageWEBP::class;
$options->quality             = 90;
// the size of one qr module in pixels
$options->scale               = 20;
$options->bgColor             = [200, 150, 200];
$options->imageTransparent    = true;
// the color that will be set transparent
// @see https://www.php.net/manual/en/function.imagecolortransparent
$options->transparencyColor   = [200, 150, 200];
$options->drawCircularModules = true;
$options->drawLightModules    = true;
$options->circleRadius        = 0.4;
$options->keepAsSquare        = [
	QRMatrix::M_FINDER_DARK,
	QRMatrix::M_FINDER_DOT,
	QRMatrix::M_ALIGNMENT_DARK,
];
$options->moduleValues        = [
	QRMatrix::M_FINDER_DARK    => [0, 63, 255], // dark (true)
	QRMatrix::M_FINDER_DOT     => [0, 63, 255], // finder dot, dark (true)
	QRMatrix::M_FINDER         => [233, 233, 233], // light (false)
	QRMatrix::M_ALIGNMENT_DARK => [255, 0, 255],
	QRMatrix::M_ALIGNMENT      => [233, 233, 233],
	QRMatrix::M_DATA_DARK      => [0, 0, 0],
	QRMatrix::M_DATA           => [233, 233, 233],
];
```

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

### header()

Source: https://github.com/chillerlan/php-qrcode/blob/main/docs/Built-In-Output/QRMarkupSVG.md

Returns the `<svg>` header with the given options parsed. This method is protected and used internally for SVG rendering.

```APIDOC
## header()

### Description
Returns the `<svg>` header with the given options parsed. This method is protected and used internally for SVG rendering.

### Method
`header`

### Return
`string` - SVG header string.
```
Tokens:
Raw