From b0a2cb6f6792f99ac92a5684eaa1548cf57504de Mon Sep 17 00:00:00 2001 From: smiley Date: Thu, 13 Jul 2023 23:15:16 +0200 Subject: [PATCH] :octocat: --- docs/API-DecoderResult.md | 4 +- docs/API-QRCode.md | 2 +- docs/API-QRMatrix.md | 63 ++++++++++--------- docs/API-QROptions.md | 2 +- docs/API-QROutputInterface.md | 6 +- ...ix-Glossary.md => Appendix-Terminology.md} | 2 +- docs/Built-In-Output-QREps.md | 26 ++++++++ docs/Built-In-Output-QRFpdf.md | 29 +++++++++ docs/Built-In-Output-QRGdImage.md | 29 +++++++++ docs/Built-In-Output-QRImagick.md | 36 +++++++++++ docs/Built-In-Output-QRMarkupHTML.md | 29 +++++++++ docs/Built-In-Output-QRMarkupSVG.md | 36 +++++++++++ docs/Built-In-Output-QRString.md | 29 +++++++++ docs/Readme.md | 14 ++++- docs/Usage-Installation.md | 2 +- docs/index.rst | 34 ++++++---- 16 files changed, 295 insertions(+), 48 deletions(-) rename docs/{Appendix-Glossary.md => Appendix-Terminology.md} (99%) create mode 100644 docs/Built-In-Output-QREps.md create mode 100644 docs/Built-In-Output-QRFpdf.md create mode 100644 docs/Built-In-Output-QRGdImage.md create mode 100644 docs/Built-In-Output-QRImagick.md create mode 100644 docs/Built-In-Output-QRMarkupHTML.md create mode 100644 docs/Built-In-Output-QRMarkupSVG.md create mode 100644 docs/Built-In-Output-QRString.md diff --git a/docs/API-DecoderResult.md b/docs/API-DecoderResult.md index 324c45145..6185e164c 100644 --- a/docs/API-DecoderResult.md +++ b/docs/API-DecoderResult.md @@ -1,7 +1,8 @@ -# `DecoderResult` +# DecoderResult The full phpDocumentor API documentation can be found at [chillerlan.github.io/php-qrcode](https://chillerlan.github.io/php-qrcode/classes/chillerlan-QRCode-Decoder-DecoderResult.html). + ## Methods | method | return | description | @@ -11,6 +12,7 @@ The full phpDocumentor API documentation can be found at [chillerlan.github.io/p | `hasStructuredAppend()` | `bool` | | | `getQRMatrix()` | `QRMatrix` | | + ## Magic Properties (read-only) | property | type | description | diff --git a/docs/API-QRCode.md b/docs/API-QRCode.md index fa7cf279d..b9e0c97d5 100644 --- a/docs/API-QRCode.md +++ b/docs/API-QRCode.md @@ -1,4 +1,4 @@ -# `QRCode` +# QRCode The full phpDocumentor API documentation can be found at [chillerlan.github.io/php-qrcode](https://chillerlan.github.io/php-qrcode/classes/chillerlan-QRCode-QRCode.html). diff --git a/docs/API-QRMatrix.md b/docs/API-QRMatrix.md index 27648e58e..f681f2bf6 100644 --- a/docs/API-QRMatrix.md +++ b/docs/API-QRMatrix.md @@ -1,7 +1,8 @@ -# `QRMatrix` +# QRMatrix The full phpDocumentor API documentation can be found at [chillerlan.github.io/php-qrcode](https://chillerlan.github.io/php-qrcode/classes/chillerlan-QRCode-Data-QRMatrix.html). + ## Methods | method | return | description | @@ -33,6 +34,7 @@ The full phpDocumentor API documentation can be found at [chillerlan.github.io/p | `writeCodewords(BitBuffer $bitBuffer)` | `self` | Maps the interleaved binary data on the matrix | | `mask(MaskPattern $maskPattern)` | `self` | Applies/reverses the mask pattern | + ### Deprecated methods | method | since | replacement | @@ -43,33 +45,38 @@ The full phpDocumentor API documentation can be found at [chillerlan.github.io/p | `maskPattern()` | `5.0.0` | `QRMatrix::getMaskPattern()` | | `size()` | `5.0.0` | `QRMatrix::getSize()` | + ## Constants -The `_DARK` prefixed constans exist purely for convenience - their value is the same as `QRMatrix::M_XXX\|QRMatrix::IS_DARK`, see [`QROutputInterface`](./API-QROutputInterface.md). +The `_DARK` and `_LIGHT` postfixed constans exist purely for convenience - their value is the same as +`QRMatrix::M_XXX | QRMatrix::IS_DARK` and `QRMatrix::M_XXX ^ QRMatrix::IS_DARK` respectively, +see [`QROutputInterface`](./API-QROutputInterface.md). -| name | description | -|--------------------|-----------------------------------------------------------------------------------| -| `IS_DARK` | sets the "dark" flag for the given value: `QRMatrix::M_DATA \| QRMatrix::IS_DARK` | -| `M_NULL` | module not set | -| `M_DARKMODULE` | once per matrix at `$xy = [8, 4 * $version + 9]` | -| `M_DATA` | the actual encoded data | -| `M_DATA_DARK` | convenience | -| `M_FINDER` | the 7x7 finder patterns | -| `M_FINDER_DARK` | convenience | -| `M_FINDER_DOT` | the inner 3x3 block of the finder pattern | -| `M_SEPARATOR` | separator lines along the finder patterns | -| `M_SEPARATOR_DARK` | convenience | -| `M_ALIGNMENT` | the 5x5 alignment patterns | -| `M_ALIGNMENT_DARK` | convenience | -| `M_TIMING` | the timing pattern lines | -| `M_TIMING_DARK` | convenience | -| `M_FORMAT` | format information pattern | -| `M_FORMAT_DARK` | convenience | -| `M_VERSION` | version information pattern | -| `M_VERSION_DARK` | convenience | -| `M_QUIETZONE` | margin around the QR Code | -| `M_QUIETZONE_DARK` | convenience | -| `M_LOGO` | space for a logo image (not used yet) | -| `M_LOGO_DARK` | convenience | -| `M_TEST` | test value | -| `M_TEST_DARK` | convenience | +| name | description | +|----------------------|-----------------------------------------------------------------------------------| +| `IS_DARK` | sets the "dark" flag for the given value: `QRMatrix::M_DATA \| QRMatrix::IS_DARK` | +| `M_NULL` | module not set | +| `M_DARKMODULE_LIGHT` | convenience (reversed reflectance) | +| `M_DARKMODULE` | once per matrix at `$xy = [8, 4 * $version + 9]` | +| `M_DATA` | the actual encoded data | +| `M_DATA_DARK` | convenience | +| `M_FINDER` | the 7x7 finder patterns | +| `M_FINDER_DARK` | convenience | +| `M_FINDER_DOT_LIGHT` | convenience (reversed reflectance) | +| `M_FINDER_DOT` | the inner 3x3 block of the finder pattern | +| `M_SEPARATOR` | separator lines along the finder patterns | +| `M_SEPARATOR_DARK` | convenience | +| `M_ALIGNMENT` | the 5x5 alignment patterns | +| `M_ALIGNMENT_DARK` | convenience | +| `M_TIMING` | the timing pattern lines | +| `M_TIMING_DARK` | convenience | +| `M_FORMAT` | format information pattern | +| `M_FORMAT_DARK` | convenience | +| `M_VERSION` | version information pattern | +| `M_VERSION_DARK` | convenience | +| `M_QUIETZONE` | margin around the QR Code | +| `M_QUIETZONE_DARK` | convenience | +| `M_LOGO` | space for a logo image (not used yet) | +| `M_LOGO_DARK` | convenience | +| `M_TEST` | test value | +| `M_TEST_DARK` | convenience | diff --git a/docs/API-QROptions.md b/docs/API-QROptions.md index 9308d73b4..bd8239a49 100644 --- a/docs/API-QROptions.md +++ b/docs/API-QROptions.md @@ -1,4 +1,4 @@ -# `QROptions` +# QROptions (via `QROptionsTrait`) The full phpDocumentor API documentation can be found at [chillerlan.github.io/php-qrcode](https://chillerlan.github.io/php-qrcode/classes/chillerlan-QRCode-QROptions.html). diff --git a/docs/API-QROutputInterface.md b/docs/API-QROutputInterface.md index 2a5447754..78ceaf428 100644 --- a/docs/API-QROutputInterface.md +++ b/docs/API-QROutputInterface.md @@ -1,14 +1,16 @@ -# `QROutputInterface` +# QROutputInterface The full phpDocumentor API documentation can be found at [chillerlan.github.io/php-qrcode](https://chillerlan.github.io/php-qrcode/classes/chillerlan-QRCode-Output-QROutputInterface.html). -## Methods +## Methods + | method | return | description | |---------------------------------------|---------|---------------------------------------------------------------------| | (static) `moduleValueIsValid($value)` | `bool` | Determines whether the given value is valid | | `dump(string $file = null)` | `mixed` | Generates the output, optionally dumps it to a file, and returns it | + ## Constants | name | description | diff --git a/docs/Appendix-Glossary.md b/docs/Appendix-Terminology.md similarity index 99% rename from docs/Appendix-Glossary.md rename to docs/Appendix-Terminology.md index ab25e3d13..10c373643 100644 --- a/docs/Appendix-Glossary.md +++ b/docs/Appendix-Terminology.md @@ -206,7 +206,7 @@ alternate character encoding for the following Byte segment (by default, ISO-885 An ECI segment starts with the 4 bit indicator `0111` followed by the ECI Assignment number (8, 16 or 24 bits), followed by a Byte segment (`0100` ...) where the contents are encoded according to the preceding ECI ID. -The lenght of the ECI Assignment number depends on the given encoding ID: +The length of the ECI Assignment number depends on the given encoding ID: | ID | length (bits) | |----------------|---------------| diff --git a/docs/Built-In-Output-QREps.md b/docs/Built-In-Output-QREps.md new file mode 100644 index 000000000..60485b4b7 --- /dev/null +++ b/docs/Built-In-Output-QREps.md @@ -0,0 +1,26 @@ +# QREps + +[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 + + +## Options that affect this module + +| property | type | +|--------------------------------|----------------| +| `$drawLightModules` | `bool` | +| `$connectPaths` | `bool` | +| `$excludeFromConnect` | `array` | +| `$scale` | `int` | + + +### Options that have no effect + +| property | reason | +|------------------------|-----------------| +| `$returnResource` | N/A | +| `$imageBase64` | N/A | +| `$bgColor` | not implemented | +| `$drawCircularModules` | not implemented | +| `$circleRadius` | not implemented | +| `$keepAsSquare` | not implemented | +| `$imageTransparent` | N/A | diff --git a/docs/Built-In-Output-QRFpdf.md b/docs/Built-In-Output-QRFpdf.md new file mode 100644 index 000000000..62115287c --- /dev/null +++ b/docs/Built-In-Output-QRFpdf.md @@ -0,0 +1,29 @@ +# QRFpdf + +[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) + + +## Options that affect this module + +| property | type | +|--------------------------------|----------------| +| `$returnResource` | `bool` | +| `$imageBase64` | `bool` | +| `$bgColor` | `mixed` | +| `$drawLightModules` | `bool` | +| `$fpdfMeasureUnit` | `string` | + + +### Options that have no effect + +| property | reason | +|------------------------|-----------------| +| `$drawCircularModules` | N/A | +| `$circleRadius` | N/A | +| `$keepAsSquare` | N/A | +| `$connectPaths` | N/A | +| `$excludeFromConnect` | N/A | +| `$scale` | not implemented | +| `$imageTransparent` | N/A | + + diff --git a/docs/Built-In-Output-QRGdImage.md b/docs/Built-In-Output-QRGdImage.md new file mode 100644 index 000000000..d1fafe85d --- /dev/null +++ b/docs/Built-In-Output-QRGdImage.md @@ -0,0 +1,29 @@ +# QRGdImage + +[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) + + +## Options that affect this module + +| property | type | +|--------------------------------|----------------| +| `$returnResource` | `bool` | +| `$imageBase64` | `bool` | +| `$bgColor` | `mixed` | +| `$drawLightModules` | `bool` | +| `$drawCircularModules` | `bool` | +| `$circleRadius` | `float` | +| `$keepAsSquare` | `array` | +| `$scale` | `int` | +| `$imageTransparent` | `bool` | +| `$transparencyColor` | `mixed` | +| `$pngCompression` | `int` | +| `$jpegQuality` | `int` | + + +### Options that have no effect + +| property | reason | +|--------------------------------|--------| +| `$connectPaths` | N/A | +| `$excludeFromConnect` | N/A | diff --git a/docs/Built-In-Output-QRImagick.md b/docs/Built-In-Output-QRImagick.md new file mode 100644 index 000000000..5d3d26957 --- /dev/null +++ b/docs/Built-In-Output-QRImagick.md @@ -0,0 +1,36 @@ +# QRImagick + +[Class `QRImagick`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRImagick.php): [ImageMagick](https://www.php.net/manual/book.imagick) output, [multiple supported image formats](https://imagemagick.org/script/formats.php) + +Please follow the installation guides for your operating system: + +- ImageMagick: [imagemagick.org/script/download.php](https://imagemagick.org/script/download.php) +- PHP `ext-imagick`: [github.com/Imagick/imagick](https://github.com/Imagick/imagick) ([Windows downloads](https://mlocati.github.io/articles/php-windows-imagick.html)) +- [PHP Imagick by Example](https://phpimagick.com/) ([github.com/Imagick/ImagickDemos](https://github.com/Imagick/ImagickDemos)) + + +## Options that affect this module + +| property | type | +|--------------------------------|----------------| +| `$returnResource` | `bool` | +| `$imageBase64` | `bool` | +| `$bgColor` | `mixed` | +| `$drawLightModules` | `bool` | +| `$drawCircularModules` | `bool` | +| `$circleRadius` | `float` | +| `$keepAsSquare` | `array` | +| `$scale` | `int` | +| `$imageTransparent` | `bool` | +| `$transparencyColor` | `mixed` | +| `$imagickFormat` | `string` | + + +### Options that have no effect + +| property | reason | +|--------------------------------|-------------------| +| `$connectPaths` | N/A | +| `$excludeFromConnect` | N/A | +| `$pngCompression` | GdImage exclusive | +| `$jpegQuality` | GdImage exclusive | diff --git a/docs/Built-In-Output-QRMarkupHTML.md b/docs/Built-In-Output-QRMarkupHTML.md new file mode 100644 index 000000000..85f6335b2 --- /dev/null +++ b/docs/Built-In-Output-QRMarkupHTML.md @@ -0,0 +1,29 @@ +# QRMarkupHTML + +[Class `QRMarkupHTML`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRMarkupHTML.php): HTML output (a cheap markup substitute when SVG is not available or not an option) + +## Options that affect this module + +| property | type | +|--------------------------------|----------------| +| `$eol` | `string` | +| `$cssClass` | `string` | +| `$markupDark` | `string` | +| `$markupLight` | `string` | + + +### Options that have no effect + +| property | reason | +|--------------------------------|---------| +| `$returnResource` | N/A | +| `$imageBase64` | N/A | +| `$bgColor` | via CSS | +| `$drawLightModules` | N/A | +| `$drawCircularModules` | N/A | +| `$circleRadius` | N/A | +| `$keepAsSquare` | N/A | +| `$connectPaths` | N/A | +| `$excludeFromConnect` | N/A | +| `$scale` | via CSS | +| `$imageTransparent` | N/A | diff --git a/docs/Built-In-Output-QRMarkupSVG.md b/docs/Built-In-Output-QRMarkupSVG.md new file mode 100644 index 000000000..fa7cb93df --- /dev/null +++ b/docs/Built-In-Output-QRMarkupSVG.md @@ -0,0 +1,36 @@ +# QRMarkupSVG + +[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 + +## Options that affect this module + +| property | type | +|--------------------------------|----------------| +| `$imageBase64` | `bool` | +| `$eol` | `string` | +| `$drawLightModules` | `bool` | +| `$drawCircularModules` | `bool` | +| `$circleRadius` | `float` | +| `$keepAsSquare` | `array` | +| `$connectPaths` | `bool` | +| `$excludeFromConnect` | `array` | +| `$cssClass` | `string` | +| `$markupDark` | `string` | +| `$markupLight` | `string` | +| `$svgAddXmlHeader` | `bool` | +| `$svgOpacity` | `float` | +| `$svgDefs` | `string` | +| `$svgViewBoxSize` | `int\|null` | +| `$svgPreserveAspectRatio` | `string` | +| `$svgWidth` | `string\|null` | +| `$svgHeight` | `string\|null` | + + +### Options that have no effect + +| property | reason | +|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `$returnResource` | N/A | +| `$bgColor` | background color can be achieved via CSS, `` or attributes, see also [php-qrcode/discussions/199 (comment)](https://github.com/chillerlan/php-qrcode/discussions/199#discussioncomment-5747471) | +| `$scale` | `$scale` is intended for raster image types, use `$svgViewBoxSize` instead | +| `$imageTransparent` | SVG is transparent by default | diff --git a/docs/Built-In-Output-QRString.md b/docs/Built-In-Output-QRString.md new file mode 100644 index 000000000..7b629b1b8 --- /dev/null +++ b/docs/Built-In-Output-QRString.md @@ -0,0 +1,29 @@ +# QRString + +[Class `QRString`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRString.php): String output: plain text, [JSON](https://developer.mozilla.org/en-US/docs/Glossary/JSON) + + +## Options that affect this module + +| property | type | +|--------------------------------|----------------| +| `$eol` | `string` | +| `$textDark` | `string` | +| `$textLight` | `string` | + + +### Options that have no effect + +| property | reason | +|--------------------------------|-----------------| +| `$returnResource` | N/A | +| `$imageBase64` | N/A | +| `$bgColor` | N/A | +| `$drawLightModules` | not implemented | +| `$drawCircularModules` | N/A | +| `$circleRadius` | N/A | +| `$keepAsSquare` | N/A | +| `$connectPaths` | N/A | +| `$excludeFromConnect` | N/A | +| `$scale` | N/A | +| `$imageTransparent` | N/A | diff --git a/docs/Readme.md b/docs/Readme.md index 75632cd63..72a358679 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -60,7 +60,17 @@ The markdown sources for the [Read the Docs online manual](https://php-qrcode.re - [Quickstart](./Usage-Quickstart.md) - [Advanced usage](./Usage-Advanced-usage.md) +### Built-In Output Modules +- [QREps](./Built-In-Output-QREps.md) +- [QRFpdf](./Built-In-Output-QRFpdf.md) +- [QRGdImage](./Built-In-Output-QRGdImage.md) +- [QRImagick](./Built-In-Output-QRImagick.md) +- [QRMarkupHTML](./Built-In-Output-QRMarkupHTML.md) +- [QRMarkupSVG](./Built-In-Output-QRMarkupSVG.md) +- [QRString](./Built-In-Output-QRString.md) + + ### Public API - [`QRCode`](./API-QRCode.md) @@ -80,7 +90,7 @@ The markdown sources for the [Read the Docs online manual](https://php-qrcode.re ### Appendix -- [Glossary](./Appendix-Glossary.md) +- [Glossary](./Appendix-Terminology.md) - [License](./Appendix-License.rst) diff --git a/docs/Usage-Installation.md b/docs/Usage-Installation.md index dfd54727b..77babb91f 100644 --- a/docs/Usage-Installation.md +++ b/docs/Usage-Installation.md @@ -91,4 +91,4 @@ PSA: [PHP versions < 8.0 are EOL](https://www.php.net/supported-versions.php) an Please follow the installation guides for your operating system: - ImageMagick: [imagemagick.org/script/download.php](https://imagemagick.org/script/download.php) -- PHP `ext-imagick`: [github.com/Imagick/imagick](https://github.com/Imagick/imagick) +- PHP `ext-imagick`: [github.com/Imagick/imagick](https://github.com/Imagick/imagick) ([Windows downloads](https://mlocati.github.io/articles/php-windows-imagick.html)) diff --git a/docs/index.rst b/docs/index.rst index 6cf2ab22d..30ac9ddb3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,25 +12,37 @@ This work is licensed under the Creative Commons Attribution 4.0 International ( :maxdepth: 3 :caption: Usage - Usage-Overview - Usage-Installation - Usage-Quickstart - Usage-Advanced-usage + Usage-Overview.md + Usage-Installation.md + Usage-Quickstart.md + Usage-Advanced-usage.md + +.. toctree:: + :maxdepth: 3 + :caption: Built-In Output Modules + + Built-In-Output-QREps.md + Built-In-Output-QRFpdf.md + Built-In-Output-QRGdImage.md + Built-In-Output-QRImagick.md + Built-In-Output-QRMarkupHTML.md + Built-In-Output-QRMarkupSVG.md + Built-In-Output-QRString.md .. toctree:: :maxdepth: 3 :caption: Public API - API-QRCode - API-QROptions - API-QROutputInterface - API-QRMatrix - API-DecoderResult + API-QRCode.md + API-QROptions.md + API-QROutputInterface.md + API-QRMatrix.md + API-DecoderResult.md .. toctree:: :maxdepth: 3 :caption: Appendix - Appendix-Glossary - Appendix-License + Appendix-Terminology.md + Appendix-License.md