michael/michaelschiemer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(Production): Complete production deployment infrastructure

Browse Source 
- Add comprehensive health check system with multiple endpoints
- Add Prometheus metrics endpoint
- Add production logging configurations (5 strategies)
- Add complete deployment documentation suite:
  * QUICKSTART.md - 30-minute deployment guide
  * DEPLOYMENT_CHECKLIST.md - Printable verification checklist
  * DEPLOYMENT_WORKFLOW.md - Complete deployment lifecycle
  * PRODUCTION_DEPLOYMENT.md - Comprehensive technical reference
  * production-logging.md - Logging configuration guide
  * ANSIBLE_DEPLOYMENT.md - Infrastructure as Code automation
  * README.md - Navigation hub
  * DEPLOYMENT_SUMMARY.md - Executive summary
- Add deployment scripts and automation
- Add DEPLOYMENT_PLAN.md - Concrete plan for immediate deployment
- Update README with production-ready features

All production infrastructure is now complete and ready for deployment.
This commit is contained in:
Michael Schiemer
2025-10-25 19:18:37 +02:00
parent caa85db796
commit fc3d7e6357
83016 changed files with 378904 additions and 20919 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
src/Framework/QrCode/DataEncoder.php
View File

@@ -1,316 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
use App\Framework\QrCode\Structure\BlockStructure;
use InvalidArgumentException;
/**
* QR Code Data Encoder
*
* Encodes data into the bit stream format required for QR codes.
* Handles different data modes and creates the final codeword sequence.
*/
final class DataEncoder
{
private BlockStructure $blockStructure;
public function __construct()
{
$this->blockStructure = new BlockStructure();
}
/**
* Encode data into QR code codewords with error correction
*/
public function encode(string $data, QrCodeVersion $version, ErrorCorrectionLevel $errorLevel): array
{
// Step 1: Create data bit stream
$mode = DataMode::detectForData($data);
$bitStream = '';
$modeIndicator = $this->addModeIndicator($mode);
$bitStream .= $modeIndicator;
error_log("DEBUG: Mode indicator: " . strlen($modeIndicator) . " bits");
$charCount = $this->addCharacterCountIndicator($data, $mode, $version);
$bitStream .= $charCount;
error_log("DEBUG: After char count: " . strlen($bitStream) . " bits total");
$encodedData = $this->encodeData($data, $mode);
$bitStream .= $encodedData;
error_log("DEBUG: After data encoding: " . strlen($bitStream) . " bits total (added " . strlen($encodedData) . " bits)");
$terminator = $this->addTerminator($bitStream, $version, $errorLevel);
$bitStream .= $terminator;
error_log("DEBUG: After terminator: " . strlen($bitStream) . " bits total");
$bitStream = $this->padToByteLength($bitStream);
error_log("DEBUG: After byte padding: " . strlen($bitStream) . " bits total");
$bitStream = $this->addPadding($bitStream, $version, $errorLevel);
// Step 2: Convert bit stream to data codewords
$dataCodewords = $this->bitStreamToCodewords($bitStream);
// Step 3: Create data blocks with error correction
$blocks = $this->blockStructure->createBlocks(
$dataCodewords,
$version->getVersion(),
$errorLevel->value
);
// Step 4: Interleave blocks to create final codeword sequence
return $this->blockStructure->interleaveBlocks($blocks);
}
/**
* Add mode indicator to bit stream (4 bits)
*/
private function addModeIndicator(DataMode $mode): string
{
return $this->intToBits($mode->getIndicator(), 4);
}
/**
* Add character count indicator
*/
private function addCharacterCountIndicator(string $data, DataMode $mode, QrCodeVersion $version): string
{
$characterCount = match($mode) {
DataMode::NUMERIC => strlen($data),
DataMode::ALPHANUMERIC => strlen($data),
DataMode::BYTE => strlen($data),
DataMode::KANJI => $this->getKanjiCount($data),
};
$bits = $mode->getCharacterCountBits($version);
return $this->intToBits($characterCount, $bits);
}
/**
* Encode the actual data based on mode
*/
private function encodeData(string $data, DataMode $mode): string
{
return match($mode) {
DataMode::NUMERIC => $this->encodeNumeric($data),
DataMode::ALPHANUMERIC => $this->encodeAlphanumeric($data),
DataMode::BYTE => $this->encodeByte($data),
DataMode::KANJI => $this->encodeKanji($data),
};
}
/**
* Encode numeric data (0-9)
*/
private function encodeNumeric(string $data): string
{
$bitStream = '';
$length = strlen($data);
// Process 3 digits at a time
for ($i = 0; $i < $length; $i += 3) {
$group = substr($data, $i, 3);
$value = (int) $group;
$bits = match(strlen($group)) {
3 => 10, // 3 digits = 10 bits
2 => 7, // 2 digits = 7 bits
1 => 4, // 1 digit = 4 bits
};
$bitStream .= $this->intToBits($value, $bits);
}
return $bitStream;
}
/**
* Encode alphanumeric data
*/
private function encodeAlphanumeric(string $data): string
{
$alphanumericMap = [
'0' => 0, '1' => 1, '2' => 2, '3' => 3, '4' => 4, '5' => 5, '6' => 6, '7' => 7, '8' => 8, '9' => 9,
'A' => 10, 'B' => 11, 'C' => 12, 'D' => 13, 'E' => 14, 'F' => 15, 'G' => 16, 'H' => 17, 'I' => 18, 'J' => 19,
'K' => 20, 'L' => 21, 'M' => 22, 'N' => 23, 'O' => 24, 'P' => 25, 'Q' => 26, 'R' => 27, 'S' => 28, 'T' => 29,
'U' => 30, 'V' => 31, 'W' => 32, 'X' => 33, 'Y' => 34, 'Z' => 35, ' ' => 36, '$' => 37, '%' => 38, '*' => 39,
'+' => 40, '-' => 41, '.' => 42, '/' => 43, ':' => 44,
];
$bitStream = '';
$length = strlen($data);
// Process 2 characters at a time
for ($i = 0; $i < $length; $i += 2) {
if ($i + 1 < $length) {
// Two characters: value = (45 * first) + second
$char1 = $data[$i];
$char2 = $data[$i + 1];
if (! isset($alphanumericMap[$char1]) || ! isset($alphanumericMap[$char2])) {
throw new InvalidArgumentException("Invalid alphanumeric character in data");
}
$value = 45 * $alphanumericMap[$char1] + $alphanumericMap[$char2];
$bitStream .= $this->intToBits($value, 11);
} else {
// Single character
$char = $data[$i];
if (! isset($alphanumericMap[$char])) {
throw new InvalidArgumentException("Invalid alphanumeric character in data");
}
$value = $alphanumericMap[$char];
$bitStream .= $this->intToBits($value, 6);
}
}
return $bitStream;
}
/**
* Encode byte data (8 bits per byte)
*/
private function encodeByte(string $data): string
{
$bitStream = '';
for ($i = 0; $i < strlen($data); $i++) {
$byte = ord($data[$i]);
$bitStream .= $this->intToBits($byte, 8);
}
return $bitStream;
}
/**
* Encode Kanji data (placeholder - complex implementation needed)
*/
private function encodeKanji(string $data): string
{
// Simplified Kanji encoding - in practice this needs proper Shift_JIS handling
throw new InvalidArgumentException("Kanji encoding not yet implemented");
}
/**
* Add terminator (0000) if space allows
*/
private function addTerminator(string $bitStream, QrCodeVersion $version, ErrorCorrectionLevel $errorLevel): string
{
$maxCapacityBits = $version->getDataCapacity($errorLevel);
$currentBits = strlen($bitStream);
// Add up to 4 terminator bits if space allows
$terminatorBits = min(4, $maxCapacityBits - $currentBits);
if ($terminatorBits > 0) {
$bitStream .= str_repeat('0', $terminatorBits);
}
return $bitStream;
}
/**
* Pad bit stream to byte boundary
*/
private function padToByteLength(string $bitStream): string
{
$remainder = strlen($bitStream) % 8;
if ($remainder > 0) {
$padding = 8 - $remainder;
$bitStream .= str_repeat('0', $padding);
}
return $bitStream;
}
/**
* Add padding bytes to reach required capacity
*/
private function addPadding(string $bitStream, QrCodeVersion $version, ErrorCorrectionLevel $errorLevel): string
{
$maxCapacityBits = $version->getDataCapacity($errorLevel);
$currentBits = strlen($bitStream);
// DEBUG: Output detailed information
error_log("DEBUG addPadding - Version: {$version->getVersion()}, Error Level: {$errorLevel->value}");
error_log("DEBUG addPadding - Current bits: $currentBits, Max capacity: $maxCapacityBits");
error_log("DEBUG addPadding - Bitstream sample (first 100 chars): " . substr($bitStream, 0, 100));
if ($currentBits > $maxCapacityBits) {
throw new InvalidArgumentException("Data exceeds capacity for version {$version->getVersion()}: {$currentBits} bits > {$maxCapacityBits} bits");
}
// Add alternating padding bytes: 11101100, 00010001
$paddingBytes = [
'11101100', // 236 in decimal
'00010001', // 17 in decimal
];
$paddingIndex = 0;
while (strlen($bitStream) < $maxCapacityBits) {
$remaining = $maxCapacityBits - strlen($bitStream);
if ($remaining >= 8) {
$bitStream .= $paddingBytes[$paddingIndex % 2];
$paddingIndex++;
} else {
// Add remaining bits as zeros
$bitStream .= str_repeat('0', $remaining);
break;
}
}
// Trim to exact capacity
return substr($bitStream, 0, $maxCapacityBits);
}
/**
* Convert integer to binary string with specified bit count
*/
private function intToBits(int $value, int $bits): string
{
return str_pad(decbin($value), $bits, '0', STR_PAD_LEFT);
}
/**
* Get Kanji character count (placeholder)
*/
private function getKanjiCount(string $data): int
{
// Simplified - real implementation would count actual Kanji characters
return mb_strlen($data, 'UTF-8');
}
/**
* Convert bit stream to array of data codewords (bytes)
*/
private function bitStreamToCodewords(string $bitStream): array
{
$codewords = [];
$length = strlen($bitStream);
// Convert every 8 bits to a byte
for ($i = 0; $i < $length; $i += 8) {
$byte = substr($bitStream, $i, 8);
// Pad if necessary (shouldn't happen after proper bit stream creation)
if (strlen($byte) < 8) {
$byte = str_pad($byte, 8, '0', STR_PAD_RIGHT);
}
$codewords[] = bindec($byte);
}
return $codewords;
}
}

106
src/Framework/QrCode/DataMode.php
View File

@@ -1,106 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
/**
* QR Code Data Mode
*
* Defines how data is encoded in the QR code.
* Different modes are optimized for different types of data.
*/
enum DataMode: int
{
case NUMERIC = 0b0001; // 0-9 digits only
case ALPHANUMERIC = 0b0010; // 0-9, A-Z, space, $, %, *, +, -, ., /, :
case BYTE = 0b0100; // Any 8-bit data (UTF-8, binary)
case KANJI = 0b1000; // Japanese Kanji characters
/**
* Get the mode indicator bits
*/
public function getIndicator(): int
{
return $this->value;
}
/**
* Get the character count bits for this mode and version
*/
public function getCharacterCountBits(QrCodeVersion $version): int
{
$versionNumber = $version->getVersion();
return match($this) {
self::NUMERIC => match(true) {
$versionNumber <= 9 => 10,
$versionNumber <= 26 => 12,
default => 14,
},
self::ALPHANUMERIC => match(true) {
$versionNumber <= 9 => 9,
$versionNumber <= 26 => 11,
default => 13,
},
self::BYTE => match(true) {
$versionNumber <= 9 => 8,
$versionNumber <= 26 => 16,
default => 16,
},
self::KANJI => match(true) {
$versionNumber <= 9 => 8,
$versionNumber <= 26 => 10,
default => 12,
},
};
}
/**
* Detect optimal mode for given data
*/
public static function detectForData(string $data): self
{
// Check if numeric (digits only)
if (ctype_digit($data)) {
return self::NUMERIC;
}
// Check if alphanumeric
if (self::isAlphanumeric($data)) {
return self::ALPHANUMERIC;
}
// Default to byte mode for any other data
return self::BYTE;
}
/**
* Check if string contains only alphanumeric QR characters
*/
private static function isAlphanumeric(string $data): bool
{
$alphanumericChars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:';
for ($i = 0; $i < strlen($data); $i++) {
if (strpos($alphanumericChars, $data[$i]) === false) {
return false;
}
}
return true;
}
/**
* Get efficiency ratio (bits per character)
*/
public function getEfficiency(): float
{
return match($this) {
self::NUMERIC => 3.33, // 10 bits for 3 digits
self::ALPHANUMERIC => 5.5, // 11 bits for 2 characters
self::BYTE => 8.0, // 8 bits per byte
self::KANJI => 13.0, // 13 bits per Kanji
};
}
}

185
src/Framework/QrCode/ErrorCorrection/ReedSolomonEncoder.php Normal file
View File

@@ -0,0 +1,185 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ErrorCorrection;
/**
* Reed-Solomon Error Correction Encoder
*
* Implements Reed-Solomon error correction for QR Codes
* Uses Galois Field GF(256) with primitive polynomial x^8 + x^4 + x^3 + x^2 + 1
*
* Phase 2: Full Reed-Solomon implementation
*/
final class ReedSolomonEncoder
{
// Generator polynomial coefficients for different EC codeword counts
private const GENERATOR_POLYNOMIALS = [
7 => [0, 87, 229, 146, 149, 238, 102, 21], // EC Level M, Version 1
10 => [0, 251, 67, 46, 61, 118, 70, 64, 94, 32, 45],
13 => [0, 74, 152, 176, 100, 86, 100, 106, 104, 130, 218, 206, 140, 78],
15 => [0, 8, 183, 61, 91, 202, 37, 51, 58, 58, 237, 140, 124, 5, 99, 105],
16 => [0, 120, 104, 107, 109, 102, 161, 76, 3, 91, 191, 147, 169, 182, 194, 225, 120],
17 => [0, 43, 139, 206, 78, 43, 239, 123, 206, 214, 147, 24, 99, 150, 39, 243, 163, 136],
18 => [0, 215, 234, 158, 94, 184, 97, 118, 170, 79, 187, 152, 148, 252, 179, 5, 98, 96, 153],
];
// Galois Field log and antilog tables
private array $gfLog;
private array $gfExp;
public function __construct()
{
$this->initializeGaloisField();
}
/**
* Initialize Galois Field GF(256) lookup tables
*/
private function initializeGaloisField(): void
{
$this->gfLog = array_fill(0, 256, 0);
$this->gfExp = array_fill(0, 512, 0);
$x = 1;
for ($i = 0; $i < 255; $i++) {
$this->gfExp[$i] = $x;
$this->gfLog[$x] = $i;
// Multiply by alpha (x^8 + x^4 + x^3 + x^2 + 1 = 0x11d)
$x <<= 1;
if ($x & 0x100) {
$x ^= 0x11d;
}
}
// Extend exp table for convenience
for ($i = 255; $i < 512; $i++) {
$this->gfExp[$i] = $this->gfExp[$i - 255];
}
}
/**
* Encode data with Reed-Solomon error correction
*
* @param array<int> $data Data codewords (bytes)
* @param int $ecCodewords Number of error correction codewords to generate
* @return array<int> Error correction codewords
*/
public function encode(array $data, int $ecCodewords): array
{
// Get generator polynomial
$generator = $this->getGeneratorPolynomial($ecCodewords);
// Initialize message polynomial (data + zero padding for EC)
$messagePolynomial = array_merge($data, array_fill(0, $ecCodewords, 0));
// Polynomial division
for ($i = 0; $i < count($data); $i++) {
$coefficient = $messagePolynomial[$i];
if ($coefficient !== 0) {
for ($j = 0; $j < count($generator); $j++) {
$messagePolynomial[$i + $j] ^= $this->gfMultiply($generator[$j], $coefficient);
}
}
}
// Return only EC codewords (last ecCodewords bytes)
return array_slice($messagePolynomial, count($data));
}
/**
* Get or generate generator polynomial for given number of EC codewords
*/
private function getGeneratorPolynomial(int $ecCodewords): array
{
// Use pre-calculated if available
if (isset(self::GENERATOR_POLYNOMIALS[$ecCodewords])) {
return self::GENERATOR_POLYNOMIALS[$ecCodewords];
}
// Generate dynamically
return $this->generateGeneratorPolynomial($ecCodewords);
}
/**
* Generate generator polynomial g(x) = (x - α^0)(x - α^1)...(x - α^(n-1))
*/
private function generateGeneratorPolynomial(int $degree): array
{
// Start with g(x) = 1
$polynomial = [1];
// Multiply by (x - α^i) for i = 0 to degree-1
for ($i = 0; $i < $degree; $i++) {
$polynomial = $this->multiplyPolynomials(
$polynomial,
[1, $this->gfExp[$i]]
);
}
return $polynomial;
}
/**
* Multiply two polynomials in GF(256)
*/
private function multiplyPolynomials(array $poly1, array $poly2): array
{
$result = array_fill(0, count($poly1) + count($poly2) - 1, 0);
for ($i = 0; $i < count($poly1); $i++) {
for ($j = 0; $j < count($poly2); $j++) {
$result[$i + $j] ^= $this->gfMultiply($poly1[$i], $poly2[$j]);
}
}
return $result;
}
/**
* Multiply two numbers in Galois Field GF(256)
*/
private function gfMultiply(int $a, int $b): int
{
if ($a === 0 || $b === 0) {
return 0;
}
return $this->gfExp[$this->gfLog[$a] + $this->gfLog[$b]];
}
/**
* Get error correction capacity for version and level
*
* @return array{dataCodewords: int, ecCodewords: int, blocks: int, ecPerBlock: int}
*/
public static function getECInfo(int $version, string $level): array
{
// EC information for Version 1-3, Level M
// Format: [total_codewords, data_codewords, ec_per_block, blocks]
$ecTable = [
1 => ['M' => [26, 16, 10, 1]], // Version 1, Level M
2 => ['M' => [44, 28, 16, 1]], // Version 2, Level M
3 => ['M' => [70, 44, 26, 1]], // Version 3, Level M
];
if (!isset($ecTable[$version][$level])) {
throw new \InvalidArgumentException(
"No EC info for Version {$version}, Level {$level}"
);
}
[$totalCodewords, $dataCodewords, $ecPerBlock, $blocks] = $ecTable[$version][$level];
return [
'totalCodewords' => $totalCodewords,
'dataCodewords' => $dataCodewords,
'ecCodewords' => $totalCodewords - $dataCodewords,
'blocks' => $blocks,
'ecPerBlock' => $ecPerBlock,
];
}
}

