Debian Codegraph @

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

raw
1 <?php
2 /**
3 * Trait QROptionsTrait
4 *
5 * Note: the docblocks in this file are optimized for readability in PhpStorm ond on readthedocs.io
6 *
7 * @created 10.03.2018
8 * @author smiley <[email protected]>
9 * @copyright 2018 smiley
10 * @license MIT
11 *
12 * @noinspection PhpUnused, PhpComposerExtensionStubsInspection
13 */
14 declare(strict_types=1);
15
16 namespace chillerlan\QRCode;
17
18 use chillerlan\QRCode\Common\{EccLevel, MaskPattern, Version};
19 use chillerlan\QRCode\Output\QRMarkupSVG;
20 use function constant, in_array, is_string, max, min, sprintf, strtolower, strtoupper, trim;
21 use const JSON_THROW_ON_ERROR, JSON_UNESCAPED_SLASHES, PHP_EOL;
22
23 /**
24 * The QRCode plug-in settings & setter functionality
25 *
26 * @property int $version
27 * @property int $versionMin
28 * @property int $versionMax
29 * @property int $eccLevel
30 * @property int $maskPattern
31 * @property bool $addQuietzone
32 * @property int $quietzoneSize
33 * @property string $outputInterface
34 * @property bool $returnResource
35 * @property string|null $cachefile
36 * @property bool $outputBase64
37 * @property string $eol
38 * @property mixed $bgColor
39 * @property bool $invertMatrix
40 * @property bool $drawLightModules
41 * @property bool $drawCircularModules
42 * @property float $circleRadius
43 * @property int[] $keepAsSquare
44 * @property bool $connectPaths
45 * @property int[] $excludeFromConnect
46 * @property array<int, mixed> $moduleValues
47 * @property bool $addLogoSpace
48 * @property int|null $logoSpaceWidth
49 * @property int|null $logoSpaceHeight
50 * @property int|null $logoSpaceStartX
51 * @property int|null $logoSpaceStartY
52 * @property int $scale
53 * @property bool $imageTransparent
54 * @property mixed $transparencyColor
55 * @property int $quality
56 * @property bool $gdImageUseUpscale
57 * @property string $imagickFormat
58 * @property string $cssClass
59 * @property bool $svgAddXmlHeader
60 * @property string $svgDefs
61 * @property string $svgPreserveAspectRatio
62 * @property bool $svgUseFillAttributes
63 * @property string $textLineStart
64 * @property int $jsonFlags
65 * @property string $fpdfMeasureUnit
66 * @property string|null $xmlStylesheet
67 */
68 trait QROptionsTrait{
69
70 /*
71 * QR Code specific settings
72 */
73
74 /**
75 * QR Code version number
76 *
77 * `1 ... 40` or `Version::AUTO` (default)
78 *
79 * @see \chillerlan\QRCode\Common\Version
80 */
81 protected int $version = Version::AUTO;
82
83 /**
84 * Minimum QR version
85 *
86 * if `QROptions::$version` is set to `Version::AUTO` (default: 1)
87 */
88 protected int $versionMin = 1;
89
90 /**
91 * Maximum QR version
92 *
93 * if `QROptions::$version` is set to `Version::AUTO` (default: 40)
94 */
95 protected int $versionMax = 40;
96
97 /**
98 * Error correct level
99 *
100 * the constant `EccLevel::X` where `X` is:
101 *
102 * - `L` => 7% (default)
103 * - `M` => 15%
104 * - `Q` => 25%
105 * - `H` => 30%
106 *
107 * alternatively you can just pass the letters L/M/Q/H (case-insensitive) to the magic setter
108 *
109 * @see \chillerlan\QRCode\Common\EccLevel
110 * @see https://github.com/chillerlan/php-qrcode/discussions/160
111 */
112 protected int $eccLevel = EccLevel::L;
113
114 /**
115 * Mask Pattern to use (no value in using, mostly for unit testing purposes)
116 *
117 * `0 ... 7` or `MaskPattern::PATTERN_AUTO` (default)
118 *
119 * @see \chillerlan\QRCode\Common\MaskPattern
120 */
121 protected int $maskPattern = MaskPattern::AUTO;
122
123 /**
124 * Add a "quiet zone" (margin) according to the QR code spec
125 *
126 * @see https://www.qrcode.com/en/howto/code.html
127 */
128 protected bool $addQuietzone = true;
129
130 /**
131 * Size of the quiet zone
132 *
133 * internally clamped to `0 ... $moduleCount / 2` (default: 4)
134 */
135 protected int $quietzoneSize = 4;
136
137
138 /*
139 * General output settings
140 */
141
142 /**
143 * The FQCN of the `QROutputInterface` to use
144 */
145 protected string $outputInterface = QRMarkupSVG::class;
146
147 /**
148 * Return the image resource instead of a render if applicable.
149 *
150 * - `QRGdImage`: `resource` (PHP < 8), `GdImage`
151 * - `QRImagick`: `Imagick`
152 * - `QRFpdf`: `FPDF`
153 *
154 * This option overrides/ignores other output settings, such as `QROptions::$cachefile`
155 * and `QROptions::$outputBase64`. (default: `false`)
156 *
157 * @see \chillerlan\QRCode\Output\QROutputInterface::dump()
158 */
159 protected bool $returnResource = false;
160
161 /**
162 * Optional cache file path `/path/to/cache.file`
163 *
164 * Please note that the `$file` parameter in `QRCode::render()` and `QRCode::renderMatrix()`
165 * takes precedence over the `QROptions::$cachefile` value. (default: `null`)
166 *
167 * @see \chillerlan\QRCode\QRCode::render()
168 * @see \chillerlan\QRCode\QRCode::renderMatrix()
169 */
170 protected string|null $cachefile = null;
171
172 /**
173 * Toggle base64 data URI or raw data output (if applicable)
174 *
175 * (default: `true`)
176 *
177 * @see \chillerlan\QRCode\Output\QROutputAbstract::toBase64DataURI()
178 */
179 protected bool $outputBase64 = true;
180
181 /**
182 * Newline string
183 *
184 * (default: `PHP_EOL`)
185 */
186 protected string $eol = PHP_EOL;
187
188
189 /*
190 * Common visual modifications
191 */
192
193 /**
194 * Sets the image background color (if applicable)
195 *
196 * - `QRImagick`: defaults to `"white"`
197 * - `QRGdImage`: defaults to `[255, 255, 255]`
198 * - `QRFpdf`: defaults to blank internally (white page)
199 */
200 protected mixed $bgColor = null;
201
202 /**
203 * Whether to invert the matrix (reflectance reversal)
204 *
205 * (default: `false`)
206 *
207 * @see \chillerlan\QRCode\Data\QRMatrix::invert()
208 */
209 protected bool $invertMatrix = false;
210
211 /**
212 * Whether to draw the light (false) modules
213 *
214 * (default: `true`)
215 */
216 protected bool $drawLightModules = true;
217
218 /**
219 * Specify whether to draw the modules as filled circles
220 *
221 * a note for `GdImage` output:
222 *
223 * if `QROptions::$scale` is less than 20, the image will be upscaled internally, then the modules will be drawn
224 * using `imagefilledellipse()` and then scaled back to the expected size
225 *
226 * No effect in: `QREps`, `QRFpdf`, `QRMarkupHTML`
227 *
228 * @see \imagefilledellipse()
229 * @see https://github.com/chillerlan/php-qrcode/issues/23
230 * @see https://github.com/chillerlan/php-qrcode/discussions/122
231 */
232 protected bool $drawCircularModules = false;
233
234 /**
235 * Specifies the radius of the modules when `QROptions::$drawCircularModules` is set to `true`
236 *
237 * (default: 0.45)
238 */
239 protected float $circleRadius = 0.45;
240
241 /**
242 * Specifies which module types to exclude when `QROptions::$drawCircularModules` is set to `true`
243 *
244 * (default: `[]`)
245 *
246 * @var int[]
247 */
248 protected array $keepAsSquare = [];
249
250 /**
251 * Whether to connect the paths for the several module types to avoid weird glitches when using gradients etc.
252 *
253 * This option is exclusive to output classes that use the module collector `QROutputAbstract::collectModules()`,
254 * which converts the `$M_TYPE` of all modules to `QRMatrix::M_DATA` and `QRMatrix::M_DATA_DARK` respectively.
255 *
256 * Module types that should not be added to the connected path can be excluded via `QROptions::$excludeFromConnect`.
257 *
258 * Currentty used in `QREps` and `QRMarkupSVG`.
259 *
260 * @see \chillerlan\QRCode\Output\QROutputAbstract::collectModules()
261 * @see \chillerlan\QRCode\QROptionsTrait::$excludeFromConnect
262 * @see https://github.com/chillerlan/php-qrcode/issues/57
263 */
264 protected bool $connectPaths = false;
265
266 /**
267 * Specify which paths/patterns to exclude from connecting if `QROptions::$connectPaths` is set to `true`
268 *
269 * @see \chillerlan\QRCode\QROptionsTrait::$connectPaths
270 *
271 * @var int[]
272 */
273 protected array $excludeFromConnect = [];
274
275 /**
276 * Module values map
277 *
278 * - `QRImagick`, `QRMarkupHTML`, `QRMarkupSVG`: #ABCDEF, cssname, rgb(), rgba()...
279 * - `QREps`, `QRFpdf`, `QRGdImage`: `[R, G, B]` // 0-255
280 * - `QREps`: `[C, M, Y, K]` // 0-255
281 *
282 * @see \chillerlan\QRCode\Output\QROutputAbstract::setModuleValues()
283 *
284 * @var array<int, mixed>
285 */
286 protected array $moduleValues = [];
287
288 /**
289 * Toggles logo space creation
290 *
291 * @see \chillerlan\QRCode\QRCode::addMatrixModifications()
292 * @see \chillerlan\QRCode\Data\QRMatrix::setLogoSpace()
293 */
294 protected bool $addLogoSpace = false;
295
296 /**
297 * Width of the logo space
298 *
299 * if only `QROptions::$logoSpaceWidth` is given, the logo space is assumed a square of that size
300 */
301 protected int|null $logoSpaceWidth = null;
302
303 /**
304 * Height of the logo space
305 *
306 * if only `QROptions::$logoSpaceHeight` is given, the logo space is assumed a square of that size
307 */
308 protected int|null $logoSpaceHeight = null;
309
310 /**
311 * Optional horizontal start position of the logo space (top left corner)
312 */
313 protected int|null $logoSpaceStartX = null;
314
315 /**
316 * Optional vertical start position of the logo space (top left corner)
317 */
318 protected int|null $logoSpaceStartY = null;
319
320
321 /*
322 * Common raster image settings (QRGdImage, QRImagick)
323 */
324
325 /**
326 * Pixel size of a QR code module
327 */
328 protected int $scale = 5;
329
330 /**
331 * Toggle transparency
332 *
333 * - `QRGdImage` and `QRImagick`: the given `QROptions::$transparencyColor` is set as transparent
334 *
335 * @see https://github.com/chillerlan/php-qrcode/discussions/121
336 */
337 protected bool $imageTransparent = false;
338
339 /**
340 * Sets a transparency color for when `QROptions::$imageTransparent` is set to `true`.
341 *
342 * Defaults to `QROptions::$bgColor`.
343 *
344 * - `QRGdImage`: `[R, G, B]`, this color is set as transparent in `imagecolortransparent()`
345 * - `QRImagick`: `"color_str"`, this color is set in `Imagick::transparentPaintImage()`
346 *
347 * @see \imagecolortransparent()
348 * @see \Imagick::transparentPaintImage()
349 */
350 protected mixed $transparencyColor = null;
351
352 /**
353 * Compression quality
354 *
355 * The given value depends on the used output type:
356 *
357 * - `QRGdImageBMP`: `[0...1]`
358 * - `QRGdImageJPEG`: `[0...100]`
359 * - `QRGdImageWEBP`: `[0...9]`
360 * - `QRGdImagePNG`: `[0...100]`
361 * - `QRImagick`: `[0...100]`
362 *
363 * @see \imagebmp()
364 * @see \imagejpeg()
365 * @see \imagepng()
366 * @see \imagewebp()
367 * @see \Imagick::setImageCompressionQuality()
368 */
369 protected int $quality = -1;
370
371
372 /*
373 * QRGdImage settings
374 */
375
376 /**
377 * Toggles the usage of internal upscaling when `QROptions::$drawCircularModules` is set to `true` and
378 * `QROptions::$scale` is less than 20
379 *
380 * @see \chillerlan\QRCode\Output\QRGdImage::createImage()
381 * @see https://github.com/chillerlan/php-qrcode/issues/23
382 */
383 protected bool $gdImageUseUpscale = true;
384
385
386 /*
387 * QRImagick settings
388 */
389
390 /**
391 * Imagick output format
392 *
393 * @see \Imagick::setImageFormat()
394 * @see https://www.imagemagick.org/script/formats.php
395 */
396 protected string $imagickFormat = 'png32';
397
398
399 /*
400 * Common markup output settings (QRMarkupSVG, QRMarkupHTML)
401 */
402
403 /**
404 * A common css class
405 */
406 protected string $cssClass = 'qrcode';
407
408
409 /*
410 * QRMarkupSVG settings
411 */
412
413 /**
414 * Whether to add an XML header line or not, e.g. to embed the SVG directly in HTML
415 *
416 * `<?xml version="1.0" encoding="UTF-8"?>`
417 */
418 protected bool $svgAddXmlHeader = true;
419
420 /**
421 * Anything in the SVG `<defs>` tag
422 *
423 * @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs
424 */
425 protected string $svgDefs = '';
426
427 /**
428 * Sets the value for the "preserveAspectRatio" on the `<svg>` element
429 *
430 * @see https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio
431 */
432 protected string $svgPreserveAspectRatio = 'xMidYMid';
433
434 /**
435 * Whether to use the SVG `fill` attributes
436 *
437 * If set to `true` (default), the `fill` attribute will be set with the module value for the `<path>` element's `$M_TYPE`.
438 * When set to `false`, the module values map will be ignored and the QR Code may be styled via CSS.
439 *
440 * @see https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill
441 */
442 protected bool $svgUseFillAttributes = true;
443
444
445 /*
446 * QRStringText settings
447 */
448
449 /**
450 * An optional line prefix, e.g. empty space to align the QR Code in a console
451 */
452 protected string $textLineStart = '';
453
454
455 /*
456 * QRStringJSON settings
457 */
458
459 /**
460 * Sets the flags to use for the `json_encode()` call
461 *
462 * @see https://www.php.net/manual/json.constants.php
463 */
464 protected int $jsonFlags = (JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
465
466
467 /*
468 * QRFpdf settings
469 */
470
471 /**
472 * Measurement unit for `FPDF` output: `pt`, `mm`, `cm`, `in` (default: `pt`)
473 *
474 * @see FPDF::__construct()
475 */
476 protected string $fpdfMeasureUnit = 'pt';
477
478
479 /*
480 * QRMarkupXML settings
481 */
482
483 /**
484 * Sets an optional XSLT stylesheet in the XML output
485 *
486 * @see https://developer.mozilla.org/en-US/docs/Web/XSLT
487 */
488 protected string|null $xmlStylesheet = null;
489
490
491 /**
492 * clamp min/max version number
493 */
494 protected function setMinMaxVersion(int $versionMin, int $versionMax):void{
495 $min = max(1, min(40, $versionMin));
496 $max = max(1, min(40, $versionMax));
497
498 $this->versionMin = min($min, $max);
499 $this->versionMax = max($min, $max);
500 }
501
502 /**
503 * sets the minimum version number
504 */
505 protected function set_versionMin(int $version):void{
506 $this->setMinMaxVersion($version, $this->versionMax);
507 }
508
509 /**
510 * sets the maximum version number
511 */
512 protected function set_versionMax(int $version):void{
513 $this->setMinMaxVersion($this->versionMin, $version);
514 }
515
516 /**
517 * sets/clamps the version number
518 */
519 protected function set_version(int $version):void{
520 $this->version = ($version !== Version::AUTO) ? max(1, min(40, $version)) : Version::AUTO;
521 }
522
523 /**
524 * sets the ECC level
525 *
526 * @throws \chillerlan\QRCode\QRCodeException
527 */
528 protected function set_eccLevel(int|string $eccLevel):void{
529
530 if(is_string($eccLevel)){
531 $ecc = strtoupper(trim($eccLevel));
532
533 if(!in_array($ecc, ['L', 'M', 'Q', 'H'], true)){
534 throw new QRCodeException(sprintf('Invalid ECC level: "%s"', $ecc));
535 }
536
537 // @todo: PHP 8.3+
538 // $eccLevel = EccLevel::{$ecc};
539 $eccLevel = constant(EccLevel::class.'::'.$ecc);
540 }
541
542 /** @var int $eccLevel */
543 if((0b11 & $eccLevel) !== $eccLevel){
544 throw new QRCodeException(sprintf('Invalid ECC level: "%s"', $eccLevel));
545 }
546
547 $this->eccLevel = $eccLevel;
548 }
549
550 /**
551 * clamps the module scale at a minimum of 1 and a maximum of 50
552 */
553 protected function set_scale(int $scale):void{
554 $this->scale = max(1, min($scale, 50));
555 }
556
557 /**
558 * sets/clamps the quiet zone size
559 */
560 protected function set_quietzoneSize(int $quietzoneSize):void{
561 $this->quietzoneSize = max(0, min($quietzoneSize, 75));
562 }
563
564 /**
565 * sets the FPDF measurement unit
566 *
567 * @codeCoverageIgnore
568 */
569 protected function set_fpdfMeasureUnit(string $unit):void{
570 $unit = strtolower($unit);
571
572 if(in_array($unit, ['cm', 'in', 'mm', 'pt'], true)){
573 $this->fpdfMeasureUnit = $unit;
574 }
575
576 // @todo throw or ignore silently?
577 }
578
579 /**
580 * clamp the logo space values between 0 and maximum length (177 modules at version 40)
581 */
582 protected function clampLogoSpaceValue(int|null $value):int|null{
583
584 if($value === null){
585 return null;
586 }
587
588 return (int)max(0, min(177, $value));
589 }
590
591 /**
592 * clamp/set logo space width
593 */
594 protected function set_logoSpaceWidth(int|null $value):void{
595 $this->logoSpaceWidth = $this->clampLogoSpaceValue($value);
596 }
597
598 /**
599 * clamp/set logo space height
600 */
601 protected function set_logoSpaceHeight(int|null $value):void{
602 $this->logoSpaceHeight = $this->clampLogoSpaceValue($value);
603 }
604
605 /**
606 * clamp/set horizontal logo space start
607 */
608 protected function set_logoSpaceStartX(int|null $value):void{
609 $this->logoSpaceStartX = $this->clampLogoSpaceValue($value);
610 }
611
612 /**
613 * clamp/set vertical logo space start
614 */
615 protected function set_logoSpaceStartY(int|null $value):void{
616 $this->logoSpaceStartY = $this->clampLogoSpaceValue($value);
617 }
618
619 /**
620 * clamp/set SVG circle radius
621 */
622 protected function set_circleRadius(float $circleRadius):void{
623 $this->circleRadius = max(0.1, min(0.75, $circleRadius));
624 }
625
626 }