Merge branch 'release/5.0.0'

Author: ma4nn

.github/workflows/ci.yaml

@@ -1,13 +1,18 @@
 name: CI
 
-on: [pull_request]
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+      - develop
 
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php-version: [ "7.4", "8.0", "8.1", "8.2", "8.3" ]
+        php-version: [ "7.4", "8.0", "8.1", "8.2", "8.3", "8.4" ]
 
     steps:
     - uses: actions/checkout@v4
@@ -21,6 +26,12 @@ jobs:
       with:
         php_version: ${{ matrix.php-version }}
 
+    - uses: php-actions/composer@v6
+      with:
+        php_version: ${{ matrix.php-version }}
+        command: 'require'
+        args: 'horstoeko/zugferd tecnickcom/tcpdf'
+
     - name: Run PHPUnit tests
       run: vendor/bin/phpunit
 

CHANGELOG.md

@@ -4,9 +4,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [5.0.0] - 2025-01-10
+### Added
+- Merger for Zugferd PDFs, i.e. PDFs with XML attachments
+### Changed
+- TCPDF to Fpdf library for merging as default (both libraries supported now)
+- Several public interfaces to support type hints and make purpose clearer
+### Removed
+- Deprecated ZendPdf merger  
+
 ## [4.0.2] - 2024-10-13
 ### Changed
-- Updated dompdf library to 3.x
+- Dompdf library to version 3.x
 
 ## [4.0.1] - 2023-11-10
 ### Fixed

README.md

@@ -1,22 +1,24 @@
-# vianetz PDF Library
+# vianetz Pdf Library
 
 This library offers an easy-to-use API for PDF generation and merging.  
