| 1 |
<?php |
| 2 |
/** |
| 3 |
* Class QRCode |
| 4 |
* |
| 5 |
* @created 26.11.2015 |
| 6 |
* @author Smiley <[email protected]> |
| 7 |
* @copyright 2015 Smiley |
| 8 |
* @license MIT |
| 9 |
*/ |
| 10 |
declare(strict_types=1); |
| 11 |
|
| 12 |
namespace chillerlan\QRCode; |
| 13 |
|
| 14 |
use chillerlan\QRCode\Common\{ |
| 15 |
ECICharset, GDLuminanceSource, IMagickLuminanceSource, LuminanceSourceInterface, MaskPattern, Mode |
| 16 |
}; |
| 17 |
use chillerlan\QRCode\Data\{AlphaNum, Byte, ECI, Hanzi, Kanji, Number, QRData, QRDataModeInterface, QRMatrix}; |
| 18 |
use chillerlan\QRCode\Decoder\{Decoder, DecoderResult}; |
| 19 |
use chillerlan\QRCode\Output\{QRCodeOutputException, QROutputInterface}; |
| 20 |
use chillerlan\Settings\SettingsContainerInterface; |
| 21 |
use function class_exists, class_implements, in_array, is_iterable, mb_convert_encoding, mb_internal_encoding; |
| 22 |
|
| 23 |
/** |
| 24 |
* Turns a text string into a Model 2 QR Code |
| 25 |
* |
| 26 |
* @see https://github.com/kazuhikoarase/qrcode-generator/tree/master/php |
| 27 |
* @see https://www.qrcode.com/en/codes/model12.html |
| 28 |
* @see https://www.swisseduc.ch/informatik/theoretische_informatik/qr_codes/docs/qr_standard.pdf |
| 29 |
* @see https://en.wikipedia.org/wiki/QR_code |
| 30 |
* @see https://www.thonky.com/qr-code-tutorial/ |
| 31 |
*/ |
| 32 |
class QRCode{ |
| 33 |
|
| 34 |
/** |
| 35 |
* The settings container |
| 36 |
*/ |
| 37 |
protected SettingsContainerInterface|QROptions $options; |
| 38 |
|
| 39 |
/** |
| 40 |
* A collection of one or more data segments of QRDataModeInterface instances to write |
| 41 |
* |
| 42 |
* @var \chillerlan\QRCode\Data\QRDataModeInterface[] |
| 43 |
*/ |
| 44 |
protected array $dataSegments = []; |
| 45 |
|
| 46 |
/** |
| 47 |
* The luminance source for the reader |
| 48 |
*/ |
| 49 |
protected string $luminanceSourceFQN = GDLuminanceSource::class; |
| 50 |
|
| 51 |
/** |
| 52 |
* QRCode constructor. |
| 53 |
* |
| 54 |
* @phpstan-param array<string, mixed> $options |
| 55 |
*/ |
| 56 |
public function __construct(SettingsContainerInterface|QROptions|iterable $options = new QROptions){ |
| 57 |
$this->setOptions($options); |
| 58 |
} |
| 59 |
|
| 60 |
/** |
| 61 |
* Sets an options instance |
| 62 |
* |
| 63 |
* @phpstan-param array<string, mixed> $options |
| 64 |
*/ |
| 65 |
public function setOptions(SettingsContainerInterface|QROptions|iterable $options):static{ |
| 66 |
|
| 67 |
if(is_iterable($options)){ |
| 68 |
$options = new QROptions($options); |
| 69 |
} |
| 70 |
|
| 71 |
$this->options = $options; |
| 72 |
|
| 73 |
if($this->options->readerUseImagickIfAvailable){ |
| 74 |
$this->luminanceSourceFQN = IMagickLuminanceSource::class; |
| 75 |
} |
| 76 |
|
| 77 |
return $this; |
| 78 |
} |
| 79 |
|
| 80 |
/** |
| 81 |
* Renders a QR Code for the given $data and QROptions, saves $file optionally |
| 82 |
*/ |
| 83 |
public function render(string|null $data = null, string|null $file = null):mixed{ |
| 84 |
|
| 85 |
if($data !== null){ |
| 86 |
/** @var \chillerlan\QRCode\Data\QRDataModeInterface $dataInterface */ |
| 87 |
foreach(Mode::INTERFACES as $dataInterface){ |
| 88 |
|
| 89 |
if($dataInterface::validateString($data)){ |
| 90 |
$this->addSegment(new $dataInterface($data)); |
| 91 |
|
| 92 |
break; |
| 93 |
} |
| 94 |
} |
| 95 |
} |
| 96 |
|
| 97 |
return $this->renderMatrix($this->getQRMatrix(), $file); |
| 98 |
} |
| 99 |
|
| 100 |
/** |
| 101 |
* Renders a QR Code for the given QRMatrix and QROptions, saves $file optionally |
| 102 |
*/ |
| 103 |
public function renderMatrix(QRMatrix $matrix, string|null $file = null):mixed{ |
| 104 |
return $this->initOutputInterface($matrix)->dump($file ?? $this->options->cachefile); |
| 105 |
} |
| 106 |
|
| 107 |
/** |
| 108 |
* Returns a QRMatrix object for the given $data and current QROptions |
| 109 |
*/ |
| 110 |
public function getQRMatrix():QRMatrix{ |
| 111 |
$matrix = (new QRData($this->options, $this->dataSegments))->writeMatrix(); |
| 112 |
|
| 113 |
$maskPattern = $this->options->maskPattern === MaskPattern::AUTO |
| 114 |
? MaskPattern::getBestPattern($matrix) |
| 115 |
: new MaskPattern($this->options->maskPattern); |
| 116 |
|
| 117 |
$matrix->setFormatInfo($maskPattern)->mask($maskPattern); |
| 118 |
|
| 119 |
return $this->addMatrixModifications($matrix); |
| 120 |
} |
| 121 |
|
| 122 |
/** |
| 123 |
* add matrix modifications after mask pattern evaluation and before handing over to output |
| 124 |
*/ |
| 125 |
protected function addMatrixModifications(QRMatrix $matrix):QRMatrix{ |
| 126 |
|
| 127 |
if($this->options->addLogoSpace){ |
| 128 |
// check whether one of the dimensions was omitted |
| 129 |
$logoSpaceWidth = ($this->options->logoSpaceWidth ?? $this->options->logoSpaceHeight ?? 0); |
| 130 |
$logoSpaceHeight = ($this->options->logoSpaceHeight ?? $logoSpaceWidth); |
| 131 |
|
| 132 |
$matrix->setLogoSpace( |
| 133 |
$logoSpaceWidth, |
| 134 |
$logoSpaceHeight, |
| 135 |
$this->options->logoSpaceStartX, |
| 136 |
$this->options->logoSpaceStartY, |
| 137 |
); |
| 138 |
} |
| 139 |
|
| 140 |
if($this->options->addQuietzone){ |
| 141 |
$matrix->setQuietZone($this->options->quietzoneSize); |
| 142 |
} |
| 143 |
|
| 144 |
return $matrix; |
| 145 |
} |
| 146 |
|
| 147 |
/** |
| 148 |
* initializes a fresh built-in or custom QROutputInterface |
| 149 |
* |
| 150 |
* @throws \chillerlan\QRCode\Output\QRCodeOutputException |
| 151 |
*/ |
| 152 |
protected function initOutputInterface(QRMatrix $matrix):QROutputInterface{ |
| 153 |
$outputInterface = $this->options->outputInterface; |
| 154 |
|
| 155 |
if(!class_exists($outputInterface)){ |
| 156 |
throw new QRCodeOutputException('invalid output class'); |
| 157 |
} |
| 158 |
|
| 159 |
if(!in_array(QROutputInterface::class, class_implements($outputInterface), true)){ |
| 160 |
throw new QRCodeOutputException('output class does not implement QROutputInterface'); |
| 161 |
} |
| 162 |
|
| 163 |
/** @var \chillerlan\QRCode\Output\QROutputInterface $instance */ |
| 164 |
$instance = new $outputInterface($this->options, $matrix); |
| 165 |
|
| 166 |
return $instance; |
| 167 |
} |
| 168 |
|
| 169 |
/** |
| 170 |
* Adds a data segment |
| 171 |
* |
| 172 |
* ISO/IEC 18004:2000 8.3.6 - Mixing modes |
| 173 |
* ISO/IEC 18004:2000 Annex H - Optimisation of bit stream length |
| 174 |
*/ |
| 175 |
public function addSegment(QRDataModeInterface $segment):static{ |
| 176 |
$this->dataSegments[] = $segment; |
| 177 |
|
| 178 |
return $this; |
| 179 |
} |
| 180 |
|
| 181 |
/** |
| 182 |
* Clears the data segments array |
| 183 |
* |
| 184 |
* @codeCoverageIgnore |
| 185 |
*/ |
| 186 |
public function clearSegments():static{ |
| 187 |
$this->dataSegments = []; |
| 188 |
|
| 189 |
return $this; |
| 190 |
} |
| 191 |
|
| 192 |
/** |
| 193 |
* Adds a numeric data segment |
| 194 |
* |
| 195 |
* ISO/IEC 18004:2000 8.3.2 - Numeric Mode |
| 196 |
*/ |
| 197 |
public function addNumericSegment(string $data):static{ |
| 198 |
return $this->addSegment(new Number($data)); |
| 199 |
} |
| 200 |
|
| 201 |
/** |
| 202 |
* Adds an alphanumeric data segment |
| 203 |
* |
| 204 |
* ISO/IEC 18004:2000 8.3.3 - Alphanumeric Mode |
| 205 |
*/ |
| 206 |
public function addAlphaNumSegment(string $data):static{ |
| 207 |
return $this->addSegment(new AlphaNum($data)); |
| 208 |
} |
| 209 |
|
| 210 |
/** |
| 211 |
* Adds a Kanji data segment (Japanese 13-bit double-byte characters, Shift-JIS) |
| 212 |
* |
| 213 |
* ISO/IEC 18004:2000 8.3.5 - Kanji Mode |
| 214 |
*/ |
| 215 |
public function addKanjiSegment(string $data):static{ |
| 216 |
return $this->addSegment(new Kanji($data)); |
| 217 |
} |
| 218 |
|
| 219 |
/** |
| 220 |
* Adds a Hanzi data segment (simplified Chinese 13-bit double-byte characters, GB2312/GB18030) |
| 221 |
* |
| 222 |
* GBT18284-2000 Hanzi Mode |
| 223 |
*/ |
| 224 |
public function addHanziSegment(string $data):static{ |
| 225 |
return $this->addSegment(new Hanzi($data)); |
| 226 |
} |
| 227 |
|
| 228 |
/** |
| 229 |
* Adds an 8-bit byte data segment |
| 230 |
* |
| 231 |
* ISO/IEC 18004:2000 8.3.4 - 8-bit Byte Mode |
| 232 |
*/ |
| 233 |
public function addByteSegment(string $data):static{ |
| 234 |
return $this->addSegment(new Byte($data)); |
| 235 |
} |
| 236 |
|
| 237 |
/** |
| 238 |
* Adds a standalone ECI designator |
| 239 |
* |
| 240 |
* The ECI designator must be followed by a Byte segment that contains the string encoded according to the given ECI charset |
| 241 |
* |
| 242 |
* ISO/IEC 18004:2000 8.3.1 - Extended Channel Interpretation (ECI) Mode |
| 243 |
*/ |
| 244 |
public function addEciDesignator(int $encoding):static{ |
| 245 |
return $this->addSegment(new ECI($encoding)); |
| 246 |
} |
| 247 |
|
| 248 |
/** |
| 249 |
* Adds an ECI data segment (including designator) |
| 250 |
* |
| 251 |
* The given string will be encoded from mb_internal_encoding() to the given ECI character set |
| 252 |
* |
| 253 |
* I hate this somehow, but I'll leave it for now |
| 254 |
* |
| 255 |
* @throws \chillerlan\QRCode\QRCodeException |
| 256 |
*/ |
| 257 |
public function addEciSegment(int $encoding, string $data):static{ |
| 258 |
// validate the encoding id |
| 259 |
$eciCharset = new ECICharset($encoding); |
| 260 |
// get charset name |
| 261 |
$eciCharsetName = $eciCharset->getName(); |
| 262 |
|
| 263 |
if($eciCharsetName === null){ |
| 264 |
throw new QRCodeException('unable to add ECI segment'); |
| 265 |
} |
| 266 |
|
| 267 |
// convert the string to the given charset |
| 268 |
$data = mb_convert_encoding($data, $eciCharsetName, mb_internal_encoding()); |
| 269 |
|
| 270 |
if($data === false){ |
| 271 |
throw new QRCodeException('mb_convert_encoding() error'); // @codeCoverageIgnore |
| 272 |
} |
| 273 |
|
| 274 |
return $this |
| 275 |
->addEciDesignator($eciCharset->getID()) |
| 276 |
->addByteSegment($data) |
| 277 |
; |
| 278 |
} |
| 279 |
|
| 280 |
/** |
| 281 |
* Reads a QR Code from a given file |
| 282 |
* |
| 283 |
* @codeCoverageIgnore |
| 284 |
*/ |
| 285 |
public function readFromFile(string $path):DecoderResult{ |
| 286 |
return $this->readFromSource($this->luminanceSourceFQN::fromFile($path, $this->options)); |
| 287 |
} |
| 288 |
|
| 289 |
/** |
| 290 |
* Reads a QR Code from the given data blob |
| 291 |
*/ |
| 292 |
public function readFromBlob(string $blob):DecoderResult{ |
| 293 |
return $this->readFromSource($this->luminanceSourceFQN::fromBlob($blob, $this->options)); |
| 294 |
} |
| 295 |
|
| 296 |
/** |
| 297 |
* Reads a QR Code from the given luminance source |
| 298 |
*/ |
| 299 |
public function readFromSource(LuminanceSourceInterface $source):DecoderResult{ |
| 300 |
return (new Decoder($this->options))->decode($source); |
| 301 |
} |
| 302 |
|
| 303 |
} |