php-qrcode/README.md

codemasher/php-qrcode

A PHP7 QR Code library based on the QR code implementation by Kazuhiko Arase, namespaced, cleaned up and made extensible.

Documentation

Installation

requires composer

composer.json

{
	"require": {
		"php": ">=7.0.3",
		"chillerlan/php-qrcode": "dev-master"
	}
}

Manual installation

Download the desired version of the package from master or release and extract the contents to your project folder. After that:

• run composer install to install the required dependencies and generate /vendor/autoload.php.
• if you use a custom autoloader, point the namespace chillerlan\QRCode to the folder src of the package

Profit!

Usage

We want to encode this data into a QRcode image:

// 10 reasons why QR codes are awesome
$data = 'https://www.youtube.com/watch?v=DLzxrzFCyOs&t=43s';

// no, for serious, we want to display a QR code for a mobile authenticator
// https://github.com/codemasher/php-googleauth
$data = 'otpauth://totp/test?secret=B3JX4VCVJDVNXNZ5&issuer=chillerlan.net';

Quick and simple:

echo '<img src="'.(new QRCode($data, new QRImage))->output().'" />';

Wait, what was that? Please again, slower!

Advanced usage

Ok, step by step. You'll need a QRCode instance which needs to be invoked with the data and a Output\QROutputInterface as parameters.

// the built-in QROutputInterface classes
$outputInterface = new QRImage;
$outputInterface = new QRMarkup;
$outputInterface = new QRString;

// invoke a fresh QRCode instance
$qrcode = new QRCode($data, $outputInterface);

// and dump the output
$qrcode->output();

Have a look in this folder for some usage examples.

The QRCode and built-in QROutputInterface classes can be optionally invoked with a QROptions or a Output\QROutputOptionsInterface Object respectively.

// image -> QRImageOptions
$outputOptions = new QRImageOptions;
$outputOptions->type = QRCode::OUTPUT_IMAGE_GIF;
$outputInterface = new QRImage($outputOptions);

// string -> QRStringOptions
$outputOptions = new QRStringOptions;
$outputOptions->type = QRCode::OUTPUT_STRING_TEXT;
$outputInterface = new QRString($outputOptions);

// QROptions
$qrOptions = new QROptions;
$qrOptions->errorCorrectLevel = QRCode::ERROR_CORRECT_LEVEL_L;

$qrcode = new QRCode($data, $outputInterface, $qrOptions);

You can reuse the QRCode object once created in case you don't need to change the output, and use the QRCode::setData() method instead.

$qrcode->setData($data);
$qrcode->setData($data, $qrOptions);

$qrcode->output();

In case you only want the raw array which represents the QR code matrix, just call QRCode::getRawData() - this method is also called internally from QRCode::output().

$matrix = $qrcode->getRawData();

foreach($matrix as $row){
	foreach($row as $dark){
		if($dark){
			// do stuff
		}
		else{
			// do other stuff
		}
	}
}

Custom output modules

But then again, instead of bloating your own code, you can simply create your own output module by extending QROutputAbstract.

$qrcode = new QRCode($data, new MyCustomOutput($myCustomOutputOptions), $qrOptions)

class MyCustomOutput extends QROutputAbstract{
	
	// inherited from QROutputAbstract
	protected $matrix; // array
	protected $pixelCount; // int
	protected $options; // MyCustomOutputOptions (if present)
	
	// optional constructor
	public function __construct(MyCustomOutputOptions $options = null){
		$this->options = $options;

		if(!$this->options){
			// MyCustomOutputOptions should supply default values
			$this->options = new MyCustomOutputOptions;
		}

	}

	public function dump(){
	
		$output = '';

		for($row = 0; $row < $this->pixelCount; $row++){
			for($col = 0; $col < $this->pixelCount; $col++){
				$output .= (string)(int)$this->matrix[$row][$col];
			}
		}

		return $output;
	}

}

Authenticator example

codemasher/php-googleauth features creation of otpauth:// URIs for use with most mobile authenticators:

use chillerlan\GoogleAuth\Authenticator;

$authenticator = new Authenticator;

$secret = $authenticator->createSecret(); // -> userdata
$data   = $authenticator->getUri($secret, 'test', 'chillerlan.net');

$qrcode->setData($data)->output();

QRCode public methods

method	return
__construct($data, QROutputInterface $output, QROptions $options = null)	-
setData($data, QROptions $options = null)	QRCode
output()	mixed QROutputInterface::dump()
getRawData()	array QRDataGenerator::$matrix

Properties of QROptions

property	type	default	allowed	description
$errorCorrectLevel	int	M	QRCode::ERROR_CORRECT_LEVEL_X	X = L, M, Q, H 7%, 15%, 25%, 30%
$typeNumber	int	null	QRCode::TYPE_XX	XX = 01 ... 10, null = auto

Properties of QRStringOptions

property	type	default	allowed	description
$type	int	JSON	QRCode::OUTPUT_STRING_XXXX	XXXX = TEXT, JSON
$textDark	string	'🔴'	*	string substitute for dark
$textLight	string	'⭕'	*	string substitute for light
$eol	string	PHP_EOL	*	newline string

Properties of QRMarkupOptions

property	type	default	allowed	description
$type	int	HTML	QRCode::OUTPUT_MARKUP_XXXX	XXXX = HTML, SVG
$htmlRowTag	string	'p'	*	the shortest available semanically correct row (block) tag to not bloat the output
$htmlOmitEndTag	bool	true	-	the closing tag may be omitted (moar bloat!)
$fgColor	string	'#000'	*	foreground color
$bgColor	string	'#fff'	*	background color
$cssClass	string	null	*	a common css class
$pixelSize	int	5	*	size of a QR code pixel
$marginSize	int	5	*	margin around the QR code
$eol	string	PHP_EOL	*	newline string

Properties of QRImageOptions

property	type	default	allowed	description
$type	string	PNG	QRCode::OUTPUT_IMAGE_XXX	XXX = PNG, JPG, GIF, SVG
$base64	bool	true	-	wether to return the image data as base64 or raw like from file_get_contents()
$cachefile	string	null	*	optional cache file path, null returns the image data
$pixelSize	int	5	1 ... 25	size of a QR code pixel (25 is HUGE!)
$marginSize	int	5	0 ... 25	margin around the QR code
$transparent	bool	true	-	toggle transparency (no jpeg support)
$fgRed	int	0	0 ... 255	foreground red
$fgGreen	int	0	0 ... 255	foreground green
$fgBlue	int	0	0 ... 255	foreground blue
$bgRed	int	255	0 ... 255	background red
$bgGreen	int	255	0 ... 255	background green
$bgBlue	int	255	0 ... 255	background blue
$pngCompression	int	-1	-1 ... 9	imagepng() compression level, -1 = auto
$jpegQuality	int	85	0 - 100	imagejpeg() quality