Merge pull request #264 from sprain/tafel-scissors-master

Add possibility to show scissors and more display options

.gitignore

@@ -6,5 +6,6 @@
 /example/HtmlOutput/html-example.htm
 /example/FpdfOutput/fpdf_example.pdf
 /.php-cs-fixer.cache
+/.phpunit.result.cache
 /composer.lock
 .idea/

README.md

@@ -79,3 +79,14 @@ The repository contains the official specifications the library is based on:
 
 For more official information see
 - [https://www.six-group.com/en/products-services/banking-services/payment-standardization/standards/qr-bill.html](https://www.six-group.com/en/products-services/banking-services/payment-standardization/standards/qr-bill.html)
+
+## For contributors of this libray
+
+How to generate new test data:
+
+1. Set `$regenerateReferenceFiles = true` in `TestQrBillCreatorTrait`
+2. `composer update --prefer-lowest`
+3. `vendor/bin/phpunit` – ignore failing tests in `testQrFile`
+4. `composer update`
+5. `vendor/bin/phpunit` – there should be no more errors
+6. Set `$regenerateReferenceFiles = false` in `TestQrBillCreatorTrait`

example/FpdfOutput/fpdf-example.php

@@ -1,6 +1,7 @@
 <?php declare(strict_types=1);
 
 use Sprain\SwissQrBill as QrBill;
+use Sprain\SwissQrBill\PaymentPart\Output\DisplayOptions;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
@@ -16,15 +17,31 @@
 //     use \Fpdf\Traits\MemoryImageSupport\MemImageTrait;
 // };
 
+// In case you want to draw scissors and dashed lines, use this way to create your FPDF instance:
+// $fpdf = new class('P', 'mm', 'A4') extends \Fpdf\Fpdf {
+//    use \Sprain\SwissQrBill\PaymentPart\Output\FpdfOutput\FpdfTrait;
+// };
+
 $fpdf->AddPage();
 
 // 3. Create a full payment part for FPDF
 $output = new QrBill\PaymentPart\Output\FpdfOutput\FpdfOutput($qrBill, 'en', $fpdf);
+
+// 4. Optional, set layout options
+$displayOptions = new DisplayOptions();
+$displayOptions
+    ->setPrintable(false) // true to remove lines for printing on a perforated stationery
+    ->setDisplayTextDownArrows(false) // true to show arrows next to separation text, if shown
+    ->setDisplayScissors(false) // true to show scissors instead of separation text
+    ->setPositionScissorsAtBottom(false) // true to place scissors at the bottom, if shown
+;
+
+// 5. Generate the output
 $output
-    ->setPrintable(false)
+    ->setDisplayOptions($displayOptions)
     ->getPaymentPart();
 
-// 4. For demo purposes, let's save the generated example in a file
+// 6. For demo purposes, let's save the generated example in a file
 $examplePath = __DIR__ . "/fpdf_example.pdf";
 $fpdf->Output($examplePath, 'F');
 

example/HtmlOutput/html-example.php

@@ -1,6 +1,7 @@
 <?php declare(strict_types=1);
 
 use Sprain\SwissQrBill as QrBill;
+use Sprain\SwissQrBill\PaymentPart\Output\DisplayOptions;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
@@ -10,11 +11,21 @@
 // 2. Create a full payment part in HTML
 $output = new QrBill\PaymentPart\Output\HtmlOutput\HtmlOutput($qrBill, 'en');
 
+// 3. Optional, set layout options
+$displayOptions = new DisplayOptions();
+$displayOptions
+    ->setPrintable(false) // true to remove lines for printing on a perforated stationery
+    ->setDisplayTextDownArrows(false) // true to show arrows next to separation text, if shown
+    ->setDisplayScissors(false) // true to show scissors instead of separation text
+    ->setPositionScissorsAtBottom(false) // true to place scissors at the bottom, if shown
+;
+
+// 4. Create a full payment part in HTML
 $html = $output
-    ->setPrintable(false)
+    ->setDisplayOptions($displayOptions)
     ->getPaymentPart();
 
-// 3. For demo purposes, let's save the generated example in a file
+// 5. For demo purposes, let's save the generated example in a file
 $examplePath = __DIR__ . '/html-example.htm';
 file_put_contents($examplePath, $html);
 

example/TcPdfOutput/tcpdf-example.php

@@ -1,6 +1,7 @@
 <?php declare(strict_types=1);
 
 use Sprain\SwissQrBill as QrBill;
+use Sprain\SwissQrBill\PaymentPart\Output\DisplayOptions;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
@@ -16,11 +17,22 @@
 
 // 3. Create a full payment part for TcPDF
 $output = new QrBill\PaymentPart\Output\TcPdfOutput\TcPdfOutput($qrBill, 'en', $tcPdf);
+
+// 4. Optional, set layout options
+$displayOptions = new DisplayOptions();
+$displayOptions
+    ->setPrintable(false) // true to remove lines for printing on a perforated stationery
+    ->setDisplayTextDownArrows(false) // true to show arrows next to separation text, if shown
+    ->setDisplayScissors(false) // true to show scissors instead of separation text
+    ->setPositionScissorsAtBottom(false) // true to place scissors at the bottom, if shown
+;
+
+// 5. Generate the output
 $output
-    ->setPrintable(false)
+    ->setDisplayOptions($displayOptions)
     ->getPaymentPart();
 
-// 4. For demo purposes, let's save the generated example in a file
+// 6. For demo purposes, let's save the generated example in a file
 $examplePath = __DIR__ . "/tcpdf_example.pdf";
 $tcPdf->Output($examplePath, 'F');
 

src/PaymentPart/Output/AbstractOutput.php

@@ -4,7 +4,6 @@
 
 use Sprain\SwissQrBill\DataGroup\Element\PaymentReference;
 use Sprain\SwissQrBill\PaymentPart\Output\Element\FurtherInformation;
-use Sprain\SwissQrBill\PaymentPart\Output\Element\OutputElementInterface;
 use Sprain\SwissQrBill\PaymentPart\Output\Element\Placeholder;
 use Sprain\SwissQrBill\PaymentPart\Output\Element\Text;
 use Sprain\SwissQrBill\PaymentPart\Output\Element\Title;
@@ -15,14 +14,14 @@ abstract class AbstractOutput implements OutputInterface
 {
     protected QrBill $qrBill;
     protected string $language;
-    protected bool $printable;
     protected string $qrCodeImageFormat;
+    private DisplayOptions $displayOptions;
 
     public function __construct(QrBill $qrBill, string $language)
     {
         $this->qrBill = $qrBill;
         $this->language = $language;
-        $this->printable = false;
+        $this->displayOptions = new DisplayOptions();
         $this->qrCodeImageFormat = QrCode::FILE_FORMAT_SVG;
     }
 
@@ -36,16 +35,36 @@ public function getLanguage(): ?string
         return $this->language;
     }
 
+    /**
+     * @deprecated Will be removed in next major release. Use setDisplayOptions() instead.
+     */
     public function setPrintable(bool $printable): static
     {
-        $this->printable = $printable;
+        $this->displayOptions->setPrintable($printable);
 
         return $this;
     }
 
+    /**
+     * @deprecated Will be removed in next major release. Use getDisplayOptions() instead.
+     */
     public function isPrintable(): bool
     {
-        return $this->printable;
+        return $this->displayOptions->isPrintable();
+    }
+
+    public function setDisplayOptions(DisplayOptions $displayOptions): static
+    {
+        $this->displayOptions = $displayOptions;
+
+        return $this;
+    }
+
+    public function getDisplayOptions(): DisplayOptions
+    {
+        $this->displayOptions->consolidate();
+
+        return $this->displayOptions;
     }
 
     public function setQrCodeImageFormat(string $fileExtension): static

src/PaymentPart/Output/DisplayOptions.php

@@ -0,0 +1,98 @@
+<?php declare(strict_types=1);
+
+namespace Sprain\SwissQrBill\PaymentPart\Output;
+
+final class DisplayOptions
+{
+    private bool $isPrintable = false;
+    private bool $displayScissors = false;
+    private bool $positionScissorsAtBottom = false;
+    private bool $displayTextDownArrows = false;
+    private bool $displayText = true;
+    private string $lineStyle = LineStyle::SOLID;
+
+    public function isPrintable(): bool
+    {
+        return $this->isPrintable;
+    }
+
+    public function setPrintable(bool $isPrintable): self
+    {
+        $this->isPrintable = $isPrintable;
+
+        return $this;
+    }
+
+    public function isDisplayScissors(): bool
+    {
+        return $this->displayScissors;
+    }
+
+    public function setDisplayScissors(bool $displayScissors): self
+    {
+        $this->displayScissors = $displayScissors;
+
+        return $this;
+    }
+
+    public function isPositionScissorsAtBottom(): bool
+    {
+        return $this->positionScissorsAtBottom;
+    }
+
+    public function setPositionScissorsAtBottom(bool $positionScissorsAtBottom): self
+    {
+        $this->positionScissorsAtBottom = $positionScissorsAtBottom;
+
+        return $this;
+    }
+
+    public function isDisplayTextDownArrows(): bool
+    {
+        return $this->displayTextDownArrows;
+    }
+
+    public function setDisplayTextDownArrows(bool $displayTextDownArrows): self
+    {
+        $this->displayTextDownArrows = $displayTextDownArrows;
+
+        return $this;
+    }
+
+    public function isDisplayText(): bool
+    {
+        return $this->displayText;
+    }
+
+    public function getLineStyle(): string
+    {
+        return $this->lineStyle;
+    }
+
+    /**
+     * @internal
+     */
+    public function consolidate(): void
+    {
+        $this->lineStyle = $this->displayScissors ? LineStyle::DASHED : LineStyle::SOLID;
+
+        if ($this->isPrintable) {
+            $this->lineStyle = LineStyle::NONE;
+        }
+
+        if ($this->displayScissors) {
+            $this->displayText = false;
+            $this->displayTextDownArrows = false;
+        }
+    }
+}
+
+/**
+ * @internal
+ */
+final class LineStyle
+{
+    public const SOLID = 'SOLID';
+    public const DASHED = 'DASHED';
+    public const NONE = 'NONE';
+}