diff --git a/docs/API-QROptions.md b/docs/API-QROptions.md index 5efa1494c..911a1fc98 100644 --- a/docs/API-QROptions.md +++ b/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) | diff --git a/docs/Built-In-Output-QREps.md b/docs/Built-In-Output-QREps.md index 60485b4b7..9cef1814f 100644 --- a/docs/Built-In-Output-QREps.md +++ b/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 | diff --git a/docs/Built-In-Output-QRFpdf.md b/docs/Built-In-Output-QRFpdf.md index 62115287c..db35e9ec1 100644 --- a/docs/Built-In-Output-QRFpdf.md +++ b/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) +## Example + +See: [FPDF example](https://github.com/chillerlan/php-qrcode/blob/main/examples/fpdf.php) + +Set the options: + +```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); + +// 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 | -|--------------------------------|----------------| -| `$returnResource` | `bool` | -| `$imageBase64` | `bool` | -| `$bgColor` | `mixed` | -| `$drawLightModules` | `bool` | -| `$fpdfMeasureUnit` | `string` | +| property | type | +|---------------------|----------| +| `$bgColor` | `array` | +| `$drawLightModules` | `bool` | +| `$fpdfMeasureUnit` | `string` | +| `$outputBase64` | `bool` | +| `$returnResource` | `bool` | +| `$scale` | `ìnt` | ### Options that have no effect -| property | reason | -|------------------------|-----------------| -| `$drawCircularModules` | N/A | -| `$circleRadius` | N/A | -| `$keepAsSquare` | N/A | -| `$connectPaths` | N/A | -| `$excludeFromConnect` | N/A | -| `$scale` | not implemented | -| `$imageTransparent` | N/A | - - +| property | reason | +|------------------------|--------| +| `$circleRadius` | N/A | +| `$connectPaths` | N/A | +| `$drawCircularModules` | N/A | +| `$excludeFromConnect` | N/A | +| `$imageTransparent` | N/A | +| `$keepAsSquare` | N/A | diff --git a/docs/Built-In-Output-QRGdImage.md b/docs/Built-In-Output-QRGdImage.md index d1fafe85d..09cc3f5ed 100644 --- a/docs/Built-In-Output-QRGdImage.md +++ b/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('%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 | diff --git a/docs/Built-In-Output-QRImagick.md b/docs/Built-In-Output-QRImagick.md index 5d3d26957..7fe94abba 100644 --- a/docs/Built-In-Output-QRImagick.md +++ b/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('%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 | diff --git a/docs/Built-In-Output-QRMarkupHTML.md b/docs/Built-In-Output-QRMarkupHTML.md index 85f6335b2..b498728b3 100644 --- a/docs/Built-In-Output-QRMarkupHTML.md +++ b/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 +render($data); + +header('Content-type: text/html'); + +?> + + + + + + QRCode HTML Example + + + + + + + +``` + + +## 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 | diff --git a/docs/Built-In-Output-QRMarkupSVG.md b/docs/Built-In-Output-QRMarkupSVG.md index fa7cb93df..96a92f022 100644 --- a/docs/Built-In-Output-QRMarkupSVG.md +++ b/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 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 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 = ' + + + + + + + + + '; +``` + + +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('%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 `` 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 `` element | +| (protected) `paths()` | `string` | returns one or more SVG `` 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, `` 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 `` 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 | diff --git a/docs/Built-In-Output-QRString.md b/docs/Built-In-Output-QRString.md index 7b629b1b8..ec84cece6 100644 --- a/docs/Built-In-Output-QRString.md +++ b/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 |