php-qrcode/docs/Customizing/QROutputAbstract.md

QROutputAbstract

The abstract class QROutputAbstract contains several commonly used methods and properties and can be used as a basis for a custom output class.

Properties

$options and $matrix

The QROptions and QRMatrix instances that were passed to the constructor of the output class. Both objects can be modified during runtime, for example to override settings or add matrix modifications.

$moduleCount, $scale and $length

These are convenience variables mostly to avoid multiple method calls to QRMatrix::getSize() and QROptions::__get('scale') inside loops, the $length is calculated from the aforementioned values ($moduleCount * $scale). The method setMatrixDimensions() can be called to update these 3 values after the matrix has been modified, e.g. by adding a quiet zone during output.

$moduleValues

The finalized map of $M_TYPE to value for the current output. This map is generated during invocation of the output class via setModuleValues().

Copies of QROptions values

Some values from the QROptions instance are copied to properties to avoid calling the magic getters in long loops for a significant performance increase, e.g. in the module collector. Currently, the following values are copied via copyVars() during invocation: $connectPaths, $excludeFromConnect, $eol, $drawLightModules, $drawCircularModules, $keepAsSquare, $circleRadius (and additionally $circleDiameter).

Methods

setModuleValues()

This method calls the abstract/interface methods moduleValueIsValid(), prepareModuleValue() and getDefaultModuleValue() to prepare the module values map.

moduleValueIsValid()

This method is declared in the QROutputInterface and needs to be implemented by the output class; it is static so that it can be called before invocation. The purpose is to determine whether the given mixed input is a valid module value for the current output class and returns bool. It's also useful to check values from QROptions such as $bgColor or $transparencyColor.

Below is a pseudo implementation, check the code of the several output classes for actual implementations (e.g. QRImagick::moduleValueIsValid())

class MyOutput extends QROutputAbstract{

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

		// check the type of the input value first
		if(!is_expected_type($value)){
			return false;
		}

		// do some more checks to determine the value
		if(!is_somehow_valid($value)){
			return false;
		}

		// looks like we got a match
		return true;
	}

}

prepareModuleValue()

This method prepares the final replacement value from the given input. It might still be necessary to validate the given value despite it being checked earlier by moduleValueIsValid() - if nothing helps, this is a good place to throw an exception. Below a pseudo implementation example (see QRGdImage::prepareModuleValue()):

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);
	}

}

getDefaultModuleValue()

Finally, setting a default value is required, in case a value for an $M_TYPE is not set or it's invalid.

class MyOutput extends QROutputAbstract{

	protected function getDefaultModuleValue(bool $isDark):mixed{
		$defaultValue = ($isDark === true)
			? 'default value for dark'
			: 'default value for light';

		return $this->prepareModuleValue($defaultValue);
	}

}

getModuleValue() and getModuleValueAt()

Both methods return a module value, the main difference is that getModuleValueAt() is a convenience method that makes an extra call to retrieve the $M_TYPE from the given matrix coordinate to return the value via getModuleValue(). A foreach loop over the matrix gives you the key (coordinate) and value of an array element:

class MyOutput extends QROutputAbstract{

	public function dump(string $file = null):string{
		$lines = [];

		foreach($this->matrix->getMatrix() as $y => $row){
			$lines[$y] = '';

			foreach($row as $x => $M_TYPE){
				$lines[$y] .= $this->getModuleValue($M_TYPE);
			}
		}

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

}

However, sometimes you might happen to use a for loop instead. The for loop leaves you only with the matrix coordinates, so you need to call getModuleValueAt():

class MyOutput extends QROutputAbstract{

	public function dump(string $file = null):string{
		$lines = [];

		for($y = 0; $y < $this->moduleCount; $y++){
			$lines[$y] = '';

			for($x = 0; $x < $this->moduleCount; $x++){
				$lines[$y] .= $this->getModuleValueAt($x, $y);
			}

		}

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

}

setMatrixDimensions()

As mentioned before, this method is supposed to set the values for the properties $moduleCount, $scale and $length. It is called in the constructor during invocation, but it might be necessary to call it again if the size of the matrix was changed in the output class (see the round quiet zone example for a use case).

getOutputDimensions()

This method provides a simple way for consistent width/height values for the output (if applicable) which then can be changed by simply overriding this method. It returns a 2-element array that contains the values in a format that can be used by the output class, which is QROutputAbstract::$length ($moduleCount * $scale):

[$width, $height] = $this->getOutputDimensions();

The output width and height can be changed in all places by simply overriding the method:

class MyOutput extends QROutputAbstract{

	protected function getOutputDimensions():array{
		// adjust the height in order to add something under the QR Code
		return [$this->length, ($this->length + 69)];
	}

}

collectModules()

The module collector is particularly useful for plain text based file formats, for example the various markup languages like SVG and HTML or other structured file formats such as EPS. This method calls a method moduleTransform() internally with 4 parameters: the module coordinates $x and $y, the $M_TYPE and $M_TYPE_LAYER. The transform method should return a value that is valid for a single module of the QR matrix, or null if no transform was performed for the current module. The $M_TYPE_LAYER is a copy of the $M_TYPE that represents the array key of the returned array and that may have been reassigned in the collector to another path layer, e.g. through QROptions::$connectPaths.

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);
	}

}

Sometimes it can be necessary to override collectModules() in order to apply special effects such as random colors - you can find some implementations in the SVG examples.

saveToFile() and toBase64DataURI()

The void method saveToFile() takes a data blob and the $file given in QROutputInterface::dump() and save to the path if it is not null - the file path itself is not checked except for writability. The final output can be transformed to a base64 data URI with toBase64DataURI(), where the data blob and a valid mime type as parameters - the mime type is not checked.

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

}