53
src/Framework/QrCode/ErrorCorrectionLevel.php
View File

@@ -1,53 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
/**
* QR Code Error Correction Level
*
* Defines the amount of error correction data included in the QR code.
* Higher levels can recover from more damage but require more space.
*/
enum ErrorCorrectionLevel: string
{
case L = 'L'; // Low - ~7% error recovery
case M = 'M'; // Medium - ~15% error recovery
case Q = 'Q'; // Quartile - ~25% error recovery
case H = 'H'; // High - ~30% error recovery
/**
* Get the error correction capacity percentage
*/
public function getCapacityPercentage(): int
{
return match($this) {
self::L => 7,
self::M => 15,
self::Q => 25,
self::H => 30,
};
}
/**
* Get the format indicator for this level
*/
public function getFormatIndicator(): int
{
return match($this) {
self::L => 0b01,
self::M => 0b00,
self::Q => 0b11,
self::H => 0b10,
};
}
/**
* Get recommended level for TOTP (balance between size and recovery)
*/
public static function forTotp(): self
{
return self::M; // Medium is good balance for TOTP URLs
}
}

340
src/Framework/QrCode/Masking/MaskEvaluator.php Normal file
View File

@@ -0,0 +1,340 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Masking;
use App\Framework\QrCode\Structure\AlignmentPattern;
use App\Framework\QrCode\ValueObjects\Module;
use App\Framework\QrCode\ValueObjects\QrCodeMatrix;
/**
* QR Code Mask Pattern Evaluator
*
* Evaluates all 8 mask patterns and selects the best one based on penalty rules:
* 1. Adjacent modules in row/column (penalty for runs of 5+)
* 2. Block of modules (penalty for 2x2 blocks of same color)
* 3. Specific patterns (penalty for patterns resembling finder patterns)
* 4. Balance (penalty for uneven dark/light ratio)
*/
final readonly class MaskEvaluator
{
/**
* Select best mask pattern based on lowest penalty score
*/
public function selectBestMask(QrCodeMatrix $matrix): MaskPattern
{
$bestPattern = MaskPattern::PATTERN_0;
$lowestPenalty = PHP_INT_MAX;
foreach (MaskPattern::all() as $pattern) {
$maskedMatrix = $this->applyMask($matrix, $pattern);
$penalty = $this->calculatePenalty($maskedMatrix);
if ($penalty < $lowestPenalty) {
$lowestPenalty = $penalty;
$bestPattern = $pattern;
}
}
return $bestPattern;
}
/**
* Apply mask pattern to matrix (without modifying function patterns)
*/
public function applyMask(QrCodeMatrix $matrix, MaskPattern $pattern): QrCodeMatrix
{
$size = $matrix->getSize();
$maskedMatrix = $matrix;
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col < $size; $col++) {
// Skip function patterns (finder, timing, alignment, format info, dark module)
if ($this->isFunctionPattern($matrix, $row, $col)) {
continue;
}
if ($pattern->shouldInvert($row, $col)) {
$currentModule = $matrix->getModuleAt($row, $col);
$invertedModule = $currentModule->isDark()
? Module::light()
: Module::dark();
$maskedMatrix = $maskedMatrix->setModuleAt($row, $col, $invertedModule);
}
}
}
return $maskedMatrix;
}
/**
* Calculate total penalty score for masked matrix
*/
private function calculatePenalty(QrCodeMatrix $matrix): int
{
return $this->penaltyRule1($matrix)
+ $this->penaltyRule2($matrix)
+ $this->penaltyRule3($matrix)
+ $this->penaltyRule4($matrix);
}
/**
* Rule 1: Adjacent modules in row/column
* Penalty: (runLength - 5 + 1) * 3 for each run of 5+ same-color modules
*/
private function penaltyRule1(QrCodeMatrix $matrix): int
{
$size = $matrix->getSize();
$penalty = 0;
// Check rows
for ($row = 0; $row < $size; $row++) {
$runColor = null;
$runLength = 0;
for ($col = 0; $col < $size; $col++) {
$isDark = $matrix->getModuleAt($row, $col)->isDark();
if ($isDark === $runColor) {
$runLength++;
} else {
if ($runLength >= 5) {
$penalty += ($runLength - 5 + 1) * 3;
}
$runColor = $isDark;
$runLength = 1;
}
}
if ($runLength >= 5) {
$penalty += ($runLength - 5 + 1) * 3;
}
}
// Check columns
for ($col = 0; $col < $size; $col++) {
$runColor = null;
$runLength = 0;
for ($row = 0; $row < $size; $row++) {
$isDark = $matrix->getModuleAt($row, $col)->isDark();
if ($isDark === $runColor) {
$runLength++;
} else {
if ($runLength >= 5) {
$penalty += ($runLength - 5 + 1) * 3;
}
$runColor = $isDark;
$runLength = 1;
}
}
if ($runLength >= 5) {
$penalty += ($runLength - 5 + 1) * 3;
}
}
return $penalty;
}
/**
* Rule 2: Block of modules
* Penalty: 3 for each 2x2 block of same color
*/
private function penaltyRule2(QrCodeMatrix $matrix): int
{
$size = $matrix->getSize();
$penalty = 0;
for ($row = 0; $row < $size - 1; $row++) {
for ($col = 0; $col < $size - 1; $col++) {
$color = $matrix->getModuleAt($row, $col)->isDark();
if (
$matrix->getModuleAt($row, $col + 1)->isDark() === $color &&
$matrix->getModuleAt($row + 1, $col)->isDark() === $color &&
$matrix->getModuleAt($row + 1, $col + 1)->isDark() === $color
) {
$penalty += 3;
}
}
}
return $penalty;
}
/**
* Rule 3: Specific patterns
* Penalty: 40 for each occurrence of patterns resembling finder patterns
* Patterns: 1:1:3:1:1 ratio (dark:light:dark:light:dark) with 4 light modules before/after
*/
private function penaltyRule3(QrCodeMatrix $matrix): int
{
$size = $matrix->getSize();
$penalty = 0;
// Pattern: dark, light, dark-dark-dark, light, dark
$pattern1 = [true, false, true, true, true, false, true];
$pattern2 = [false, true, false, false, false, true, false];
// Check rows
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col <= $size - 11; $col++) {
if ($this->matchesPattern($matrix, $row, $col, true, $pattern1) ||
$this->matchesPattern($matrix, $row, $col, true, $pattern2)) {
$penalty += 40;
}
}
}
// Check columns
for ($col = 0; $col < $size; $col++) {
for ($row = 0; $row <= $size - 11; $row++) {
if ($this->matchesPattern($matrix, $row, $col, false, $pattern1) ||
$this->matchesPattern($matrix, $row, $col, false, $pattern2)) {
$penalty += 40;
}
}
}
return $penalty;
}
/**
* Rule 4: Balance
* Penalty based on deviation from 50% dark modules
*/
private function penaltyRule4(QrCodeMatrix $matrix): int
{
$size = $matrix->getSize();
$totalModules = $size * $size;
$darkModules = 0;
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col < $size; $col++) {
if ($matrix->getModuleAt($row, $col)->isDark()) {
$darkModules++;
}
}
}
$percent = (int) (($darkModules * 100) / $totalModules);
$previousMultiple = (int) (floor($percent / 5) * 5);
$nextMultiple = (int) (ceil($percent / 5) * 5);
$deviation1 = abs($previousMultiple - 50) / 5;
$deviation2 = abs($nextMultiple - 50) / 5;
return (int) (min($deviation1, $deviation2) * 10);
}
/**
* Check if position is a function pattern (finder, timing, alignment, format info, dark module)
* MUST match QrCodeGenerator::isOccupied() exactly!
*/
private function isFunctionPattern(QrCodeMatrix $matrix, int $row, int $col): bool
{
$size = $matrix->getSize();
// Finder patterns with 1-module separators (9x9 blocks)
if (
($row <= 8 && $col <= 8) || // Top-left
($row <= 8 && $col >= $size - 8) || // Top-right
($row >= $size - 8 && $col <= 8) // Bottom-left
) {
return true;
}
// Timing patterns
if ($row === 6 || $col === 6) {
return true;
}
// Dark module (row = 4*version + 9, col = 8)
$darkModuleRow = 4 * $matrix->getVersion()->getVersionNumber() + 9;
if ($row === $darkModuleRow && $col === 8) {
return true;
}
// Format information areas (15+15 bits, NOT entire row/column 8)
// Horizontal: row 8, cols 0-5, 7-8 (left) and cols size-8 to size-1 (right)
if ($row === 8) {
// Left side: columns 0-5, 7-8 (skip timing column 6)
if (($col >= 0 && $col <= 5) || $col === 7 || $col === 8) {
return true;
}
// Right side: columns size-8 to size-1
if ($col >= $size - 8) {
return true;
}
}
// Vertical: column 8, rows 0-8 (top) and size-7 to size-1 (bottom)
if ($col === 8) {
// Top side: rows 0-5, 7-8 (skip timing row 6)
if (($row >= 0 && $row <= 5) || $row === 7 || $row === 8) {
return true;
}
// Bottom side: rows size-7 to size-1
if ($row >= $size - 7) {
return true;
}
}
// Alignment patterns (Version 2+)
$version = $matrix->getVersion()->getVersionNumber();
$alignmentLocations = AlignmentPattern::getLocations($version);
foreach ($alignmentLocations as $alignRow) {
foreach ($alignmentLocations as $alignCol) {
// Skip overlaps with finders
if ($alignRow <= 8 && $alignCol <= 8) {
continue;
}
if ($alignRow <= 8 && $alignCol >= $size - 8) {
continue;
}
if ($alignRow >= $size - 8 && $alignCol <= 8) {
continue;
}
// Check if within 5x5 alignment pattern
if (abs($row - $alignRow) <= 2 && abs($col - $alignCol) <= 2) {
return true;
}
}
}
return false;
}
/**
* Check if pattern matches at given position
*/
private function matchesPattern(
QrCodeMatrix $matrix,
int $row,
int $col,
bool $horizontal,
array $pattern
): bool {
$size = $matrix->getSize();
for ($i = 0; $i < count($pattern); $i++) {
$checkRow = $horizontal ? $row : $row + $i;
$checkCol = $horizontal ? $col + $i : $col;
if ($checkRow >= $size || $checkCol >= $size) {
return false;
}
if ($matrix->getModuleAt($checkRow, $checkCol)->isDark() !== $pattern[$i]) {
return false;
}
}
return true;
}
}

58
src/Framework/QrCode/Masking/MaskPattern.php Normal file
View File

@@ -0,0 +1,58 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Masking;
/**
* QR Code Mask Patterns
*
* Defines the 8 standard QR Code mask patterns
*/
enum MaskPattern: int
{
case PATTERN_0 = 0; // (row + column) % 2 == 0
case PATTERN_1 = 1; // row % 2 == 0
case PATTERN_2 = 2; // column % 3 == 0
case PATTERN_3 = 3; // (row + column) % 3 == 0
case PATTERN_4 = 4; // (floor(row/2) + floor(column/3)) % 2 == 0
case PATTERN_5 = 5; // (row * column) % 2 + (row * column) % 3 == 0
case PATTERN_6 = 6; // ((row * column) % 2 + (row * column) % 3) % 2 == 0
case PATTERN_7 = 7; // ((row + column) % 2 + (row * column) % 3) % 2 == 0
/**
* Check if module at position should be inverted by this mask
*/
public function shouldInvert(int $row, int $column): bool
{
return match ($this) {
self::PATTERN_0 => ($row + $column) % 2 === 0,
self::PATTERN_1 => $row % 2 === 0,
self::PATTERN_2 => $column % 3 === 0,
self::PATTERN_3 => ($row + $column) % 3 === 0,
self::PATTERN_4 => ((int) ($row / 2) + (int) ($column / 3)) % 2 === 0,
self::PATTERN_5 => (($row * $column) % 2 + ($row * $column) % 3) === 0,
self::PATTERN_6 => (($row * $column) % 2 + ($row * $column) % 3) % 2 === 0,
self::PATTERN_7 => (($row + $column) % 2 + ($row * $column) % 3) % 2 === 0,
};
}
/**
* Get all patterns
*
* @return array<MaskPattern>
*/
public static function all(): array
{
return [
self::PATTERN_0,
self::PATTERN_1,
self::PATTERN_2,
self::PATTERN_3,
self::PATTERN_4,
self::PATTERN_5,
self::PATTERN_6,
self::PATTERN_7,
];
}
}

441
src/Framework/QrCode/MatrixGenerator.php
View File

