Skip to content

Commit de3d321

Browse files
codemashercodemasher
committed
📖
1 parent e4cbe56 commit de3d321

16 files changed

+362
-175
lines changed

‎README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,9 @@ It also features a QR Code reader based on a [PHP port](https://github.com/khana
6161
- [`ext-imagick`](https://github.com/Imagick/imagick) with [ImageMagick](https://imagemagick.org) installed
6262
- [`ext-fileinfo`](https://www.php.net/manual/book.fileinfo.php) (required by `QRImagick` output)
6363
- [`setasign/fpdf`](https://github.com/setasign/fpdf) for the PDF output module
64+
- [`intervention/image`](https://github.com/Intervention/image) for alternative GD/ImageMagick output
6465

65-
For the QRCode reader, either `ext-gd` or `ext-imagick` is required!
66+
For the QR Code reader, either `ext-gd` or `ext-imagick` is required!
6667

6768

6869
# Documentation

‎docs/Built-In-Output/QREps.md

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# QREps
22

3-
[Class `QREps`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QREps.php): [Encapsulated Postscript](https://en.wikipedia.org/wiki/Encapsulated_PostScript) (EPS) output.
3+
[Class `QREps`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QREps.php):
4+
[Encapsulated Postscript](https://en.wikipedia.org/wiki/Encapsulated_PostScript) (EPS) output.
45

56

67
## Example
@@ -50,6 +51,7 @@ echo (new QRCode($options))->render($data);
5051
exit;
5152
```
5253

54+
5355
## Additional methods
5456

5557
| method | return | description |
@@ -67,15 +69,3 @@ exit;
6769
| `$drawLightModules` | `bool` |
6870
| `$excludeFromConnect` | `array` |
6971
| `$scale` | `int` |
70-
71-
72-
### Options that have no effect
73-
74-
| property | reason |
75-
|------------------------|-----------------|
76-
| `$circleRadius` | not implemented |
77-
| `$drawCircularModules` | not implemented |
78-
| `$outputBase64` | N/A |
79-
| `$imageTransparent` | N/A |
80-
| `$keepAsSquare` | not implemented |
81-
| `$returnResource` | N/A |

‎docs/Built-In-Output/QRFpdf.md

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# QRFpdf
22

3-
[Class `QRFpdf`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRFpdf.php): [Portable Document Format](https://en.wikipedia.org/wiki/PDF) (PDF) output via [FPDF](https://github.com/setasign/fpdf)
3+
[Class `QRFpdf`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRFpdf.php):
4+
[Portable Document Format](https://en.wikipedia.org/wiki/PDF) (PDF) output via [FPDF](https://github.com/setasign/fpdf).
45

56

67
## Example
@@ -74,15 +75,3 @@ echo $fpdf->Output('S');
7475
| `$outputBase64` | `bool` |
7576
| `$returnResource` | `bool` |
7677
| `$scale` | `ìnt` |
77-
78-
79-
### Options that have no effect
80-
81-
| property | reason |
82-
|------------------------|--------|
83-
| `$circleRadius` | N/A |
84-
| `$connectPaths` | N/A |
85-
| `$drawCircularModules` | N/A |
86-
| `$excludeFromConnect` | N/A |
87-
| `$imageTransparent` | N/A |
88-
| `$keepAsSquare` | N/A |

‎docs/Built-In-Output/QRGdImage.md

Lines changed: 12 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# QRGdImage
22

3-
[Class `QRGdImage`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRGdImage.php): [GdImage](https://www.php.net/manual/book.image) raster graphic output (GIF, JPG, PNG)
3+
[Class `QRGdImage`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRGdImage.php):
4+
[GdImage](https://www.php.net/manual/book.image) raster graphic output (GIF, JPG, PNG, ...)
45

56

67
## Example
@@ -51,12 +52,12 @@ printf('<img alt="%s" src="%s" />', $alt, $out);
5152
```
5253

5354

54-
Return the `GdImage` instance/resource (will ignore other output options):
55+
Return the `GdImage` instance (will ignore other output options):
5556

5657
```php
5758
$options->returnResource = true;
5859

59-
/** @var \GdImage|resource $gdImage */
60+
/** @var \GdImage $gdImage */
6061
$gdImage = (new QRCode($options))->render($data);
6162

6263
// do stuff with the GdImage instance...
@@ -73,13 +74,14 @@ imagedestroy($gdImage);
7374

7475
## Additional methods
7576

76-
| method | return | description |
77-
|---------------------------------------------------|----------|-------------------------------------------------------------------|
78-
| (protected) `drawImage()` | `void` | Draws the QR image |
79-
| (protected) `dumpImage()` | `string` | Creates the final image by calling the desired GD output function |
80-
| (protected) `module(int $x, int $y, int $M_TYPE)` | `void` | Renders a single module |
81-
| (protected) `setBgColor()` | `void` | Sets the background color |
82-
| (protected) `setTransparencyColor()` | `void` | Sets the transparency color |
77+
| method | return | description |
78+
|---------------------------------------------------|----------|--------------------------------------------------------------------------------------------------|
79+
| (protected) `drawImage()` | `void` | Draws the QR image |
80+
| (protected) `dumpImage()` | `string` | Creates the final image by calling the desired GD output function |
81+
| (protected) `module(int $x, int $y, int $M_TYPE)` | `void` | Renders a single module |
82+
| (protected) `setBgColor()` | `void` | Sets the background color |
83+
| (protected) `setTransparencyColor()` | `void` | Sets the transparency color |
84+
| (abstract protected) `renderImage()` | `void` | Renders the image with the gdimage function for the desired output, implemented by child classes |
8385

8486

8587
## Options that affect this module
@@ -97,11 +99,3 @@ imagedestroy($gdImage);
9799
| `$returnResource` | `bool` |
98100
| `$scale` | `int` |
99101
| `$transparencyColor` | `mixed` |
100-
101-
102-
### Options that have no effect
103-
104-
| property | reason |
105-
|-----------------------|--------|
106-
| `$connectPaths` | N/A |
107-
| `$excludeFromConnect` | N/A |

‎docs/Built-In-Output/QRImagick.md

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -102,11 +102,3 @@ echo $imagick->getImageBlob();
102102
| `$returnResource` | `bool` |
103103
| `$scale` | `int` |
104104
| `$transparencyColor` | `mixed` |
105-
106-
107-
### Options that have no effect
108-
109-
| property | reason |
110-
|-----------------------|--------|
111-
| `$connectPaths` | N/A |
112-
| `$excludeFromConnect` | N/A |

‎docs/Built-In-Output/QRInterventionImage.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# QRInterventionImage
2+
3+
[Class `QRInterventionImage`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRInterventionImage.php):
4+
[intervention/image](https://image.intervention.io/) alternative GD/ImageMagick output.
5+
6+
***Note:** this output class works significantly slower than the native GD/Imagick output classes due to the several underlying abstraction layers. Use only if you must.*
7+
8+
9+
## Example
10+
11+
See: [intervention/image example](https://github.com/chillerlan/php-qrcode/blob/main/examples/intervention-image.php)
12+
13+
Set the options:
14+
15+
```php
16+
$options = new QROptions;
17+
18+
$options->outputInterface = QRInterventionImage::class;
19+
$options->scale = 20;
20+
$options->bgColor = '#ccccaa';
21+
$options->imageTransparent = false;
22+
$options->transparencyColor = '#ccccaa';
23+
$options->drawLightModules = false;
24+
$options->drawCircularModules = true;
25+
$options->circleRadius = 0.4;
26+
$options->keepAsSquare = [
27+
QRMatrix::M_FINDER_DARK,
28+
QRMatrix::M_FINDER_DOT,
29+
QRMatrix::M_ALIGNMENT_DARK,
30+
];
31+
$options->moduleValues = [
32+
QRMatrix::M_FINDER_DARK => '#A71111', // dark (true)
33+
QRMatrix::M_FINDER_DOT => '#A71111', // finder dot, dark (true)
34+
QRMatrix::M_FINDER => '#FFBFBF', // light (false)
35+
QRMatrix::M_ALIGNMENT_DARK => '#A70364',
36+
QRMatrix::M_ALIGNMENT => '#FFC9C9',
37+
QRMatrix::M_VERSION_DARK => '#650098',
38+
QRMatrix::M_VERSION => '#E0B8FF',
39+
];
40+
```
41+
42+
43+
Render the output:
44+
45+
```php
46+
$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
47+
$out = (new QRCode($options))->render($data); // -> data:image/png;base64,...
48+
49+
printf('<img alt="%s" src="%s" />', $alt, $out);
50+
```
51+
52+
53+
Return the `ImageInterface` instance (will ignore other output options):
54+
55+
```php
56+
$options->returnResource = true;
57+
58+
/** @var \Intervention\Image\Interfaces\ImageInterface $image */
59+
$image = (new QRCode($options))->render($data);
60+
61+
// do stuff with the ImageInterface instance...
62+
63+
// ...dump output
64+
65+
header('Content-type: image/png');
66+
67+
echo $image->toPng()->toString();
68+
```
69+
70+
Set a different driver in the internal `ImageManager` instance (the internal detection order is: 1. GD, 2. Imagick):
71+
72+
```php
73+
$qrOutputInterface = new QRInterventionImage($options, $matrix);
74+
// set a different driver
75+
$qrOutputInterface->setDriver(new \Intervention\Image\Drivers\Imagick\Driver);
76+
// dump output
77+
$out = $qrOutputInterface->dump();
78+
```
79+
80+
81+
## Additional methods
82+
83+
| method | return | description |
84+
|--------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------|
85+
| `setDriver(DriverInterface $driver)` | `static` | Sets a DriverInterface, see [instantiation (intervention.io)](https://image.intervention.io/v3/basics/instantiation) |
86+
| (protected) `module()` | `void` | Draws a single pixel at the given position |
87+
88+
89+
## Options that affect this module
90+
91+
| property | type |
92+
|------------------------|----------|
93+
| `$bgColor` | `mixed` |
94+
| `$circleRadius` | `float` |
95+
| `$drawCircularModules` | `bool` |
96+
| `$drawLightModules` | `bool` |
97+
| `$imageTransparent` | `bool` |
98+
| `$keepAsSquare` | `array` |
99+
| `$outputBase64` | `bool` |
100+
| `$returnResource` | `bool` |
101+
| `$scale` | `int` |
102+
| `$transparencyColor` | `mixed` |

‎docs/Built-In-Output/QRMarkupSVG.md

Lines changed: 7 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
# QRMarkupSVG
22

3-
[Class `QRMarkupSVG`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRMarkupSVG.php): [Scalable Vector Graphics](https://developer.mozilla.org/en-US/docs/Glossary/SVG) (SVG) output
3+
[Class `QRMarkupSVG`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRMarkupSVG.php):
4+
[Scalable Vector Graphics](https://developer.mozilla.org/en-US/docs/Glossary/SVG) (SVG) output.
5+
46

57
## Example
68

7-
See: [ImageMagick example](https://github.com/chillerlan/php-qrcode/blob/main/examples/imagick.php)
9+
See: [SVG example](https://github.com/chillerlan/php-qrcode/blob/main/examples/svg.php)
810

911
Set the options:
1012

@@ -62,13 +64,14 @@ printf('<img alt="%s" src="%s" />', $alt, $out);
6264
| method | return | description |
6365
|---------------------------------------------------|----------|---------------------------------------------------------------|
6466
| (protected) `getCssClass(int $M_TYPE = 0)` | `string` | returns a string with all css classes for the current element |
67+
| (protected) `getViewBox()` | `string` | returns the value for the SVG viewBox attribute |
6568
| (protected) `header()` | `string` | returns the `<svg>` header with the given options parsed |
66-
| (protected) `module(int $x, int $y, int $M_TYPE)` | `string` | returns a path segment for a single module |
6769
| (protected) `path(string $path, int $M_TYPE)` | `string` | renders and returns a single `<path>` element |
6870
| (protected) `paths()` | `string` | returns one or more SVG `<path>` elements |
71+
| (protected) `module(int $x, int $y, int $M_TYPE)` | `string` | returns a path segment for a single module |
6972
7073
71-
## Options that affect this module
74+
## Options that affect this class
7275
7376
| property | type |
7477
|---------------------------|-------------|
@@ -87,13 +90,3 @@ printf('<img alt="%s" src="%s" />', $alt, $out);
8790
| `$svgPreserveAspectRatio` | `string` |
8891
| `$svgViewBoxSize` | `int\|null` |
8992
| `$svgUseFillAttributes` | `bool` |
90-
91-
92-
### Options that have no effect
93-
94-
| property | reason |
95-
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
96-
| `$bgColor` | background color can be achieved via CSS, attributes or the `<defs>` element, see also [php-qrcode/discussions/199 (comment)](https://github.com/chillerlan/php-qrcode/discussions/199#discussioncomment-5747471) |
97-
| `$imageTransparent` | SVG is - similar to a HTML element - transparent by default |
98-
| `$returnResource` | N/A |
99-
| `$scale` | `$scale` (pixel size of a qr module) is intended for raster image types, use `$svgViewBoxSize` instead |

‎docs/Built-In-Output/QRMarkupXML.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# QRMarkupXML
2+
3+
[Class `QRMarkupXML`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRMarkupXML.php): [eXtensible Markup Language](https://developer.mozilla.org/en-US/docs/Glossary/XML) (XML) output
4+
5+
6+
## Example
7+
8+
See: [XML example](https://github.com/chillerlan/php-qrcode/blob/main/examples/xml.php)
9+
10+
Set the options:
11+
12+
```php
13+
$options = new QROptions;
14+
15+
$options->outputInterface = QRMarkupXML::class;
16+
$options->outputBase64 = false;
17+
// if set to false, the light modules won't be included in the output
18+
$options->drawLightModules = false;
19+
20+
// assign an XSLT stylesheet
21+
$options->xmlStylesheet = './qrcode.style.xsl';
22+
23+
$options->moduleValues = [
24+
QRMatrix::M_FINDER_DARK => '#A71111', // dark (true)
25+
QRMatrix::M_FINDER_DOT => '#A71111', // finder dot, dark (true)
26+
QRMatrix::M_FINDER => '#FFBFBF', // light (false)
27+
QRMatrix::M_ALIGNMENT_DARK => '#A70364',
28+
QRMatrix::M_ALIGNMENT => '#FFC9C9',
29+
QRMatrix::M_VERSION_DARK => '#650098',
30+
QRMatrix::M_VERSION => '#E0B8FF',
31+
];
32+
```
33+
34+
35+
The XSLT stylesheet `qrcode.style.xsl`:
36+
37+
```XSLT
38+
<?xml version="1.0" encoding="UTF-8"?>
39+
<!-- XSLT style for the XML output example -->
40+
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
41+
<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>
42+
<xsl:template match="/">
43+
<!-- SVG header -->
44+
<svg xmlns="http://www.w3.org/2000/svg"
45+
version="1.0"
46+
viewBox="0 0 {qrcode/matrix/@width} {qrcode/matrix/@height}"
47+
preserveAspectRatio="xMidYMid"
48+
>
49+
<!--
50+
path for a single module
51+
we could define a path for each layer and use the @layer attribute for selection,
52+
but that would exaggerate this example
53+
-->
54+
<symbol id="module" width="1" height="1">
55+
<circle cx="0.5" cy="0.5" r="0.4" />
56+
</symbol>
57+
<!-- loop over the rows -->
58+
<xsl:for-each select="qrcode/matrix/row">
59+
<!-- set a variable for $y (vertical) -->
60+
<xsl:variable name="y" select="@y"/>
61+
<xsl:for-each select="module">
62+
<!-- set a variable for $x (horizontal) -->
63+
<xsl:variable name="x" select="@x"/>
64+
<!-- draw only dark modules -->
65+
<xsl:if test="@dark='true'">
66+
<!-- position the module and set its fill color -->
67+
<use href="#module" class="{@layer}" x="{$x}" y="{$y}" fill="{@value}"/>
68+
</xsl:if>
69+
</xsl:for-each>
70+
</xsl:for-each>
71+
</svg>
72+
</xsl:template>
73+
</xsl:stylesheet>
74+
```
75+
76+
77+
Render the output:
78+
79+
```php
80+
$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
81+
$out = (new QRCode($options))->render($data); // -> XML, rendered as SVG
82+
83+
printf('<img alt="%s" src="%s" />', $alt, $out);
84+
```
85+
86+
The associated [XML schema](https://www.w3.org/XML/Schema) can be found over at GitHub: [`qrcode.schema.xsd`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/qrcode.schema.xsd)
87+
88+
89+
## Additional methods
90+
91+
| method | return | description |
92+
|---------------------------------------------------|--------------------|-------------------------------------------|
93+
| (protected) `createMatrix()` | `DOMElement` | creates the matrix element |
94+
| (protected) `row(int $y, array $row)` | `DOMElement\|null` | creates a DOM element for a matrix row |
95+
| (protected) `module(int $x, int $y, int $M_TYPE)` | `DOMElement\|null` | creates a DOM element for a single module |
96+
97+
98+
## Options that affect this class
99+
100+
| property | type |
101+
|---------------------------|----------|
102+
| `$drawLightModules` | `bool` |
103+
| `$outputBase64` | `bool` |
104+
| `xmlStylesheet` | `string` |

0 commit comments

Comments
 (0)