diff --git a/docs/Customizing/Module-Values.md b/docs/Customizing/Module-Values.md index d25de444e..c758434b4 100644 --- a/docs/Customizing/Module-Values.md +++ b/docs/Customizing/Module-Values.md @@ -2,9 +2,10 @@ ## Basics -The QR Code matrix is a 2-dimensional array of numerical values that hold a bit mask for +The QR Code matrix is a 2-dimensional array of numerical values that hold a bitmask for each QR pixel ("module" as per specification), the so-called "module type" or `$M_TYPE`, which is represented by [the `QRMatrix::M_*` constants](https://chillerlan.github.io/php-qrcode/classes/chillerlan-QRCode-Data-QRMatrix.html#toc-constants). +The bitmask is 12 bits wide; the first 11 bits stand for the pattern type, the highest bit designates whether the module is dark or light. You can assign different values for the several [function patterns](../Appendix/Terminology.md#function-patterns) to colorize them or even draw pixel-art. @@ -14,13 +15,14 @@ To map the values and properly render the modules for the given `QROutputInterfa [default values](https://chillerlan.github.io/php-qrcode/classes/chillerlan-QRCode-Output-QROutputInterface.html#constant_DEFAULT_MODULE_VALUES), that are replaced by the user defined values in `QROptions::$moduleValues` during the render process. -The map of `QRMatrix::M_*` constants => default values looks similar to the following: +The map of `QRMatrix::M_*` constants => default values looks similar to the following +(values with "_DARK" and "_LIGHT" suffix are for convenience): ```php $options->moduleValues = [ // light - QRMatrix::M_NULL => false, - QRMatrix::M_DARKMODULE_LIGHT => false, + QRMatrix::M_NULL => false, // special value - always 0 + QRMatrix::M_DARKMODULE_LIGHT => false, // key equivalent to (QRMatrix::M_DARKMODULE & ~QRMatrix::IS_DARK) QRMatrix::M_DATA => false, QRMatrix::M_FINDER => false, QRMatrix::M_SEPARATOR => false, @@ -31,10 +33,9 @@ $options->moduleValues = [ QRMatrix::M_QUIETZONE => false, QRMatrix::M_LOGO => false, QRMatrix::M_FINDER_DOT_LIGHT => false, - QRMatrix::M_TEST => false, // dark QRMatrix::M_DARKMODULE => true, - QRMatrix::M_DATA_DARK => true, + QRMatrix::M_DATA_DARK => true, // key equivalent to (QRMatrix::M_DATA | QRMatrix::IS_DARK) QRMatrix::M_FINDER_DARK => true, QRMatrix::M_SEPARATOR_DARK => true, QRMatrix::M_ALIGNMENT_DARK => true, @@ -44,7 +45,6 @@ $options->moduleValues = [ QRMatrix::M_QUIETZONE_DARK => true, QRMatrix::M_LOGO_DARK => true, QRMatrix::M_FINDER_DOT => true, - QRMatrix::M_TEST_DARK => true, ]; ``` diff --git a/docs/Usage/Advanced-usage.md b/docs/Usage/Advanced-usage.md index 725bf9c41..07122d0ed 100644 --- a/docs/Usage/Advanced-usage.md +++ b/docs/Usage/Advanced-usage.md @@ -39,7 +39,7 @@ $options->fromIterable($myOptions); ``` -### Load and save JSON +### Load and save options from/to JSON The settings can be saved to and loaded from JSON, e.g. to store them in a database: @@ -122,18 +122,6 @@ $qrcode->setOptions($options); ``` -### Save to file - -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 -$qrcode->render($data, '/path/to/qrcode.svg'); - -printf('QR Code', '/path/to/qrcode.svg'); -``` - - ### Render a `QRMatrix` instance You can render a [`QRMatrix`](https://github.com/chillerlan/php-qrcode/blob/main/src/Data/QRMatrix.php) instance directly: @@ -151,6 +139,7 @@ $output = $qrcode->renderMatrix($matrix); $qrcode->renderMatrix($matrix, '/path/to/qrcode.svg'); ``` + ### Mixed mode Mixed mode QR Codes can be generated by adding several data segments: @@ -199,7 +188,10 @@ $options->readerUseImagickIfAvailable = true; $options->readerIncreaseContrast = true; $options->readerGrayscale = true; -$result = (new QRCode($options))->readFromFile('path/to/qrcode.png'); +$qrcode = new QRCode($options); + +$result = $qrcode->readFromFile('path/to/qrcode.png'); +$result = $qrcode->readFromBlob($imagedata); ``` The `QRMatrix` object from the [`DecoderResult`](https://github.com/chillerlan/php-qrcode/blob/main/src/Decoder/DecoderResult.php) can be reused: @@ -213,3 +205,71 @@ $output = (new QRCode($options))->renderMatrix($matrix); // ...output ``` + +## Common output options + +### Save to file + +You can specify an output file path in which the QR Code content is stored: + +```php +$options->outputBase64 = false; +$options->cachefile = '/path/to/qrcode.svg'; + +$qrcode->render($data); + +printf('QR Code', $options->cachefile); +``` + +The file path can also be supplied as second parameter to the render methods (this will override the `QROptions::$cachefile` setting): + +```php +$qrcode->render($data, '/path/to/qrcode.svg'); +``` + + +### Base64 URI output + +By default, a [Base64 encoded data URI](https://en.wikipedia.org/wiki/Data_URI_scheme) will be returned (where applicable): + +```php +echo $qrcode->render($data); // -> data:image/png;base64,... +``` + +Disable Base64 output: + +```php +$options->outputBase64 = false; + +header('Content-type: image/png'); + +echo $qrcode->render($data); +``` + + +### Return the image resource + +In some cases you might want to modify the QR image after creation (without crating a custom output class), in which case you want the internal image resource rather than the final output. + +```php +$options->outputType = QROutputInterface::IMAGICK; +$options->returnResource = true; + +/** @var Imagick $imagick */ +$imagick = $qrcode->render($data); + +echo $imagick->getImageBlob(); +``` + + +### Add a logo space + + +```php +$options->addLogoSpace = true; +$options->logoSpaceWidth = 9; +$options->logoSpaceHeight = 9; +$options->logoSpaceStartX = 10; +$options->logoSpaceStartY = 10; + +``` diff --git a/docs/Usage/Installation.md b/docs/Usage/Installation.md index 77babb91f..e311719aa 100644 --- a/docs/Usage/Installation.md +++ b/docs/Usage/Installation.md @@ -42,12 +42,16 @@ Most of the v2.0 API remains unchanged throughout the several versions up to v5. To install `php-qrcode` on the terminal, use: -`composer require chillerlan/php-qrcode` +```shell +composer require chillerlan/php-qrcode +``` If you want to install the package from a specific tag or commit, do as follows: -- `composer require chillerlan/php-qrcode:4.3.4` -- `composer require chillerlan/php-qrcode:dev-main#f15b0afe9d4128bf734c3bf1bcffae72bf7b3e53` +```shell +composer require chillerlan/php-qrcode:4.3.4 +composer require chillerlan/php-qrcode:dev-main#f15b0afe9d4128bf734c3bf1bcffae72bf7b3e53 +``` ## Manual installation diff --git a/docs/Usage/Overview.md b/docs/Usage/Overview.md index cbce5bdc4..c763d4878 100644 --- a/docs/Usage/Overview.md +++ b/docs/Usage/Overview.md @@ -59,6 +59,7 @@ For the QR Code reader, either `ext-gd` or `ext-imagick` is required! - [openITCOCKPIT](https://github.com/it-novum/openITCOCKPIT) - [twill](https://github.com/area17/twill) - [Elefant CMS](https://github.com/jbroadway/elefant) + - [OSIRIS](https://github.com/JKoblitz/osiris) - Articles: - [Twilio: How to Create a QR Code in PHP](https://www.twilio.com/blog/create-qr-code-in-php) (featuring v4.3.x) diff --git a/docs/Usage/Quickstart.md b/docs/Usage/Quickstart.md index 10c2ff7fb..b85f911ef 100644 --- a/docs/Usage/Quickstart.md +++ b/docs/Usage/Quickstart.md @@ -17,6 +17,7 @@ We want to encode this URI for a mobile authenticator into a QRcode image: $data = 'otpauth://totp/test?secret=B3JX4VCVJDVNXNZ5&issuer=chillerlan.net'; $qrcode = (new QRCode)->render($data); +// default output is a base64 encoded data URI printf('QR Code', $qrcode); ``` @@ -35,7 +36,8 @@ 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 +and [configuration settings](../Usage/Configuration-settings.md) for a list of available options. Also, have a look [in the examples folder](https://github.com/chillerlan/php-qrcode/tree/main/examples) for some more usage examples. @@ -45,17 +47,16 @@ Using the built-in QR Code reader is pretty straight-forward: ```php try{ $result = (new QRCode)->readFromFile('path/to/file.png'); // -> DecoderResult + + // you can now use the result instance... + $content = $result->data; + + // ...or simply cast the result instance to string to get the content + $content = (string)$result; } catch(Throwable $exception){ // handle exception... - // throw ... } - -// you can now use the result instance... -$content = $result->data; - -// ...or simply cast the result instance to string to get the content -$content = (string)$result; ``` It's generally a good idea to wrap the reading in a try/catch block to handle any errors that may occur in the process.