Migrating from Version 1
Table of Contents
Introduction
FPDI version 2 is a complete rewrite of FPDI and comes with some backwards incompatibility changes.
Loading
Version 2 supports PSR-4 autoloading. A require of a classfile is obsolete but you can register FPDI in your own PSR-4 compatible autoload implementation or by simply requiring the file /src/autoload.php.
Namespaces
FPDI 2 uses namespaces throughout and no class is registered in the global namespace. The namespace of FPDI 2 is:
namespace setasign\Fpdi;
Class Names
Internally nearly all class names had changed. The public classes which are used in userland are renamed as following:
- FPDI
- \setasign\Fpdi\Fpdi
- FPDF_TPL
- \setasign\Fpdi\FpdfTpl
If you want to use FPDI with TCPDF you will need to use the new class \setasign\Fpdi\TcpdfFpdi.
FpdfTpl::beginTemplate()
The method signature had changed while the $x and $y parameter were removed:
Description
float|int|null $height = null,
bool $groupXObject = false
Begins a new template.
Parameters
- $width : float|int|null
The width of the template. If null, the current page width is used.
- $height : float|int|null
The height of the template. If null, the current page height is used.
- $groupXObject : bool
Define the form XObject as a group XObject to support transparency (if used).
Return Values
A template identifier.
getTemplateSize()
The default values of $width and $height were changed to null instead of 0 in all implementations of getTemplateSize(). Passing 0 or a less value will end in an InvalidArgumentException:
Description
float|int|null $width = null,
float|int|null $height = null
Get the size of a template.
Give only one of the size parameters (width, height) to calculate the other one automatically in view to the aspect ratio.
Parameters
- $tpl : mixed
The template id
- $width : float|int|null
The width.
- $height : float|int|null
The height.
Return Values
An array with following keys: width, height, 0 (=width), 1 (=height), orientation (L or P)
The return value in version 1 was different and you need to refactor your code!
The format was ['w' => width, 'h' => height].
useTemplate()
The useTemplate() method is implemented in \setasign\Fpdi\FpdfTpl while the final FPDI implementations also offer this method as an alias for useImportedPage().
The default parameter of the useTemplate() method had changed to:
Description
float|int|array $x = 0,
float|int $y = 0,
float|int|null $width = null,
float|int|null $height = null,
bool $adjustPageSize = false
Draws an imported page or a template onto the page or another template.
Give only one of the size parameters (width, height) to calculate the other one automatically in view to the aspect ratio.
Parameters
- $tpl : mixed
The template id
- $x : float|int|array
The abscissa of upper-left corner. Alternatively you could use an assoc array with the keys "x", "y", "width", "height", "adjustPageSize".
- $y : float|int
The ordinate of upper-left corner.
- $width : float|int|null
The width.
- $height : float|int|null
The height.
- $adjustPageSize : bool
Return Values
The size
See
Fpdi::importPage()
The $box parameter of the importPage() method accepts only real box names without a slash prefix.
There are constants for the box parameter now, too. So replace the argument with following constants/values:
- "/MediaBox"
- \setasign\Fpdi\PdfReader\PageBoundaries::MediaBox or "MediaBox"
- "/CropBox"
- \setasign\Fpdi\PdfReader\PageBoundaries::CropBox or "CropBox"
- "/BleedBox"
- \setasign\Fpdi\PdfReader\PageBoundaries::BleedBox or "BleedBox"
- "/TrimBox"
- \setasign\Fpdi\PdfReader\PageBoundaries::TrimBox or "TrimBox"
- "/ArtBox"
- \setasign\Fpdi\PdfReader\PageBoundaries::ArtBox or "ArtBox"
For backwards compatibility the box names prefixed with a slash are still supported.
Description
string $box = \setasign\Fpdi\PdfReader\PageBoundaries::CROP_BOX,
bool $groupXObject = true,
bool $importExternalLinks = false
Imports a page.
Parameters
- $pageNumber : int
The page number.
- $box : string
The page boundary to import. Default set to PageBoundaries::CROP_BOX.
- $groupXObject : bool
Define the form XObject as a group XObject to support transparency (if used).
- $importExternalLinks : bool
Define whether external links are imported or not.
Return Values
A unique string identifying the imported page.
Exceptions
Throws \setasign\Fpdi\PdfParser\CrossReference\CrossReferenceException
Throws \setasign\Fpdi\PdfParser\Filter\FilterException
Throws \setasign\Fpdi\PdfParser\PdfParserException
Throws \setasign\Fpdi\PdfParser\Type\PdfTypeException
Throws \setasign\Fpdi\PdfReader\PdfReaderException
See
- PageBoundaries