@@ -1,441 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
use App\Framework\QrCode\Patterns\FormatInfo;
use App\Framework\QrCode\Patterns\MaskingPattern;
/**
* QR Code Matrix Generator
*
* Generates the complete QR code matrix including:
* - Finder patterns (corner squares)
* - Timing patterns (alternating lines)
* - Data placement
* - Masking patterns
*/
final readonly class MatrixGenerator
{
/**
* Generate QR code matrix from encoded data
*/
public function generateMatrix(
array $codewords,
QrCodeVersion $version,
ErrorCorrectionLevel $errorLevel
): QrCodeMatrix {
$size = $version->getModuleCount();
$matrix = QrCodeMatrix::create($size);
// Step 1: Add function patterns (finder, timing, etc.)
$matrix = $this->addFunctionPatterns($matrix, $version);
// Step 2: Add data modules
$matrix = $this->addDataModules($matrix, $codewords, $version);
// Step 3: Find and apply best masking pattern
$maskResult = MaskingPattern::findAndApplyBest($matrix, $version);
$matrix = $maskResult['matrix'];
$maskPattern = $maskResult['pattern'];
// Step 4: Add format information (standard QR placement)
$matrix = $this->addFormatInformation($matrix, $errorLevel, $maskPattern);
return $matrix;
}
/**
* Add all function patterns (finder, separators, timing, dark module)
*/
private function addFunctionPatterns(QrCodeMatrix $matrix, QrCodeVersion $version): QrCodeMatrix
{
$size = $version->getModuleCount();
// Add finder patterns (3 corner squares)
$matrix = $this->addFinderPattern($matrix, 0, 0); // Top-left
$matrix = $this->addFinderPattern($matrix, $size - 7, 0); // Top-right
$matrix = $this->addFinderPattern($matrix, 0, $size - 7); // Bottom-left
// Add separators (white borders around finder patterns)
$matrix = $this->addSeparators($matrix, $size);
// Add timing patterns (alternating black/white lines)
$matrix = $this->addTimingPatterns($matrix, $size);
// Add dark module (always at specific position)
$matrix = $this->addDarkModule($matrix, $version);
// Add alignment patterns (for versions 2+)
if ($version->hasAlignmentPatterns()) {
$matrix = $this->addAlignmentPatterns($matrix, $version);
}
return $matrix;
}
/**
* Add finder pattern (7x7 square with specific pattern)
*/
private function addFinderPattern(QrCodeMatrix $matrix, int $startRow, int $startCol): QrCodeMatrix
{
$pattern = [
[1,1,1,1,1,1,1],
[1,0,0,0,0,0,1],
[1,0,1,1,1,0,1],
[1,0,1,1,1,0,1],
[1,0,1,1,1,0,1],
[1,0,0,0,0,0,1],
[1,1,1,1,1,1,1],
];
$updates = [];
for ($i = 0; $i < 7; $i++) {
for ($j = 0; $j < 7; $j++) {
$updates[] = [
'row' => $startRow + $i,
'col' => $startCol + $j,
'dark' => (bool) $pattern[$i][$j],
];
}
}
return $matrix->withModules($updates);
}
/**
* Add white separator borders around finder patterns
*/
private function addSeparators(QrCodeMatrix $matrix, int $size): QrCodeMatrix
{
$updates = [];
// Top-left separator
for ($i = 0; $i < 8; $i++) {
if ($i < 8) {
$updates[] = ['row' => 7, 'col' => $i, 'dark' => false];
}
if ($i < 8) {
$updates[] = ['row' => $i, 'col' => 7, 'dark' => false];
}
}
// Top-right separator
for ($i = 0; $i < 8; $i++) {
if ($size - 8 + $i >= 0) {
$updates[] = ['row' => 7, 'col' => $size - 8 + $i, 'dark' => false];
}
if ($size - 8 >= 0) {
$updates[] = ['row' => $i, 'col' => $size - 8, 'dark' => false];
}
}
// Bottom-left separator
for ($i = 0; $i < 8; $i++) {
if ($size - 8 >= 0) {
$updates[] = ['row' => $size - 8, 'col' => $i, 'dark' => false];
}
if ($size - 8 + $i < $size) {
$updates[] = ['row' => $size - 8 + $i, 'col' => 7, 'dark' => false];
}
}
return $matrix->withModules($updates);
}
/**
* Add timing patterns (alternating horizontal and vertical lines)
*/
private function addTimingPatterns(QrCodeMatrix $matrix, int $size): QrCodeMatrix
{
$updates = [];
// Horizontal timing pattern (row 6)
for ($col = 8; $col < $size - 8; $col++) {
$updates[] = ['row' => 6, 'col' => $col, 'dark' => ($col % 2) === 0];
}
// Vertical timing pattern (column 6)
for ($row = 8; $row < $size - 8; $row++) {
$updates[] = ['row' => $row, 'col' => 6, 'dark' => ($row % 2) === 0];
}
return $matrix->withModules($updates);
}
/**
* Add dark module (always present at specific position)
*/
private function addDarkModule(QrCodeMatrix $matrix, QrCodeVersion $version): QrCodeMatrix
{
$row = (4 * $version->getVersion()) + 9;
$col = 8;
return $matrix->withModule($row, $col, true);
}
/**
* Add alignment patterns (for versions 2+)
*/
private function addAlignmentPatterns(QrCodeMatrix $matrix, QrCodeVersion $version): QrCodeMatrix
{
$positions = $version->getAlignmentPositions();
$pattern = [
[1,1,1,1,1],
[1,0,0,0,1],
[1,0,1,0,1],
[1,0,0,0,1],
[1,1,1,1,1],
];
$updates = [];
foreach ($positions as $row) {
foreach ($positions as $col) {
// Skip positions that conflict with finder patterns
if ($this->isFinderPatternArea($row, $col, $version->getModuleCount())) {
continue;
}
// Add 5x5 alignment pattern centered at (row, col)
for ($i = -2; $i <= 2; $i++) {
for ($j = -2; $j <= 2; $j++) {
$updates[] = [
'row' => $row + $i,
'col' => $col + $j,
'dark' => (bool) $pattern[$i + 2][$j + 2],
];
}
}
}
}
return $matrix->withModules($updates);
}
/**
* Place data modules in zigzag pattern
*/
private function addDataModules(QrCodeMatrix $matrix, array $codewords, QrCodeVersion $version): QrCodeMatrix
{
$size = $version->getModuleCount();
// Convert codewords to bit string
$bitString = '';
foreach ($codewords as $codeword) {
$bitString .= str_pad(decbin($codeword), 8, '0', STR_PAD_LEFT);
}
$dataIndex = 0;
$updates = [];
// Start from bottom-right, move in zigzag pattern
$direction = -1; // -1 = up, 1 = down
for ($col = $size - 1; $col > 0; $col -= 2) {
// Skip timing column
if ($col === 6) {
$col--;
}
for ($i = 0; $i < $size; $i++) {
$row = $direction === -1 ? $size - 1 - $i : $i;
// Place data in two columns (col and col-1)
for ($c = 0; $c < 2; $c++) {
$currentCol = $col - $c;
if (! $this->isFunctionModule($row, $currentCol, $version)) {
$bit = $dataIndex < strlen($bitString) ? $bitString[$dataIndex] : '0';
$updates[] = [
'row' => $row,
'col' => $currentCol,
'dark' => $bit === '1',
];
$dataIndex++;
}
}
}
$direction *= -1; // Switch direction
}
return $matrix->withModules($updates);
}
/**
* Add format information around finder patterns according to QR standard
*/
private function addFormatInformation(QrCodeMatrix $matrix, ErrorCorrectionLevel $errorLevel, int $maskPattern): QrCodeMatrix
{
$size = $matrix->getSize();
$formatBits = FormatInfo::generate($errorLevel, $maskPattern);
$updates = [];
// Place format information bits according to QR Code specification
// Total: 15 bits placed in specific positions around finder patterns
// Horizontal format info (around top-left finder pattern)
// Bits 0-5: positions (8,0) to (8,5)
for ($i = 0; $i < 6; $i++) {
$updates[] = [
'row' => 8,
'col' => $i,
'dark' => $formatBits[$i] === 1,
];
}
// Bit 6: position (8,7) - skip (8,6) which is timing pattern
$updates[] = [
'row' => 8,
'col' => 7,
'dark' => $formatBits[6] === 1,
];
// Bit 7: position (8,8)
$updates[] = [
'row' => 8,
'col' => 8,
'dark' => $formatBits[7] === 1,
];
// Bits 8-14: positions (8, size-7) to (8, size-1) - around top-right finder
for ($i = 8; $i < 15; $i++) {
$col = $size - 15 + $i;
if ($col >= 0 && $col < $size) {
$updates[] = [
'row' => 8,
'col' => $col,
'dark' => $formatBits[$i] === 1,
];
}
}
// Vertical format info (around bottom-left finder pattern)
// Bits 0-6: positions (size-1,8) to (size-7,8) - going upward
for ($i = 0; $i < 7; $i++) {
$row = $size - 1 - $i;
if ($row >= 0) {
$updates[] = [
'row' => $row,
'col' => 8,
'dark' => $formatBits[$i] === 1,
];
}
}
// Bits 7-14: positions (7,8) to (0,8) - skip (6,8) which is timing
for ($i = 7; $i < 15; $i++) {
$row = 14 - $i;
if ($row >= 0 && $row !== 6) { // Skip timing pattern row
$updates[] = [
'row' => $row,
'col' => 8,
'dark' => $formatBits[$i] === 1,
];
}
}
return $matrix->withModules($updates);
}
/**
* Add simplified format information for basic QR code compatibility
*/
private function addSimpleFormatInfo(QrCodeMatrix $matrix, ErrorCorrectionLevel $errorLevel, int $maskPattern): QrCodeMatrix
{
$size = $matrix->getSize();
$updates = [];
// Basic format info pattern for M error correction + mask pattern
$formatBits = FormatInfo::generate($errorLevel, $maskPattern);
// Place some format bits horizontally (row 8)
for ($i = 0; $i < min(6, count($formatBits)); $i++) {
if ($i < $size) {
$updates[] = [
'row' => 8,
'col' => $i,
'dark' => $formatBits[$i] === 1,
];
}
}
// Place some format bits vertically (col 8)
for ($i = 0; $i < min(6, count($formatBits)); $i++) {
if (($size - 1 - $i) >= 0) {
$updates[] = [
'row' => $size - 1 - $i,
'col' => 8,
'dark' => $formatBits[$i] === 1,
];
}
}
return $matrix->withModules($updates);
}
/**
* Check if position is in finder pattern area
*/
private function isFinderPatternArea(int $row, int $col, int $size): bool
{
// Top-left finder pattern + separator
if ($row <= 8 && $col <= 8) {
return true;
}
// Top-right finder pattern + separator
if ($row <= 8 && $col >= $size - 8) {
return true;
}
// Bottom-left finder pattern + separator
if ($row >= $size - 8 && $col <= 8) {
return true;
}
return false;
}
/**
* Check if position is a function module (finder, timing, etc.)
*/
private function isFunctionModule(int $row, int $col, QrCodeVersion $version): bool
{
$size = $version->getModuleCount();
// Finder patterns and separators
if ($this->isFinderPatternArea($row, $col, $size)) {
return true;
}
// Timing patterns
if (($row === 6 && $col >= 8 && $col < $size - 8) ||
($col === 6 && $row >= 8 && $row < $size - 8)) {
return true;
}
// Dark module
if ($row === (4 * $version->getVersion()) + 9 && $col === 8) {
return true;
}
// Alignment patterns (simplified check)
if ($version->hasAlignmentPatterns()) {
$positions = $version->getAlignmentPositions();
foreach ($positions as $alignRow) {
foreach ($positions as $alignCol) {
if (! $this->isFinderPatternArea($alignRow, $alignCol, $size)) {
if (abs($row - $alignRow) <= 2 && abs($col - $alignCol) <= 2) {
return true;
}
}
}
}
}
return false;
}
}

127
src/Framework/QrCode/Patterns/FormatInfo.php
View File

@@ -1,127 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Patterns;
use App\Framework\QrCode\ErrorCorrectionLevel;
/**
* QR Code Format Information
*
* Encodes error correction level and mask pattern into format info bits
* placed around finder patterns for QR code readers to identify settings
*/
final class FormatInfo
{
/**
* Generate format information bits for error correction level and mask pattern
*/
public static function generate(ErrorCorrectionLevel $errorLevel, int $maskPattern): array
{
// Error correction level indicators
$errorLevelBits = match($errorLevel) {
ErrorCorrectionLevel::L => 0b01, // 01
ErrorCorrectionLevel::M => 0b00, // 00
ErrorCorrectionLevel::Q => 0b11, // 11
ErrorCorrectionLevel::H => 0b10, // 10
};
// Combine error level (2 bits) and mask pattern (3 bits)
$formatData = ($errorLevelBits << 3) | ($maskPattern & 0b111);
// Apply BCH error correction for format info
$formatInfo = self::applyFormatErrorCorrection($formatData);
// Apply mask pattern 0x5412 (standard QR format info mask)
$formatInfo ^= 0x5412;
// Convert to array of bits (MSB first)
$bits = [];
for ($i = 14; $i >= 0; $i--) {
$bits[] = ($formatInfo >> $i) & 1;
}
return $bits;
}
/**
* Apply BCH error correction to format data (5 bits -> 15 bits)
*/
private static function applyFormatErrorCorrection(int $data): int
{
// Generator polynomial for QR format info: x^10 + x^8 + x^5 + x^4 + x^2 + x + 1
$generator = 0x537; // 10100110111 in binary
// Shift data to make room for error correction bits
$data <<= 10;
// Perform BCH division
for ($i = 4; $i >= 0; $i--) {
if ($data & (1 << ($i + 10))) {
$data ^= $generator << $i;
}
}
return $data;
}
/**
* Get format info placement positions for QR code matrix
*/
public static function getPlacementPositions(int $size): array
{
$positions = [];
// Horizontal format info (row 8)
for ($i = 0; $i <= 5; $i++) {
$positions[] = ['row' => 8, 'col' => $i, 'bit_index' => $i];
}
$positions[] = ['row' => 8, 'col' => 7, 'bit_index' => 6]; // Skip col 6 (timing)
$positions[] = ['row' => 8, 'col' => 8, 'bit_index' => 7];
// Right side (horizontal)
for ($i = 0; $i < 7; $i++) {
$positions[] = ['row' => 8, 'col' => $size - 7 + $i, 'bit_index' => 8 + $i];
}
// Vertical format info (col 8)
for ($i = 0; $i < 6; $i++) {
$positions[] = ['row' => $size - 1 - $i, 'col' => 8, 'bit_index' => $i];
}
for ($i = 0; $i < 8; $i++) {
if ($i == 6) {
continue;
} // Skip row 6 (timing)
$bitIndex = $i < 6 ? 14 - $i : 14 - ($i - 1);
$positions[] = ['row' => $i, 'col' => 8, 'bit_index' => $bitIndex];
}
return $positions;
}
/**
* Place format information in QR code matrix
*/
public static function placeInMatrix(array $matrix, ErrorCorrectionLevel $errorLevel, int $maskPattern): array
{
$size = count($matrix);
$formatBits = self::generate($errorLevel, $maskPattern);
$positions = self::getPlacementPositions($size);
$updates = [];
foreach ($positions as $pos) {
if (isset($formatBits[$pos['bit_index']])) {
$updates[] = [
'row' => $pos['row'],
'col' => $pos['col'],
'dark' => $formatBits[$pos['bit_index']] === 1,
];
}
}
return $updates;
}
}

303
src/Framework/QrCode/Patterns/MaskingPattern.php
View File

@@ -1,303 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Patterns;
use App\Framework\QrCode\QrCodeMatrix;
use App\Framework\QrCode\QrCodeVersion;
/**
* QR Code Masking Patterns
*
* Applies masking patterns to data modules and evaluates quality
* to select the best pattern for readability
*/
final class MaskingPattern
{
/**
* Available masking patterns (0-7)
*/
private const PATTERNS = [
0 => 'pattern0',
1 => 'pattern1',
2 => 'pattern2',
3 => 'pattern3',
4 => 'pattern4',
5 => 'pattern5',
6 => 'pattern6',
7 => 'pattern7',
];
/**
* Find and apply the best masking pattern
*/
public static function findAndApplyBest(QrCodeMatrix $matrix, QrCodeVersion $version): array
{
$bestPattern = 0;
$lowestPenalty = PHP_INT_MAX;
$bestMatrix = null;
// Try all 8 patterns and find the one with lowest penalty
for ($pattern = 0; $pattern < 8; $pattern++) {
$testMatrix = self::applyPattern($matrix, $pattern, $version);
$penalty = self::calculatePenalty($testMatrix, $version);
if ($penalty < $lowestPenalty) {
$lowestPenalty = $penalty;
$bestPattern = $pattern;
$bestMatrix = $testMatrix;
}
}
return ['matrix' => $bestMatrix, 'pattern' => $bestPattern];
}
/**
* Apply specific masking pattern to data modules
*/
public static function applyPattern(QrCodeMatrix $matrix, int $pattern, QrCodeVersion $version): QrCodeMatrix
{
$size = $version->getModuleCount();
$updates = [];
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col < $size; $col++) {
// Only mask data modules, not function patterns
if (! self::isFunctionModule($row, $col, $version)) {
$shouldMask = self::shouldMaskModule($row, $col, $pattern);
if ($shouldMask) {
$currentValue = $matrix->getModule($row, $col);
$updates[] = [
'row' => $row,
'col' => $col,
'dark' => ! $currentValue, // Flip the bit
];
}
}
}
}
return $matrix->withModules($updates);
}
/**
* Check if module should be masked based on pattern
*/
private static function shouldMaskModule(int $row, int $col, int $pattern): bool
{
return match($pattern) {
0 => ($row + $col) % 2 === 0,
1 => $row % 2 === 0,
2 => $col % 3 === 0,
3 => ($row + $col) % 3 === 0,
4 => (intval($row / 2) + intval($col / 3)) % 2 === 0,
5 => (($row * $col) % 2) + (($row * $col) % 3) === 0,
6 => ((($row * $col) % 2) + (($row * $col) % 3)) % 2 === 0,
7 => ((($row + $col) % 2) + (($row * $col) % 3)) % 2 === 0,
default => false
};
}
/**
* Calculate penalty score for masking pattern quality
*/
private static function calculatePenalty(QrCodeMatrix $matrix, QrCodeVersion $version): int
{
$penalty = 0;
$size = $version->getModuleCount();
// Rule 1: Adjacent modules in same color (horizontal and vertical)
$penalty += self::calculateConsecutiveModulesPenalty($matrix, $size);
// Rule 2: Block of modules in same color
$penalty += self::calculateBlockPenalty($matrix, $size);
// Rule 3: Patterns similar to finder patterns
$penalty += self::calculateFinderLikePenalty($matrix, $size);
// Rule 4: Proportion of dark modules
$penalty += self::calculateProportionPenalty($matrix, $size);
return $penalty;
}
/**
* Penalty for consecutive modules of same color
*/
private static function calculateConsecutiveModulesPenalty(QrCodeMatrix $matrix, int $size): int
{
$penalty = 0;
// Check rows
for ($row = 0; $row < $size; $row++) {
$count = 1;
$prevDark = $matrix->getModule($row, 0);
for ($col = 1; $col < $size; $col++) {
$isDark = $matrix->getModule($row, $col);
if ($isDark === $prevDark) {
$count++;
} else {
if ($count >= 5) {
$penalty += $count - 2;
}
$count = 1;
$prevDark = $isDark;
}
}
if ($count >= 5) {
$penalty += $count - 2;
}
}
// Check columns
for ($col = 0; $col < $size; $col++) {
$count = 1;
$prevDark = $matrix->getModule(0, $col);
for ($row = 1; $row < $size; $row++) {
$isDark = $matrix->getModule($row, $col);
if ($isDark === $prevDark) {
$count++;
} else {
if ($count >= 5) {
$penalty += $count - 2;
}
$count = 1;
$prevDark = $isDark;
}
}
if ($count >= 5) {
$penalty += $count - 2;
}
}
return $penalty;
}
/**
* Penalty for 2x2 blocks of same color
*/
private static function calculateBlockPenalty(QrCodeMatrix $matrix, int $size): int
{
$penalty = 0;
for ($row = 0; $row < $size - 1; $row++) {
for ($col = 0; $col < $size - 1; $col++) {
$color = $matrix->getModule($row, $col);
if ($color === $matrix->getModule($row, $col + 1) &&
$color === $matrix->getModule($row + 1, $col) &&
$color === $matrix->getModule($row + 1, $col + 1)) {
$penalty += 3;
}
}
}
return $penalty;
}
/**
* Penalty for finder-like patterns
*/
private static function calculateFinderLikePenalty(QrCodeMatrix $matrix, int $size): int
{
$penalty = 0;
$finderPattern = [true, false, true, true, true, false, true, false, false, false, false]; // 10111010000
// Check rows
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col <= $size - 11; $col++) {
$matches = true;
for ($i = 0; $i < 11; $i++) {
if ($matrix->getModule($row, $col + $i) !== $finderPattern[$i]) {
$matches = false;
break;
}
}
if ($matches) {
$penalty += 40;
}
}
}
// Check columns
for ($col = 0; $col < $size; $col++) {
for ($row = 0; $row <= $size - 11; $row++) {
$matches = true;
for ($i = 0; $i < 11; $i++) {
if ($matrix->getModule($row + $i, $col) !== $finderPattern[$i]) {
$matches = false;
break;
}
}
if ($matches) {
$penalty += 40;
}
}
}
return $penalty;
}
/**
* Penalty for proportion of dark modules
*/
private static function calculateProportionPenalty(QrCodeMatrix $matrix, int $size): int
{
$darkCount = 0;
$totalCount = $size * $size;
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col < $size; $col++) {
if ($matrix->getModule($row, $col)) {
$darkCount++;
}
}
}
$percentage = ($darkCount * 100) / $totalCount;
$k = (int) abs(($percentage - 50) / 5);
return $k * 10;
}
/**
* Check if position is a function module (finder, timing, etc.)
*/
private static function isFunctionModule(int $row, int $col, QrCodeVersion $version): bool
{
$size = $version->getModuleCount();
// Finder patterns (3 corners)
if (($row < 9 && $col < 9) || // Top-left
($row < 9 && $col >= $size - 8) || // Top-right
($row >= $size - 8 && $col < 9)) { // Bottom-left
return true;
}
// Timing patterns
if (($row === 6) || ($col === 6)) {
return true;
}
// Dark module
if ($row === 4 * $version->getVersion() + 9 && $col === 8) {
return true;
}
// Format info areas (exclude from masking since added after)
if (($row === 8 && ($col < 9 || $col >= $size - 8)) ||
($col === 8 && ($row < 9 || $row >= $size - 7))) {
return true;
}
return false;
}
}

