xref: /plugin/dw2pdf/vendor/setasign/fpdi/README.md (revision 01d4b863f647689752623420d92bf6c538d91460) 
1FPDI - Free PDF Document Importer
2=================================
3
4[![Latest Stable Version](https://poser.pugx.org/setasign/fpdi/v/stable.svg)](https://packagist.org/packages/setasign/fpdi)
5[![Total Downloads](https://poser.pugx.org/setasign/fpdi/downloads.svg)](https://packagist.org/packages/setasign/fpdi)
6[![License](https://poser.pugx.org/setasign/fpdi/license.svg)](https://packagist.org/packages/setasign/fpdi)
7
8:heavy_exclamation_mark: This document refers to FPDI 2. Version 1 is deprecated and development is discontinued. :heavy_exclamation_mark:
9
10FPDI is a collection of PHP classes facilitating developers to read pages from existing PDF
11documents and use them as templates in [FPDF](http://www.fpdf.org), which was developed by Olivier Plathey. Apart
12from a copy of [FPDF](http://www.fpdf.org), FPDI does not require any special PHP extensions.
13
14FPDI can also be used as an extension for [TCPDF](https://github.com/tecnickcom/TCPDF) or
15[tFPDF](http://fpdf.org/en/script/script92.php), too.
16
17## Installation with [Composer](https://packagist.org/packages/setasign/fpdi)
18
19Because FPDI can be used with FPDF, TCPDF or tFPDF we haven't added a fixed dependency in the main
20composer.json file. You need to add the dependency to the PDF generation library of your choice
21yourself.
22
23To use FPDI with FPDF include following in your composer.json file:
24
25```json
26{
27    "require": {
28        "setasign/fpdf": "1.8.*",
29        "setasign/fpdi": "^2.5"
30    }
31}
32```
33
34If you want to use TCPDF, you have to update your composer.json to:
35
36```json
37{
38    "require": {
39        "tecnickcom/tcpdf": "6.6.*",
40        "setasign/fpdi": "^2.5"
41    }
42}
43```
44
45If you want to use tFPDF, you have to update your composer.json to:
46
47```json
48{
49    "require": {
50        "setasign/tfpdf": "1.33.*",
51        "setasign/fpdi": "^2.3"
52    }
53}
54```
55
56## Manual Installation
57
58If you do not use composer, just require the autoload.php in the /src folder:
59
60```php
61require_once('src/autoload.php');
62```
63
64If you have a PSR-4 autoloader implemented, just register the src path as follows:
65```php
66$loader = new \Example\Psr4AutoloaderClass;
67$loader->register();
68$loader->addNamespace('setasign\Fpdi', 'path/to/src/');
69```
70
71## Changes to Version 1
72
73Version 2 is a complete rewrite from scratch of FPDI which comes with:
74- Namespaced code
75- Clean and up-to-date code base and style
76- PSR-4 compatible autoloading
77- Performance improvements by up to 100%
78- Less memory consumption
79- Native support for reading PDFs from strings or stream-resources
80- Support for documents with "invalid" data before their file-header
81- Optimized page tree resolving
82- Usage of individual exceptions
83- Several test types (unit, functional and visual tests)
84
85We tried to keep the main methods and logical workflow the same as in version 1 but please
86notice that there were incompatible changes which you should consider when updating to
87version 2:
88- You need to load the code using the `src/autoload.php` file instead of `classes/FPDI.php`.
89- The classes and traits are namespaced now: `setasign\Fpdi`
90- Page boundaries beginning with a slash, such as `/MediaBox`, are not supported anymore. Remove
91  the slash or use a constant of `PdfReader\PageBoundaries`.
92- The parameters $x, $y, $width and $height of the `useTemplate()` or `getTemplateSize()`
93  method have more logical correct default values now. Passing `0` as width or height will
94  result in an `InvalidArgumentException` now.
95- The return value of `getTemplateSize()` had changed to an array with more speaking keys
96  and reusability: Use `width` instead of `w` and `height` instead of `h`.
97- If you want to use **FPDI with TCPDF** you need to refactor your code to use the class `Tcpdf\Fpdi`
98(since 2.1; before it was `TcpdfFpdi`) instead of `FPDI`.
99
100## Example and Documentation
101
102A simple example, that imports a single page and places this onto a new created page:
103
104```php
105<?php
106use setasign\Fpdi\Fpdi;
107// or for usage with TCPDF:
108// use setasign\Fpdi\Tcpdf\Fpdi;
109
110// or for usage with tFPDF:
111// use setasign\Fpdi\Tfpdf\Fpdi;
112
113// setup the autoload function
114require_once('vendor/autoload.php');
115
116// initiate FPDI
117$pdf = new Fpdi();
118// add a page
119$pdf->AddPage();
120// set the source file
121$pdf->setSourceFile("Fantastic-Speaker.pdf");
122// import page 1
123$tplId = $pdf->importPage(1);
124// use the imported page and place it at point 10,10 with a width of 100 mm
125$pdf->useTemplate($tplId, 10, 10, 100);
126
127$pdf->Output();
128```
129
130A full end-user documentation and API reference is available [here](https://manuals.setasign.com/fpdi-manual/).
131