php-qrcode/docs/Usage/Logos.md

Logos and logo space

Info

Brand logos on QR Codes are a common sight and it's quite simple to produce them, however, there are some pitfalls to avoid in order to properly create branded QR Codes.

Logos are not part of any specification, instead, placing a logo on a QR symbol is merely abusing the error correction capacity and the symbol may become unreadable, especially in environments with chances to receive damage, such as prints (bug reports regarding unreadable logo QR Codes will not be accepted, you have been warned).

As a general rule, the ECC level should be set to H (30%) and a minimum version number of 7 or higher is recommended, even though the data would fit in a much smaller symbol:

$options = new QROptions;

$options->version         = Version::AUTO;
$options->versionMin      = 7;
$options->eccLevel        = EccLevel::H;

For best results, the logo (-space) should not exceed 1/5 of the symbol width and height, excluding the quiet zone. Overwriting the function patterns should be avoided, however, overwriting one of the alignment patterns is almost inevitable (but also not much of an issue).

Adding a logo space

A logo space might not be necessary if the QR Code is rendered in a raster format via GD or ImageMagick, where a logo and a possibly required space can be added with the respective built-in functions. For vector/markup based formats it can be useful to prevent the rendering of modules in the area where the logo is supposed to be.

The QRMatrix instance offers a method to clear a rectangular space, that can be utilized from the options:

$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;

It's also possible to call QRMatrix::setLogoSpace() from within a custom output class, e.g. to dynamically scale the logo space:

$size = (int)ceil($this->moduleCount * $logoScale);

$this->matrix->setLogoSpace($size, $size);

Further, the QRMatrix instance can be modified from outside too:

$qrcode = new QRCode($options);

// create a matrix instance
$matrix = $qrcode
	->addByteSegment('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
	->getQRMatrix();

// modify
for($y = $startY; $y < $endY; $y++){
	for($x = $startX; $x < $endX; $x++){
		$matrix->set($x, $y, false, QRMatrix::M_LOGO);
	}
}

// render the QR Code
$out = $qrcode->renderMatrix($matrix);