:book: docs

docs/API-QROptions.md

@@ -57,8 +57,7 @@ Inherited from [`SettingsContainerAbstract`](https://github.com/chillerlan/php-s
 | `$scale`                       | `int`          | `5`                             | *                                       | Pixel size of a QR code module                                                                                                                                                          |
 | `$imageTransparent`            | `bool`         | `true`                          | *                                       | Toggle transparency (no jpeg support), QRGdImage and QRImagick only. The given `QROptions::$transparencyColor` is set as transparent                                                    |
 | `$transparencyColor`           | `mixed`        | `null`                          | a valid GD or Imagick color value       | Sets a transparency color for when `QROptions::$imageTransparent` is set to true. Defaults to `QROptions::$bgColor`.                                                                    |
-| `$pngCompression`              | `int`          | `-1`                            | `-1...9`                                | `imagepng()` compression level, -1 = auto                                                                                                                                               |
-| `$jpegQuality`                 | `int`          | `85`                            | `0...100`                               | `imagejpeg()` quality                                                                                                                                                                   |
+| `$quality`                     | `int`          | `-1`                            | *                                       | compression quality setting for `imagejpeg()`, `imagepng()`, `imagewebp()`, `Imagick::setImageCompressionQuality()`                                                                     |
 | `$imagickFormat`               | `string`       | `'png'`                         | *                                       | ImageMagick output type, see `Imagick::setType()`                                                                                                                                       |
 | `$cssClass`                    | `string`       | `'qrcode'`                      | *                                       | A common css class                                                                                                                                                                      |
 | `$markupDark`                  | `string`       | `'#000'`                        | *                                       | Markup substitute for dark (CSS value)                                                                                                                                                  |

docs/Built-In-Output-QREps.md

@@ -1,26 +1,81 @@
 # 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
+[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.
+
+
+## Example
+
+See: [EPS example](https://github.com/chillerlan/php-qrcode/blob/main/examples/eps.php)
+
+Set the options:
+
+```php
+$options = new QROptions;
+
+$options->outputType       = QROutputInterface::EPS;
+$options->scale            = 5;
+$options->drawLightModules = false;
+// colors can be specified either as [R, G, B] or [C, M, Y, K] (0-255)
+$options->bgColor          = [222, 222, 222];
+$options->moduleValues     = [
+	QRMatrix::M_FINDER_DARK    => [0, 63, 255],    // dark (true)
+	QRMatrix::M_FINDER_DOT     => [0, 63, 255],    // finder dot, dark (true)
+	QRMatrix::M_FINDER         => [233, 233, 233], // light (false)
+	QRMatrix::M_ALIGNMENT_DARK => [255, 0, 255],
+	QRMatrix::M_ALIGNMENT      => [233, 233, 233],
+	QRMatrix::M_DATA_DARK      => [0, 0, 0],
+	QRMatrix::M_DATA           => [233, 233, 233],
+];
+```
+
+
+Render and save to file:
+
+```php
+$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
+$file = __DIR__.'/qrcode.eps';
+
+(new QRCode($options))->render($data, $file);
+```
+
+
+Push as file download in a browser:
+
+```php
+header('Content-type: application/postscript');
+header('Content-Disposition: filename="qrcode.eps"');
+
+echo (new QRCode($options))->render($data);
+
+exit;
+```
+
+## Additional methods
+
+| method                                            | return   | description                                |
+|---------------------------------------------------|----------|--------------------------------------------|
+| (protected) `formatColor(array $values)`          | `string` | Set the color format string                |
+| (protected) `module(int $x, int $y, int $M_TYPE)` | `string` | Returns a path segment for a single module |
 
 
 ## Options that affect this module
 
-| property                       | type           |
-|--------------------------------|----------------|
-| `$drawLightModules`            | `bool`         |
-| `$connectPaths`                | `bool`         |
-| `$excludeFromConnect`          | `array`        |
-| `$scale`                       | `int`          |
+| property              | type    |
+|-----------------------|---------|
+| `$bgColor`            | `array` |
+| `$connectPaths`       | `bool`  |
+| `$drawLightModules`   | `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 |
+| `$drawCircularModules` | not implemented |
+| `$outputBase64`        | N/A             |
 | `$imageTransparent`    | N/A             |
+| `$keepAsSquare`        | not implemented |
+| `$returnResource`      | N/A             |

docs/Built-In-Output-QRFpdf.md

@@ -3,27 +3,86 @@
 [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
+## Example
 
-| property                       | type           |
-|--------------------------------|----------------|
-| `$returnResource`              | `bool`         |
-| `$imageBase64`                 | `bool`         |
-| `$bgColor`                     | `mixed`        |
-| `$drawLightModules`            | `bool`         |
-| `$fpdfMeasureUnit`             | `string`       |
+See: [FPDF example](https://github.com/chillerlan/php-qrcode/blob/main/examples/fpdf.php)
 
+Set the options:
 
-### Options that have no effect
+```php
+$options = new QROptions;
+
+$options->outputType       = QROutputInterface::FPDF;
+$options->scale            = 5;
+$options->fpdfMeasureUnit  = 'mm'; // pt, mm, cm, in
+$options->bgColor          = [222, 222, 222]; // [R, G, B]
+$options->drawLightModules = false;
+$options->moduleValues     = [
+	QRMatrix::M_FINDER_DARK    => [0, 63, 255],    // dark (true)
+	QRMatrix::M_FINDER_DOT     => [0, 63, 255],    // finder dot, dark (true)
+	QRMatrix::M_FINDER         => [255, 255, 255], // light (false)
+	QRMatrix::M_ALIGNMENT_DARK => [255, 0, 255],
+	QRMatrix::M_ALIGNMENT      => [255, 255, 255],
+	QRMatrix::M_DATA_DARK      => [0, 0, 0],
+	QRMatrix::M_DATA           => [255, 255, 255],
+];
+```
+
+
+Render the output:
+
+```php
+$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
+$out  = (new QRCode($options))->render($data); // -> data:application/pdf;base64,...
+
+echo $out;
+```
+
+
+Return the `FPDF` instance (will ignore other output options):
+
+```php
+$options->returnResource = true;
+
+/** @var \FPDF $fpdf */
+$fpdf = (new QRCode($options))->render($data);
 
-| property               | reason          |
-|------------------------|-----------------|
-| `$drawCircularModules` | N/A             |
-| `$circleRadius`        | N/A             |
-| `$keepAsSquare`        | N/A             |
-| `$connectPaths`        | N/A             |
-| `$excludeFromConnect`  | N/A             |
-| `$scale`               | not implemented |
-| `$imageTransparent`    | N/A             |
+// do stuff with the FPDF instance...
 
+// ...dump output
+header('application/pdf');
+
+echo $fpdf->Output('S');
+```
+
+
+## Additional methods
+
+| method                                            | return | description                  |
+|---------------------------------------------------|--------|------------------------------|
+| (protected) `initFPDF()`                          | `FPDF` | Initializes an FPDF instance |
+| (protected) `module(int $x, int $y, int $M_TYPE)` | `void` | Renders a single module      |
+
+
+## Options that affect this module
+
+| property            | type     |
+|---------------------|----------|
+| `$bgColor`          | `array`  |
+| `$drawLightModules` | `bool`   |
+| `$fpdfMeasureUnit`  | `string` |
+| `$outputBase64`     | `bool`   |
+| `$returnResource`   | `bool`   |
+| `$scale`            | `ìnt`    |
+
+
+### Options that have no effect
 
+| property               | reason |
+|------------------------|--------|
+| `$circleRadius`        | N/A    |
+| `$connectPaths`        | N/A    |
+| `$drawCircularModules` | N/A    |
+| `$excludeFromConnect`  | N/A    |
+| `$imageTransparent`    | N/A    |
+| `$keepAsSquare`        | N/A    |

docs/Built-In-Output-QRGdImage.md

@@ -3,27 +3,104 @@
 [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)
 
 
+## Example
+
+See: [GdImage example](https://github.com/chillerlan/php-qrcode/blob/main/examples/image.php)
+
+Set the options:
+```php
+$options = new QROptions;
+
+// $outputType can be one of: GDIMAGE_BMP, GDIMAGE_GIF, GDIMAGE_JPG, GDIMAGE_PNG, GDIMAGE_WEBP
+$options->outputType          = QROutputInterface::GDIMAGE_WEBP;
+$options->quality             = 90;
+// the size of one qr module in pixels
+$options->scale               = 20;
+$options->bgColor             = [200, 150, 200];
+$options->imageTransparent    = true;
+// the color that will be set transparent
+// @see https://www.php.net/manual/en/function.imagecolortransparent
+$options->transparencyColor   = [200, 150, 200];
+$options->drawCircularModules = true;
+$options->drawLightModules    = true;
+$options->circleRadius        = 0.4;
+$options->keepAsSquare        = [
+	QRMatrix::M_FINDER_DARK,
+	QRMatrix::M_FINDER_DOT,
+	QRMatrix::M_ALIGNMENT_DARK,
+];
+$options->moduleValues        = [
+	QRMatrix::M_FINDER_DARK    => [0, 63, 255], // dark (true)
+	QRMatrix::M_FINDER_DOT     => [0, 63, 255], // finder dot, dark (true)
+	QRMatrix::M_FINDER         => [233, 233, 233], // light (false)
+	QRMatrix::M_ALIGNMENT_DARK => [255, 0, 255],
+	QRMatrix::M_ALIGNMENT      => [233, 233, 233],
+	QRMatrix::M_DATA_DARK      => [0, 0, 0],
+	QRMatrix::M_DATA           => [233, 233, 233],
+];
+```
+
+Render the output:
+
+```php
+$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
+$out  = (new QRCode($options))->render($data); // -> data:image/webp;base64,...
+
+printf('<img alt="%s" src="%s" />', $alt, $out);
+```
+
+
+Return the `GdImage` instance/resource (will ignore other output options):
+
+```php
+$options->returnResource = true;
+
+/** @var \GdImage|resource $gdImage */
+$gdImage = (new QRCode($options))->render($data);
+
+// do stuff with the GdImage instance...
+$size = imagesx($gdImage);
+// ...
+
+// ...dump output
+header('Content-type: image/jpeg');
+
+imagejpeg($gdImage);
+imagedestroy($gdImage);
+```
+
+
+## Additional methods
+
+| method                                            | return   | description                                                       |
+|---------------------------------------------------|----------|-------------------------------------------------------------------|
+| (protected) `drawImage()`                         | `void`   | Draws the QR image                                                |
+| (protected) `dumpImage()`                         | `string` | Creates the final image by calling the desired GD output function |
+| (protected) `module(int $x, int $y, int $M_TYPE)` | `void`   | Renders a single module                                           |
+| (protected) `setBgColor()`                        | `void`   | Sets the background color                                         |
+| (protected) `setTransparencyColor()`              | `void`   | Sets the transparency color                                       |
+
+
 ## 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`          |
+| property               | type           |
+|------------------------|----------------|
+| `$bgColor`             | `mixed`        |
+| `$circleRadius`        | `float`        |
+| `$drawCircularModules` | `bool`         |
+| `$drawLightModules`    | `bool`         |
+| `$imageTransparent`    | `bool`         |
+| `$quality`             | `int`          |
+| `$keepAsSquare`        | `array`        |
+| `$outputBase64`        | `bool`         |
+| `$returnResource`      | `bool`         |
+| `$scale`               | `int`          |
+| `$transparencyColor`   | `mixed`        |
 
 
 ### Options that have no effect
 
-| property                       | reason |
-|--------------------------------|--------|
-| `$connectPaths`                | N/A    |
-| `$excludeFromConnect`          | N/A    |
+| property              | reason |
+|-----------------------|--------|
+| `$connectPaths`       | N/A    |
+| `$excludeFromConnect` | N/A    |

docs/Built-In-Output-QRImagick.md

@@ -9,28 +9,103 @@ Please follow the installation guides for your operating system:
 - [PHP Imagick by Example](https://phpimagick.com/) ([github.com/Imagick/ImagickDemos](https://github.com/Imagick/ImagickDemos))
 
 
+## Example
+
+See: [ImageMagick example](https://github.com/chillerlan/php-qrcode/blob/main/examples/imagick.php)
+
+Set the options:
+```php
+$options = new QROptions;
+
+$options->outputType          = QROutputInterface::IMAGICK;
+$options->imagickFormat       = 'webp'; // e.g. png32, jpeg, webp
+$options->quality             = 90;
+$options->scale               = 20;
+$options->bgColor             = '#ccccaa';
+$options->imageTransparent    = true;
+$options->transparencyColor   = '#ccccaa';
+$options->drawLightModules    = true;
+$options->drawCircularModules = true;
+$options->circleRadius        = 0.4;
+$options->keepAsSquare        = [
+	QRMatrix::M_FINDER_DARK,
+	QRMatrix::M_FINDER_DOT,
+	QRMatrix::M_ALIGNMENT_DARK,
+];
+$options->moduleValues        = [
+	QRMatrix::M_FINDER_DARK    => '#A71111', // dark (true)
+	QRMatrix::M_FINDER_DOT     => '#A71111', // finder dot, dark (true)
+	QRMatrix::M_FINDER         => '#FFBFBF', // light (false)
+	QRMatrix::M_ALIGNMENT_DARK => '#A70364',
+	QRMatrix::M_ALIGNMENT      => '#FFC9C9',
+	QRMatrix::M_VERSION_DARK   => '#650098',
+	QRMatrix::M_VERSION        => '#E0B8FF',
+];
+```
+
+
+Render the output:
+
+```php
+$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
+$out  = (new QRCode($options))->render($data); // -> data:image/webp;base64,...
+
+printf('<img alt="%s" src="%s" />', $alt, $out);
+```
+
+
+Return the `Imagick` instance (will ignore other output options):
+
+```php
+$options->returnResource = true;
+
+/** @var \Imagick $imagick */
+$imagick = (new QRCode($options))->render($data);
+
+// do stuff with the Imagick instance...
+$imagick->scaleImage(150, 150, true);
+// ...
+
+// ...dump output
+$imagick->setImageFormat('png32');
+
+header('Content-type: image/png');
+
+echo $imagick->getImageBlob();
+```
+
+
+## Additional methods
+
+| method                               | return | description                                |
+|--------------------------------------|--------|--------------------------------------------|
+| (protected) `drawImage()`            | `void` | Creates the QR image via ImagickDraw       |
+| (protected) `module()`               | `void` | Draws a single pixel at the given position |
+| (protected) `setBgColor()`           | `void` | Sets the background color                  |
+| (protected) `setTransparencyColor()` | `void` | Sets the transparency color                |
+
+
 ## 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`       |
+| property               | type     |
+|------------------------|----------|
+| `$bgColor`             | `mixed`  |
+| `$circleRadius`        | `float`  |
+| `$drawCircularModules` | `bool`   |
+| `$drawLightModules`    | `bool`   |
+| `$imageTransparent`    | `bool`   |
+| `$imagickFormat`       | `string` |
+| `$keepAsSquare`        | `array`  |
+| `$outputBase64`        | `bool`   |
+| `$quality`             | `int`    |
+| `$returnResource`      | `bool`   |
+| `$scale`               | `int`    |
+| `$transparencyColor`   | `mixed`  |
 
 
 ### Options that have no effect
 
-| property                       | reason            |
-|--------------------------------|-------------------|
-| `$connectPaths`                | N/A               |
-| `$excludeFromConnect`          | N/A               |
-| `$pngCompression`              | GdImage exclusive |
-| `$jpegQuality`                 | GdImage exclusive |
+| property              | reason            |
+|-----------------------|-------------------|
+| `$connectPaths`       | N/A               |
+| `$excludeFromConnect` | N/A               |

docs/Built-In-Output-QRMarkupHTML.md

@@ -1,29 +1,109 @@
 # 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)
+[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).
+
+
+## Example
+
+See: [HTML example](https://github.com/chillerlan/php-qrcode/blob/main/examples/html.php)
+
+Set the options:
+
+```php
+$options = new QROptions;
+
+$options->outputType   = QROutputInterface::MARKUP_HTML;
+$options->cssClass     = 'qrcode';
+// default values for unassigned module types
+$options->markupDark   = '#555';
+$options->markupLight  = '#CCC';
+$options->moduleValues = [
+	// finder
+	QRMatrix::M_FINDER_DARK    => '#A71111', // dark (true)
+	QRMatrix::M_FINDER_DOT     => '#A71111', // finder dot, dark (true)
+	QRMatrix::M_FINDER         => '#FFBFBF', // light (false)
+	// alignment
+	QRMatrix::M_ALIGNMENT_DARK => '#A70364',
+	QRMatrix::M_ALIGNMENT      => '#FFC9C9',
+];
+```
+
+Output in a HTML document (via PHP):
+
+```php
+<?php
+
+$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
+$out  = (new QRCode($options))->render($data);
+
+header('Content-type: text/html');
+
+?>
+<!DOCTYPE html>
+<html lang="none">
+<head>
+	<meta charset="UTF-8"/>
+	<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+	<title>QRCode HTML Example</title>
+	<style>
+		div.qrcode{
+			margin: 1em;
+		}
+
+		/* rows */
+		div.qrcode > div {
+			height: 10px;
+		}
+
+		/* modules */
+		div.qrcode > div > span {
+			display: inline-block;
+			width: 10px;
+			height: 10px;
+		}
+	</style>
+</head>
+<body>
+<!-- php poutput -->
+<?php echo $out; ?>
+</body>
+</html>
+```
+
+
+## Additional methods
+
+| method                                       | return   | description                                                             |
+|----------------------------------------------|----------|-------------------------------------------------------------------------|
+| (protected) `createMarkup(bool $saveToFile)` | `string` | Returns the fully parsed and rendered markup string for the given input |
+| (protected) `getCssClass(int $M_TYPE = 0)`   | `string` | Returns a string with all css classes for the current element           |
+
 
 ## Options that affect this module
 
-| property                       | type           |
-|--------------------------------|----------------|
-| `$eol`                         | `string`       |
-| `$cssClass`                    | `string`       |
-| `$markupDark`                  | `string`       |
-| `$markupLight`                 | `string`       |
+| property       | type     |
+|----------------|----------|
+| `$cssClass`    | `string` |
+| `$eol`         | `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     |
+| property               | reason  |
+|------------------------|---------|
+| `$bgColor`             | via CSS |
+| `$circleRadius`        | N/A     |
+| `$connectPaths`        | N/A     |
+| `$drawCircularModules` | N/A     |
+| `$drawLightModules`    | N/A     |
+| `$excludeFromConnect`  | N/A     |
+| `$imageTransparent`    | N/A     |
+| `$keepAsSquare`        | N/A     |
+| `$outputBase64`        | N/A     |
+| `$returnResource`      | N/A     |
+| `$scale`               | via CSS |

docs/Built-In-Output-QRMarkupSVG.md

@@ -2,35 +2,103 @@
 
 [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
 
+## Example
+
+See: [ImageMagick example](https://github.com/chillerlan/php-qrcode/blob/main/examples/imagick.php)
+
+Set the options:
+
+```php
+$options = new QROptions;
+
+$options->version             = 7;
+$options->outputType          = QROutputInterface::MARKUP_SVG;
+// if set to false, the light modules won't be rendered
+$options->drawLightModules    = true;
+// empty the default value to remove the fill* and opacity* attributes from the <path> elements
+$options->markupDark          = '';
+$options->markupLight         = '';
+// draw the modules as circles isntead of squares
+$options->drawCircularModules = true;
+$options->circleRadius        = 0.4;
+// connect paths to avoid render glitches
+// @see https://github.com/chillerlan/php-qrcode/issues/57
+$options->connectPaths        = true;
+// keep modules of these types as square
+$options->keepAsSquare        = [
+	QRMatrix::M_FINDER_DARK,
+	QRMatrix::M_FINDER_DOT,
+	QRMatrix::M_ALIGNMENT_DARK,
+];
+// add a gradient via the <defs> element
+// @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs
+// @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient
+$options->svgDefs             = '
+	<linearGradient id="rainbow" x1="1" y2="1">
+		<stop stop-color="#e2453c" offset="0"/>
+		<stop stop-color="#e07e39" offset="0.2"/>
+		<stop stop-color="#e5d667" offset="0.4"/>
+		<stop stop-color="#51b95b" offset="0.6"/>
+		<stop stop-color="#1e72b7" offset="0.8"/>
+		<stop stop-color="#6f5ba7" offset="1"/>
+	</linearGradient>
+	<style><![CDATA[
+		.dark{fill: url(#rainbow);}
+		.light{fill: #eee;}
+	]]></style>';
+```
+
+
+Render the output:
+
+```php
+$data = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
+$out  = (new QRCode($options))->render($data); // -> data:image/svg+xml;base64,PD94bWwgdmVyc2...
+
+printf('<img alt="%s" src="%s" />', $alt, $out);
+```
+
+
+## Additional methods
+
+| method                                            | return   | description                                                   |
+|---------------------------------------------------|----------|---------------------------------------------------------------|
+| (protected) `getCssClass(int $M_TYPE = 0)`        | `string` | returns a string with all css classes for the current element |
+| (protected) `header()`                            | `string` | returns the `<svg>` header with the given options parsed      |
+| (protected) `module(int $x, int $y, int $M_TYPE)` | `string` | returns a path segment for a single module                    |
+| (protected) `path(string $path, int $M_TYPE)`     | `string` | renders and returns a single `<path>` element                 |
+| (protected) `paths()`                             | `string` | returns one or more SVG `<path>` elements                     |
+
+
 ## 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` |
+| property                  | type           |
+|---------------------------|----------------|
+| `$circleRadius`           | `float`        |
+| `$connectPaths`           | `bool`         |
+| `$cssClass`               | `string`       |
+| `$drawCircularModules`    | `bool`         |
+| `$drawLightModules`       | `bool`         |
+| `$eol`                    | `string`       |
+| `$excludeFromConnect`     | `array`        |
+| `$keepAsSquare`           | `array`        |
+| `$markupDark`             | `string`       |
+| `$markupLight`            | `string`       |
+| `$outputBase64`           | `bool`         |
+| `$svgAddXmlHeader`        | `bool`         |
+| `$svgDefs`                | `string`       |
+| `$svgHeight`              | `string\|null` |
+| `$svgOpacity`             | `float`        |
+| `$svgPreserveAspectRatio` | `string`       |
+| `$svgViewBoxSize`         | `int\|null`    |
+| `$svgWidth`               | `string\|null` |
 
 
 ### Options that have no effect
 
-| property            | reason                                                                                                                                                                                                |
-|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `$returnResource`   | N/A                                                                                                                                                                                                   |
-| `$bgColor`          | background color can be achieved via CSS, `<defs>` 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                                                                                                                                                                         |
+| property            | reason                                                                                                                                                                                                            |
+|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `$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) |
+| `$imageTransparent` | SVG is - similar to a HTML element - transparent by default                                                                                                                                                       |
+| `$returnResource`   | N/A                                                                                                                                                                                                               |
+| `$scale`            | `$scale` (pixel size of a qr module) is intended for raster image types, use `$svgViewBoxSize` instead                                                                                                            |

docs/Built-In-Output-QRString.md

@@ -2,28 +2,97 @@
 
 [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)
 
+## Plain text
+
+Render in a CLI console, using [ANSI colors](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) and [block elements](https://en.wikipedia.org/wiki/Block_Elements):
+
+```php
+// a little helper to a create proper ANSI 8-bit color escape sequence
+function ansi8(string $str, int $color, bool $background = false):string{
+	$color      = max(0, min($color, 255));
+	$background = ($background ? 48 : 38);
+
+	return sprintf("\x1b[%s;5;%sm%s\x1b[0m", $background, $color, $str);
+}
+
+$options = new QROptions;
+
+$options->outputType     = QROutputInterface::STRING_TEXT;
+$options->eol            = "\n";
+// add some space on the line start
+$options->textLineStart  = str_repeat(' ', 6);
+// default values for unassigned module types
+$options->textDark       = QRString::ansi8('██', 253);
+$options->textLight      = QRString::ansi8('░░', 253);
+$options->moduleValues   = [
+	QRMatrix::M_FINDER_DARK    => QRString::ansi8('██', 124),
+	QRMatrix::M_FINDER         => QRString::ansi8('░░', 124),
+	QRMatrix::M_FINDER_DOT     => QRString::ansi8('██', 124),
+	QRMatrix::M_ALIGNMENT_DARK => QRString::ansi8('██', 2),
+	QRMatrix::M_ALIGNMENT      => QRString::ansi8('░░', 2),
+	QRMatrix::M_VERSION_DARK   => QRString::ansi8('██', 21),
+	QRMatrix::M_VERSION        => QRString::ansi8('░░', 21),
+];
+```
+
+
+Output:
+
+```php
+$data   = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
+$qrcode = (new QRCode($options))->render($data);
+
+echo "\n\n$qrcode\n\n";
+```
+
+
+## JSON
+
+```php
+$options = new QROptions;
+
+$options->outputType     = QROutputInterface::STRING_JSON;
+// output the integer values ($M_TYPE) held in the matrix object
+$options->jsonAsBooleans = false;
+
+header('Content-type: application/json');
+
+echo (new QRCode($options))->render($data);
+```
+
+
+## Additional methods
+
+| method                                                    | return   | description                                                         |
+|-----------------------------------------------------------|----------|---------------------------------------------------------------------|
+| (protected) `text()`                                      | `string` | string output                                                       |
+| (protected) `json()`                                      | `string` | JSON output                                                         |
+| `ansi8(string $str, int $color, bool $background = null)` | `string` | a little helper to create a proper ANSI 8-bit color escape sequence |
+
 
 ## Options that affect this module
 
-| property                       | type           |
-|--------------------------------|----------------|
-| `$eol`                         | `string`       |
-| `$textDark`                    | `string`       |
-| `$textLight`                   | `string`       |
+| property          | type     |
+|-------------------|----------|
+| `$eol`            | `string` |
+| `$jsonAsBooleans` | `bool`   |
+| `$textDark`       | `string` |
+| `$textLight`      | `string` |
+| `$textLineStart`  | `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             |
+| property               | reason          |
+|------------------------|-----------------|
+| `$bgColor`             | N/A             |
+| `$circleRadius`        | N/A             |
+| `$connectPaths`        | N/A             |
+| `$drawCircularModules` | N/A             |
+| `$drawLightModules`    | not implemented |
+| `$excludeFromConnect`  | N/A             |
+| `$imageTransparent`    | N/A             |
+| `$keepAsSquare`        | N/A             |
+| `$outputBase64`        | N/A             |
+| `$returnResource`      | N/A             |
+| `$scale`               | N/A             |