📖

Author: codemasher

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

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)
 

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

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

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

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

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

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 |

docs/Customizing/Custom-output-interface.md

@@ -89,46 +89,35 @@ 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:
-
-```php
-	protected function module(int $x, int $y, int $M_TYPE):string{
-
-		if(!$this->drawLightModules && !$this->matrix->isDark($M_TYPE)){
-			return '';
-		}
-
-		return sprintf('x: %s, y: %s', $x, $y);
-	}
-```
-
 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:
+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 only need the first 3 parameters, so our closure would look as follows:
+We'## introduce another method that handles the module rendering, which incooperates handling of the `QROptions::$drawLightModules` setting:
 
 ```php
-$closure = fn(int $x, int $y, int $M_TYPE):string => $this->module($x, $y, $M_TYPE);
-```
+	protected function moduleTransform(int $x, int $y, int $M_TYPE, int $M_TYPE_LAYER):string{
 
-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):
+		if(!$this->drawLightModules && !$this->matrix->isDark($M_TYPE)){
+			return '';
+		}
 
-```php
-$closure = $this->module(...);
+		return sprintf('x: %s, y: %s', $x, $y);
+	}
 ```
 
+
 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 '';

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{