geckon01/php-qrcode
1
0
Fork 0
mirror of https://github.com/chillerlan/php-qrcode.git synced 2026-08-17 14:51:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

🛀 doc cleanup

Browse Source
This commit is contained in:
smiley
2023-10-04 17:54:49 +02:00
parent 17733e7269
commit cf0648e24d
18 changed files with 547 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Appendix/Contribute.md
+66
View File
@@ -0,0 +1,66 @@
# How to contribute
## Questions and issues
If you have a question about or a general issue while using this library,
head over to the [discussions section](https://github.com/chillerlan/php-qrcode/discussions),
create a new post and describe your issue as precise as possible, ideally add a code example (if applicable).
Please don't just write "headline says all" because the reply will likely be similarly concise - help me (and others) help you!
(just to clarify: the "general" does not mean general PHP support, in which case you're better off on
[StackOverflow](https://stackoverflow.com/questions/tagged/php) or [/r/PHPhelp](https://www.reddit.com/r/PHPhelp/))
## Bug reports
So you found a bug or the library code is somehow misbehaving? That's great (well, not that great tho). In that case,
please [open a bug report and FILL OUT THE ISSUE TEMPLATE](https://github.com/chillerlan/php-qrcode/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D)
(i have to write that in all caps because nobody actually does it which usually leads to several avoidable follow-up questions that cost both of us precious time).
Below an example of the bug report template (it's not that hard):
**Describe the bug**
A clear and concise description of what the bug is.
**Steps to reproduce the behavior**
- When i do ...
- The code below ...
- Error message: ...
**Code sample**
```php
// your code here
```
**Expected behavior**
A clear and concise description of what you expected to happen.
**Screenshots**
If applicable, add screenshots to help explain your problem.
**Environment (please complete the following information):**
- PHP version/OS: [e.g. 7.4.12, Ubuntu 20.04]
- Library version: [e.g. 4.3.4]
**Additional context**
Add any other useful context about the problem.
## Pull requests and bug fixes
You want to contribute code to fix something or add a feature? Hey that's cool! However, there's a few things to keep in mind:
- Please add a description of what the PR does or fixes and why it should be merged. If you're unsure, [open an issue](https://github.com/chillerlan/php-qrcode/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BENHANCEMENT%5D) before to gather feedback.
- Make sure your branch is up-to-date/even with the upstream branch you're submitting your PR to.
- Please try to adhere to the [*loosely outlined* coding standards](https://github.com/chillerlan/php-qrcode/discussions/60), or, in case you're using [PHPStorm](https://www.jetbrains.com/phpstorm/), make sure you're using [the supplied IDE profile](https://github.com/chillerlan/php-qrcode/tree/main/.idea).
## Documentation
The documentation is a work in progress - any suggestion and contribution is very welcome!
The API documentation is auto generated with [phpDocumentor](https://www.phpdoc.org/) from the docblocks [in the PHP sources](https://github.com/chillerlan/php-qrcode/tree/main/src).
The markdown sources for the [Read the Docs online manual](https://php-qrcode.readthedocs.io) are located in the [/docs directory](https://github.com/chillerlan/php-qrcode/tree/main/docs)
docs/Appendix-License.rst → docs/Appendix/License.rst
View File
docs/Appendix-Terminology.md → docs/Appendix/Terminology.md
View File
docs/Appendix-URI-Content.md → docs/Appendix/URI-Content.md
View File
docs/Built-In-Output-QREps.md → docs/Built-In-Output/QREps.md
View File
docs/Built-In-Output-QRFpdf.md → docs/Built-In-Output/QRFpdf.md
View File
docs/Built-In-Output-QRGdImage.md → docs/Built-In-Output/QRGdImage.md
View File
docs/Built-In-Output-QRImagick.md → docs/Built-In-Output/QRImagick.md
View File
docs/Built-In-Output-QRMarkupHTML.md → docs/Built-In-Output/QRMarkupHTML.md
+1 -1
View File
@@ -3,7 +3,7 @@
[Class `QRMarkupHTML`](https://github.com/chillerlan/php-qrcode/blob/main/src/Output/QRMarkupHTML.php): HTML output
This class is a cheap markup substitute for when SVG is not available or not an option (which was an issue before ca 2012).
As a general rule: if you plan to display the QR Code in a web browser, you should be using the [SVG output](./Built-In-Output-QRMarkupSVG.md).
As a general rule: if you plan to display the QR Code in a web browser, you should be using the [SVG output](../Built-In-Output/QRMarkupSVG.md).
## Example
docs/Built-In-Output-QRMarkupSVG.md → docs/Built-In-Output/QRMarkupSVG.md
View File
docs/Built-In-Output-QRString.md → docs/Built-In-Output/QRString.md
View File
docs/Readme.md
+21 -33
View File
@@ -34,7 +34,8 @@ Follow these steps to create the user manual:
[![pages-build-deployment](https://github.com/chillerlan/php-qrcode/actions/workflows/pages/pages-build-deployment/badge.svg?branch=gh-pages)](https://github.com/chillerlan/php-qrcode/actions/workflows/pages/pages-build-deployment)
The API documentation can be auto generated with [phpDocumentor](https://www.phpdoc.org/).
There is an [online version available](https://chillerlan.github.io/php-qrcode/) via the [`gh-pages` branch](https://github.com/chillerlan/php-qrcode/tree/gh-pages) that is [automatically deployed](https://github.com/chillerlan/php-qrcode/deployments) on each push to main.
There is an [online version available](https://chillerlan.github.io/php-qrcode/) via the [`gh-pages` branch](https://github.com/chillerlan/php-qrcode/tree/gh-pages)
that is [automatically deployed](https://github.com/chillerlan/php-qrcode/deployments) on each push to main.
#### Run phpDocumentor locally
@@ -55,44 +56,31 @@ The markdown sources for the [Read the Docs online manual](https://php-qrcode.re
### Usage
- [Overview](./Usage-Overview.md)
- [Installation](./Usage-Installation.md)
- [Quickstart](./Usage-Quickstart.md)
- [Advanced usage](./Usage-Advanced-usage.md)
- [Overview](./Usage/Overview.md)
- [Installation](./Usage/Installation.md)
- [Quickstart](./Usage/Quickstart.md)
- [Advanced usage](./Usage/Advanced-usage.md)
- [Configuration settings](./Usage/Configuration-settings.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)
<!--
### Customizing output
- [Module values](./Customizing-Module-Values.md)
- [Custom output interface](./Customizing-Custom-output-interface.md)
- [QROutputAbstract](./Customizing-QROutputAbstract.md)
### Examples
- [Built-in Output Interfaces](./Examples-Built-in.md)
-->
### Public API
- [`QRCode`](./API-QRCode.md)
- [`QROptions`](./API-QROptions.md)
- [`QROutputInterface`](./API-QROutputInterface.md)
- [`QRMatrix`](./API-QRMatrix.md)
- [`DecoderResult`](./API-DecoderResult.md)
- [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)
### Appendix
- [Glossary](./Appendix-Appendix-URI-Content.md)
- [Glossary](./Appendix-Terminology.md)
- [License](./Appendix-License.rst)
- [How to contribute](./Appendix/Contribute.md)
- [Terminology](./Appendix/Terminology.md)
- [Popular content and URI schemes](./Appendix/URI-Content.md)
- [License](./Appendix/License.rst)
## License
docs/Usage-Advanced-usage.md → docs/Usage/Advanced-usage.md
+5 -27
View File
@@ -3,6 +3,7 @@
## Configuration via `QROptions`
The [`QROptions`](https://github.com/chillerlan/php-qrcode/blob/main/src/QROptions.php) class is a container based on [chillerlan/php-settings-container](https://github.com/chillerlan/php-settings-container) that behaves similar to a [`\stdClass`](https://www.php.net/manual/class.stdclass) object, but with fixed properties.
A list with all available `QROptions` can be found under [cnfiguration settings](../Usage/Configuration-settings.md).
```php
$options = new QROptions;
@@ -123,21 +124,13 @@ $qrcode->setOptions($options);
### Save to file
Save the QR Code output to `/path/to/qrcode.svg`:
You can specify an output file path in which the QR Code content is stored (this will override the `QROptions::$cachefile`
setting, see [common output options](../Customizing/Common.md#save-to-file)):
```php
$options->outputBase64 = false;
$options->cachefile = '/path/to/qrcode.svg';
$qrcode->render($data, '/path/to/qrcode.svg');
$qrcode->render($data);
```
Alternatively, you can specify an output path, which will override the `QROptions::$cachefile` setting:
```php
$qrcode->render($data, '/other/path/to/qrcode.svg');
printf('<img src="%s" alt="QR Code" />', '/other/path/to/qrcode.svg');
printf('<img src="%s" alt="QR Code" />', '/path/to/qrcode.svg');
```
@@ -158,21 +151,6 @@ $output = $qrcode->renderMatrix($matrix);
$qrcode->renderMatrix($matrix, '/path/to/qrcode.svg');
```
Manual invocation of a `QROutputInterface` to render a `QRMatrix` instance:
```php
class MyCustomOutput extends QRMarkupSVG{
// ...
}
$qrOutputInterface = new MyCustomOutput($options, $matrix);
$output = $qrOutputInterface->dump()
// render to file
$qrOutputInterface->dump('/path/to/qrcode.svg');
```
### Mixed mode
Mixed mode QR Codes can be generated by adding several data segments:
docs/Usage/Configuration-settings.md
+432
View File
@@ -0,0 +1,432 @@
# Configuration settings
<!-- This file is auto generated from the source of QROptionsTrait.php -->
## version
QR Code version number
`1 ... 40` or `Version::AUTO` (default)
**See also:**
- `\chillerlan\QRCode\Common\Version`
## versionMin
Minimum QR version
if `QROptions::$version` is set to `Version::AUTO` (default: 1)
## versionMax
Maximum QR version
if `QROptions::$version` is set to `Version::AUTO` (default: 40)
## eccLevel
Error correct level
`EccLevel::X` where `X` is:
- `L` => 7% (default)
- `M` => 15%
- `Q` => 25%
- `H` => 30%
**See also:**
- `\chillerlan\QRCode\Common\EccLevel`
- [github.com/chillerlan/php-qrcode/discussions/160](https://github.com/chillerlan/php-qrcode/discussions/160)
## maskPattern
Mask Pattern to use (no value in using, mostly for unit testing purposes)
`0 ... 7` or `MaskPattern::PATTERN_AUTO` (default)
**See also:**
- `\chillerlan\QRCode\Common\MaskPattern`
## addQuietzone
Add a "quiet zone" (margin) according to the QR code spec
**See also:**
- [www.qrcode.com/en/howto/code.html](https://www.qrcode.com/en/howto/code.html)
## quietzoneSize
Size of the quiet zone
internally clamped to `0 ... $moduleCount / 2` (default: 4)
## outputType
The built-in output type
- `QROutputInterface::MARKUP_SVG` (default)
- `QROutputInterface::MARKUP_HTML`
- `QROutputInterface::GDIMAGE_BMP`
- `QROutputInterface::GDIMAGE_GIF`
- `QROutputInterface::GDIMAGE_JPG`
- `QROutputInterface::GDIMAGE_PNG`
- `QROutputInterface::GDIMAGE_WEBP`
- `QROutputInterface::STRING_TEXT`
- `QROutputInterface::STRING_JSON`
- `QROutputInterface::IMAGICK`
- `QROutputInterface::EPS`
- `QROutputInterface::FPDF`
- `QROutputInterface::CUSTOM`
**See also:**
- `\chillerlan\QRCode\Output\QREps`
- `\chillerlan\QRCode\Output\QRFpdf`
- `\chillerlan\QRCode\Output\QRGdImage`
- `\chillerlan\QRCode\Output\QRImagick`
- `\chillerlan\QRCode\Output\QRMarkupHTML`
- `\chillerlan\QRCode\Output\QRMarkupSVG`
- `\chillerlan\QRCode\Output\QRString`
## outputInterface
The FQCN of the custom `QROutputInterface`
if `QROptions::$outputType` is set to `QROutputInterface::CUSTOM` (default: `null`)
## returnResource
Return the image resource instead of a render if applicable.
- `QRGdImage`: `resource` (PHP < 8), `GdImage`
- `QRImagick`: `Imagick`
- `QRFpdf`: `FPDF`
This option overrides/ignores other output settings, such as `QROptions::$cachefile`
and `QROptions::$outputBase64`. (default: `false`)
**See also:**
- `\chillerlan\QRCode\Output\QROutputInterface::dump()`
## cachefile
Optional cache file path `/path/to/cache.file`
Please note that the `$file` parameter in `QRCode::render()` and `QRCode::renderMatrix()`
takes precedence over the `QROptions::$cachefile` value. (default: `null`)
**See also:**
- `\chillerlan\QRCode\QRCode::render()`
- `\chillerlan\QRCode\QRCode::renderMatrix()`
## outputBase64
Toggle base64 data URI or raw data output (if applicable)
(default: `true`)
**See also:**
- `\chillerlan\QRCode\Output\QROutputAbstract::toBase64DataURI()`
## eol
Newline string
(default: `PHP_EOL`)
## bgColor
Sets the image background color (if applicable)
- `QRImagick`: defaults to `"white"`
- `QRGdImage`: defaults to `[255, 255, 255]`
- `QRFpdf`: defaults to blank internally (white page)
## invertMatrix
Whether to invert the matrix (reflectance reversal)
(default: `false`)
**See also:**
- `\chillerlan\QRCode\Data\QRMatrix::invert()`
## drawLightModules
Whether to draw the light (false) modules
(default: `true`)
## drawCircularModules
Specify whether to draw the modules as filled circles
a note for `GdImage` output:
if `QROptions::$scale` is less than 20, the image will be upscaled internally, then the modules will be drawn
using `imagefilledellipse()` and then scaled back to the expected size
No effect in: `QREps`, `QRFpdf`, `QRMarkupHTML`
**See also:**
- [php.net: `\imagefilledellipse()`](https://www.php.net/manual/function.imagefilledellipse)
- [github.com/chillerlan/php-qrcode/issues/23](https://github.com/chillerlan/php-qrcode/issues/23)
- [github.com/chillerlan/php-qrcode/discussions/122](https://github.com/chillerlan/php-qrcode/discussions/122)
## circleRadius
Specifies the radius of the modules when `QROptions::$drawCircularModules` is set to `true`
(default: 0.45)
## keepAsSquare
Specifies which module types to exclude when `QROptions::$drawCircularModules` is set to `true`
(default: `[]`)
## connectPaths
Whether to connect the paths for the several module types to avoid weird glitches when using gradients etc.
**See also:**
- [github.com/chillerlan/php-qrcode/issues/57](https://github.com/chillerlan/php-qrcode/issues/57)
## excludeFromConnect
Specify which paths/patterns to exclude from connecting if `QROptions::$connectPaths` is set to `true`
## moduleValues
Module values map
- `QRImagick`, `QRMarkupHTML`, `QRMarkupSVG`: #ABCDEF, cssname, rgb(), rgba()...
- `QREps`, `QRFpdf`, `QRGdImage`: `[R, G, B]` // 0-255
- `QREps`: `[C, M, Y, K]` // 0-255
**See also:**
- `\chillerlan\QRCode\Output\QROutputAbstract::setModuleValues()`
## addLogoSpace
Toggles logo space creation
**See also:**
- `\chillerlan\QRCode\QRCode::addMatrixModifications()`
- `\chillerlan\QRCode\Data\QRMatrix::setLogoSpace()`
## logoSpaceWidth
Width of the logo space
if only `QROptions::$logoSpaceWidth` is given, the logo space is assumed a square of that size
## logoSpaceHeight
Height of the logo space
if only `QROptions::$logoSpaceHeight` is given, the logo space is assumed a square of that size
## logoSpaceStartX
Optional horizontal start position of the logo space (top left corner)
## logoSpaceStartY
Optional vertical start position of the logo space (top left corner)
## scale
Pixel size of a QR code module
## imageTransparent
Toggle transparency
- `QRGdImage` and `QRImagick`: the given `QROptions::$transparencyColor` is set as transparent
**See also:**
- [github.com/chillerlan/php-qrcode/discussions/121](https://github.com/chillerlan/php-qrcode/discussions/121)
## transparencyColor
Sets a transparency color for when `QROptions::$imageTransparent` is set to `true`.
Defaults to `QROptions::$bgColor`.
- `QRGdImage`: `[R, G, B]`, this color is set as transparent in `imagecolortransparent()`
- `QRImagick`: `"color_str"`, this color is set in `Imagick::transparentPaintImage()`
**See also:**
- [php.net: `\imagecolortransparent()`](https://www.php.net/manual/function.imagecolortransparent)
- [php.net: `\Imagick::transparentPaintImage()`](https://www.php.net/manual/imagick.transparentpaintimage)
## quality
Compression quality
The given value depends on the used output type:
- `QROutputInterface::GDIMAGE_BMP`: `[0...1]`
- `QROutputInterface::GDIMAGE_JPG`: `[0...100]`
- `QROutputInterface::GDIMAGE_WEBP`: `[0...9]`
- `QROutputInterface::GDIMAGE_PNG`: `[0...100]`
- `QROutputInterface::IMAGICK`: `[0...100]`
**See also:**
- [php.net: `\imagebmp()`](https://www.php.net/manual/function.imagebmp)
- [php.net: `\imagejpeg()`](https://www.php.net/manual/function.imagejpeg)
- [php.net: `\imagepng()`](https://www.php.net/manual/function.imagepng)
- [php.net: `\imagewebp()`](https://www.php.net/manual/function.imagewebp)
- [php.net: `\Imagick::setImageCompressionQuality()`](https://www.php.net/manual/imagick.setimagecompressionquality)
## imagickFormat
Imagick output format
**See also:**
- [php.net: `\Imagick::setImageFormat()`](https://www.php.net/manual/imagick.setimageformat)
- [www.imagemagick.org/script/formats.php](https://www.imagemagick.org/script/formats.php)
## cssClass
A common css class
## markupDark
Markup substitute for dark (CSS value)
## markupLight
Markup substitute for light (CSS value)
## svgAddXmlHeader
Whether to add an XML header line or not, e.g. to embed the SVG directly in HTML
`<?xml version="1.0" encoding="UTF-8"?>`
## svgOpacity
SVG path opacity
Sets the value for the SVG "fill-opacity" on a `<path>` element. Only in effect when non-empty values
for `QROptions::$markupDark` and `QROptions::$markupLight` are given.
The opacity value is the same for all paths - please use CSS for more sophisticated implementations.
## svgDefs
Anything in the SVG `<defs>` tag
**See also:**
- [developer.mozilla.org/en-US/docs/Web/SVG/Element/defs](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs)
## svgPreserveAspectRatio
Sets the value for the "preserveAspectRatio" on the `<svg>` element
**See also:**
- [developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio)
## textDark
String substitute for dark
## textLight
String substitute for light
## textLineStart
An optional line prefix, e.g. empty space to align the QR Code in a console
## jsonAsBooleans
Whether to return matrix values in JSON as booleans or `$M_TYPE` integers
## fpdfMeasureUnit
Measurement unit for `FPDF` output: pt, mm, cm, in (defaults to "pt")
**See also:**
- `FPDF::__construct()`
## readerUseImagickIfAvailable
Use Imagick (if available) when reading QR Codes
## readerGrayscale
Grayscale the image before reading
## readerIncreaseContrast
Increase the contrast before reading
note that applying contrast works different in GD and Imagick, so mileage may vary
docs/Usage-Installation.md → docs/Usage/Installation.md
View File
docs/Usage-Overview.md → docs/Usage/Overview.md
View File
docs/Usage-Quickstart.md → docs/Usage/Quickstart.md
+1 -1
View File
@@ -35,7 +35,7 @@ header('Content-type: image/svg+xml'); // the image type is SVG by default
echo (new QRCode($options))->render($data);
```
See [Advanced usage](./Usage-Advanced-usage.md) for a more in-depth usage guide.
See [Advanced usage](../Usage/Advanced-usage.md) for a more in-depth usage guide.
Also, have a look [in the examples folder](https://github.com/chillerlan/php-qrcode/tree/main/examples) for some more usage examples.
docs/index.rst
+21 -25
View File
@@ -1,10 +1,14 @@
.. php-qrcode documentation master file, created by sphinx-quickstart on Sun Jul 9 21:45:56 2023.
markdown-rst converter: https://pandoc.org/try/
=================
PHP-QRCode Manual
=================
Edition for `chillerlan/php-qrcode <https://github.com/chillerlan/php-qrcode/>`__ [|version|]. Updated on |today|.
User manual for `chillerlan/php-qrcode <https://github.com/chillerlan/php-qrcode/>`__ [|version|]. Updated on |today|.
The phpDocumentor API documentation can be found at `chillerlan.github.io/php-qrcode <https://chillerlan.github.io/php-qrcode/>`__.
This work is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.
@@ -12,38 +16,30 @@ This work is licensed under the Creative Commons Attribution 4.0 International (
:maxdepth: 3
:caption: Usage
Usage-Overview.md
Usage-Installation.md
Usage-Quickstart.md
Usage-Advanced-usage.md
Usage/Overview.md
Usage/Installation.md
Usage/Quickstart.md
Usage/Advanced-usage.md
Usage/Configuration-settings.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.md
API-QROptions.md
API-QROutputInterface.md
API-QRMatrix.md
API-DecoderResult.md
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: Appendix
Appendix-Terminology.md
Appendix-URI-Content.md
Appendix-License.md
Appendix/Contribute.md
Appendix/Terminology.md
Appendix/URI-Content.md
Appendix/License.md