120
src/Framework/QrCode/QrCodeException.php
View File

@@ -1,120 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
use App\Framework\Exception\ErrorCode;
use App\Framework\Exception\ExceptionContext;
use App\Framework\Exception\FrameworkException;
/**
* QR Code Exception
*
* Thrown when QR code generation or processing fails.
*/
final class QrCodeException extends FrameworkException
{
/**
* Data too large for any QR code version
*/
public static function dataTooLarge(int $dataLength): self
{
return self::create(
ErrorCode::VAL_BUSINESS_RULE_VIOLATION,
"Data too large for QR code: {$dataLength} bytes exceeds maximum capacity"
)->withData([
'data_length' => $dataLength,
'max_capacity' => 2953, // Version 40, Level L
'operation' => 'qr_generation',
]);
}
/**
* Invalid QR code version
*/
public static function invalidVersion(int $version): self
{
return self::create(
ErrorCode::VAL_PARAMETER_INVALID,
"Invalid QR code version: {$version}"
)->withData([
'version' => $version,
'valid_range' => '1-40',
]);
}
/**
* Encoding failed
*/
public static function encodingFailed(string $reason, ?string $data = null): self
{
$context = ExceptionContext::forOperation('qr.encode', 'DataEncoder')
->withData([
'reason' => $reason,
'data_length' => $data ? strlen($data) : null,
]);
return self::fromContext(
"QR code encoding failed: {$reason}",
$context,
ErrorCode::PROCESSING_FAILED
);
}
/**
* Matrix generation failed
*/
public static function matrixGenerationFailed(string $reason): self
{
return self::forOperation(
'qr.matrix_generation',
'MatrixGenerator',
"QR code matrix generation failed: {$reason}",
ErrorCode::PROCESSING_FAILED
)->withData(['reason' => $reason]);
}
/**
* SVG rendering failed
*/
public static function renderingFailed(string $reason): self
{
return self::forOperation(
'qr.render',
'SvgRenderer',
"QR code rendering failed: {$reason}",
ErrorCode::PROCESSING_FAILED
)->withData(['reason' => $reason]);
}
/**
* Invalid TOTP URI format
*/
public static function invalidTotpUri(string $uri): self
{
return self::create(
ErrorCode::VAL_FORMAT_INVALID,
"Invalid TOTP URI format"
)->withData([
'uri_prefix' => substr($uri, 0, 20),
'expected_prefix' => 'otpauth://totp/',
'operation' => 'totp_qr_generation',
]);
}
/**
* Configuration error
*/
public static function invalidConfiguration(string $parameter, mixed $value): self
{
return self::create(
ErrorCode::CONFIG_INVALID_VALUE,
"Invalid QR code configuration: {$parameter}"
)->withData([
'parameter' => $parameter,
'value' => $value,
'component' => 'QrCodeGenerator',
]);
}
}

431
src/Framework/QrCode/QrCodeGenerator.php
View File

