Merge pull request #3 from evosys21/feature/dev-v1.0.0

Feature/dev v1.0.0

README.md

@@ -1,83 +1,129 @@
-# Fpdf, TCPDF, tFpdf - Advanced Multicell and Table 
+<h1>Fpdf, TCPDF, tFpdf - Advanced Multicell and Table</h1>
 
-`evosys21/pdflib` is a collection of PHP classes facilitating developers to create [Advanced Multicells]() and [Tables]() in [FPDF](http://www.fpdf.org), [TCPDF](https://github.com/tecnickcom/TCPDF) or 
-[tFPDF](http://fpdf.org/en/script/script92.php).
+[![Build status](https://github.com/evosys21/pdflib/workflows/build/badge.svg)](https://github.com/evosys21/pdflib/actions)
+[![Latest Stable Version](https://poser.pugx.org/evosys21/phplib/v/stable)](https://packagist.org/packages/evosys21/phplib)
 
+<!-- TOC -->
+  * [Overview](#overview)
+  * [Advanced Multicell](#advanced-multicell)
+    * [Features](#features)
+    * [Examples](#examples)
+    * [Usage and documentation](#usage-and-documentation)
+  * [Advanced table](#advanced-table)
+    * [Features](#features-1)
+    * [Examples](#examples-1)
+    * [Usage and documentation](#usage-and-documentation-1)
+  * [FAQ](#faq)
+    * [Why use the custom pdf class instead of `FPDF/TCPDF/tFPDF`](#why-use-the-custom-pdf-class-instead-of-fpdftcpdftfpdf)
+    * [Where do I report issues?](#where-do-i-report-issues)
+  * [Contribute](#contribute)
+  * [License](#license)
+<!-- TOC --> 
 
-[![Build status](https://github.com/evosys21/pdflib/workflows/build/badge.svg)](https://github.com/evosys21/pdflib/actions) [![Latest Stable Version](https://poser.pugx.org/evosys21/phplib/v/stable)](https://packagist.org/packages/evosys21/phplib)
+---
 
-## Contents
+## Overview
 
-<!-- TOC -->
-* [Fpdf, TCPDF, tFpdf - Advanced Multicell and Table](#fpdf-tcpdf-tfpdf---advanced-multicell-and-table-)
-  * [Contents](#contents)
-  * [Installation with Composer](#installation-with-composer)
-  * [Example and Documentation](#example-and-documentation)
-    * [Advanced Multicell](#advanced-multicell)
-    * [Advanced table](#advanced-table)
-  * [FAQ 🔮](#faq-)
-    * [Where do I report issues?](#where-do-i-report-issues)
-  * [Contribute 🚀](#contribute-)
-  * [License 📗](#license-)
-<!-- TOC -->
+`evosys21/pdflib` is a collection of PHP classes facilitating developers to create [Advanced Multicells](#advanced-multicell) and [Tables](#advanced-table) in [FPDF](http://www.fpdf.org), [TCPDF](https://github.com/tecnickcom/TCPDF), or
+[tFPDF](http://fpdf.org/en/script/script92.php).
 
-***
+## Advanced Multicell
 
-## Installation with Composer
+This addon class allows the creation of an **Advanced Multicell for FPDF/TCPDF/tFPDF**, which uses as input a TAG-based formatted
+string instead of a simple string. The use of tags allows changing the font, style (bold, italic, underline),
+size, and color of characters and many other features.
 
-`evosys21/pdflib` can be used with FPDF, TCPDF or tFPDF. Because of this we haven't added a fixed dependency in the main composer.json file. You need to add the dependency to the PDF generation library of your choice yourself.
+The function is similar to the Multicell function in the TCPDF base class with extended parameters.
 
-To use `evosys21/pdflib` with FPDF, install it via Composer:
+### Features
 
-```shell
-composer require evosys21/pdflib
-composer require setasign/fpdf
-```
+- Text can be **aligned**, **centered**, or **justified**.
+- Different **fonts**, **sizes**, **styles**, and **colors** can be used.
+- The cell block can be **framed**, and the **background** can be **colored**.
+- **Links** can be used in any tag.
+- **TAB** spaces (`\t`) can be used.
+- Variable vertical positions can be used for **subscripts** or **superscripts**.
+- **Cell padding** (left, right, top, bottom) can be adjusted.
+- Controlled **tag sizes** can be used.
+
+### Examples
 
-If you want to use TCPDF:
+|         | Multicell Example #1 - Overview                                                                                             | multicell Example #1 - Overview                                                                                               | 
+|---------|-----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
+| Code    | [example-multicell-1-overview.php](examples/Tcpdf/example-multicell-1-overview.php)                                         | [example-multicell-6-shrinking.php](examples/Tcpdf/example-multicell-6-shrinking.php)                                         |
+| Preview | [<img src="examples/Tcpdf/example-multicell-1-overview.png" height="300">](examples/Tcpdf/example-multicell-1-overview.pdf) | [<img src="examples/Tcpdf/example-multicell-6-shrinking.png" height="300">](examples/Tcpdf/example-multicell-6-shrinking.pdf) |
+| Pdf     | [example-multicell-1-overview.pdf](examples/Tcpdf/example-multicell-1-overview.pdf)                                         | [example-multicell-1-overview.pdf](examples/Tcpdf/example-multicell-1-overview.pdf)                                           |      |
 
-```shell
-composer require evosys21/pdflib
-composer require tecnickcom/tcpdf
-```
+Check the [examples](examples) folder for more examples with preview and the associated code.
 
-If you want to use tFPDF:
+### Usage and documentation
 
-```shell
-composer require evosys21/pdflib
-composer require setasign/tfpdf
-```
+[Click here](docs/multicell.md) for the end-user documentation for Advanced Multicell.
 
-## Example and Documentation
+## Advanced table
 
-### Advanced Multicell
+This addon class allows creation of an **Advanced Table for FPDF/TCPDF/tFPDF** in the pdf document in a very simple way.
 
-A full end-user documentation for Advanced Multicell is available [here](docs/multicell.md).
+### Features
 
-### Advanced table
+- Every table cell supports [Advanced Multicell](#advanced-multicell) functionality.
+- Table cells can be aligned both **vertically** and **horizontally**.
+- Cells can span multiple **columns** and **rows**.
+- The table automatically splits on **page breaks**.
+- The **header** is automatically added to every new page.
+- Default properties for **headers** and **rows** can be set but can be overridden per individual cell.
+- **Advanced cell-splitting mode** is available.
+- The table supports **transparency**.
+- **Images** can be inserted into table cells.
 
 A full end-user documentation for Advanced Table is available [here](docs/table.md).
 
-## FAQ 🔮
+### Examples
+
+|         | Table Example #1 - Overview                                                                                         | Table Example #1 - Overview                                                                                         | 
+|---------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
+| Code    | [example-table-1-overview.php](examples/Tcpdf/example-table-1-overview.php)                                         | [example-table-2-overview.php](examples/Tcpdf/example-table-2-overview.php)                                         |
+| Preview | [<img src="examples/Tcpdf/example-table-1-overview.png" height="300">](examples/Tcpdf/example-table-1-overview.pdf) | [<img src="examples/Tcpdf/example-table-2-overview.png" height="300">](examples/Tcpdf/example-table-2-overview.pdf) |
+| Pdf     | [example-table-1-overview.pdf](examples/Tcpdf/example-table-1-overview.pdf)                                         | [example-table-1-overview.pdf](examples/Tcpdf/example-table-1-overview.pdf)                                         |      |
+
+### Usage and documentation
+
+[Click here](docs/table.md) for the end-user documentation for Advanced Table.
+
+## FAQ
+
+### Why use the custom pdf class instead of `FPDF/TCPDF/tFPDF`
+
+The custom `EvoSys21\PdfLib\Fpdf\Pdf` object is used instead of `FPDF` because `FPDF`'s private/protected properties,
+like widths, margins, and fonts, need to be accessed to implement add-ons.  
+Since `FPDF` doesn't provide setters/getters for these properties, the class was extended to access them.
+
+The same is valid for all 3 pdf classes: `FPDF/TCPDF/tFPDF`.
+
+For more details see:
+- [src/Fpdf/Pdf.php](src/Fpdf/Pdf.php)
+- [src/Tcpdf/Pdf.php](src/Tcpdf/Pdf.php)
+- [src/Tfpdf/Pdf.php](src/Tfpdf/Pdf.php)
 
 ### Where do I report issues?
 
-If something is not working as expected, please check or open an 
+If something is not working as expected, please check or open an
 [issue](https://github.com/evosys21/pdflib/issues).
 
 If you would like to discuss your use case or ask a general question, please use the discussions board:
 [discussions](https://github.com/evosys21/pdflib/discussions).
 
-## Contribute 🚀
+## Contribute
 
 We welcome contributors to the project.
+
 - Before opening a pull request, please create an issue to
   [discuss the scope of your proposal](https://github.com/evosys21/pdflib/issues).
 - Never send PR to `main` unless you want to contribute to the development
   version of the client (`main` represents the next major version).
-- Each PR should include a **unit test** using [PHPUnit](https://phpunit.de/).
+
 Thanks in advance for your contribution! :heart:
 
-## License 📗
+## License
 
 MIT License. For more information, please see the [LICENSE](LICENSE.TXT) file.

composer.json

@@ -28,14 +28,14 @@
     },
     "autoload": {
         "psr-4": {
-            "evosys21\\PdfLib\\": "src/"
+            "EvoSys21\\PdfLib\\": "src/"
         }
     },
     "autoload-dev": {
         "psr-4": {
-            "evosys21\\PdfLib\\Dev\\": "dev/",
-            "evosys21\\PdfLib\\Tests\\": "tests/",
-            "evosys21\\PdfLib\\Examples\\": "examples/"
+            "EvoSys21\\PdfLib\\Dev\\": "dev/",
+            "EvoSys21\\PdfLib\\Tests\\": "tests/",
+            "EvoSys21\\PdfLib\\Examples\\": "examples/"
         }
     }
 }

dev/DevFactory.php

@@ -1,15 +1,15 @@
 <?php
 
-namespace evosys21\PdfLib\Dev;
-
-use evosys21\PdfLib\Multicell;
-use evosys21\PdfLib\Table;
-use evosys21\PdfLib\Examples\Fpdf\PdfFactory as FpdfFactory;
-use evosys21\PdfLib\Examples\Fpdf\PdfSettings as FpdfSettings;
-use evosys21\PdfLib\Examples\Tcpdf\PdfFactory as TcpdfFactory;
-use evosys21\PdfLib\Examples\Tcpdf\PdfSettings as TcpdfSettings;
-use evosys21\PdfLib\Examples\Tfpdf\PdfFactory as TfpdfFactory;
-use evosys21\PdfLib\Examples\Tfpdf\PdfSettings as TfpdfSettings;
+namespace EvoSys21\PdfLib\Dev;
+
+use EvoSys21\PdfLib\Multicell;
+use EvoSys21\PdfLib\Table;
+use EvoSys21\PdfLib\Examples\Fpdf\PdfFactory as FpdfFactory;
+use EvoSys21\PdfLib\Examples\Fpdf\PdfSettings as FpdfSettings;
+use EvoSys21\PdfLib\Examples\Tcpdf\PdfFactory as TcpdfFactory;
+use EvoSys21\PdfLib\Examples\Tcpdf\PdfSettings as TcpdfSettings;
+use EvoSys21\PdfLib\Examples\Tfpdf\PdfFactory as TfpdfFactory;
+use EvoSys21\PdfLib\Examples\Tfpdf\PdfSettings as TfpdfSettings;
 
 class DevFactory
 {

dev/dev-example-multicell.php

@@ -5,8 +5,8 @@
 
 require_once __DIR__ . '/../autoload.php';
 
-use evosys21\PdfLib\Fpdf\Pdf;
-use evosys21\PdfLib\Multicell;
+use EvoSys21\PdfLib\Fpdf\Pdf;
+use EvoSys21\PdfLib\Multicell;
 
 // Pdf extends FPDF
 $pdf = new Pdf();

dev/dev-multicell-shrinking4.php

@@ -3,8 +3,8 @@
  * Pdf Advanced Multicell - Example
  */
 
-use evosys21\PdfLib\Dev\DevFactory;
-use evosys21\PdfLib\Examples\Fpdf\PdfSettings;
+use EvoSys21\PdfLib\Dev\DevFactory;
+use EvoSys21\PdfLib\Examples\Fpdf\PdfSettings;
 
 $factory = new DevFactory();
 

dev/dev-multicell-style-inheritance.php

@@ -5,8 +5,8 @@
 
 require_once __DIR__ . '/../autoload.php';
 
-use evosys21\PdfLib\Fpdf\Pdf;
-use evosys21\PdfLib\Multicell;
+use EvoSys21\PdfLib\Fpdf\Pdf;
+use EvoSys21\PdfLib\Multicell;
 
 // Pdf extends FPDF
 $pdf = new Pdf();

dev/dev-multicell-style-inheritance1.php

@@ -5,8 +5,8 @@
 
 require_once __DIR__ . '/../autoload.php';
 
-use evosys21\PdfLib\Fpdf\Pdf;
-use evosys21\PdfLib\Multicell;
+use EvoSys21\PdfLib\Fpdf\Pdf;
+use EvoSys21\PdfLib\Multicell;
 
 // Pdf extends FPDF
 $pdf = new Pdf();

dev/dev-multicell-style.php

@@ -3,7 +3,7 @@
  * Pdf Advanced Multicell - Example
  */
 
-use evosys21\PdfLib\Tools;
+use EvoSys21\PdfLib\Tools;
 
 $factory = new DevFactory();
 

dev/dev-multicell-style1.php

@@ -3,7 +3,7 @@
  * Pdf Advanced Multicell - Example
  */
 
-use evosys21\PdfLib\Tools;
+use EvoSys21\PdfLib\Tools;
 
 $factory = new DevFactory();
 

dev/example-multicell-dev.php

@@ -5,8 +5,8 @@
 
 require_once __DIR__ . '/../autoload.php';
 
-use evosys21\PdfLib\Fpdf\Pdf;
-use evosys21\PdfLib\Multicell;
+use EvoSys21\PdfLib\Fpdf\Pdf;
+use EvoSys21\PdfLib\Multicell;
 
 // Pdf extends FPDF
 $pdf = new Pdf();

dev/example-table-dev.php

@@ -5,9 +5,9 @@
 
 require_once __DIR__ . '/../autoload.php';
 
-use evosys21\PdfLib\Fpdf\Pdf;
-use evosys21\PdfLib\Table;
-use evosys21\PdfLib\Table\Cell\Image;
+use EvoSys21\PdfLib\Fpdf\Pdf;
+use EvoSys21\PdfLib\Table;
+use EvoSys21\PdfLib\Table\Cell\Image;
 
 // Pdf extends FPDF
 $pdf = new Pdf();

dev/example-table-dev1.php

@@ -5,8 +5,8 @@
 
 require_once __DIR__ . '/../autoload.php';
 
-use evosys21\PdfLib\Fpdf\Pdf;
-use evosys21\PdfLib\Table;
+use EvoSys21\PdfLib\Fpdf\Pdf;
+use EvoSys21\PdfLib\Table;
 
 // Pdf extends FPDF
 $pdf = new Pdf();

dev/samples/sample-test-code.php

@@ -5,8 +5,6 @@
 
 require_once __DIR__ . '/../autoload.php';
 
-$factory = new PdfFactory();
-
 //get the PDF object
 $pdf = PdfFactory::newPdf('multicell');
 

dev/table/disable-page-break.php

@@ -1,6 +1,6 @@
 <?php
 
-use evosys21\PdfLib\Table;
+use EvoSys21\PdfLib\Table;
 
 if (!isset($splitMode)) {
     $splitMode = true;

dev/table/draw-table-model1.php

@@ -1,6 +1,6 @@
 <?php
 
-use evosys21\PdfLib\Table;
+use EvoSys21\PdfLib\Table;
 global $pdf;
 
 if (!isset($splitMode)) {

dev/table/draw-table-model2.php

@@ -1,6 +1,6 @@
 <?php
 
-use evosys21\PdfLib\Table;
+use EvoSys21\PdfLib\Table;
 
 if (!isset($splitMode)) {
     $splitMode = true;

dev/test-multicell-align.php

@@ -1,6 +1,6 @@
 <?php
 
-use evosys21\PdfLib\Dev\DevFactory;
+use EvoSys21\PdfLib\Dev\DevFactory;
 
 require_once __DIR__ . '/autoload.php';
 

dev/test-multicell-shrinking.php

@@ -1,6 +1,6 @@
 <?php
 
-use evosys21\PdfLib\Dev\DevFactory;
+use EvoSys21\PdfLib\Dev\DevFactory;
 
 require_once __DIR__ . '/autoload.php';
 

dev/test-multicell-shrinking2.php

@@ -1,6 +1,6 @@
 <?php
 
-use evosys21\PdfLib\Dev\DevFactory;
+use EvoSys21\PdfLib\Dev\DevFactory;
 
 require_once __DIR__ . '/autoload.php';
 

dev/test-multicell-style.php

@@ -1,7 +1,7 @@
 <?php
 
-use evosys21\PdfLib\Dev\DevFactory;
-use evosys21\PdfLib\Tools;
+use EvoSys21\PdfLib\Dev\DevFactory;
+use EvoSys21\PdfLib\Tools;
 
 require_once __DIR__ . '/autoload.php';
 

dev/test-table1.php

@@ -1,6 +1,6 @@
 <?php
 
-use evosys21\PdfLib\Dev\DevFactory;
+use EvoSys21\PdfLib\Dev\DevFactory;
 
 require_once __DIR__ . '/autoload.php';