geckon01/php-qrcode
1
0
Fork 0
mirror of https://github.com/chillerlan/php-qrcode.git synced 2026-08-30 20:17:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

:octocat: auto generate options doc from the QROptionsTrait source

Browse Source
This commit is contained in:
smiley
2023-10-04 17:56:26 +02:00
parent cf0648e24d
commit 0eb1dfe657
3 changed files with 224 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/ci.yml
+9
View File
@@ -135,9 +135,18 @@ jobs:
- name: "Checkout sources"
uses: actions/checkout@v3
- name: "Install PHP"
uses: shivammathur/setup-php@v2
with:
php-version: "8.1"
coverage: none
- name: "Install Sphinx"
run: pip install sphinx myst-parser sphinx-rtd-theme
- name: "Build QROptions doc"
run: php docs/qroptions-doc.php
- name: "Build manual"
run: |
cd docs
docs/qroptions-doc.php
+94
View File
@@ -0,0 +1,94 @@
<?php
/**
* Auto generates the configuration settings markdown source
*
* @created 03.10.2023
* @author smiley <smiley@chillerlan.net>
* @copyright 2023 smiley
* @license MIT
*/
use chillerlan\QRCode\QROptionsTrait;
require_once __DIR__.'/../vendor/autoload.php';
$file = 'Usage/Configuration-settings.md';
$content = [
'# Configuration settings',
'<!-- This file is auto generated from the source of QROptionsTrait.php -->',
];
$reflectionClass = new ReflectionClass(QROptionsTrait::class);
foreach($reflectionClass->getProperties(ReflectionProperty::IS_PROTECTED) as $reflectionProperty){
$docblock = $reflectionProperty->getDocComment();
// don't document deprecated settings
if(str_contains($docblock, '@deprecated')){
continue;
}
$content[] = sprintf("## %s\n", $reflectionProperty->getName());
$lines = array_map(fn($l) => trim($l, "\ \t\n\r\0\x0B*"), explode("\n", $docblock));
array_shift($lines);
array_pop($lines);
$see = [];
foreach($lines as $line){
// skip @todo and @var
if(str_contains($line, '@todo') || str_contains($line, '@var')){
continue;
}
// collect links for "see also"
if(str_starts_with($line, '@see')){
$see[] = $line;
continue;
}
$content[] = $line;
}
// add a "see also" section
if(!empty($see)){
$content[] = "**See also:**\n";
foreach($see as $line){
$line = substr($line, 5); // cut off the "@see "
// normal links
if(str_starts_with($line, 'http')){
$content[] = sprintf('- [%s](%s)', explode('://', $line)[1], $line);
}
// php.net documentation
elseif(str_starts_with($line, '\\') && !str_contains($line, 'chillerlan')){
$path = str_replace(['\\', '::', '()'], ['', '.', ''], strtolower($line));
if(!str_contains($line, '::')){
$path = 'function.'.$path;
}
$content[] = sprintf('- [php.net: `%s`](https://www.php.net/manual/%s)', $line, $path);
}
// FQCN
else{
$content[] = sprintf('- `%s`', $line);
}
}
}
$content[] = "\n";
}
file_put_contents(__DIR__.'/'.$file, implode("\n", $content));
printf('Built "%s" from "%s"', $file, QROptionsTrait::class);
exit(0);
src/QROptionsTrait.php
+121 -55
View File
@@ -2,6 +2,8 @@
/**
* Trait QROptionsTrait
*
* Note: the docblocks in this file are optimized for readability in PhpStorm ond on readthedocs.io
*
* @created 10.03.2018
* @author smiley <smiley@chillerlan.net>
* @copyright 2018 smiley
@@ -15,6 +17,7 @@ namespace chillerlan\QRCode;
use chillerlan\QRCode\Output\QROutputInterface;
use chillerlan\QRCode\Common\{EccLevel, MaskPattern, Version};
use function extension_loaded, in_array, max, min, strtolower;
use const PHP_EOL;
/**
* The QRCode plug-in settings & setter functionality
@@ -28,33 +31,38 @@ trait QROptionsTrait{
/**
* QR Code version number
*
* [1 ... 40] or Version::AUTO
* `1 ... 40` or `Version::AUTO` (default)
*
* @see \chillerlan\QRCode\Common\Version
*/
protected int $version = Version::AUTO;
/**
* Minimum QR version
*
* if $version = QRCode::VERSION_AUTO
* if `QROptions::$version` is set to `Version::AUTO` (default: 1)
*/
protected int $versionMin = 1;
/**
* Maximum QR version
*
* if `QROptions::$version` is set to `Version::AUTO` (default: 40)
*/
protected int $versionMax = 40;
/**
* Error correct level
*
* QRCode::ECC_X where X is:
* `EccLevel::X` where `X` is:
*
* - L => 7%
* - M => 15%
* - Q => 25%
* - H => 30%
* - `L` => 7% (default)
* - `M` => 15%
* - `Q` => 25%
* - `H` => 30%
*
* @todo: accept string values (PHP8+)
* @see \chillerlan\QRCode\Common\EccLevel
* @see https://github.com/chillerlan/php-qrcode/discussions/160
*/
protected int $eccLevel = EccLevel::L;
@@ -62,7 +70,9 @@ trait QROptionsTrait{
/**
* Mask Pattern to use (no value in using, mostly for unit testing purposes)
*
* [0...7] or MaskPattern::PATTERN_AUTO
* `0 ... 7` or `MaskPattern::PATTERN_AUTO` (default)
*
* @see \chillerlan\QRCode\Common\MaskPattern
*/
protected int $maskPattern = MaskPattern::AUTO;
@@ -76,7 +86,7 @@ trait QROptionsTrait{
/**
* Size of the quiet zone
*
* internally clamped to [0 ... $moduleCount / 2], defaults to 4 modules
* internally clamped to `0 ... $moduleCount / 2` (default: 4)
*/
protected int $quietzoneSize = 4;
@@ -88,51 +98,75 @@ trait QROptionsTrait{
/**
* The built-in output type
*
* - QROutputInterface::MARKUP_XXXX where XXXX = HTML, SVG
* - QROutputInterface::GDIMAGE_XXX where XXX = BMP, GIF, JPG, PNG, WEBP
* - QROutputInterface::STRING_XXXX where XXXX = TEXT, JSON
* - QROutputInterface::IMAGICK
* - QROutputInterface::EPS
* - QROutputInterface::FPDF
* - QROutputInterface::CUSTOM
* - `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 \chillerlan\QRCode\Output\QREps
* @see \chillerlan\QRCode\Output\QRFpdf
* @see \chillerlan\QRCode\Output\QRGdImage
* @see \chillerlan\QRCode\Output\QRImagick
* @see \chillerlan\QRCode\Output\QRMarkupHTML
* @see \chillerlan\QRCode\Output\QRMarkupSVG
* @see \chillerlan\QRCode\Output\QRString
*/
protected string $outputType = QROutputInterface::MARKUP_SVG;
/**
* The FQCN of the custom QROutputInterface if $outputType is set to QRCode::OUTPUT_CUSTOM
* The FQCN of the custom `QROutputInterface`
*
* if `QROptions::$outputType` is set to `QROutputInterface::CUSTOM` (default: `null`)
*/
protected ?string $outputInterface = null;
/**
* Return the image resource instead of a render if applicable.
* This option overrides/ignores other output options, such as $cachefile and $outputBase64.
*
* Supported by the following modules:
* - `QRGdImage`: `resource` (PHP < 8), `GdImage`
* - `QRImagick`: `Imagick`
* - `QRFpdf`: `FPDF`
*
* - 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 \chillerlan\QRCode\Output\QROutputInterface::dump()
*
* @var bool
*/
protected bool $returnResource = false;
/**
* Optional cache file path `/path/to/cache.file`
*
* please note that the $file parameter in QRCode::render*() takes precedence over the $cachefile value
* Please note that the `$file` parameter in `QRCode::render()` and `QRCode::renderMatrix()`
* takes precedence over the `QROptions::$cachefile` value. (default: `null`)
*
* @see \chillerlan\QRCode\QRCode::render()
* @see \chillerlan\QRCode\QRCode::renderMatrix()
*/
protected ?string $cachefile = null;
/**
* Toggle base64 data URI or raw data output (if applicable)
*
* (default: `true`)
*
* @see \chillerlan\QRCode\Output\QROutputAbstract::toBase64DataURI()
*/
protected bool $outputBase64 = true;
/**
* Newline string
*
* (default: `PHP_EOL`)
*/
protected string $eol = PHP_EOL;
@@ -143,9 +177,9 @@ trait QROptionsTrait{
/**
* Sets the image background color (if applicable)
*
* - QRImagick: defaults to "white"
* - QRGdImage: defaults to [255, 255, 255]
* - QRFpdf: defaults to blank internally (white page)
* - `QRImagick`: defaults to `"white"`
* - `QRGdImage`: defaults to `[255, 255, 255]`
* - `QRFpdf`: defaults to blank internally (white page)
*
* @var mixed|null
*/
@@ -153,36 +187,47 @@ trait QROptionsTrait{
/**
* Whether to invert the matrix (reflectance reversal)
*
* (default: `false`)
*
* @see \chillerlan\QRCode\Data\QRMatrix::invert()
*/
protected bool $invertMatrix = false;
/**
* Whether to draw the light (false) modules
*
* (default: `true`)
*/
protected bool $drawLightModules = true;
/**
* Specify whether to draw the modules as filled circles
*
* a note for GDImage output:
* 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
* 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
* No effect in: `QREps`, `QRFpdf`, `QRMarkupHTML`
*
* @see \imagefilledellipse()
* @see https://github.com/chillerlan/php-qrcode/issues/23
* @see https://github.com/chillerlan/php-qrcode/discussions/122
*/
protected bool $drawCircularModules = false;
/**
* Specifies the radius of the modules when $drawCircularModules is set to true
* Specifies the radius of the modules when `QROptions::$drawCircularModules` is set to `true`
*
* (default: 0.45)
*/
protected float $circleRadius = 0.45;
/**
* Specifies which module types to exclude when $drawCircularModules is set to true
* Specifies which module types to exclude when `QROptions::$drawCircularModules` is set to `true`
*
* (default: `[]`)
*/
protected array $keepAsSquare = [];
@@ -194,35 +239,40 @@ trait QROptionsTrait{
protected bool $connectPaths = false;
/**
* Specify which paths/patterns to exclude from connecting if $connectPaths is set to true
* Specify which paths/patterns to exclude from connecting if `QROptions::$connectPaths` is set to `true`
*/
protected array $excludeFromConnect = [];
/**
* 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
* - `QRImagick`, `QRMarkupHTML`, `QRMarkupSVG`: #ABCDEF, cssname, rgb(), rgba()...
* - `QREps`, `QRFpdf`, `QRGdImage`: `[R, G, B]` // 0-255
* - `QREps`: `[C, M, Y, K]` // 0-255
*
* @see \chillerlan\QRCode\Output\QROutputAbstract::setModuleValues()
*/
protected ?array $moduleValues = null;
/**
* Toggles logo space creation
*
* @see \chillerlan\QRCode\QRCode::addMatrixModifications()
* @see \chillerlan\QRCode\Data\QRMatrix::setLogoSpace()
*/
protected bool $addLogoSpace = false;
/**
* Width of the logo space
*
* if only either $logoSpaceWidth or $logoSpaceHeight is given, the logo space is assumed a square of that size
* if only `QROptions::$logoSpaceWidth` is given, the logo space is assumed a square of that size
*/
protected ?int $logoSpaceWidth = null;
/**
* Height of the logo space
*
* if only either $logoSpaceWidth or $logoSpaceHeight is given, the logo space is assumed a square of that size
* if only `QROptions::$logoSpaceHeight` is given, the logo space is assumed a square of that size
*/
protected ?int $logoSpaceHeight = null;
@@ -249,18 +299,22 @@ trait QROptionsTrait{
/**
* Toggle transparency
*
* - QRGdImage and QRImagick: the given {@see \chillerlan\QRCode\QROptions::$transparencyColor $transparencyColor} is set as transparent
* - `QRGdImage` and `QRImagick`: the given `QROptions::$transparencyColor` is set as transparent
*
* @see https://github.com/chillerlan/php-qrcode/discussions/121
*/
protected bool $imageTransparent = false;
/**
* Sets a transparency color for when {@see \chillerlan\QRCode\QROptions::$imageTransparent QROptions::$imageTransparent} is set to true.
* Defaults to {@see \chillerlan\QRCode\QROptions::$bgColor QROptions::$bgColor}.
* Sets a transparency color for when `QROptions::$imageTransparent` is set to `true`.
*
* - QRGdImage: [R, G, B], this color is set as transparent in {@see imagecolortransparent()}
* - QRImagick: "color_str", this color is set in {@see Imagick::transparentPaintImage()}
* 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 \imagecolortransparent()
* @see \Imagick::transparentPaintImage()
*
* @var mixed|null
*/
@@ -271,11 +325,17 @@ trait QROptionsTrait{
*
* The given value depends on the used output type:
*
* - GDIMAGE_BMP {@see \imagebmp()} [0-1]
* - GDIMAGE_JPG {@see \imagejpeg()} [0-100]
* - GDIMAGE_WEBP {@see \imagepng()} [0-9]
* - GDIMAGE_PNG {@see \imagewebp()} [0-100]
* - IMAGICK {@see \Imagick::setImageCompressionQuality()} [0-100]
* - `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 \imagebmp()
* @see \imagejpeg()
* @see \imagepng()
* @see \imagewebp()
* @see \Imagick::setImageCompressionQuality()
*/
protected int $quality = -1;
@@ -325,12 +385,16 @@ trait QROptionsTrait{
protected bool $svgAddXmlHeader = true;
/**
* SVG opacity
* 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.
*/
protected float $svgOpacity = 1.0;
/**
* Anything in the <defs> tag
* Anything in the SVG `<defs>` tag
*
* @see https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs
*/
@@ -350,6 +414,8 @@ trait QROptionsTrait{
protected ?int $svgViewBoxSize = null;
/**
* Sets the value for the "preserveAspectRatio" on the `<svg>` element
*
* @see https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio
*/
protected string $svgPreserveAspectRatio = 'xMidYMid';
@@ -375,7 +441,7 @@ trait QROptionsTrait{
protected string $textLineStart = '';
/**
* Whether to return matrix values in JSON as booleans or $M_TYPE integers
* Whether to return matrix values in JSON as booleans or `$M_TYPE` integers
*/
protected bool $jsonAsBooleans = false;
@@ -384,9 +450,9 @@ trait QROptionsTrait{
*/
/**
* Measurement unit for FPDF output: pt, mm, cm, in (defaults to "pt")
* Measurement unit for `FPDF` output: pt, mm, cm, in (defaults to "pt")
*
* @see \FPDF::__construct()
* @see FPDF::__construct()
*/
protected string $fpdfMeasureUnit = 'pt';