woocommerce-pos / vendor_prefixed / chillerlan / php-qrcode / src / QROptionsTrait.php

QROptionsTrait.php in WCPOS – Point of Sale (POS) plugin for WooCommerce 1.10.19, at vendor_prefixed/chillerlan/php-qrcode/src/QROptionsTrait.php

657 lines 20.2 KB

Raw Download Zip

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