:book:

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,
 ];
 ```
 

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('<img src="%s" alt="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('<img src="%s" alt="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;
+
+```

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

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)
 

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('<img src="%s" alt="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.