Debian Codegraph @

vendor/chillerlan/php-qrcode/src/QRCode.php

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