@@ -4,183 +4,320 @@ declare(strict_types=1);
namespace App\Framework\QrCode;
use InvalidArgumentException;
use App\Framework\Exception\FrameworkException;
use App\Framework\QrCode\ErrorCorrection\ReedSolomonEncoder;
use App\Framework\QrCode\Masking\MaskEvaluator;
use App\Framework\QrCode\Structure\AlignmentPattern;
use App\Framework\QrCode\Structure\FinderPattern;
use App\Framework\QrCode\Structure\FormatInformation;
use App\Framework\QrCode\Structure\TimingPattern;
use App\Framework\QrCode\ValueObjects\EncodingMode;
use App\Framework\QrCode\ValueObjects\ErrorCorrectionLevel;
use App\Framework\QrCode\ValueObjects\Module;
use App\Framework\QrCode\ValueObjects\ModulePosition;
use App\Framework\QrCode\ValueObjects\QrCodeConfig;
use App\Framework\QrCode\ValueObjects\QrCodeMatrix;
/**
* QR Code Generator
*
* Main facade for generating QR codes from data.
* Orchestrates encoding, matrix generation, and rendering.
* Phase 2: Full Reed-Solomon error correction with mask pattern selection
* Generates scannable QR codes compliant with ISO/IEC 18004
*/
final readonly class QrCodeGenerator
final class QrCodeGenerator
{
public function __construct(
private DataEncoder $dataEncoder,
private MatrixGenerator $matrixGenerator,
private SvgRenderer $svgRenderer
) {
}
/**
* Create QR code generator with default components
* Generate QR Code from data
*/
public static function create(): self
public static function generate(string $data, ?QrCodeConfig $config = null): QrCodeMatrix
{
return new self(
dataEncoder: new DataEncoder(),
matrixGenerator: new MatrixGenerator(),
svgRenderer: new SvgRenderer()
);
}
/**
* Create QR code generator for TOTP URLs
*/
public static function forTotp(): self
{
return new self(
dataEncoder: new DataEncoder(),
matrixGenerator: new MatrixGenerator(),
svgRenderer: SvgRenderer::withModuleSize(4)->withQuietZone(2)
);
}
/**
* Generate QR code as SVG string
*/
public function generateSvg(
string $data,
?ErrorCorrectionLevel $errorLevel = null,
?QrCodeVersion $version = null
): string {
$matrix = $this->generateMatrix($data, $errorLevel, $version);
return $this->svgRenderer->render($matrix);
}
/**
* Generate QR code as SVG data URI
*/
public function generateDataUri(
string $data,
?ErrorCorrectionLevel $errorLevel = null,
?QrCodeVersion $version = null
): string {
$matrix = $this->generateMatrix($data, $errorLevel, $version);
return $this->svgRenderer->renderAsDataUri($matrix);
}
/**
* Generate QR code matrix
*/
public function generateMatrix(
string $data,
?ErrorCorrectionLevel $errorLevel = null,
?QrCodeVersion $version = null
): QrCodeMatrix {
if (empty($data)) {
throw new InvalidArgumentException('QR code data cannot be empty');
// Auto-detect configuration if not provided
if ($config === null) {
$config = QrCodeConfig::autoSize($data);
}
$errorLevel = $errorLevel ?? ErrorCorrectionLevel::forTotp();
$version = $version ?? $this->determineOptimalVersion($data, $errorLevel);
// Encode data into bit stream
$encodedData = $this->dataEncoder->encode($data, $version, $errorLevel);
// Generate matrix from encoded data
return $this->matrixGenerator->generateMatrix($encodedData, $version, $errorLevel);
}
/**
* Create generator with custom renderer
*/
public function withRenderer(SvgRenderer $renderer): self
{
return new self(
dataEncoder: $this->dataEncoder,
matrixGenerator: $this->matrixGenerator,
svgRenderer: $renderer
);
}
/**
* Get recommended configuration for data
*/
public function analyzeData(string $data): array
{
if (empty($data)) {
throw new InvalidArgumentException('Cannot analyze empty data');
// Validate implementation status
if (!$config->encodingMode->isImplemented()) {
throw FrameworkException::simple(
"Encoding mode {$config->encodingMode->value} not yet implemented"
);
}
$mode = DataMode::detectForData($data);
$errorLevel = ErrorCorrectionLevel::forTotp();
$version = $this->determineOptimalVersion($data, $errorLevel);
return [
'data_length' => strlen($data),
'detected_mode' => $mode,
'recommended_error_level' => $errorLevel,
'optimal_version' => $version->getVersion(),
'matrix_size' => $version->getModuleCount(),
'data_capacity' => $version->getDataCapacity($errorLevel),
'efficiency' => $mode->getEfficiency(),
'capacity_used' => round((strlen($data) / $version->getDataCapacity($errorLevel)) * 100, 1),
];
}
/**
* Generate QR code for TOTP URI
*/
public function generateTotpQrCode(string $totpUri): string
{
// Validate TOTP URI format
if (! str_starts_with($totpUri, 'otpauth://totp/')) {
throw new InvalidArgumentException('Invalid TOTP URI format');
if (!$config->errorCorrectionLevel->isImplemented()) {
throw FrameworkException::simple(
"Error correction level {$config->errorCorrectionLevel->value} not yet implemented"
);
}
// Use appropriate settings for TOTP (allow larger versions)
$errorLevel = ErrorCorrectionLevel::M; // Medium error correction for TOTP
if (!$config->version->isImplemented()) {
throw FrameworkException::simple(
"Version {$config->version->getVersionNumber()} not yet implemented"
);
}
return $this->generateSvg($totpUri, $errorLevel, null); // Auto-detect version
}
/**
* Determine the optimal QR code version for given data
*/
private function determineOptimalVersion(string $data, ErrorCorrectionLevel $errorLevel): QrCodeVersion
{
// Validate data length
$dataLength = strlen($data);
$capacity = $config->version->getDataCapacity(
$config->encodingMode,
$config->errorCorrectionLevel
);
// Try to find the smallest version that can fit the data
return QrCodeVersion::forDataLength($dataLength, $errorLevel);
if ($dataLength > $capacity) {
throw FrameworkException::simple(
"Data too long: {$dataLength} bytes exceeds capacity of {$capacity} bytes for version {$config->version->getVersionNumber()}"
);
}
// Generate matrix
$matrix = self::generateMatrix($data, $config);
return $matrix;
}
/**
* Get generator configuration
* Generate QR Code matrix
*/
public function getConfiguration(): array
private static function generateMatrix(string $data, QrCodeConfig $config): QrCodeMatrix
{
return [
'encoder' => DataEncoder::class,
'matrix_generator' => MatrixGenerator::class,
'renderer' => $this->svgRenderer->getConfiguration(),
];
// 1. Create empty matrix
$matrix = QrCodeMatrix::create($config->version);
// 2. Add finder patterns (3 corners)
$matrix = FinderPattern::apply($matrix);
$matrix = FinderPattern::applySeparators($matrix);
// 3. Add alignment patterns (Version 2+)
$matrix = AlignmentPattern::apply($matrix);
// 4. Add timing patterns (alternating modules)
$matrix = TimingPattern::apply($matrix);
// 5. Add dark module (always at [4 * version + 9, 8])
$darkModuleRow = 4 * $config->version->getVersionNumber() + 9;
$matrix = $matrix->setModuleAt($darkModuleRow, 8, Module::dark());
// 6. Encode data into codewords
$dataCodewords = self::encodeData($data, $config);
// 7. Generate error correction codewords using Reed-Solomon
$reedSolomon = new ReedSolomonEncoder();
$ecInfo = ReedSolomonEncoder::getECInfo(
$config->version->getVersionNumber(),
$config->errorCorrectionLevel->value
);
$ecCodewords = $reedSolomon->encode($dataCodewords, $ecInfo['ecCodewords']);
// 8. Place data and EC codewords in matrix
$allCodewords = array_merge($dataCodewords, $ecCodewords);
$matrix = self::placeDataCodewords($matrix, $allCodewords);
// 9. Select best mask pattern (evaluates all 8 patterns)
$maskEvaluator = new MaskEvaluator();
$bestMask = $maskEvaluator->selectBestMask($matrix);
// 10. Apply selected mask (only to data bits, not function patterns)
$matrix = $maskEvaluator->applyMask($matrix, $bestMask);
// 11. Add format information AFTER masking
// Format information bits are NOT masked!
$matrix = FormatInformation::apply(
$matrix,
$config->errorCorrectionLevel,
$bestMask->value
);
return $matrix;
}
/**
* Validate data before encoding
* Encode data into codewords (Phase 2: Byte mode with proper structure)
*/
private function validateData(string $data): void
private static function encodeData(string $data, QrCodeConfig $config): array
{
if (strlen($data) > 2953) { // Max capacity for version 40, error level L
throw new InvalidArgumentException('Data too large for QR code: ' . strlen($data) . ' bytes');
$codewords = [];
$bits = '';
// 1. Mode indicator (4 bits) - Byte mode = 0100
$bits .= $config->encodingMode->getModeBits();
// 2. Character count indicator (8 bits for version 1-9 byte mode)
$charCountBits = $config->encodingMode->getCharacterCountBits($config->version);
$dataLength = strlen($data);
$bits .= str_pad(decbin($dataLength), $charCountBits, '0', STR_PAD_LEFT);
// 3. Data bytes (8 bits each)
for ($i = 0; $i < $dataLength; $i++) {
$byte = ord($data[$i]);
$bits .= str_pad(decbin($byte), 8, '0', STR_PAD_LEFT);
}
// Check for null bytes or other problematic characters
if (strpos($data, "\0") !== false) {
throw new InvalidArgumentException('Data contains null bytes');
// 4. Terminator (0000) - up to 4 bits
$ecInfo = ReedSolomonEncoder::getECInfo(
$config->version->getVersionNumber(),
$config->errorCorrectionLevel->value
);
$requiredBits = $ecInfo['dataCodewords'] * 8;
$terminatorLength = min(4, max(0, $requiredBits - strlen($bits)));
$bits .= str_repeat('0', $terminatorLength);
// 5. Pad to make multiple of 8
$remainder = strlen($bits) % 8;
if ($remainder !== 0) {
$bits .= str_repeat('0', 8 - $remainder);
}
// 6. Add pad codewords if needed (alternating 11101100 and 00010001)
$padBytes = ['11101100', '00010001'];
$padIndex = 0;
while (strlen($bits) < $requiredBits) {
$bits .= $padBytes[$padIndex % 2];
$padIndex++;
}
// 7. Convert bits to codewords
for ($i = 0; $i < strlen($bits); $i += 8) {
$byte = substr($bits, $i, 8);
$codewords[] = bindec($byte);
}
return $codewords;
}
/**
* Place data codewords in matrix using zig-zag pattern
*/
private static function placeDataCodewords(QrCodeMatrix $matrix, array $codewords): QrCodeMatrix
{
$size = $matrix->getSize();
$bitIndex = 0;
// Convert codewords to bit string
$bits = '';
foreach ($codewords as $codeword) {
$bits .= str_pad(decbin($codeword), 8, '0', STR_PAD_LEFT);
}
$totalBits = strlen($bits);
// Start from bottom-right, move in columns of 2, zig-zag up/down
for ($col = $size - 1; $col >= 1; $col -= 2) {
// Skip timing column (column 6)
if ($col === 6) {
$col--;
}
// Zig-zag direction (up for even pairs, down for odd pairs)
$upward = ((int) (($size - 1 - $col) / 2) % 2) === 0;
for ($i = 0; $i < $size; $i++) {
$row = $upward ? ($size - 1 - $i) : $i;
// Place bits in both columns of the pair
for ($c = 0; $c < 2; $c++) {
$currentCol = $col - $c;
$position = ModulePosition::at($row, $currentCol);
// Skip if position is already occupied (function patterns)
if (self::isOccupied($matrix, $position)) {
continue;
}
// Place bit if we still have data
if ($bitIndex < $totalBits) {
$bit = $bits[$bitIndex];
$module = ($bit === '1') ? Module::dark() : Module::light();
$matrix = $matrix->setModule($position, $module);
$bitIndex++;
} else {
// Padding with light modules
$matrix = $matrix->setModule($position, Module::light());
}
}
}
}
return $matrix;
}
/**
* Check if position is occupied by function pattern
*/
private static function isOccupied(QrCodeMatrix $matrix, ModulePosition $position): bool
{
$size = $matrix->getSize();
$row = $position->row;
$col = $position->column;
// Finder patterns (top-left, top-right, bottom-left) + separators
if (
// Top-left (0-8, 0-8)
($row <= 8 && $col <= 8) ||
// Top-right (0-7, size-9 to size-1) - EXCLUDE row 8 (format info)
($row <= 7 && $col >= $size - 8) ||
// Bottom-left (size-9 to size-1, 0-8) - EXCLUDE col 8 (format info)
($row >= $size - 8 && $col <= 7)
) {
return true;
}
// Timing patterns (row 6 or column 6)
if ($row === 6 || $col === 6) {
return true;
}
// Dark module position
$darkModuleRow = 4 * $matrix->getVersion()->getVersionNumber() + 9;
if ($row === $darkModuleRow && $col === 8) {
return true;
}
// Format information areas (15+15 bits, NOT entire row/column 8)
// Horizontal: row 8, columns 0-5, 7-8 (left) and size-8 to size-1 (right)
if ($row === 8) {
// Left side: columns 0-5, 7-8 (skip timing column 6)
if (($col >= 0 && $col <= 5) || $col === 7 || $col === 8) {
return true;
}
// Right side: columns size-8 to size-1
if ($col >= $size - 8) {
return true;
}
}
// Vertical: column 8, rows 0-8 (top) and size-7 to size-1 (bottom)
if ($col === 8) {
// Top side: rows 0-5, 7-8 (skip timing row 6)
if (($row >= 0 && $row <= 5) || $row === 7 || $row === 8) {
return true;
}
// Bottom side: rows size-7 to size-1
if ($row >= $size - 7) {
return true;
}
}
// Alignment patterns (Version 2+)
$alignmentLocations = AlignmentPattern::getLocations($matrix->getVersion()->getVersionNumber());
foreach ($alignmentLocations as $alignRow) {
foreach ($alignmentLocations as $alignCol) {
// Check if this is a valid alignment pattern position
// (not overlapping with finder patterns)
if ($alignRow <= 8 && $alignCol <= 8) {
continue; // Top-left finder
}
if ($alignRow <= 8 && $alignCol >= $size - 8) {
continue; // Top-right finder
}
if ($alignRow >= $size - 8 && $alignCol <= 8) {
continue; // Bottom-left finder
}
// Check if current position is within 5x5 alignment pattern
if (abs($row - $alignRow) <= 2 && abs($col - $alignCol) <= 2) {
return true;
}
}
}
return false;
}
}

194
src/Framework/QrCode/QrCodeMatrix.php
View File

@@ -1,194 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
use InvalidArgumentException;
/**
* QR Code Matrix
*
* Represents the 2D matrix of modules (black/white squares) that make up a QR code.
* Each module is either true (black) or false (white).
*/
final readonly class QrCodeMatrix
{
/**
* @param array<array<bool>> $modules 2D array of boolean values
*/
public function __construct(
private array $modules,
private int $size
) {
$this->validateMatrix($modules, $size);
}
/**
* Create empty matrix of given size
*/
public static function create(int $size): self
{
if ($size < 1) {
throw new InvalidArgumentException("Matrix size must be positive, got: {$size}");
}
$modules = array_fill(0, $size, array_fill(0, $size, false));
return new self($modules, $size);
}
/**
* Get the size of the matrix (width/height in modules)
*/
public function getSize(): int
{
return $this->size;
}
/**
* Get module value at position (row, column)
*/
public function getModule(int $row, int $col): bool
{
if (! $this->isValidPosition($row, $col)) {
throw new InvalidArgumentException("Position ({$row}, {$col}) is out of bounds for size {$this->size}");
}
return $this->modules[$row][$col];
}
/**
* Check if module at position is dark (true)
*/
public function isDark(int $row, int $col): bool
{
return $this->getModule($row, $col);
}
/**
* Check if module at position is light (false)
*/
public function isLight(int $row, int $col): bool
{
return ! $this->getModule($row, $col);
}
/**
* Set module value at position
*/
public function withModule(int $row, int $col, bool $dark): self
{
if (! $this->isValidPosition($row, $col)) {
throw new InvalidArgumentException("Position ({$row}, {$col}) is out of bounds for size {$this->size}");
}
$newModules = $this->modules;
$newModules[$row][$col] = $dark;
return new self($newModules, $this->size);
}
/**
* Set multiple modules at once
* @param array<array{row: int, col: int, dark: bool}> $updates
*/
public function withModules(array $updates): self
{
$newModules = $this->modules;
foreach ($updates as $update) {
if (! isset($update['row'], $update['col'], $update['dark'])) {
throw new InvalidArgumentException('Update must have row, col, and dark keys');
}
if (! $this->isValidPosition($update['row'], $update['col'])) {
throw new InvalidArgumentException("Position ({$update['row']}, {$update['col']}) is out of bounds");
}
$newModules[$update['row']][$update['col']] = $update['dark'];
}
return new self($newModules, $this->size);
}
/**
* Get all modules as 2D array
*/
public function getModules(): array
{
return $this->modules;
}
/**
* Convert matrix to string representation (for debugging)
*/
public function toString(string $darkChar = '█', string $lightChar = ' '): string
{
$result = '';
for ($row = 0; $row < $this->size; $row++) {
for ($col = 0; $col < $this->size; $col++) {
$result .= $this->modules[$row][$col] ? $darkChar : $lightChar;
}
$result .= "\n";
}
return $result;
}
/**
* Get matrix statistics (for debugging/optimization)
*/
public function getStatistics(): array
{
$darkCount = 0;
$totalCount = $this->size * $this->size;
for ($row = 0; $row < $this->size; $row++) {
for ($col = 0; $col < $this->size; $col++) {
if ($this->modules[$row][$col]) {
$darkCount++;
}
}
}
return [
'size' => $this->size,
'total_modules' => $totalCount,
'dark_modules' => $darkCount,
'light_modules' => $totalCount - $darkCount,
'dark_ratio' => $darkCount / $totalCount,
];
}
/**
* Check if position is within matrix bounds
*/
private function isValidPosition(int $row, int $col): bool
{
return $row >= 0 && $row < $this->size && $col >= 0 && $col < $this->size;
}
/**
* Validate matrix structure
*/
private function validateMatrix(array $modules, int $size): void
{
if (count($modules) !== $size) {
throw new InvalidArgumentException("Matrix must have {$size} rows, got: " . count($modules));
}
foreach ($modules as $row => $cols) {
if (! is_array($cols) || count($cols) !== $size) {
throw new InvalidArgumentException("Row {$row} must have {$size} columns, got: " . count($cols));
}
foreach ($cols as $col => $value) {
if (! is_bool($value)) {
throw new InvalidArgumentException("Module at ({$row}, {$col}) must be boolean, got: " . gettype($value));
}
}
}
}
}

152
src/Framework/QrCode/QrCodeRenderer.php Normal file
View File

@@ -0,0 +1,152 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
use App\Framework\Core\ValueObjects\Dimensions;
use App\Framework\Filesystem\FileStorage;
use App\Framework\QrCode\ValueObjects\ModulePosition;
use App\Framework\QrCode\ValueObjects\QrCodeMatrix;
use App\Framework\QrCode\ValueObjects\QrCodeStyle;
use App\Framework\Svg\Builder\SvgBuilder;
use App\Framework\Svg\Builder\SvgCanvas;
use App\Framework\Svg\ValueObjects\Geometry\Position;
use App\Framework\Svg\ValueObjects\Styling\Fill;
/**
* QR Code SVG Renderer
*
* Renders QR Code matrix to SVG using the framework's SVG module
*/
final readonly class QrCodeRenderer
{
public function __construct(
private ?FileStorage $fileStorage = null
) {}
/**
* Render QR Code matrix to SVG string
*/
public function renderSvg(QrCodeMatrix $matrix, ?QrCodeStyle $style = null): string
{
$style = $style ?? QrCodeStyle::default();
$canvas = $this->createCanvas($matrix, $style);
$canvas = $this->renderModules($canvas, $matrix, $style);
return $canvas->toSvg();
}
/**
* Render QR Code matrix to inline SVG (without XML declaration)
*/
public function renderInlineSvg(QrCodeMatrix $matrix, ?QrCodeStyle $style = null): string
{
$style = $style ?? QrCodeStyle::default();
$canvas = $this->createCanvas($matrix, $style);
$canvas = $this->renderModules($canvas, $matrix, $style);
return $canvas->toInlineSvg();
}
/**
* Render QR Code matrix to SVG file
*/
public function renderToFile(
QrCodeMatrix $matrix,
string $filepath,
?QrCodeStyle $style = null
): void {
$style = $style ?? QrCodeStyle::default();
$canvas = $this->createCanvas($matrix, $style);
$canvas = $this->renderModules($canvas, $matrix, $style);
$canvas->toFile($filepath);
}
/**
* Create SVG canvas with proper dimensions
*/
private function createCanvas(QrCodeMatrix $matrix, QrCodeStyle $style): SvgCanvas
{
$matrixSize = $matrix->getSize();
$canvasSize = $style->calculateCanvasSize($matrixSize);
$dimensions = new Dimensions($canvasSize, $canvasSize);
return SvgBuilder::canvas($dimensions, null, $this->fileStorage)
->withTitle('QR Code')
->withDescription("QR Code Version {$matrix->getVersion()->getVersionNumber()}");
}
/**
* Render all modules to canvas
*/
private function renderModules(
SvgCanvas $canvas,
QrCodeMatrix $matrix,
QrCodeStyle $style
): SvgCanvas {
// Background (light color)
$canvas->rect(
Position::zero(),
new Dimensions(
$style->calculateCanvasSize($matrix->getSize()),
$style->calculateCanvasSize($matrix->getSize())
),
Fill::solid($style->lightColor)
);
// Render each dark module as rectangle
$matrixSize = $matrix->getSize();
$offset = $style->getQuietZoneOffset();
for ($row = 0; $row < $matrixSize; $row++) {
for ($col = 0; $col < $matrixSize; $col++) {
$position = ModulePosition::at($row, $col);
$module = $matrix->getModule($position);
if ($module->isDark()) {
$x = $offset + ($col * $style->moduleSize);
$y = $offset + ($row * $style->moduleSize);
$canvas->rect(
new Position($x, $y),
new Dimensions($style->moduleSize, $style->moduleSize),
Fill::solid($style->darkColor)
);
}
}
}
return $canvas;
}
/**
* Render QR Code with custom styling
*/
public function renderCustom(
QrCodeMatrix $matrix,
QrCodeStyle $style,
bool $inline = false
): string {
$canvas = $this->createCanvas($matrix, $style);
$canvas = $this->renderModules($canvas, $matrix, $style);
return $inline ? $canvas->toInlineSvg() : $canvas->toSvg();
}
/**
* Get data URL for embedding in HTML
*/
public function toDataUrl(QrCodeMatrix $matrix, ?QrCodeStyle $style = null): string
{
$svg = $this->renderInlineSvg($matrix, $style);
$base64 = base64_encode($svg);
return "data:image/svg+xml;base64,{$base64}";
}
}

133
src/Framework/QrCode/QrCodeVersion.php
View File

@@ -1,133 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
use InvalidArgumentException;
/**
* QR Code Version (Size)
*
* QR codes come in versions 1-40, where each version determines the size:
* Version 1: 21x21 modules
* Version 2: 25x25 modules
* Version N: (17 + 4*N) x (17 + 4*N) modules
*/
final readonly class QrCodeVersion
{
public function __construct(
private int $version
) {
if ($version < 1 || $version > 40) {
throw new InvalidArgumentException("QR Code version must be between 1 and 40, got: {$version}");
}
}
/**
* Create version 1 (smallest)
*/
public static function v1(): self
{
return new self(1);
}
/**
* Create version for typical TOTP URLs
*/
public static function forTotp(): self
{
return new self(3); // Good size for TOTP URLs (~130 chars)
}
/**
* Get the version number (1-40)
*/
public function getVersion(): int
{
return $this->version;
}
/**
* Get the module count per side (21, 25, 29, etc.)
*/
public function getModuleCount(): int
{
return 17 + 4 * $this->version;
}
/**
* Get the total data capacity for this version/error correction level
*/
public function getDataCapacity(ErrorCorrectionLevel $errorLevel): int
{
// Data capacity table for first few versions (in BYTES) - From QR Code specification
$capacitiesInBytes = [
1 => ['L' => 19, 'M' => 16, 'Q' => 13, 'H' => 9], // Version 1
2 => ['L' => 34, 'M' => 28, 'Q' => 22, 'H' => 16], // Version 2
3 => ['L' => 55, 'M' => 44, 'Q' => 34, 'H' => 26], // Version 3
4 => ['L' => 80, 'M' => 64, 'Q' => 48, 'H' => 36], // Version 4
5 => ['L' => 108, 'M' => 86, 'Q' => 62, 'H' => 46], // Version 5
6 => ['L' => 136, 'M' => 108, 'Q' => 76, 'H' => 60], // Version 6
];
if (! isset($capacitiesInBytes[$this->version])) {
// For higher versions, use approximation based on module count
$totalModules = $this->getModuleCount() ** 2;
$dataModulesRatio = 0.6; // Approximate ratio of data modules to total modules
$errorReduction = $errorLevel->getCapacityPercentage() / 100;
$estimatedBytes = (int) (($totalModules * $dataModulesRatio * (1 - $errorReduction)) / 8);
return $estimatedBytes * 8; // Convert to bits
}
// Convert bytes to bits (1 byte = 8 bits)
return $capacitiesInBytes[$this->version][$errorLevel->value] * 8;
}
/**
* Determine minimum version needed for data length (in bytes)
*/
public static function forDataLength(int $dataLength, ErrorCorrectionLevel $errorLevel = ErrorCorrectionLevel::M): self
{
// Convert bytes to bits for comparison (8 bits per byte + overhead for mode/length indicators)
$requiredBits = ($dataLength * 8) + 32; // Add 32 bits overhead for mode, length, terminator
for ($version = 1; $version <= 40; $version++) {
$qrVersion = new self($version);
if ($qrVersion->getDataCapacity($errorLevel) >= $requiredBits) {
return $qrVersion;
}
}
throw new InvalidArgumentException("Data too large for any QR Code version: {$dataLength} bytes ({$requiredBits} bits needed)");
}
/**
* Check if this version has alignment patterns
*/
public function hasAlignmentPatterns(): bool
{
return $this->version >= 2;
}
/**
* Get alignment pattern positions for this version
*/
public function getAlignmentPositions(): array
{
if (! $this->hasAlignmentPatterns()) {
return [];
}
// Simplified - in full implementation this would be complete table
$patterns = [
2 => [6, 18],
3 => [6, 22],
4 => [6, 26],
5 => [6, 30],
];
return $patterns[$this->version] ?? [6, 6 + 4 * $this->version];
}
}

154
src/Framework/QrCode/ReedSolomon/GaloisField.php
View File

@@ -1,154 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ReedSolomon;
/**
* Galois Field GF(256) for Reed-Solomon Error Correction
*
* Implements Galois Field arithmetic using primitive polynomial x^8 + x^4 + x^3 + x^2 + 1
*/
final class GaloisField
{
private const PRIMITIVE_POLYNOMIAL = 0x11d; // x^8 + x^4 + x^3 + x^2 + 1
private array $expTable;
private array $logTable;
public function __construct()
{
$this->buildTables();
}
/**
* Get singleton instance
*/
public static function getInstance(): self
{
static $instance = null;
if ($instance === null) {
$instance = new self();
}
return $instance;
}
/**
* Add two numbers in GF(256)
*/
public function add(int $a, int $b): int
{
return $a ^ $b;
}
/**
* Subtract two numbers in GF(256) (same as addition)
*/
public function subtract(int $a, int $b): int
{
return $a ^ $b;
}
/**
* Multiply two numbers in GF(256)
*/
public function multiply(int $a, int $b): int
{
if ($a === 0 || $b === 0) {
return 0;
}
return $this->expTable[($this->logTable[$a] + $this->logTable[$b]) % 255];
}
/**
* Divide two numbers in GF(256)
*/
public function divide(int $a, int $b): int
{
if ($b === 0) {
throw new \InvalidArgumentException('Division by zero in GF(256)');
}
if ($a === 0) {
return 0;
}
return $this->expTable[($this->logTable[$a] - $this->logTable[$b] + 255) % 255];
}
/**
* Raise a number to a power in GF(256)
*/
public function power(int $base, int $exponent): int
{
if ($base === 0) {
return 0;
}
if ($exponent === 0) {
return 1;
}
return $this->expTable[($this->logTable[$base] * $exponent) % 255];
}
/**
* Get multiplicative inverse of a number in GF(256)
*/
public function inverse(int $a): int
{
if ($a === 0) {
throw new \InvalidArgumentException('Cannot find inverse of 0 in GF(256)');
}
return $this->expTable[255 - $this->logTable[$a]];
}
/**
* Build exponential and logarithm tables
*/
private function buildTables(): void
{
$this->expTable = array_fill(0, 512, 0);
$this->logTable = array_fill(0, 256, 0);
$x = 1;
for ($i = 0; $i < 255; $i++) {
$this->expTable[$i] = $x;
$this->logTable[$x] = $i;
$x <<= 1;
if ($x & 0x100) {
$x ^= self::PRIMITIVE_POLYNOMIAL;
}
}
// Extend exp table for easier calculations
for ($i = 255; $i < 512; $i++) {
$this->expTable[$i] = $this->expTable[$i - 255];
}
}
/**
* Get exp table value
*/
public function exp(int $a): int
{
return $this->expTable[$a];
}
/**
* Get log table value
*/
public function log(int $a): int
{
if ($a === 0) {
throw new \InvalidArgumentException('Cannot take log of 0');
}
return $this->logTable[$a];
}
}

223
src/Framework/QrCode/ReedSolomon/Polynomial.php
View File

@@ -1,223 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ReedSolomon;
/**
* Polynomial for Reed-Solomon Error Correction
*/
final class Polynomial
{
private GaloisField $field;
private array $coefficients;
public function __construct(GaloisField $field, array $coefficients)
{
$this->field = $field;
// Remove leading zeros
$firstNonZero = 0;
while ($firstNonZero < count($coefficients) && $coefficients[$firstNonZero] === 0) {
$firstNonZero++;
}
if ($firstNonZero === count($coefficients)) {
$this->coefficients = [0];
} else {
$this->coefficients = array_slice($coefficients, $firstNonZero);
}
}
/**
* Get coefficient at given power
*/
public function getCoefficient(int $degree): int
{
$index = count($this->coefficients) - 1 - $degree;
return $index < 0 ? 0 : $this->coefficients[$index];
}
/**
* Get all coefficients
*/
public function getCoefficients(): array
{
return $this->coefficients;
}
/**
* Get degree of polynomial
*/
public function getDegree(): int
{
return count($this->coefficients) - 1;
}
/**
* Check if polynomial is zero
*/
public function isZero(): bool
{
return count($this->coefficients) === 1 && $this->coefficients[0] === 0;
}
/**
* Add two polynomials
*/
public function add(self $other): self
{
if ($this->isZero()) {
return $other;
}
if ($other->isZero()) {
return $this;
}
$smallerCoeffs = $this->coefficients;
$largerCoeffs = $other->coefficients;
if (count($smallerCoeffs) > count($largerCoeffs)) {
[$smallerCoeffs, $largerCoeffs] = [$largerCoeffs, $smallerCoeffs];
}
$sumDiff = array_fill(0, count($largerCoeffs), 0);
$lengthDiff = count($largerCoeffs) - count($smallerCoeffs);
// Copy first part
for ($i = 0; $i < $lengthDiff; $i++) {
$sumDiff[$i] = $largerCoeffs[$i];
}
// Add overlapping part
for ($i = $lengthDiff; $i < count($largerCoeffs); $i++) {
$sumDiff[$i] = $this->field->add($smallerCoeffs[$i - $lengthDiff], $largerCoeffs[$i]);
}
return new self($this->field, $sumDiff);
}
/**
* Multiply two polynomials
*/
public function multiply(self $other): self
{
if ($this->isZero() || $other->isZero()) {
return new self($this->field, [0]);
}
$aCoeffs = $this->coefficients;
$bCoeffs = $other->coefficients;
$product = array_fill(0, count($aCoeffs) + count($bCoeffs) - 1, 0);
for ($i = 0; $i < count($aCoeffs); $i++) {
for ($j = 0; $j < count($bCoeffs); $j++) {
$product[$i + $j] = $this->field->add(
$product[$i + $j],
$this->field->multiply($aCoeffs[$i], $bCoeffs[$j])
);
}
}
return new self($this->field, $product);
}
/**
* Multiply by scalar
*/
public function multiplyByScalar(int $scalar): self
{
if ($scalar === 0) {
return new self($this->field, [0]);
}
if ($scalar === 1) {
return $this;
}
$result = array_fill(0, count($this->coefficients), 0);
for ($i = 0; $i < count($this->coefficients); $i++) {
$result[$i] = $this->field->multiply($this->coefficients[$i], $scalar);
}
return new self($this->field, $result);
}
/**
* Multiply by monomial
*/
public function multiplyByMonomial(int $degree, int $coefficient): self
{
if ($coefficient === 0) {
return new self($this->field, [0]);
}
$result = array_fill(0, count($this->coefficients) + $degree, 0);
for ($i = 0; $i < count($this->coefficients); $i++) {
$result[$i] = $this->field->multiply($this->coefficients[$i], $coefficient);
}
return new self($this->field, $result);
}
/**
* Divide polynomials
*/
public function divide(self $other): array
{
if ($other->isZero()) {
throw new \InvalidArgumentException('Cannot divide by zero polynomial');
}
$quotient = new self($this->field, [0]);
$remainder = $this;
$denominatorLeadingTerm = $other->getCoefficient($other->getDegree());
$inverseDenominatorLeadingTerm = $this->field->inverse($denominatorLeadingTerm);
while ($remainder->getDegree() >= $other->getDegree() && ! $remainder->isZero()) {
$degreeDifference = $remainder->getDegree() - $other->getDegree();
$scale = $this->field->multiply(
$remainder->getCoefficient($remainder->getDegree()),
$inverseDenominatorLeadingTerm
);
$term = $other->multiplyByMonomial($degreeDifference, $scale);
$iterationQuotient = new self($this->field, [$scale]);
if ($degreeDifference > 0) {
$iterationQuotient = $iterationQuotient->multiplyByMonomial($degreeDifference, 1);
}
$quotient = $quotient->add($iterationQuotient);
$remainder = $remainder->add($term);
}
return [$quotient, $remainder];
}
/**
* Evaluate polynomial at given point
*/
public function evaluateAt(int $a): int
{
if ($a === 0) {
return $this->getCoefficient(0);
}
$result = $this->coefficients[0];
for ($i = 1; $i < count($this->coefficients); $i++) {
$result = $this->field->add(
$this->field->multiply($a, $result),
$this->coefficients[$i]
);
}
return $result;
}
}

129
src/Framework/QrCode/ReedSolomon/ReedSolomonEncoder.php
View File

@@ -1,129 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ReedSolomon;
/**
* Reed-Solomon Encoder for QR Code Error Correction
*
* Generates error correction codewords for QR code data blocks
* using Reed-Solomon error correction codes over GF(256)
*/
final class ReedSolomonEncoder
{
private GaloisField $field;
private array $generatorPolynomials;
public function __construct()
{
$this->field = GaloisField::getInstance();
$this->generatorPolynomials = [];
}
/**
* Encode data bytes with error correction codewords
*/
public function encode(array $dataBytes, int $ecCodewords): array
{
if (count($dataBytes) === 0) {
throw new \InvalidArgumentException('Data bytes cannot be empty');
}
if ($ecCodewords <= 0) {
throw new \InvalidArgumentException('Error correction codewords must be positive');
}
// Get generator polynomial for this number of error correction codewords
$generator = $this->getGeneratorPolynomial($ecCodewords);
// Create info polynomial from data bytes
$infoCoeffs = array_merge($dataBytes, array_fill(0, $ecCodewords, 0));
$info = new Polynomial($this->field, $infoCoeffs);
// Divide info polynomial by generator polynomial
[$quotient, $remainder] = $info->divide($generator);
// Extract error correction codewords from remainder
$numZeroCoeffs = $ecCodewords - $remainder->getDegree() - 1;
$ecBytes = array_fill(0, $numZeroCoeffs, 0);
$remainderCoeffs = $remainder->getCoefficients();
for ($i = count($remainderCoeffs) - 1; $i >= 0; $i--) {
$ecBytes[] = $remainderCoeffs[$i];
}
return array_merge($dataBytes, $ecBytes);
}
/**
* Get generator polynomial for given number of error correction codewords
*/
private function getGeneratorPolynomial(int $degree): Polynomial
{
if (isset($this->generatorPolynomials[$degree])) {
return $this->generatorPolynomials[$degree];
}
// Build generator polynomial: (x - α^0)(x - α^1)...(x - α^(degree-1))
$generator = new Polynomial($this->field, [1]);
for ($i = 0; $i < $degree; $i++) {
$root = $this->field->exp($i);
$factor = new Polynomial($this->field, [1, $root]);
$generator = $generator->multiply($factor);
}
$this->generatorPolynomials[$degree] = $generator;
return $generator;
}
/**
* Calculate required error correction codewords for QR code version and level
*/
public static function getErrorCorrectionCodewords(int $version, string $errorLevel): int
{
// Error correction codewords lookup table for QR versions 1-40
$ecTable = [
'L' => [7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30, 30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
'M' => [10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28],
'Q' => [13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30, 30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
'H' => [17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
];
if (! isset($ecTable[$errorLevel])) {
throw new \InvalidArgumentException("Invalid error correction level: $errorLevel");
}
if ($version < 1 || $version > 40) {
throw new \InvalidArgumentException("Invalid QR version: $version");
}
return $ecTable[$errorLevel][$version - 1];
}
/**
* Get data capacity for QR code version and error correction level
*/
public static function getDataCapacity(int $version, string $errorLevel): int
{
// Total codewords for each version
$totalCodewords = [
26, 44, 70, 100, 134, 172, 196, 242, 292, 346,
404, 466, 532, 581, 655, 733, 815, 901, 991, 1085,
1156, 1258, 1364, 1474, 1588, 1706, 1828, 1921, 2051, 2185,
2323, 2465, 2611, 2761, 2876, 3034, 3196, 3362, 3532, 3706,
];
if ($version < 1 || $version > 40) {
throw new \InvalidArgumentException("Invalid QR version: $version");
}
$total = $totalCodewords[$version - 1];
$errorCorrection = self::getErrorCorrectionCodewords($version, $errorLevel);
return $total - $errorCorrection;
}
}

144
src/Framework/QrCode/Structure/AlignmentPattern.php Normal file
View File

@@ -0,0 +1,144 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Structure;
use App\Framework\QrCode\ValueObjects\Module;
use App\Framework\QrCode\ValueObjects\ModulePosition;
use App\Framework\QrCode\ValueObjects\QrCodeMatrix;
/**
* QR Code Alignment Pattern Generator
*
* Generates 5x5 alignment patterns for Version 2+ QR Codes
* Alignment patterns help scanners correct for distortion
*
* Pattern structure (5x5):
* █████
* █░░░█
* █░█░█
* █░░░█
* █████
*/
final readonly class AlignmentPattern
{
/**
* Alignment pattern center positions by version
* ISO/IEC 18004:2015 Table E.1
*/
private const ALIGNMENT_PATTERN_LOCATIONS = [
1 => [], // No alignment patterns
2 => [6, 18],
3 => [6, 22],
4 => [6, 26],
5 => [6, 30],
6 => [6, 34],
7 => [6, 22, 38],
8 => [6, 24, 42],
9 => [6, 26, 46],
10 => [6, 28, 50],
];
/**
* Apply all alignment patterns to matrix
*/
public static function apply(QrCodeMatrix $matrix): QrCodeMatrix
{
$version = $matrix->getVersion()->getVersionNumber();
if (!isset(self::ALIGNMENT_PATTERN_LOCATIONS[$version])) {
// No alignment patterns for this version (should not happen)
return $matrix;
}
$locations = self::ALIGNMENT_PATTERN_LOCATIONS[$version];
if (empty($locations)) {
// Version 1 has no alignment patterns
return $matrix;
}
// Generate alignment patterns at all valid positions
foreach ($locations as $row) {
foreach ($locations as $col) {
// Skip if this position overlaps with a finder pattern
if (self::overlapsWithFinderPattern($row, $col, $matrix->getSize())) {
continue;
}
$center = ModulePosition::at($row, $col);
$matrix = self::drawPattern($matrix, $center);
}
}
return $matrix;
}
/**
* Draw single 5x5 alignment pattern centered at position
*/
private static function drawPattern(QrCodeMatrix $matrix, ModulePosition $center): QrCodeMatrix
{
$centerRow = $center->row;
$centerCol = $center->column;
// 5x5 pattern centered at position
for ($dr = -2; $dr <= 2; $dr++) {
for ($dc = -2; $dc <= 2; $dc++) {
$row = $centerRow + $dr;
$col = $centerCol + $dc;
$position = ModulePosition::at($row, $col);
// Outer border (always dark)
if (abs($dr) === 2 || abs($dc) === 2) {
$matrix = $matrix->setModule($position, Module::dark());
}
// Center module (dark)
elseif ($dr === 0 && $dc === 0) {
$matrix = $matrix->setModule($position, Module::dark());
}
// Inner ring (light)
else {
$matrix = $matrix->setModule($position, Module::light());
}
}
}
return $matrix;
}
/**
* Check if alignment pattern position overlaps with finder pattern
*/
private static function overlapsWithFinderPattern(int $row, int $col, int $size): bool
{
// Finder patterns occupy 9x9 area (7x7 pattern + 1 module separator)
// Top-left finder pattern (0-8, 0-8)
if ($row <= 8 && $col <= 8) {
return true;
}
// Top-right finder pattern (0-8, size-9 to size-1)
if ($row <= 8 && $col >= $size - 8) {
return true;
}
// Bottom-left finder pattern (size-9 to size-1, 0-8)
if ($row >= $size - 8 && $col <= 8) {
return true;
}
return false;
}
/**
* Get alignment pattern center positions for version
*/
public static function getLocations(int $version): array
{
return self::ALIGNMENT_PATTERN_LOCATIONS[$version] ?? [];
}
}

167
src/Framework/QrCode/Structure/BlockStructure.php
View File

@@ -1,167 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Structure;
use App\Framework\QrCode\ReedSolomon\ReedSolomonEncoder;
/**
* QR Code Block Structure Manager
*
* Handles data block division and error correction code generation
* according to QR code specification
*/
final class BlockStructure
{
private ReedSolomonEncoder $encoder;
public function __construct()
{
$this->encoder = new ReedSolomonEncoder();
}
/**
* Create blocks from data codewords
*/
public function createBlocks(array $dataCodewords, int $version, string $errorLevel): array
{
$blockInfo = $this->getBlockInfo($version, $errorLevel);
$blocks = [];
$dataOffset = 0;
// Create Group 1 blocks (if any)
for ($i = 0; $i < $blockInfo['group1_blocks']; $i++) {
$blockData = array_slice(
$dataCodewords,
$dataOffset,
$blockInfo['group1_data_per_block']
);
$errorCodewords = $this->encoder->encode(
$blockData,
$blockInfo['error_correction_per_block']
);
$blocks[] = new QrCodeBlock(
$blockData,
array_slice($errorCodewords, count($blockData))
);
$dataOffset += $blockInfo['group1_data_per_block'];
}
// Create Group 2 blocks (if any)
for ($i = 0; $i < $blockInfo['group2_blocks']; $i++) {
$blockData = array_slice(
$dataCodewords,
$dataOffset,
$blockInfo['group2_data_per_block']
);
$errorCodewords = $this->encoder->encode(
$blockData,
$blockInfo['error_correction_per_block']
);
$blocks[] = new QrCodeBlock(
$blockData,
array_slice($errorCodewords, count($blockData))
);
$dataOffset += $blockInfo['group2_data_per_block'];
}
return $blocks;
}
/**
* Interleave data and error correction codewords from blocks
*/
public function interleaveBlocks(array $blocks): array
{
if (empty($blocks)) {
return [];
}
$result = [];
// Interleave data codewords
$maxDataLength = max(array_map(fn ($block) => $block->getDataLength(), $blocks));
for ($i = 0; $i < $maxDataLength; $i++) {
foreach ($blocks as $block) {
if ($i < $block->getDataLength()) {
$result[] = $block->dataCodewords[$i];
}
}
}
// Interleave error correction codewords
$maxEcLength = max(array_map(fn ($block) => $block->getErrorCorrectionLength(), $blocks));
for ($i = 0; $i < $maxEcLength; $i++) {
foreach ($blocks as $block) {
if ($i < $block->getErrorCorrectionLength()) {
$result[] = $block->errorCorrectionCodewords[$i];
}
}
}
return $result;
}
/**
* Get block structure information for version and error level
*/
private function getBlockInfo(int $version, string $errorLevel): array
{
// Block structure lookup table for QR versions 1-10 (simplified for now)
$blockStructures = [
1 => [
'L' => ['group1_blocks' => 1, 'group1_data_per_block' => 19, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 7],
'M' => ['group1_blocks' => 1, 'group1_data_per_block' => 16, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 10],
'Q' => ['group1_blocks' => 1, 'group1_data_per_block' => 13, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 13],
'H' => ['group1_blocks' => 1, 'group1_data_per_block' => 9, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 17],
],
2 => [
'L' => ['group1_blocks' => 1, 'group1_data_per_block' => 34, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 10],
'M' => ['group1_blocks' => 1, 'group1_data_per_block' => 28, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 16],
'Q' => ['group1_blocks' => 1, 'group1_data_per_block' => 22, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 22],
'H' => ['group1_blocks' => 1, 'group1_data_per_block' => 16, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 28],
],
3 => [
'L' => ['group1_blocks' => 1, 'group1_data_per_block' => 55, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 15],
'M' => ['group1_blocks' => 1, 'group1_data_per_block' => 44, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 26],
'Q' => ['group1_blocks' => 2, 'group1_data_per_block' => 17, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 18],
'H' => ['group1_blocks' => 2, 'group1_data_per_block' => 13, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 22],
],
4 => [
'L' => ['group1_blocks' => 1, 'group1_data_per_block' => 80, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 20],
'M' => ['group1_blocks' => 2, 'group1_data_per_block' => 32, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 18],
'Q' => ['group1_blocks' => 2, 'group1_data_per_block' => 24, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 26],
'H' => ['group1_blocks' => 4, 'group1_data_per_block' => 9, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 16],
],
5 => [
'L' => ['group1_blocks' => 1, 'group1_data_per_block' => 108, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 26],
'M' => ['group1_blocks' => 2, 'group1_data_per_block' => 43, 'group2_blocks' => 0, 'group2_data_per_block' => 0, 'error_correction_per_block' => 24],
'Q' => ['group1_blocks' => 2, 'group1_data_per_block' => 15, 'group2_blocks' => 2, 'group2_data_per_block' => 16, 'error_correction_per_block' => 18],
'H' => ['group1_blocks' => 2, 'group1_data_per_block' => 11, 'group2_blocks' => 2, 'group2_data_per_block' => 12, 'error_correction_per_block' => 22],
],
];
if (! isset($blockStructures[$version][$errorLevel])) {
// Default fallback for unsupported versions
return [
'group1_blocks' => 1,
'group1_data_per_block' => ReedSolomonEncoder::getDataCapacity($version, $errorLevel),
'group2_blocks' => 0,
'group2_data_per_block' => 0,
'error_correction_per_block' => ReedSolomonEncoder::getErrorCorrectionCodewords($version, $errorLevel),
];
}
return $blockStructures[$version][$errorLevel];
}
}

112
src/Framework/QrCode/Structure/FinderPattern.php Normal file
View File

@@ -0,0 +1,112 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Structure;
use App\Framework\QrCode\ValueObjects\Module;
use App\Framework\QrCode\ValueObjects\ModulePosition;
use App\Framework\QrCode\ValueObjects\QrCodeMatrix;
/**
* QR Code Finder Pattern Generator
*
* Generates the three 7x7 finder patterns (position detection patterns)
* Located in three corners: top-left, top-right, bottom-left
*
* Pattern structure (7x7):
* █████████
* █░░░░░░█
* █░█████░█
* █░█░░░█░█
* █░█████░█
* █░░░░░░█
* █████████
*/
final readonly class FinderPattern
{
/**
* Apply all three finder patterns to matrix
*/
public static function apply(QrCodeMatrix $matrix): QrCodeMatrix
{
$size = $matrix->getSize();
// Top-left corner
$matrix = self::drawPattern($matrix, ModulePosition::at(0, 0));
// Top-right corner
$matrix = self::drawPattern($matrix, ModulePosition::at(0, $size - 7));
// Bottom-left corner
$matrix = self::drawPattern($matrix, ModulePosition::at($size - 7, 0));
return $matrix;
}
/**
* Draw single 7x7 finder pattern at position
*
* QR Code Finder Pattern (1:1:3:1:1 ratio):
* - Outer ring (1 module): DARK
* - White ring (1 module): LIGHT
* - Inner 3x3 center (3 modules): DARK
*/
private static function drawPattern(QrCodeMatrix $matrix, ModulePosition $topLeft): QrCodeMatrix
{
// 7x7 finder pattern with inner 3x3 dark, 1-module white ring, outer dark ring
for ($r = 0; $r < 7; $r++) {
for ($c = 0; $c < 7; $c++) {
$row = $topLeft->row + $r;
$col = $topLeft->column + $c;
$pos = ModulePosition::at($row, $col);
// Outer ring (r==0 || r==6 || c==0 || c==6) => DARK
if ($r === 0 || $r === 6 || $c === 0 || $c === 6) {
$matrix = $matrix->setModule($pos, Module::dark());
continue;
}
// White ring (r==1 || r==5 || c==1 || c==5) => LIGHT
if ($r === 1 || $r === 5 || $c === 1 || $c === 5) {
$matrix = $matrix->setModule($pos, Module::light());
continue;
}
// Inner 3x3 (r,c in 2..4) => DARK
$matrix = $matrix->setModule($pos, Module::dark());
}
}
return $matrix;
}
/**
* Add separator (1 module white border around finder pattern)
* The separator is the 8th row/column around the 7x7 finder pattern
*/
public static function applySeparators(QrCodeMatrix $matrix): QrCodeMatrix
{
$size = $matrix->getSize();
// Top-left separator (row 7 and column 7)
for ($i = 0; $i < 8; $i++) {
$matrix = $matrix->setModuleAt(7, $i, Module::light()); // Row 7
$matrix = $matrix->setModuleAt($i, 7, Module::light()); // Column 7
}
// Top-right separator (row 7 and column size-8)
for ($i = 0; $i < 8; $i++) {
$matrix = $matrix->setModuleAt(7, $size - 1 - $i, Module::light()); // Row 7
$matrix = $matrix->setModuleAt($i, $size - 8, Module::light()); // Column size-8
}
// Bottom-left separator (row size-8 and column 7)
for ($i = 0; $i < 8; $i++) {
$matrix = $matrix->setModuleAt($size - 8, $i, Module::light()); // Row size-8
$matrix = $matrix->setModuleAt($size - 1 - $i, 7, Module::light()); // Column 7
}
return $matrix;
}
}

154
src/Framework/QrCode/Structure/FormatInformation.php Normal file
View File

@@ -0,0 +1,154 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Structure;
use App\Framework\QrCode\ValueObjects\ErrorCorrectionLevel;
use App\Framework\QrCode\ValueObjects\Module;
use App\Framework\QrCode\ValueObjects\ModulePosition;
use App\Framework\QrCode\ValueObjects\QrCodeMatrix;
/**
* QR Code Format Information
*
* Encodes error correction level and mask pattern into 15-bit format string
* Uses BCH(15,5) error correction
*/
final readonly class FormatInformation
{
// Format information with error correction for each EC level and mask pattern
// Pre-calculated to avoid BCH encoding at runtime
private const FORMAT_INFO_TABLE = [
'L' => [
0 => 0b111011111000100, // Level L, Mask 0
1 => 0b111001011110011,
2 => 0b111110110101010,
3 => 0b111100010011101,
4 => 0b110011000101111,
5 => 0b110001100011000,
6 => 0b110110001000001,
7 => 0b110100101110110,
],
'M' => [
0 => 0b101010000010010, // Level M, Mask 0
1 => 0b101000100100101,
2 => 0b101111001111100,
3 => 0b101101101001011,
4 => 0b100010111111001,
5 => 0b100000011001110,
6 => 0b100111110010111,
7 => 0b100101010100000,
],
'Q' => [
0 => 0b011010101011111, // Level Q, Mask 0
1 => 0b011000001101000,
2 => 0b011111100110001,
3 => 0b011101000000110,
4 => 0b010010010110100,
5 => 0b010000110000011,
6 => 0b010111011011010,
7 => 0b010101111101101,
],
'H' => [
0 => 0b001011010001001, // Level H, Mask 0
1 => 0b001001110111110,
2 => 0b001110011100111,
3 => 0b001100111010000,
4 => 0b000011101100010,
5 => 0b000001001010101,
6 => 0b000110100001100,
7 => 0b000100000111011,
],
];
/**
* Apply format information to matrix
*/
public static function apply(
QrCodeMatrix $matrix,
ErrorCorrectionLevel $level,
int $maskPattern
): QrCodeMatrix {
$formatBits = self::getFormatBits($level, $maskPattern);
// Apply format information in two locations
$matrix = self::applyFormatBitsHorizontal($matrix, $formatBits);
$matrix = self::applyFormatBitsVertical($matrix, $formatBits);
return $matrix;
}
/**
* Get 15-bit format information
*/
private static function getFormatBits(ErrorCorrectionLevel $level, int $maskPattern): int
{
$levelValue = $level->value;
if (!isset(self::FORMAT_INFO_TABLE[$levelValue][$maskPattern])) {
throw new \InvalidArgumentException(
"Invalid EC level ({$levelValue}) or mask pattern ({$maskPattern})"
);
}
return self::FORMAT_INFO_TABLE[$levelValue][$maskPattern];
}
/**
* Apply format bits horizontally (top-left to top-right)
*
* ISO/IEC 18004:2015 Section 7.9
* Bits are placed sequentially (0-14), but the COLUMN ORDER creates
* the appearance of bit swaps when read left-to-right
*/
private static function applyFormatBitsHorizontal(QrCodeMatrix $matrix, int $formatBits): QrCodeMatrix
{
$size = $matrix->getSize();
// Horizontal placement columns (size-dependent, non-sequential due to timing separator)
// First 8 bits: columns 0-5, 7-8 (skip timing column 6)
// Last 7 bits: columns from right edge backwards (size-1 down to size-7)
$columns = [
0, 1, 2, 3, 4, 5, 7, 8, // First 8 bits (left side)
$size - 1, $size - 2, $size - 3, $size - 4, $size - 5, $size - 6, $size - 7 // Last 7 bits (right side)
];
// Place bits SEQUENTIALLY - the column order creates the swap effect
for ($i = 0; $i < 15; $i++) {
$bit = ($formatBits >> (14 - $i)) & 1;
$module = $bit === 1 ? Module::dark() : Module::light();
$matrix = $matrix->setModuleAt(8, $columns[$i], $module);
}
return $matrix;
}
/**
* Apply format bits vertically (top-left to bottom-left)
*/
private static function applyFormatBitsVertical(QrCodeMatrix $matrix, int $formatBits): QrCodeMatrix
{
$size = $matrix->getSize();
// Format bits are placed MSB-first
// Bits 0-6: Column 8, rows from bottom (MSB first)
for ($i = 0; $i < 7; $i++) {
$bit = ($formatBits >> (14 - $i)) & 1;
$module = $bit === 1 ? Module::dark() : Module::light();
$matrix = $matrix->setModuleAt($size - 1 - $i, 8, $module);
}
// Bits 7-14: Column 8, rows 8 down to 0 (skip row 6 - timing)
// Rows 8, 7, 5, 4, 3, 2, 1, 0 (skip 6)
$rows = [8, 7, 5, 4, 3, 2, 1, 0];
for ($i = 0; $i < 8; $i++) {
$bit = ($formatBits >> (14 - (7 + $i))) & 1;
$module = $bit === 1 ? Module::dark() : Module::light();
$matrix = $matrix->setModuleAt($rows[$i], 8, $module);
}
return $matrix;
}
}

43
src/Framework/QrCode/Structure/QrCodeBlock.php
View File

@@ -1,43 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Structure;
/**
* QR Code Data Block
*
* Represents a single data block with error correction codewords
*/
final readonly class QrCodeBlock
{
public function __construct(
public array $dataCodewords,
public array $errorCorrectionCodewords
) {
}
/**
* Get total codewords (data + error correction)
*/
public function getTotalCodewords(): array
{
return array_merge($this->dataCodewords, $this->errorCorrectionCodewords);
}
/**
* Get number of data codewords
*/
public function getDataLength(): int
{
return count($this->dataCodewords);
}
/**
* Get number of error correction codewords
*/
public function getErrorCorrectionLength(): int
{
return count($this->errorCorrectionCodewords);
}
}

49
src/Framework/QrCode/Structure/TimingPattern.php Normal file
View File

@@ -0,0 +1,49 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\Structure;
use App\Framework\QrCode\ValueObjects\Module;
use App\Framework\QrCode\ValueObjects\ModulePosition;
use App\Framework\QrCode\ValueObjects\QrCodeMatrix;
/**
* QR Code Timing Pattern Generator
*
* Generates alternating dark/light modules between finder patterns
* Horizontal: Row 6, columns between finder patterns
* Vertical: Column 6, rows between finder patterns
*
* Used for coordinate detection and alignment
*/
final readonly class TimingPattern
{
/**
* Apply timing patterns to matrix
*/
public static function apply(QrCodeMatrix $matrix): QrCodeMatrix
{
$size = $matrix->getSize();
// Horizontal timing pattern (row 6)
for ($col = 8; $col < $size - 8; $col++) {
$module = ($col % 2 === 0) ? Module::dark() : Module::light();
$matrix = $matrix->setModule(
ModulePosition::at(6, $col),
$module
);
}
// Vertical timing pattern (column 6)
for ($row = 8; $row < $size - 8; $row++) {
$module = ($row % 2 === 0) ? Module::dark() : Module::light();
$matrix = $matrix->setModule(
ModulePosition::at($row, 6),
$module
);
}
return $matrix;
}
}

221
src/Framework/QrCode/SvgRenderer.php
View File

@@ -1,221 +0,0 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode;
use InvalidArgumentException;
/**
* SVG Renderer for QR Code Matrix
*
* Renders a QR code matrix as scalable SVG format.
* Supports customizable colors, sizes, and quiet zones.
*/
final readonly class SvgRenderer
{
public function __construct(
private int $moduleSize = 4,
private int $quietZone = 4,
private string $foregroundColor = '#000000',
private string $backgroundColor = '#FFFFFF'
) {
if ($moduleSize < 1) {
throw new InvalidArgumentException("Module size must be positive, got: {$moduleSize}");
}
if ($quietZone < 0) {
throw new InvalidArgumentException("Quiet zone must be non-negative, got: {$quietZone}");
}
}
/**
* Create renderer with custom module size
*/
public static function withModuleSize(int $moduleSize): self
{
return new self(moduleSize: $moduleSize);
}
/**
* Create compact renderer (small size, no quiet zone)
*/
public static function compact(): self
{
return new self(moduleSize: 2, quietZone: 0);
}
/**
* Create large renderer with quiet zone
*/
public static function large(): self
{
return new self(moduleSize: 8, quietZone: 4);
}
/**
* Render QR code matrix as SVG string
*/
public function render(QrCodeMatrix $matrix): string
{
$matrixSize = $matrix->getSize();
$totalSize = ($matrixSize + 2 * $this->quietZone) * $this->moduleSize;
$svg = $this->createSvgHeader($totalSize);
$svg .= $this->createBackground($totalSize);
$svg .= $this->renderModules($matrix);
$svg .= $this->createSvgFooter();
return $svg;
}
/**
* Render as data URI for direct embedding
*/
public function renderAsDataUri(QrCodeMatrix $matrix): string
{
$svg = $this->render($matrix);
$base64 = base64_encode($svg);
return "data:image/svg+xml;base64,{$base64}";
}
/**
* Get the dimensions of the rendered SVG
*/
public function getDimensions(QrCodeMatrix $matrix): array
{
$matrixSize = $matrix->getSize();
$totalSize = ($matrixSize + 2 * $this->quietZone) * $this->moduleSize;
return [
'width' => $totalSize,
'height' => $totalSize,
'matrix_size' => $matrixSize,
'module_size' => $this->moduleSize,
'quiet_zone' => $this->quietZone,
];
}
/**
* Create custom renderer with different colors
*/
public function withColors(string $foreground, string $background): self
{
return new self(
moduleSize: $this->moduleSize,
quietZone: $this->quietZone,
foregroundColor: $foreground,
backgroundColor: $background
);
}
/**
* Create custom renderer with different quiet zone
*/
public function withQuietZone(int $quietZone): self
{
return new self(
moduleSize: $this->moduleSize,
quietZone: $quietZone,
foregroundColor: $this->foregroundColor,
backgroundColor: $this->backgroundColor
);
}
/**
* Create SVG header with viewport and namespaces
*/
private function createSvgHeader(int $totalSize): string
{
return sprintf(
'<svg width="%d" height="%d" viewBox="0 0 %d %d" xmlns="http://www.w3.org/2000/svg">',
$totalSize,
$totalSize,
$totalSize,
$totalSize
);
}
/**
* Create background rectangle
*/
private function createBackground(int $totalSize): string
{
return sprintf(
'<rect width="%d" height="%d" fill="%s"/>',
$totalSize,
$totalSize,
htmlspecialchars($this->backgroundColor)
);
}
/**
* Render all dark modules as rectangles
*/
private function renderModules(QrCodeMatrix $matrix): string
{
$svg = '';
$matrixSize = $matrix->getSize();
for ($row = 0; $row < $matrixSize; $row++) {
for ($col = 0; $col < $matrixSize; $col++) {
if ($matrix->isDark($row, $col)) {
$x = ($col + $this->quietZone) * $this->moduleSize;
$y = ($row + $this->quietZone) * $this->moduleSize;
$svg .= sprintf(
'<rect x="%d" y="%d" width="%d" height="%d" fill="%s"/>',
$x,
$y,
$this->moduleSize,
$this->moduleSize,
htmlspecialchars($this->foregroundColor)
);
}
}
}
return $svg;
}
/**
* Create SVG footer
*/
private function createSvgFooter(): string
{
return '</svg>';
}
/**
* Validate color format (hex or named colors)
*/
private function isValidColor(string $color): bool
{
// Check hex colors (#RGB, #RRGGBB)
if (preg_match('/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/', $color)) {
return true;
}
// Check some common named colors
$namedColors = [
'black', 'white', 'red', 'green', 'blue', 'yellow', 'cyan', 'magenta',
'gray', 'grey', 'orange', 'purple', 'pink', 'brown', 'transparent',
];
return in_array(strtolower($color), $namedColors, true);
}
/**
* Get configuration array
*/
public function getConfiguration(): array
{
return [
'module_size' => $this->moduleSize,
'quiet_zone' => $this->quietZone,
'foreground_color' => $this->foregroundColor,
'background_color' => $this->backgroundColor,
];
}
}

81
src/Framework/QrCode/ValueObjects/EncodingMode.php Normal file
View File

@@ -0,0 +1,81 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ValueObjects;
/**
* QR Code Encoding Mode
*
* Phase 1 (MVP): BYTE mode only
* Phase 2: NUMERIC, ALPHANUMERIC
* Phase 3: KANJI, ECI
*/
enum EncodingMode: string
{
case NUMERIC = 'numeric'; // 🔮 Phase 2: 0-9 (most efficient for numbers)
case ALPHANUMERIC = 'alphanumeric'; // 🔮 Phase 2: 0-9, A-Z, space, $%*+-./:
case BYTE = 'byte'; // ✅ Phase 1: UTF-8 strings (universal)
case KANJI = 'kanji'; // 🔮 Phase 3: Japanese characters
case ECI = 'eci'; // 🔮 Phase 3: Extended Channel Interpretation
/**
* Get mode indicator bits for QR Code format
*/
public function getModeBits(): string
{
return match ($this) {
self::NUMERIC => '0001',
self::ALPHANUMERIC => '0010',
self::BYTE => '0100',
self::KANJI => '1000',
self::ECI => '0111',
};
}
/**
* Get character count indicator length for given version
*/
public function getCharacterCountBits(QrCodeVersion $version): int
{
$versionNum = $version->getVersionNumber();
return match ($this) {
self::NUMERIC => match (true) {
$versionNum <= 9 => 10,
$versionNum <= 26 => 12,
default => 14,
},
self::ALPHANUMERIC => match (true) {
$versionNum <= 9 => 9,
$versionNum <= 26 => 11,
default => 13,
},
self::BYTE => match (true) {
$versionNum <= 9 => 8,
$versionNum <= 26 => 16,
default => 16,
},
self::KANJI => match (true) {
$versionNum <= 9 => 8,
$versionNum <= 26 => 10,
default => 12,
},
self::ECI => 0, // ECI mode has special handling
};
}
/**
* Check if this mode is implemented in current phase
*/
public function isImplemented(): bool
{
return match ($this) {
self::BYTE => true, // ✅ Phase 1
self::NUMERIC => false, // 🔮 Phase 2
self::ALPHANUMERIC => false,// 🔮 Phase 2
self::KANJI => false, // 🔮 Phase 3
self::ECI => false, // 🔮 Phase 3
};
}
}

68
src/Framework/QrCode/ValueObjects/ErrorCorrectionLevel.php Normal file
View File

@@ -0,0 +1,68 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ValueObjects;
/**
* QR Code Error Correction Level
*
* Determines how much damage a QR Code can sustain and still be readable
*
* Phase 1 (MVP): M level only (15% recovery)
* Phase 2: All levels (L, M, Q, H)
*/
enum ErrorCorrectionLevel: string
{
case L = 'L'; // Low: ~7% recovery - 🔮 Phase 2
case M = 'M'; // Medium: ~15% recovery - ✅ Phase 1
case Q = 'Q'; // Quartile: ~25% recovery - 🔮 Phase 2
case H = 'H'; // High: ~30% recovery - 🔮 Phase 2
/**
* Get format bits for error correction level
*/
public function getFormatBits(): string
{
return match ($this) {
self::L => '01',
self::M => '00',
self::Q => '11',
self::H => '10',
};
}
/**
* Get recovery percentage
*/
public function getRecoveryPercentage(): int
{
return match ($this) {
self::L => 7,
self::M => 15,
self::Q => 25,
self::H => 30,
};
}
/**
* Check if this level is implemented in current phase
*/
public function isImplemented(): bool
{
return match ($this) {
self::M => true, // ✅ Phase 1
self::L => false, // 🔮 Phase 2
self::Q => false, // 🔮 Phase 2
self::H => false, // 🔮 Phase 2
};
}
/**
* Get default level for MVP
*/
public static function default(): self
{
return self::M;
}
}

90
src/Framework/QrCode/ValueObjects/Module.php Normal file
View File

@@ -0,0 +1,90 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ValueObjects;
/**
* Single QR Code Module (Pixel)
*
* Represents a single module in the QR Code matrix
* Each module is either dark (1) or light (0)
*/
final readonly class Module
{
private function __construct(
private bool $isDark
) {}
/**
* Create dark module
*/
public static function dark(): self
{
return new self(true);
}
/**
* Create light module
*/
public static function light(): self
{
return new self(false);
}
/**
* Create from boolean
*/
public static function fromBool(bool $isDark): self
{
return new self($isDark);
}
/**
* Create from bit (0 or 1)
*/
public static function fromBit(int $bit): self
{
return new self($bit === 1);
}
/**
* Check if module is dark
*/
public function isDark(): bool
{
return $this->isDark;
}
/**
* Check if module is light
*/
public function isLight(): bool
{
return !$this->isDark;
}
/**
* Get as bit (0 or 1)
*/
public function toBit(): int
{
return $this->isDark ? 1 : 0;
}
/**
* Invert module (for masking)
*/
public function invert(): self
{
return new self(!$this->isDark);
}
/**
* Convert to string for debugging
*/
public function toString(): string
{
return $this->isDark ? '█' : '░';
}
}

87
src/Framework/QrCode/ValueObjects/ModulePosition.php Normal file
View File

@@ -0,0 +1,87 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ValueObjects;
/**
* Position in QR Code Matrix
*
* Represents row and column coordinates in the matrix
* (0,0) is top-left corner
*/
final readonly class ModulePosition
{
public function __construct(
public int $row,
public int $column
) {}
/**
* Create from coordinates
*/
public static function at(int $row, int $column): self
{
return new self($row, $column);
}
/**
* Get adjacent position (up)
*/
public function up(): self
{
return new self($this->row - 1, $this->column);
}
/**
* Get adjacent position (down)
*/
public function down(): self
{
return new self($this->row + 1, $this->column);
}
/**
* Get adjacent position (left)
*/
public function left(): self
{
return new self($this->row, $this->column - 1);
}
/**
* Get adjacent position (right)
*/
public function right(): self
{
return new self($this->row, $this->column + 1);
}
/**
* Check if position is within bounds
*/
public function isWithinBounds(int $matrixSize): bool
{
return $this->row >= 0
&& $this->row < $matrixSize
&& $this->column >= 0
&& $this->column < $matrixSize;
}
/**
* Check equality
*/
public function equals(self $other): bool
{
return $this->row === $other->row
&& $this->column === $other->column;
}
/**
* Convert to string for debugging
*/
public function toString(): string
{
return "({$this->row},{$this->column})";
}
}

105
src/Framework/QrCode/ValueObjects/QrCodeConfig.php Normal file
View File

@@ -0,0 +1,105 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ValueObjects;
/**
* QR Code Configuration
*
* Immutable configuration for QR Code generation
*/
final readonly class QrCodeConfig
{
public function __construct(
public QrCodeVersion $version,
public ErrorCorrectionLevel $errorCorrectionLevel,
public EncodingMode $encodingMode,
public int $quietZone = 4 // Quiet zone in modules (standard: 4)
) {}
/**
* Create default configuration (auto-size, medium error correction, byte mode)
*/
public static function default(): self
{
return new self(
version: QrCodeVersion::default(),
errorCorrectionLevel: ErrorCorrectionLevel::default(),
encodingMode: EncodingMode::BYTE,
quietZone: 4
);
}
/**
* Create with auto-detected version based on data length
*/
public static function autoSize(
string $data,
?ErrorCorrectionLevel $level = null,
?EncodingMode $mode = null
): self {
$level = $level ?? ErrorCorrectionLevel::default();
$mode = $mode ?? EncodingMode::BYTE;
$dataLength = strlen($data);
$version = QrCodeVersion::fromDataLength($dataLength, $mode, $level);
return new self(
version: $version,
errorCorrectionLevel: $level,
encodingMode: $mode,
quietZone: 4
);
}
/**
* Create with specific version
*/
public static function withVersion(
int $versionNumber,
?ErrorCorrectionLevel $level = null,
?EncodingMode $mode = null
): self {
return new self(
version: QrCodeVersion::fromNumber($versionNumber),
errorCorrectionLevel: $level ?? ErrorCorrectionLevel::default(),
encodingMode: $mode ?? EncodingMode::BYTE,
quietZone: 4
);
}
/**
* Get total size including quiet zone
*/
public function getTotalSize(): int
{
return $this->version->getMatrixSize() + ($this->quietZone * 2);
}
/**
* With different quiet zone
*/
public function withQuietZone(int $quietZone): self
{
return new self(
version: $this->version,
errorCorrectionLevel: $this->errorCorrectionLevel,
encodingMode: $this->encodingMode,
quietZone: $quietZone
);
}
/**
* With different error correction level
*/
public function withErrorCorrection(ErrorCorrectionLevel $level): self
{
return new self(
version: $this->version,
errorCorrectionLevel: $level,
encodingMode: $this->encodingMode,
quietZone: $this->quietZone
);
}
}

192
src/Framework/QrCode/ValueObjects/QrCodeMatrix.php Normal file
View File

@@ -0,0 +1,192 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ValueObjects;
use App\Framework\Exception\FrameworkException;
/**
* QR Code Matrix
*
* Represents the complete QR Code matrix with all modules
* Immutable - any modifications return a new instance
*/
final readonly class QrCodeMatrix
{
/**
* @param array<int, array<int, Module>> $modules 2D array of modules
*/
private function __construct(
private QrCodeVersion $version,
private array $modules
) {}
/**
* Create empty matrix for given version
*/
public static function create(QrCodeVersion $version): self
{
$size = $version->getMatrixSize();
$modules = [];
for ($row = 0; $row < $size; $row++) {
$modules[$row] = [];
for ($col = 0; $col < $size; $col++) {
$modules[$row][$col] = Module::light(); // Default: light
}
}
return new self($version, $modules);
}
/**
* Get QR Code version
*/
public function getVersion(): QrCodeVersion
{
return $this->version;
}
/**
* Get matrix size
*/
public function getSize(): int
{
return $this->version->getMatrixSize();
}
/**
* Get module at position
*/
public function getModule(ModulePosition $position): Module
{
if (!$position->isWithinBounds($this->getSize())) {
throw FrameworkException::simple(
"Position {$position->toString()} is out of bounds for matrix size {$this->getSize()}"
);
}
return $this->modules[$position->row][$position->column];
}
/**
* Get module at coordinates
*/
public function getModuleAt(int $row, int $column): Module
{
return $this->getModule(ModulePosition::at($row, $column));
}
/**
* Set module at position (returns new instance)
*/
public function setModule(ModulePosition $position, Module $module): self
{
if (!$position->isWithinBounds($this->getSize())) {
throw FrameworkException::simple(
"Position {$position->toString()} is out of bounds for matrix size {$this->getSize()}"
);
}
$modules = $this->modules;
$modules[$position->row][$position->column] = $module;
return new self($this->version, $modules);
}
/**
* Set module at coordinates (returns new instance)
*/
public function setModuleAt(int $row, int $column, Module $module): self
{
return $this->setModule(ModulePosition::at($row, $column), $module);
}
/**
* Set dark module at position
*/
public function setDark(ModulePosition $position): self
{
return $this->setModule($position, Module::dark());
}
/**
* Set light module at position
*/
public function setLight(ModulePosition $position): self
{
return $this->setModule($position, Module::light());
}
/**
* Check if position is dark
*/
public function isDark(ModulePosition $position): bool
{
return $this->getModule($position)->isDark();
}
/**
* Get all modules as 2D array
*/
public function toArray(): array
{
return $this->modules;
}
/**
* Convert to binary string (for debugging)
*/
public function toBinaryString(): string
{
$result = '';
$size = $this->getSize();
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col < $size; $col++) {
$result .= $this->modules[$row][$col]->toBit();
}
$result .= "\n";
}
return $result;
}
/**
* Convert to ASCII art (for debugging)
*/
public function toAsciiArt(): string
{
$result = '';
$size = $this->getSize();
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col < $size; $col++) {
$result .= $this->modules[$row][$col]->toString();
}
$result .= "\n";
}
return $result;
}
/**
* Count dark modules
*/
public function countDarkModules(): int
{
$count = 0;
$size = $this->getSize();
for ($row = 0; $row < $size; $row++) {
for ($col = 0; $col < $size; $col++) {
if ($this->modules[$row][$col]->isDark()) {
$count++;
}
}
}
return $count;
}
}

127
src/Framework/QrCode/ValueObjects/QrCodeStyle.php Normal file
View File

@@ -0,0 +1,127 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ValueObjects;
use App\Framework\Svg\ValueObjects\Styling\SvgColor;
/**
* QR Code Styling Configuration
*
* Styling options for rendering QR Codes
* Phase 1: Basic colors
* Phase 2: Gradients, rounded corners
* Phase 3: Logo overlay, custom shapes
*/
final readonly class QrCodeStyle
{
public readonly SvgColor $darkColor;
public readonly SvgColor $lightColor;
public function __construct(
public int $moduleSize = 10, // Size of each module in pixels
?SvgColor $darkColor = null, // Color for dark modules
?SvgColor $lightColor = null, // Color for light modules
public int $quietZoneSize = 4, // Quiet zone in modules
public bool $includeQuietZone = true // Whether to include quiet zone in output
) {
// Use default colors if not provided
$this->darkColor = $darkColor ?? SvgColor::black();
$this->lightColor = $lightColor ?? SvgColor::white();
}
/**
* Create default style (black on white, 10px modules)
*/
public static function default(): self
{
return new self(
moduleSize: 10,
darkColor: SvgColor::black(),
lightColor: SvgColor::white(),
quietZoneSize: 4,
includeQuietZone: true
);
}
/**
* Create compact style (smaller modules, no quiet zone)
*/
public static function compact(): self
{
return new self(
moduleSize: 5,
darkColor: SvgColor::black(),
lightColor: SvgColor::white(),
quietZoneSize: 0,
includeQuietZone: false
);
}
/**
* Create large style (bigger modules for printing)
*/
public static function large(): self
{
return new self(
moduleSize: 20,
darkColor: SvgColor::black(),
lightColor: SvgColor::white(),
quietZoneSize: 4,
includeQuietZone: true
);
}
/**
* Create inverted style (white on black)
*/
public static function inverted(): self
{
return new self(
moduleSize: 10,
darkColor: SvgColor::white(),
lightColor: SvgColor::black(),
quietZoneSize: 4,
includeQuietZone: true
);
}
/**
* With custom colors
*/
public static function withColors(SvgColor $dark, SvgColor $light): self
{
return new self(
moduleSize: 10,
darkColor: $dark,
lightColor: $light,
quietZoneSize: 4,
includeQuietZone: true
);
}
/**
* Calculate total canvas size
*/
public function calculateCanvasSize(int $matrixSize): int
{
$modules = $matrixSize;
if ($this->includeQuietZone) {
$modules += ($this->quietZoneSize * 2);
}
return $modules * $this->moduleSize;
}
/**
* Get quiet zone offset in pixels
*/
public function getQuietZoneOffset(): int
{
return $this->includeQuietZone
? $this->quietZoneSize * $this->moduleSize
: 0;
}
}

155
src/Framework/QrCode/ValueObjects/QrCodeVersion.php Normal file
View File

@@ -0,0 +1,155 @@
<?php
declare(strict_types=1);
namespace App\Framework\QrCode\ValueObjects;
use App\Framework\Exception\FrameworkException;
/**
* QR Code Version (Size)
*
* Version determines the size of the QR Code matrix
* Version 1 = 21x21 modules
* Each version adds 4 modules per side
*
* Phase 1 (MVP): Version 1-3 (21x21 to 29x29)
* Phase 2: Version 1-10 (21x21 to 57x57)
* Phase 3: Version 1-40 (21x21 to 177x177)
*/
final readonly class QrCodeVersion
{
private const MIN_VERSION = 1;
private const MAX_VERSION_PHASE_1 = 3; // ✅ MVP
private const MAX_VERSION_PHASE_2 = 10; // 🔮 Later
private const MAX_VERSION_PHASE_3 = 40; // 🔮 Full spec
private function __construct(
private int $version
) {
if ($version < self::MIN_VERSION || $version > self::MAX_VERSION_PHASE_3) {
throw FrameworkException::simple(
"QR Code version must be between 1 and 40, got {$version}"
);
}
// Phase 1 limitation
if ($version > self::MAX_VERSION_PHASE_1) {
throw FrameworkException::simple(
"QR Code version {$version} not yet implemented. Phase 1 supports versions 1-3 only."
);
}
}
/**
* Create version from number
*/
public static function fromNumber(int $version): self
{
return new self($version);
}
/**
* Auto-select version based on data length
*
* Phase 1: Simple selection for versions 1-3
* Phase 2: Full capacity table lookup
*/
public static function fromDataLength(
int $dataLength,
EncodingMode $mode,
ErrorCorrectionLevel $level
): self {
// Phase 1: Simplified capacity calculation
// Version 1: ~20 bytes, Version 2: ~38 bytes, Version 3: ~61 bytes
$version = match (true) {
$dataLength <= 20 => 1,
$dataLength <= 38 => 2,
$dataLength <= 61 => 3,
default => throw FrameworkException::simple(
"Data too long ({$dataLength} bytes). Phase 1 supports up to 61 bytes."
),
};
return new self($version);
}
/**
* Get version number (1-40)
*/
public function getVersionNumber(): int
{
return $this->version;
}
/**
* Get matrix size in modules
* Formula: (version - 1) * 4 + 21
*/
public function getMatrixSize(): int
{
return ($this->version - 1) * 4 + 21;
}
/**
* Get number of alignment patterns
*
* Phase 1: Version 1 has no alignment patterns
* Phase 2: Version 2+ have alignment patterns
*/
public function getAlignmentPatternCount(): int
{
if ($this->version === 1) {
return 0;
}
// Phase 2: Full alignment pattern calculation
return (int) floor($this->version / 7) + 2;
}
/**
* Check if version information is required
* (Versions 7+ need version information)
*/
public function requiresVersionInformation(): bool
{
return $this->version >= 7;
}
/**
* Get data capacity in bytes for this version
*
* Phase 1: Approximate values
* Phase 2: Exact capacity table
*/
public function getDataCapacity(
EncodingMode $mode,
ErrorCorrectionLevel $level
): int {
// Phase 1: Simplified capacity (byte mode, level M)
return match ($this->version) {
1 => 20,
2 => 38,
3 => 61,
default => throw FrameworkException::simple(
"Version {$this->version} not implemented in Phase 1"
),
};
}
/**
* Check if this version is implemented
*/
public function isImplemented(): bool
{
return $this->version <= self::MAX_VERSION_PHASE_1;
}
/**
* Get default version for MVP
*/
public static function default(): self
{
return new self(1);
}
}