diff --git a/docs/Appendix/Contribute.md b/docs/Appendix/Contribute.md index 1bae31147..c6a74b9e0 100644 --- a/docs/Appendix/Contribute.md +++ b/docs/Appendix/Contribute.md @@ -14,7 +14,7 @@ Please don't just write "headline says all" because the reply will likely be sim So you found a bug or the library code is somehow misbehaving? That's great (well, not that great tho). In that case, please [open a bug report and FILL OUT THE ISSUE TEMPLATE](https://github.com/chillerlan/php-qrcode/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D) -(i have to write that in all caps because nobody actually does it which usually leads to several avoidable follow-up questions that cost both of us precious time). +(I have to write that in all caps because nobody actually does it which usually leads to several avoidable follow-up questions that cost both of us precious time). Below an example of the bug report template (it's not that hard): **Describe the bug** diff --git a/docs/Appendix/URI-Content.md b/docs/Appendix/URI-Content.md index d06536c7e..3697bf3b9 100644 --- a/docs/Appendix/URI-Content.md +++ b/docs/Appendix/URI-Content.md @@ -253,11 +253,11 @@ END:VCALENDAR ## Credit Transfer -### SEPA +### SEPA (European Payments Council) - [Guidelines to Enable the Data Capture for the Initiation of a SEPA Credit Transfer](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/quick-response-code-guidelines-enable-data-capture-initiation) - [sepa-qr-data library for PHP (GitHub)](https://github.com/smhg/sepa-qr-data-php) -### Pix +### Pix (Banco Central do Brasil) - [Manual de Padrões para Iniciação do Pix (PDF)](https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/II_ManualdePadroesparaIniciacaodoPix.pdf) - [OpenBoleto (GitHub)](https://github.com/openboleto/openboleto) diff --git a/docs/Built-In-Output/QREps.md b/docs/Built-In-Output/QREps.md index 63cedb994..74ceec275 100644 --- a/docs/Built-In-Output/QREps.md +++ b/docs/Built-In-Output/QREps.md @@ -60,7 +60,7 @@ exit; | (protected) `module(int $x, int $y, int $M_TYPE)` | `string` | Returns a path segment for a single module | -## Options that affect this module +## Options that affect this class | property | type | |-----------------------|---------| diff --git a/docs/Built-In-Output/QRFpdf.md b/docs/Built-In-Output/QRFpdf.md index ff6c2cd3b..c9d6ca0e3 100644 --- a/docs/Built-In-Output/QRFpdf.md +++ b/docs/Built-In-Output/QRFpdf.md @@ -65,7 +65,7 @@ echo $fpdf->Output('S'); | (protected) `module(int $x, int $y, int $M_TYPE)` | `void` | Renders a single module | -## Options that affect this module +## Options that affect this class | property | type | |---------------------|----------| diff --git a/docs/Built-In-Output/QRGdImage.md b/docs/Built-In-Output/QRGdImage.md index 7fd0dfe92..a4853f4fa 100644 --- a/docs/Built-In-Output/QRGdImage.md +++ b/docs/Built-In-Output/QRGdImage.md @@ -84,7 +84,7 @@ imagedestroy($gdImage); | (abstract protected) `renderImage()` | `void` | Renders the image with the gdimage function for the desired output, implemented by child classes | -## Options that affect this module +## Options that affect this class | property | type | |------------------------|----------------| diff --git a/docs/Built-In-Output/QRImagick.md b/docs/Built-In-Output/QRImagick.md index 24ce09600..433362c65 100644 --- a/docs/Built-In-Output/QRImagick.md +++ b/docs/Built-In-Output/QRImagick.md @@ -86,7 +86,7 @@ echo $imagick->getImageBlob(); | (protected) `setTransparencyColor()` | `void` | Sets the transparency color | -## Options that affect this module +## Options that affect this class | property | type | |------------------------|----------| diff --git a/docs/Built-In-Output/QRInterventionImage.md b/docs/Built-In-Output/QRInterventionImage.md index e747d3c35..a7f06cd2d 100644 --- a/docs/Built-In-Output/QRInterventionImage.md +++ b/docs/Built-In-Output/QRInterventionImage.md @@ -86,7 +86,7 @@ $out = $qrOutputInterface->dump(); | (protected) `module()` | `void` | Draws a single pixel at the given position | -## Options that affect this module +## Options that affect this class | property | type | |------------------------|----------| diff --git a/docs/Built-In-Output/QRMarkupHTML.md b/docs/Built-In-Output/QRMarkupHTML.md index e6fb9c454..0f3106885 100644 --- a/docs/Built-In-Output/QRMarkupHTML.md +++ b/docs/Built-In-Output/QRMarkupHTML.md @@ -79,26 +79,9 @@ header('Content-type: text/html'); | (protected) `getCssClass(int $M_TYPE = 0)` | `string` | Returns a string with all css classes for the current element | -## Options that affect this module +## Options that affect this class | property | type | |----------------|----------| | `$cssClass` | `string` | | `$eol` | `string` | - - -### Options that have no effect - -| 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/Customizing/Custom-output-interface.md b/docs/Customizing/Custom-output-interface.md index 338335949..33c2fd588 100644 --- a/docs/Customizing/Custom-output-interface.md +++ b/docs/Customizing/Custom-output-interface.md @@ -89,10 +89,20 @@ In order to do so, we need to collect the modules per `$M_TYPE` before we can re } ``` -We've introduced another method that handles the module rendering, which incooperates handling of the `QROptions::$drawLightModules` setting: +Speaking of option settings, there's also `QROptions::$connectPaths` which we haven't taken care of yet - the good news is that we don't need to as it is already implemented! +We'll modify the above `dump()` method to use `QROutputAbstract::collectModules()` instead. + +The module collector calls a method `moduleTransform()` internally, which is called with 4 parameters: + +- `$x` : current column +- `$y` : current row +- `$M_TYPE` : field value +- `$M_TYPE_LAYER`: (possibly modified) field value that acts as layer id + +We'## introduce another method that handles the module rendering, which incooperates handling of the `QROptions::$drawLightModules` setting: ```php - protected function module(int $x, int $y, int $M_TYPE):string{ + protected function moduleTransform(int $x, int $y, int $M_TYPE, int $M_TYPE_LAYER):string{ if(!$this->drawLightModules && !$this->matrix->isDark($M_TYPE)){ return ''; @@ -102,33 +112,12 @@ We've introduced another method that handles the module rendering, which incoope } ``` -Speaking of option settings, there's also `QROptions::$connectPaths` which we haven't taken care of yet - the good news is that we don't need to as it is already implemented! -We'll modify the above `dump()` method to use `QROutputAbstract::collectModules()` instead. - -The module collector accepts a `Closure` as its only parameter, which is called with 4 parameters: - -- `$x` : current column -- `$y` : current row -- `$M_TYPE` : field value -- `$M_TYPE_LAYER`: (possibly modified) field value that acts as layer id - -We only need the first 3 parameters, so our closure would look as follows: - -```php -$closure = fn(int $x, int $y, int $M_TYPE):string => $this->module($x, $y, $M_TYPE); -``` - -As of PHP 8.1+ we can narrow this down with the [first class callable syntax](https://www.php.net/manual/en/functions.first_class_callable_syntax.php): - -```php -$closure = $this->module(...); -``` This is our final output method then: ```php public function dump(string $file = null):string{ - $collections = $this->collectModules($this->module(...)); + $collections = $this->collectModules(); // build the final output $out = []; @@ -151,8 +140,7 @@ This is our final output method then: To run the output we just need to set the `QROptions::$outputInterface` to our custom class: ```php -$options = new QROptions; -$options->outputType = QROutputInterface::CUSTOM; +$options = new QROptions; $options->outputInterface = MyCustomOutput::class; $options->connectPaths = true; $options->drawLightModules = true; @@ -169,7 +157,20 @@ $qrcode->addByteSegment('test'); var_dump($qrcode->render()); ``` +Alternatively, you can invoke the `QROutputInterface` manually: + +```php +$qrcode = new QRCode($options); +$qrOutputInterface = new MyCustomOutput($options, $qrcode->getMatrix($data)); + +//dump the output, which is equivalent to QRCode::render() +$qrOutputInterface->dump(); +// render to file +$qrOutputInterface->dump('/path/to/qrcode.svg'); +``` + The output looks similar to the following: + ``` these-modules-are-light (000000000010) @@ -227,7 +228,7 @@ class MyCustomOutput extends QROutputAbstract{ return implode("\n", $out); } - protected function module(int $x, int $y, int $M_TYPE):string{ + protected function moduleTransform(int $x, int $y, int $M_TYPE, int $M_TYPE_LAYER):string{ if(!$this->drawLightModules && !$this->matrix->isDark($M_TYPE)){ return ''; diff --git a/docs/Customizing/QROutputAbstract.md b/docs/Customizing/QROutputAbstract.md index 5eba80063..bc557b6be 100644 --- a/docs/Customizing/QROutputAbstract.md +++ b/docs/Customizing/QROutputAbstract.md @@ -117,7 +117,6 @@ class MyOutput extends QROutputAbstract{ Both methods return a module value, the main difference is that `getModuleValueAt()` is a convenience method that makes an extra call to retrieve the `$M_TYPE` from the given matrix coordinate to return the value via `getModuleValue()`. - A `foreach` loop over the matrix gives you the key (coordinate) *and* value of an array element: ```php @@ -222,6 +221,7 @@ class MyOutput extends QROutputAbstract{ return implode($this->options->eol, $paths); } + // this method must be implemented/overridden if your output class uses the module collector protected function moduleTransform(int $x, int $y, int $M_TYPE, int $M_TYPE_LAYER):string{ return sprintf('%d %d %012b', $x, $y, $M_TYPE); } @@ -235,11 +235,8 @@ Sometimes it can be necessary to override `collectModules()` in order to apply s ### `saveToFile()` and `toBase64DataURI()` The void method `saveToFile()` takes a data blob and the `$file` given in `QROutputInterface::dump()` and save to the path if it is not `null` - the file path itself is not checked except for writability. - The final output can be transformed to a [base64 data URI](https://en.wikipedia.org/wiki/Data_URI_scheme) with `toBase64DataURI()`, where the data blob and a valid mime type as parameters - the mime type is not checked. - - ```php class MyOutput extends QROutputAbstract{ diff --git a/docs/Usage/Overview.md b/docs/Usage/Overview.md index 6addcb459..fbbc6467e 100644 --- a/docs/Usage/Overview.md +++ b/docs/Usage/Overview.md @@ -51,28 +51,29 @@ For the QR Code reader, either `ext-gd` or `ext-imagick` is required! - [Filament](https://github.com/filamentphp/filament) - Symfony: - [phpqrcode-bundle](https://github.com/jonasarts/phpqrcode-bundle) +- WoltLab Suite: + - [two-step-verification](http://pluginstore.woltlab.com/file/3007-two-step-verification/) + - [[Developer] PHP QR Code](https://www.woltlab.com/pluginstore/file/7995-entwickler-php-qr-code/) - 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/) - - [[Developer] PHP QR Code](https://www.woltlab.com/pluginstore/file/7995-entwickler-php-qr-code/) - 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) - - [OSIRIS](https://github.com/JKoblitz/osiris) - [EspoCRM](https://github.com/espocrm/espocrm) - [FusionCMS](https://github.com/FusionWowCMS/FusionCMS) - [HortusFox](https://github.com/danielbrendel/hortusfox-web) - - [Pelican Panel](https://github.com/pelican-dev/panel) - [Laravel Boleto](https://github.com/eduardokum/laravel-boleto) + - [LORIS](https://github.com/aces/Loris) - [OpenBoleto](https://github.com/openboleto/openboleto) + - [openITCOCKPIT](https://github.com/it-novum/openITCOCKPIT) + - [OSIRIS](https://github.com/JKoblitz/osiris) + - [Pelican Panel](https://github.com/pelican-dev/panel) + - [twill](https://github.com/area17/twill) - Articles: - [Twilio: How to Create a QR Code in PHP](https://www.twilio.com/blog/create-qr-code-in-php) (featuring v4.3.x) diff --git a/docs/index.rst b/docs/index.rst index e20a44a71..3b4f36e07 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,7 +32,7 @@ This work is licensed under the Creative Commons Attribution 4.0 International ( .. toctree:: :maxdepth: 3 - :caption: Built-In Output Modules + :caption: Built-In Output Classes Built-In-Output/QREps.md Built-In-Output/QRFpdf.md