php-qrcode

The chillerlan/php-qrcode library is a PHP QR Code generator and reader.

Key Capabilities:

• Generation: Creates Model 2 QR Codes (Versions 1 to 40) with support for Error Correction Levels (ECC) L, M, Q, and H.
• Encoding Modes: Supports mixed mode encoding, including numeric, alphanumeric, 8-bit binary (with ECI support), and 13-bit double-byte (Kanji/Shift-JIS and Hanzi/GB2312/GB18030).
• Output Formats: Highly extensible output modules including:
  • Raster Graphics: Via GdImage (avif, bmp, gif, jpeg, png, webp) or ImageMagick.
  • Markup/Vector: SVG, HTML, and Encapsulated Postscript (EPS).
  • Documents: PDF via setasign/fpdf.
  • Data Formats: JSON and plain text.
• Reading: Includes a QR Code reader (based on a PHP port of the ZXing library) that requires either ext-gd or ext-imagick.

The php-qrcode library supports a wide variety of output formats depending on your requirements. Available output types include:

Raster Images

• GD extension: Standard raster images via the PHP GD extension.
• ImageMagick: Raster images via the ImageMagick library.
• intervention/image: Alternative raster output using the intervention/image library.

Vector and Markup

• SVG: Scalable Vector Graphics.
• HTML: HTML markup.
• XML: XML output (can be rendered as SVG via XSLT).

Document and Text

• FPDF: PDF output.
• EPS: Encapsulated PostScript.
• String: Plain text output.

Specialized Outputs

• Custom output: Implement your own output logic by creating custom output classes.
• Multi mode: Demonstrates multi-mode usage.
• Reflectance: Demonstrates reflectance reversal.

The version of a QR symbol determines the side length of its matrix and its maximum data capacity.

• Range: Versions range from 1 to 40.
• Matrix Size:
  • Version 1 is a 21×21 module matrix.
  • Version 40 is a 177×177 module matrix.
• Calculation: You can calculate the number of modules per side using the formula: 4 * version + 17.

QR codes use Reed–Solomon error correction to allow readers to detect and correct errors. The amount of error correction capability is determined by the ECC Level.

Choosing a higher ECC level increases the code's ability to be read even if damaged, but reduces the total amount of data that can be stored in the symbol.

A QR code is a two-dimensional matrix of square elements called modules.

• Modules: Each module acts as a single binary unit (a 'pixel' in the matrix). A dark module represents a binary 1, and a light module represents a binary 0.
• Coordinates: Module positions are defined using (x, y) coordinates, where x is the column (left to right) and y is the row (top to bottom). Counting starts at 0, so the top-left module is (0, 0).

QR Code symbols rely on specific spacing for correct detection:

• Separators: A pattern of all light modules, one module wide, that separates the Position Detection Patterns from the rest of the symbol.
• Quiet Zone: A region 4 modules wide that must be free of all other markings, surrounding the symbol on all four sides. Its reflectance value should match that of the light modules.

When implementing dump(), instead of manually looping over the matrix, it is recommended to use QROutputAbstract::collectModules(). This method internally calls moduleTransform(), which allows you to handle module rendering logic, including respecting the QROptions::$drawLightModules setting.

moduleTransform accepts four parameters:

• $x: current column
• $y: current row
• $M_TYPE: field value
• $M_TYPE_LAYER: (possibly modified) field value acting as a layer ID

Example implementation to handle light modules:

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

When creating a custom output class extending QROutputAbstract, you must implement three abstract methods to handle how QROptions::$moduleValues are processed and stored. QROutputAbstract::setModuleValues() will automatically call these methods to populate the internal $this->moduleValues map.

1. moduleValueIsValid($value): bool: Validates if the user-provided value matches the expected format for your output type (e.g., checking if an array contains valid RGB integers).
2. getModuleValue($value): Transforms the validated user input into the final format used by your rendering engine (e.g., clamping RGB values between 0-255).
3. getDefaultModuleValue(bool $isDark): mixed: Returns the fallback value used when no user value is provided for a specific module type.

To ensure readability, the library evaluates different mask patterns. This is a complex and computationally expensive operation.

While you can manually set a mask pattern via configuration settings to avoid this evaluation, it is not recommended as it can result in an unreadable QR symbol.

Approximate performance impact of mask evaluation (in milliseconds):