-Internally it uses the DomPDF library for PDF generation and TCPDF for merging.
+Internally it uses the [DomPDF library](https://github.com/dompdf/dompdf) for PDF generation and [FPDI](https://github.com/Setasign/FPDI) for merging.
+
+More information about this PDF API can also be found [on my website](https://www.vianetz.com/en/pdf-invoice-api-magento/).
 
 ## Usage
 
-### Create PDF document from HTML contents 
+### Create PDF document from HTML contents
+
 ```php
 // Create a new pdf instance.
-$pdf = Vianetz\Pdf\Model\PdfFactory::general()->create();
+$pdf = \Vianetz\Pdf\Model\PdfFactory::general()->create();
 
 // Create the document. You can return any kind of HTML content here.
-$document = new \Vianetz\Pdf\Model\Document();
-$document->setHtmlContents('<strong>Hello</strong> World!');
+$document = new \Vianetz\Pdf\Model\HtmlDocument('<strong>Hello</strong> World!');
 
 // Add our document to the pdf. You can add as many documents as you like
 // as they will all be merged into one PDF file.
-$pdf->addDocument($document);
+$pdf->add($document);
 
 // Save the resulting PDF to file test.pdf - That's it :-)
 $pdf->saveToFile('test.pdf');
@@ -28,15 +30,14 @@ $pdf->saveToFile('test.pdf');
 $pdfString = file_get_contents('test1.pdf');
 
 // Setup things
-$pdf = Vianetz\Pdf\Model\PdfFactory::general()->create();
-$pdfMerge = Vianetz\Pdf\Model\PdfMerge::create();
+$pdfMerge = \Vianetz\Pdf\Model\PdfMerge::create();
 
 // Do the merge.
-$pdfMerge->mergePdfString($pdfString);
+$pdfMerge->mergePdfString($pdfString, 'background.pdf');
 $pdfMerge->mergePdfFile('test2.pdf');
 
 // Save the result PDF to file result.pdf.
-$pdfMerge->saveToFile('result.pdf');
+file_put_contents($fileName, $pdfMerge->toPdf());
 ```
 
 ### Tips & Tricks
@@ -50,12 +51,6 @@ Please find the Frequently Asked Questions [on my website](https://www.vianetz.c
 If you have any issues or suggestions with this extension, please do not hesitate to
 [contact me](https://www.vianetz.com/en/contacts).
 
-## Credits
-Of course this extension would not have been possible without the great open source eco-system.
-Therewith credits go to:
-- [DomPDF](https://github.com/dompdf/dompdf)
-- [FPDI](https://github.com/Setasign/FPDI)
-
 ## License
 [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html)  
 See also LICENSE file.

composer.json

@@ -27,17 +27,18 @@
   "require": {
     "php": "^7.4|^8",
     "dompdf/dompdf": "^2.0|^3.0",
-    "setasign/fpdi": "^2.0",
-    "tecnickcom/tcpdf": "^6.4"
+    "setasign/fpdi": "^2.6",
+    "setasign/fpdf": "^1.8"
   },
   "require-dev": {
     "phpunit/phpunit": "^9|^10|^11",
     "phpstan/phpstan": "^1.8",
     "phpstan/phpstan-phpunit": "^1.1"
   },
   "suggest": {
+    "horstoeko/zugferd": "Create Zugferd documents with this merger library",
     "vianetz/signaturportal-api": "Use this library to sign your generated PDF documents.",
-    "zf1/zend-pdf": "Necessary if you want to use Zend_Pdf for merging. By default this package uses the fpdi merger."
+    "tecnickcom/tcpdf": "Necessary if you want to use TCPDF for merging. By default this package uses the fpdf merger."
   },
   "config": {
     "allow-plugins": {

src/Exception.php

@@ -1,7 +1,7 @@
 <?php
+declare(strict_types=1);
+
 /**
- * Pdf Exception Class
- *
  * @section LICENSE
  * This file is created by vianetz <[email protected]>.
  * The code is distributed under the GPL license.

src/FileNotFoundException.php

@@ -0,0 +1,24 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @section LICENSE
+ * This file is created by vianetz <[email protected]>.
+ * The code is distributed under the GPL license.
+ *
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to [email protected] so we can send you a copy immediately.
+ *
+ * @package     Vianetz\Pdf
+ * @author      Christoph Massmann, <[email protected]>
+ * @link        https://www.vianetz.com
+ * @copyright   Copyright (c) since 2006 vianetz - Dipl.-Ing. C. Massmann (https://www.vianetz.com)
+ * @license     http://www.gnu.org/licenses/gpl-3.0.txt GNU GENERAL PUBLIC LICENSE
+ */
+
+namespace Vianetz\Pdf;
+
+class FileNotFoundException extends \Exception
+{
+}

src/Model/PdfDocumentInterface.php renamed to src/Model/CanSave.php

@@ -1,4 +1,6 @@
 <?php
+declare(strict_types=1);
+
 /**
  * @section LICENSE
  * This file is created by vianetz <[email protected]>.
@@ -17,16 +19,12 @@
 
 namespace Vianetz\Pdf\Model;
 
-interface PdfDocumentInterface
+interface CanSave
 {
     /**
-     * @return string
-     */
-    public function getPdfFile();
-
-    /**
-     * @param string $pdfFile
-     * @return void
+     * @api
+     * @return bool true in case of success
+     * @throws \Vianetz\Pdf\NoDataException
      */
-    public function setPdfFile($pdfFile);
+    public function saveToFile(string $fileName): bool;
 }

src/Model/Document.php

@@ -1,7 +1,7 @@
 <?php
+declare(strict_types=1);
+
 /**
- * Event manager interface class
- *
  * @section LICENSE
  * This file is created by vianetz <[email protected]>.
  * The code is distributed under the GPL license.
@@ -27,9 +27,7 @@ interface EventManagerInterface
      * Calls all observer callbacks registered for this event
      * and multiple observers matching event name pattern
      *
-     * @param string $eventName
      * @param array<mixed,mixed> $data
-     * @return void
      */
-    public function dispatch($eventName, array $data = []);
+    public function dispatch(string $eventName, array $data = []): void;
 }