🛀 doc cleanup

docs/Usage/Advanced-usage.md

@@ -0,0 +1,215 @@
+# Advanced usage
+
+## 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;
+
+// set some values
+$options->version = 7;     // property "version" exists
+$options->foo     = 'bar'; // property "foo" does not exist (and will not be created)
+
+// retrieve values
+var_dump($options->version); // -> 7
+var_dump($options->foo);     // -> null (no error will be thrown)
+```
+
+
+### Supply an `iterable` of options
+
+The constructor takes an `iterable` of `$key => $value` pairs. For each setting an optional setter will be called if present.
+
+```php
+$myOptions = [
+	'version'    => 5,
+	'outputType' => QROutputInterface::GDIMAGE_PNG,
+	'eccLevel'   => EccLevel::M,
+];
+
+$options = new QROptions($myOptions);
+```
+
+You can also set an `iterable` of options on an existing QROptions instance:
+
+```php
+$options->fromIterable($myOptions);
+```
+
+
+### Load and save JSON
+
+The settings can be saved to and loaded from JSON, e.g. to store them in a database:
+
+```php
+$json = $options->toJSON(JSON_THROW_ON_ERROR);
+// via JsonSerializable interface
+$json = json_encode($options, JSON_THROW_ON_ERROR);
+// via __toString()
+$json = (string)$options;
+
+$options = (new QROptions)->fromJSON($json);
+// on an existing instance - properties will be overwriten
+$options->fromJSON($json);
+```
+
+### Extending the `QROptions` class
+
+In case you need additional settings for your output module, just extend `QROptions`...
+
+```php
+class MyCustomOptions extends QROptions{
+	protected string $myParam = 'defaultValue';
+	// ...
+}
+```
+...or use the [`SettingsContainerInterface`](https://github.com/chillerlan/php-settings-container/blob/main/src/SettingsContainerInterface.php), which is the more flexible approach.
+
+```php
+trait MyCustomOptionsTrait{
+	protected string $myParam = 'defaultValue';
+	// ...
+
+	// an optional magic setter, named "set_" + property name
+	protected function set_myParam(string $myParam):void{
+		$this->myParam = trim($myParam);
+	}
+
+	// an optional magic getter, named "get_" + property name
+	protected function get_myParam():string{
+		return strtoupper($this->myParam);
+	}
+}
+
+class MyCustomOptions extends SettingsContainerAbstract{
+	use QROptionsTrait, MyCustomOptionsTrait;
+}
+
+// set the options
+$myCustomOptions = new MyCustomOptions;
+$myCustomOptions->myParam = 'whatever value';
+```
+
+Extend the `SettingsContainerInterface` on-the-fly:
+
+```php
+$myOptions = [
+	'myParam' => 'whatever value',
+	// ...
+];
+
+$myCustomOptions = new class($myOptions) extends SettingsContainerAbstract{
+	use QROptionsTrait, MyCustomOptionsTrait;
+};
+```
+
+
+## `QRCode` methods
+
+Aside of invoking a `QRCode` instance with an optional `QROptions` object as parameter, you can also set the options instance after invocation.
+After invocation of the `QROptions` instance, values can be set without calling `QRCode::setOptions()` again (instance is backreferenced), however, this may create side effects.
+
+```php
+// instance will be invoked with default settings
+$qrcode  = new QRCode;
+
+// set options after QRCode invocation
+$options = new QROptions;
+
+$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:
+
+```php
+// a matrix from the current data segments
+$matrix = $qrcode->getQRMatrix();
+// from the QR Code reader
+$matrix = $readerResult->getQRMatrix();
+// manually invoked
+$matrix = (new QRMatrix(new Version(7), new EccLevel(EccLevel::M)))->initFunctionalPatterns();
+
+$output = $qrcode->renderMatrix($matrix);
+// save to file
+$qrcode->renderMatrix($matrix, '/path/to/qrcode.svg');
+```
+
+### Mixed mode
+
+Mixed mode QR Codes can be generated by adding several data segments:
+
+```php
+// make sure to set a proper internal encoding character set
+// ideally, this should be set in php.ini internal_encoding,
+// default_charset or mbstring.internal_encoding
+mb_internal_encoding('UTF-8');
+
+// clear any existing data segments
+$qrcode->clearSegments();
+
+$qrcode
+	->addNumericSegment($numericData)
+	->addAlphaNumSegment($alphaNumData)
+	->addKanjiSegment($kanjiData)
+	->addHanziSegment($hanziData)
+	->addByteSegment($binaryData)
+	->addEciSegment(ECICharset::GB18030, $encodedEciData)
+;
+
+$output = $qrcode->render();
+// render to file
+$qrcode->render(null, '/path/to/qrcode.svg');
+```
+
+The [`QRDataModeInterface`](https://github.com/chillerlan/php-qrcode/blob/main/src/Data/QRDataModeInterface.php) offers the `validateString()` method (implemended for `AlphaNum`, `Byte`, `Hanzi`, `Kanji` and `Number`).
+This method is used internally when a data mode is invoked, but it can come in handy if you need to check input data beforehand.
+
+```php
+if(!Hanzi::validateString($data)){
+	throw new Exception('invalid GB2312 data');
+}
+
+$qrcode->addHanziSegment($data);
+```
+
+
+### QR Code reader
+
+In some cases it might be necessary to increase the contrast of a QR Code image:
+
+```php
+$options->readerUseImagickIfAvailable = true;
+$options->readerIncreaseContrast      = true;
+$options->readerGrayscale             = true;
+
+$result = (new QRCode($options))->readFromFile('path/to/qrcode.png');
+```
+
+The `QRMatrix` object from the [`DecoderResult`](https://github.com/chillerlan/php-qrcode/blob/main/src/Decoder/DecoderResult.php) can be reused:
+
+```php
+$matrix = $result->getQRMatrix();
+
+// ...matrix modification...
+
+$output = (new QRCode($options))->renderMatrix($matrix);
+
+// ...output
+```

docs/Usage/Configuration-settings.md

@@ -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

@@ -0,0 +1,94 @@
+# Installation
+
+## Installation with Composer
+
+**[Composer](https://getcomposer.org) is required to install this package. Please do not open an issue to complain about "monopolizing the implementation" or similar - we've been there before.**
+
+
+### composer.json
+
+Installation via [`composer.json`](https://getcomposer.org/doc/04-schema.md):
+
+```json
+{
+	"require": {
+		"php": "^7.4",
+		"chillerlan/php-qrcode": "dev-main"
+	}
+}
+```
+
+Note: replace `dev-main` with a [version constraint](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints), e.g. `^4.3` - see [releases](https://github.com/chillerlan/php-qrcode/releases) for valid versions.
+In case you want to keep using `dev-main`, specify the hash of a commit to avoid running into unforseen issues, like so: `dev-main#cb69751c3bc090a7fdd2f2601bbe10f28d225f10`
+
+
+#### Version switch
+
+If your application supports older PHP versions and uses the basic `QRCode` syntax `(new QRCode)->render($data)`, then you can add a version switch to your `composer.json` to allow installing a `php-qrcode` version that suits the platform it runs on:
+
+```json
+{
+	"require": {
+		"php": "^7.0 || ^8.0",
+		"chillerlan/php-qrcode": "^2.0 || ^3.4 || ^4.3 || ^5.0"
+	}
+}
+```
+
+Most of the v2.0 API remains unchanged throughout the several versions up to v5.x, however, please test and verify the expected output before you deploy such a switch.
+
+
+### Terminal
+
+To install `php-qrcode` on the terminal, use:
+
+`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`
+
+
+## Manual installation
+
+Download the desired version of the package from [main](https://github.com/chillerlan/php-qrcode/archive/refs/heads/main.zip) or
+[release](https://github.com/chillerlan/php-qrcode/releases) and extract the contents to your project folder.
+After that, run `composer install` in the package root directory to install the required dependencies and generate `./vendor/autoload.php`.
+
+Profit!
+
+
+### Can i use this library without using composer?
+
+You can, but it's absolutely not recommended, nor supported.
+
+With that said, I'll leave you with this info:
+
+- download the .zip for a version of your choice and also all required dependencies listed in the `composer.json` for that version (you can find links to the respective repos [on packagist](https://packagist.org/packages/chillerlan/php-qrcode))
+- extract the files into your library folder
+- include the files manually or with whatever autoloader you are using
+
+Good luck!
+
+
+## Supported PHP versions & extension requirements
+
+The PHP built-in extensions [GdImage](https://www.php.net/manual/book.image.php) and [mbstring](https://www.php.net/manual/book.mbstring.php) are used across all versions, [ImageMagick](https://www.php.net/manual/book.imagick.php) is optional since v3.x.
+
+| version | branch/tag                                                           | PHP              | supported | required extensions | optional extensions                                                                | info                      |
+|---------|----------------------------------------------------------------------|------------------|-----------|---------------------|------------------------------------------------------------------------------------|---------------------------|
+| **v5**  | [`dev-main`](https://github.com/chillerlan/php-qrcode/tree/main)     | `^7.4 \|\| ^8.0` | yes       | `mbstring`          | `gd` or `imagick` required for reading QR Codes, `fileinfo` is used in `QRImagick` |                           |
+| **v4**  | [`4.3.4`](https://github.com/chillerlan/php-qrcode/tree/v4.3.x)      | `^7.4 \|\| ^8.0` | yes       | `gd`, `mbstring`    | `imagick`                                                                          |                           |
+| **v3**  | [`3.4.1`](https://github.com/chillerlan/php-qrcode/tree/v3.2.x)      | `^7.2`           | no        | `gd`, `mbstring`    | `imagick`                                                                          | v3.4.1 also supports PHP8 |
+| **v2**  | [`2.0.8`](https://github.com/chillerlan/php-qrcode/tree/v2.0.x)      | `>=7.0.3`        | no        | `gd`, `mbstring`    |                                                                                    |                           |
+| **v1**  | [`1.0.9`](https://github.com/chillerlan/php-qrcode/tree/v2.0.x-php5) | `>=5.6`          | no        | `gd`, `mbstring`    |                                                                                    | please let PHP 5 die!     |
+
+PSA: [PHP versions < 8.0 are EOL](https://www.php.net/supported-versions.php) and therefore the respective `QRCode` versions are also no longer supported!
+
+
+## ImageMagick
+
+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))

docs/Usage/Overview.md

@@ -0,0 +1,75 @@
+# Overview
+
+A PHP QR Code generator based on the [implementation by Kazuhiko Arase](https://github.com/kazuhikoarase/qrcode-generator), namespaced, cleaned up, improved and other stuff. <br>
+It also features a QR Code reader based on a [PHP port](https://github.com/khanamiryan/php-qrcode-detector-decoder) of the [ZXing library](https://github.com/zxing/zxing).
+
+
+## Features
+
+- Creation of [Model 2 QR Codes](https://www.qrcode.com/en/codes/model12.html), [Version 1 to 40](https://www.qrcode.com/en/about/version.html)
+- [ECC Levels](https://www.qrcode.com/en/about/error_correction.html) L/M/Q/H supported
+- Mixed mode support (encoding modes can be combined within a QR symbol). Supported modes:
+  - numeric
+  - alphanumeric
+  - 8-bit binary
+  - 13-bit double-byte:
+    - kanji (Japanese, Shift-JIS)
+    - hanzi (simplified Chinese, GB2312/GB18030) as [defined in GBT18284-2000](https://www.chinesestandard.net/PDF/English.aspx/GBT18284-2000)
+- Flexible, easily extensible output modules, built-in support for the following output formats:
+  - [GdImage](https://www.php.net/manual/book.image)
+  - [ImageMagick](https://www.php.net/manual/book.imagick)
+  - Markup types: SVG, HTML, etc.
+  - String types: JSON, plain text, etc.
+  - Encapsulated Postscript (EPS)
+  - PDF via [FPDF](https://github.com/setasign/fpdf)
+- QR Code reader (via GD and ImageMagick)
+
+
+## Requirements
+
+- PHP 7.4+
+  - [`ext-mbstring`](https://www.php.net/manual/book.mbstring.php)
+  - optional:
+    - [`ext-fileinfo`](https://www.php.net/manual/book.fileinfo.php) (required by `QRImagick` output)
+    - [`ext-gd`](https://www.php.net/manual/book.image)
+    - [`ext-imagick`](https://github.com/Imagick/imagick) with [ImageMagick](https://imagemagick.org) installed
+    - [`setasign/fpdf`](https://github.com/setasign/fpdf) for the PDF output module
+
+For the QR Code reader, either `ext-gd` or `ext-imagick` is required!
+
+
+## Framework Integration
+
+- Drupal:
+  - [Two-factor Authentication `tfa`](https://www.drupal.org/project/tfa) (Drupal 8+)
+  - [Google Authenticator Login `ga_login`](https://www.drupal.org/project/ga_login) (deprecated, Drupal 7)
+- Symfony
+  - [phpqrcode-bundle](https://github.com/jonasarts/phpqrcode-bundle)
+- WordPress:
+  - [wp-two-factor-auth](https://github.com/sjinks/wp-two-factor-auth)
+  - [simple-2fa](https://wordpress.org/plugins/simple-2fa/)
+  - [floating-share-button](https://github.com/qriouslad/floating-share-button)
+- WoltLab Suite
+  - [two-step-verification](http://pluginstore.woltlab.com/file/3007-two-step-verification/)
+- other uses:
+  - [dependents](https://github.com/chillerlan/php-qrcode/network/dependents) / [packages](https://github.com/chillerlan/php-qrcode/network/dependents?dependent_type=PACKAGE)
+  - [Appwrite](https://github.com/appwrite/appwrite)
+  - [Cachet](https://github.com/CachetHQ/Cachet)
+  - [GÉANT CAT](https://github.com/GEANT/CAT)
+  - [openITCOCKPIT](https://github.com/it-novum/openITCOCKPIT)
+  - [twill](https://github.com/area17/twill)
+  - [Elefant CMS](https://github.com/jbroadway/elefant)
+- Articles:
+  - [Twilio: How to Create a QR Code in PHP](https://www.twilio.com/blog/create-qr-code-in-php) (featuring v4.3.x)
+
+
+## Shameless advertising
+
+Hi, please check out some of my other projects that are way cooler than qrcodes!
+
+- [js-qrcode](https://github.com/chillerlan/js-qrcode) - a javascript port of this library
+- [php-authenticator](https://github.com/chillerlan/php-authenticator) - a Google Authenticator implementation (see [authenticator example](https://github.com/chillerlan/php-qrcode/blob/main/examples/authenticator.php))
+- [php-httpinterface](https://github.com/chillerlan/php-httpinterface) - a PSR-7/15/17/18 implemetation
+- [php-oauth-core](https://github.com/chillerlan/php-oauth-core) - an OAuth 1/2 client library along with a bunch of [providers](https://github.com/chillerlan/php-oauth-providers)
+- [php-database](https://github.com/chillerlan/php-database) - a database client & querybuilder for MySQL, Postgres, SQLite, MSSQL, Firebird
+- [php-tootbot](https://github.com/php-tootbot/tootbot-template) - a Mastodon bot library

docs/Usage/Quickstart.md

@@ -0,0 +1,66 @@
+# Quickstart
+
+## Import the library
+
+Import the main class(es) and include the autoloader (if necessary):
+```php
+use chillerlan\QRCode\{QRCode, QROptions};
+
+require_once __DIR__.'/../vendor/autoload.php';
+```
+
+
+## Create your first QR Code
+
+We want to encode this URI for a mobile authenticator into a QRcode image:
+```php
+$data   = 'otpauth://totp/test?secret=B3JX4VCVJDVNXNZ5&issuer=chillerlan.net';
+$qrcode = (new QRCode)->render($data);
+
+printf('<img src="%s" alt="QR Code" />', $qrcode);
+```
+
+
+### Configuration
+
+Configuration using `QROptions`:
+
+```php
+$options = new QROptions;
+$options->version      = 7;
+$options->outputBase64 = false; // output raw image instead of base64 data URI
+
+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.
+Also, have a look [in the examples folder](https://github.com/chillerlan/php-qrcode/tree/main/examples) for some more usage examples.
+
+
+## Reading QR Codes
+
+Using the built-in QR Code reader is pretty straight-forward:
+```php
+try{
+	$result = (new QRCode)->readFromFile('path/to/file.png'); // -> DecoderResult
+}
+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.
+
+
+## Notes
+The QR encoder, especially the subroutines for mask pattern testing, can cause high CPU load on increased matrix size.
+You can avoid a part of this load by choosing a fast output module, like SVG.
+Oh hey and don't forget to sanitize any user input!