FPDI

https://manuals.setasign.com/fpdi-manual/
Admin
FPDI is a PHP library and extension for FPDF that allows developers to import single pages from...
Tokens:10,783
Snippets:69
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manual Installation: Require Autoload File

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Requires the FPDI autoload file manually when no PSR-4 autoloader is in use.

```PHP
require_once('path/to/src/autoload.php');
```

--------------------------------

### Using StreamReader with resources, paths, and strings

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class

Shows how to pass a file resource, a file path, or a string to setSourceFile(). The resource and path examples show equivalent direct passing. Remember to close the file handle with fclose().

```PHP
// use a resource
$fh = fopen('a/path/to/a.pdf', 'rb');
$pdf->setSourceFile(new StreamReader($fh));
// same as
$pdf->setSourceFile($fh);
// don't forget to call fclose($fh);

// use a path
$path = 'a/path/to/a.pdf';
$pdf->setSourceFile(StreamReader::createByFile($path));
// same as
$pdf->setSourceFile($path);

// use a string
$pdfString = '%%PDF-1.4...';
$pdf->setSourceFile(StreamReader::createByString($pdfString));
```

--------------------------------

### Manual Installation: PSR-4 Autoloader Registration

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Registers the setasign\Fpdi namespace with a PSR-4 autoloader, pointing to the /src folder of the extracted FPDI package.

```PHP
$loader = new \Example\Psr4AutoloaderClass;
$loader->register();
$loader->addNamespace('setasign\Fpdi\\', 'path/to/src/');
```

--------------------------------

### getTemplateSize()

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class

Get the size of an imported page or template. Optionally provide width or height to calculate the other dimension based on aspect ratio.

```APIDOC
## getTemplateSize()

### Description
Get the size of an imported page or template. Give only one of the size parameters (width, height) to calculate the other one automatically in view to the aspect ratio.

### Method
public \setasign\Fpdi\FpdfTrait::getTemplateSize(mixed $tpl, float|int|null $width = null, float|int|null $height = null): array|bool

### Parameters
- **$tpl** (mixed) - Required - The template id
- **$width** (float|int|null) - Optional - The width.
- **$height** (float|int|null) - Optional - The height.

### Return Values
An array with following keys: width, height, 0 (=width), 1 (=height), orientation (L or P)
```

--------------------------------

### getTemplateSize()

Source: https://manuals.setasign.com/fpdi-manual/v2/migrating

Get the size of a template. The default values of $width and $height changed to null instead of 0, and passing 0 or less throws an InvalidArgumentException.

```APIDOC
## getTemplateSize()

### Description
public \setasign\Fpdi\FpdfTplTrait::getTemplateSize (
mixed $tpl,  
float|int|null $width = null,  
float|int|null $height = null
): array|bool
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) - Required - The template id
- **$width** (float|int|null) - Optional - The width.
- **$height** (float|int|null) - Optional - The height.

### Return Values
An array with following keys: width, height, 0 (=width), 1 (=height), orientation (L or P)
```

--------------------------------

### getImportedPageSize()

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class

Get the size of an imported page. Optionally provide width or height to calculate the other dimension based on aspect ratio.

```APIDOC
## getImportedPageSize()

### Description
Get the size of an imported page. Give only one of the size parameters (width, height) to calculate the other one automatically in view to the aspect ratio.

### Method
public \setasign\Fpdi\FpdiTrait::getImportedPageSize(mixed $tpl, float|int|null $width = null, float|int|null $height = null): array|bool

### Parameters
- **$tpl** (mixed) - Required - The template id
- **$width** (float|int|null) - Optional - The width.
- **$height** (float|int|null) - Optional - The height.

### Return Values
An array with following keys: width, height, 0 (=width), 1 (=height), orientation (L or P)
```

--------------------------------

### Usage with tFPDF: Instantiate Fpdi and FpdfTpl Classes

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Shows how to use FPDI with tFPDF by instantiating the \setasign\Fpdi\Tfpdf\Fpdi and \setasign\Fpdi\Tfpdf\FpdfTpl classes.

```PHP
<?php
use setasign\Fpdi\Tfpdf\Fpdi;
use setasign\Fpdi\Tfpdf\FpdfTpl;

$fpdi = new Fpdi();
$fpdftpl = new FpdfTpl();
```

--------------------------------

### FpdfTpl::beginTemplate()

Source: https://manuals.setasign.com/fpdi-manual/v2/migrating

Begins a new template. The method signature changed in version 2 with the removal of the $x and $y parameters.

```APIDOC
## FpdfTpl::beginTemplate()

### Description
public \setasign\Fpdi\FpdfTplTrait::beginTemplate (
float|int|null $width = null,  
float|int|null $height = null,  
bool $groupXObject = false
): int
Begins a new template.

### Parameters
- **$width** (float|int|null) - Optional - The width of the template. If null, the current page width is used.
- **$height** (float|int|null) - Optional - The height of the template. If null, the current page height is used.
- **$groupXObject** (bool) - Optional - Define the form XObject as a group XObject to support transparency (if used).

### Return Values
A template identifier.
```

--------------------------------

### Simple PDF Import with FPDI

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class/examples

Imports a single page from a PDF and places it at a specified position and width. Then adds text on top of the imported page. Requires FPDF and FPDI libraries.

```php
<?php
use \setasign\Fpdi\Fpdi;

require_once('fpdf/fpdf.php');
require_once('fpdi2/src/autoload.php');

// initiate FPDI
$pdf = new Fpdi();
// add a page
$pdf->AddPage();
// set the source file
$pdf->setSourceFile("Fantastic-Speaker.pdf");
// import page 1
$tplIdx = $pdf->importPage(1);
// use the imported page and place it at point 10,10 with a width of 100 mm
$pdf->useImportedPage($tplIdx, 10, 10, 100);

// now write some text above the imported page
$pdf->SetFont('Helvetica');
$pdf->SetTextColor(255, 0, 0);
$pdf->SetXY(30, 30);
$pdf->Write(0, 'This is just a simple text');

$pdf->Output();
```

--------------------------------

### Usage with TCPDF: Instantiate Fpdi Class

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Shows how to use FPDI with TCPDF by instantiating the \setasign\Fpdi\Tcpdf\Fpdi class (required as of version 2.1).

```PHP
<?php
use setasign\Fpdi\Tcpdf\Fpdi;

$tcpdf = new Fpdi();
```

--------------------------------

### Accessing FPDI Version Constant

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Shows how to access the FPDI version via class constants.

```PHP
$fpdiVersion = \setasign\Fpdi\Fpdi::VERSION;
// or
$fpdiVersion = \setasign\Fpdi\TcpdfFpdi::VERSION;
```

--------------------------------

### useTemplate()

Source: https://manuals.setasign.com/fpdi-manual/v2/migrating

Draws an imported page or a template onto the page or another template. The default parameter changed.

```APIDOC
## useTemplate()

### Description
public \setasign\Fpdi\FpdfTrait::useTemplate (
mixed $tpl,  
float|int|array $x = 0,  
float|int $y = 0,  
float|int|null $width = null,  
float|int|null $height = null,  
bool $adjustPageSize = false
): array
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) - Required - The template id
- **$x** (float|int|array) - Optional - The abscissa of upper-left corner. Alternatively you could use an assoc array with the keys "x", "y", "width", "height", "adjustPageSize".
- **$y** (float|int) - Optional - The ordinate of upper-left corner.
- **$width** (float|int|null) - Optional - The width.
- **$height** (float|int|null) - Optional - The height.
- **$adjustPageSize** (bool) - Optional - 

### Return Values
The size

### See
- \setasign\Fpdi\Fpdi::getTemplateSize()
```

--------------------------------

### useTemplate()

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class

Draws an imported page or a template onto the page or another template. Optionally provide width or height to calculate the other dimension based on aspect ratio.

```APIDOC
## useTemplate()

### Description
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.

### Method
public \setasign\Fpdi\FpdfTrait::useTemplate(mixed $tpl, float|int|array $x = 0, float|int $y = 0, float|int|null $width = null, float|int|null $height = null, bool $adjustPageSize = false): array

### Parameters
- **$tpl** (mixed) - Required - The template id
- **$x** (float|int|array) - Optional - The abscissa of upper-left corner. Alternatively you could use an assoc array with the keys "x", "y", "width", "height", "adjustPageSize".
- **$y** (float|int) - Optional - The ordinate of upper-left corner.
- **$width** (float|int|null) - Optional - The width.
- **$height** (float|int|null) - Optional - The height.
- **$adjustPageSize** (bool) - Optional - (no description)

### Return Values
The size

### See
- \setasign\Fpdi\Fpdi::getTemplateSize()
```

--------------------------------

### Import Whole Document with FPDI

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class/examples

Imports all pages of a PDF document by iterating over the page count returned by setSourceFile(). Adjusts the page size to match each imported page and adds text on each page.

```php
<?php
use \setasign\Fpdi\Fpdi;

require_once('fpdf/fpdf.php');
require_once('fpdi2/src/autoload.php');

// initiate FPDI
$pdf = new Fpdi();

// get the page count
$pageCount = $pdf->setSourceFile('Laboratory-Report.pdf');
// iterate through all pages
for ($pageNo = 1; $pageNo <= $pageCount; $pageNo++) {
    // import a page
    $templateId = $pdf->importPage($pageNo);

    $pdf->AddPage();
    // use the imported page and adjust the page size
    $pdf->useTemplate($templateId, ['adjustPageSize' => true]);

    $pdf->SetFont('Helvetica');
    $pdf->SetXY(5, 5);
    $pdf->Write(8, 'A complete document imported with FPDI');
}

// Output the new PDF
$pdf->Output();
```

--------------------------------

### Letterhead with FPDI Header() Method

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class/examples

Adds a letterhead to every page by overriding the Header() method in a class that extends Fpdi. Imports the letterhead once and uses it on each page. Includes dummy functions to generate random text for demonstration.

```php
<?php
use \setasign\Fpdi\Fpdi;

require_once('fpdf/fpdf.php');
require_once('fpdi2/src/autoload.php');

// Some dummy functions to generate text content
function GenerateWord()
{
    // Get a random word
    $nb = rand(3, 10);
    $w = '';
    for ($i = 1; $i <= $nb; $i++)
        $w .= chr(rand(ord('a'), ord('z')));
    return $w;
}

function GenerateSentence($words = 500)
{
    // Get a random sentence
    $nb = rand(20, $words);
    $s = '';
    for ($i = 1; $i <= $nb; $i++)
        $s .= GenerateWord() . ' ';
    return substr($s, 0, -1);
}

// The class, that overwrites the Header() method:
class Pdf extends Fpdi
{
    protected $_tplIdx;

    public function Header()
    {
        if (null === $this->_tplIdx) {
            $this->setSourceFile('Letterhead.pdf');
            $this->_tplIdx = $this->importPage(1);
        }

        $this->useImportedPage($this->_tplIdx);
    }
}

// initiate PDF
$pdf = new Pdf();
$pdf->SetTopMargin(30);

// Add a single page and trigger some auto page breaks.
$pdf->AddPage();
$pdf->SetFont('Helvetica');
for ($i = 20; $i > 0; $i--) {
    $pdf->MultiCell(0, 6, GenerateSentence());
    $pdf->Ln();
}

// Output the new PDF
$pdf->Output();
```

--------------------------------

### Create and reuse a header template with FpdfTpl

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdf-tpl-class

Creates a header template with FpdfTpl and reuses it on every page. Requires fpdf/fpdf.php and fpdi2/src/autoload.php. The template is defined between beginTemplate() and endTemplate(), then placed with useTemplate().

```php
<?php
use \setasign\Fpdi\FpdfTpl;

require_once('fpdf/fpdf.php');
require_once('fpdi2/src/autoload.php');

$pdf = new FpdfTpl();
$pdf->AddPage();

$templateId = $pdf->beginTemplate();
$pdf->setFont('Helvetica');
$pdf->Text(10, 10, 'HEADING');
$pdf->endTemplate();

$pdf->useTemplate($templateId);

for ($i = 9; $i > 0; $i--) {
    $pdf->AddPage();
    $pdf->useTemplate($templateId);
}

$pdf->Output();
```

--------------------------------

### Making S3 streams seekable per stream

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class

Registers the S3 stream wrapper and creates a stream context with seekable enabled. Opens the stream with fopen() and passes it to setSourceFile() either via a StreamReader or directly. Finally closes the stream.

```PHP
// register the stream wrapper
$s3 = new S3Client(...);
$s3->registerStreamWrapper();

// create a stream context
$context = stream_context_create(['s3' => ['seekable' => true]]);
// and open the stream
$stream = fopen("s3://{$bucket}/{$key}", 'r', false, $context);

// then we can use the stream in a StreamReader instance
$pdf->setSourceFile(new StreamReader($stream));

// it is also possible to pass the stream directly
// (this will create a StreamReader instance internally
$pdf->setSourceFile($stream);


// ...

// finally close the stream
fclose($stream);
```

--------------------------------

### Version Number Format

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Shows the semantic versioning format used by FPDI as of version 2.

```text
[MAJOR].[MINOR].[PATCH]
```

--------------------------------

### Composer Configuration for FPDF

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Adds FPDF and FPDI dependencies to composer.json for using FPDI with FPDF.

```JSON
{
    "require": {
        "setasign/fpdf": "1.8.*",
        "setasign/fpdi": "^2.0"
    }
}
```

--------------------------------

### Making S3 streams seekable globally

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class

Registers the S3 stream wrapper and forces all s3 streams to be seekable using stream_context_set_default(). Then the file can be passed directly to setSourceFile().

```PHP
// register the stream wrapper
$s3 = new S3Client(...);
$s3->registerStreamWrapper();

// make all files for the s3 protocol seekable
stream_context_set_default(['s3' => ['seekable' => true]]);

// now the file can be handled as any other file
$pdf->setSourceFile("s3://{$bucket}/{$key}");
```

--------------------------------

### Composer Configuration for tFPDF

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Updates composer.json to use tFPDF with FPDI.

```JSON
{
    "require": {
        "setasign/tfpdf": "1.31.*",
        "setasign/fpdi": "^2.3"
    }
}
```

--------------------------------

### Composer Configuration for TCPDF

Source: https://manuals.setasign.com/fpdi-manual/v2/installation

Updates composer.json to use TCPDF with FPDI.

```JSON
{
    "require": {
        "tecnickcom/tcpdf": "6.2.*",
        "setasign/fpdi": "^2.0"
    }
}
```

--------------------------------

### setSourceFile()

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class

Set the source PDF file. Returns the page count of the PDF document.

```APIDOC
## setSourceFile()

### Description
Set the source PDF file.

### Method
public \setasign\Fpdi\FpdiTrait::setSourceFile(string|resource|\setasign\Fpdi\PdfParser\StreamReader $file): int

### Parameters
- **$file** (string|resource|\setasign\Fpdi\PdfParser\StreamReader) - Required - Path to the file or a stream resource or a StreamReader instance.

### Return Values
The page count of the PDF document.

### Exceptions
Throws \setasign\Fpdi\PdfParser\PdfParserException
```

--------------------------------

### useImportedPage()

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class

Draws an imported page onto the page. Optionally provide width or height to calculate the other dimension based on aspect ratio.

```APIDOC
## useImportedPage()

### Description
Draws an imported page onto the page. Give only one of the size parameters (width, height) to calculate the other one automatically in view to the aspect ratio.

### Method
public \setasign\Fpdi\FpdiTrait::useImportedPage(mixed $pageId, float|int|array $x = 0, float|int $y = 0, float|int|null $width = null, float|int|null $height = null, bool $adjustPageSize = false): array

### Parameters
- **$pageId** (mixed) - Required - The page id
- **$x** (float|int|array) - Optional - The abscissa of upper-left corner. Alternatively you could use an assoc array with the keys "x", "y", "width", "height", "adjustPageSize".
- **$y** (float|int) - Optional - The ordinate of upper-left corner.
- **$width** (float|int|null) - Optional - The width.
- **$height** (float|int|null) - Optional - The height.
- **$adjustPageSize** (bool) - Optional - (no description)

### Return Values
The size.

### See
- \setasign\Fpdi\Fpdi::getTemplateSize()
```

--------------------------------

### Concatenate Several Documents with FPDI

Source: https://manuals.setasign.com/fpdi-manual/v2/the-fpdi-class/examples

Concatenates multiple PDF documents by iterating over a list of files, importing each page, and adding it to the output with the same orientation and size. Uses getTemplateSize() to determine page dimensions.

```php
<?php
use \setasign\Fpdi\Fpdi;

require_once('fpdf/fpdf.php');
require_once('fpdi2/src/autoload.php');

// define some files to concatenate
$files = array(
    'Boombastic-Box.pdf',
    'Fantastic-Speaker.pdf',
    'Noisy-Tube.pdf'
);

// initiate FPDI
$pdf = new Fpdi();

// iterate through the files
foreach ($files AS $file) {
    // get the page count
    $pageCount = $pdf->setSourceFile($file);
    // iterate through all pages
    for ($pageNo = 1; $pageNo <= $pageCount; $pageNo++) {
        // import a page
        $templateId = $pdf->importPage($pageNo);
        // get the size of the imported page
        $size = $pdf->getTemplateSize($templateId);

        // add a page with the same orientation and size
        $pdf->AddPage($size['orientation'], $size);

        // use the imported page
        $pdf->useTemplate($templateId);

        $pdf->SetFont('Helvetica');
        $pdf->SetXY(5, 5);
        $pdf->Write(8, 'A simple concatenation demo with FPDI');
    }
}

// Output the new PDF
$pdf->Output();
```

--------------------------------

### importPage()

Source: https://manuals.setasign.com/fpdi-manual/v2/migrating

Imports a page from a PDF document and returns a unique string identifier for the imported page.

```APIDOC
## importPage()

### Description
Imports a page from a PDF document. The method accepts a page number and optional parameters for page boundary, group XObject, and external links.

### Method
importPage

### Signature
public \setasign\Fpdi\FpdiTrait::importPage(
  int $pageNumber,
  string $box = \setasign\Fpdi\PdfReader\PageBoundaries::CROP_BOX,
  bool $groupXObject = true,
  bool $importExternalLinks = false
): string

### Parameters
- **$pageNumber** (int) - Required - The page number.
- **$box** (string) - Optional - The page boundary to import. Default set to PageBoundaries::CROP_BOX. Accepts constants or box names without a slash prefix. For backwards compatibility, box names prefixed with a slash are still supported. Valid values: "MediaBox", "CropBox", "BleedBox", "TrimBox", "ArtBox" or the corresponding constants.
- **$groupXObject** (bool) - Optional - Define the form XObject as a group XObject to support transparency (if used). Default true.
- **$importExternalLinks** (bool) - Optional - Define whether external links are imported or not. Default false.

### 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 Also
- PageBoundaries
```

--------------------------------

### FPDI 2 namespace declaration

Source: https://manuals.setasign.com/fpdi-manual/v2/migrating

Declares the FPDI 2 namespace. All FPDI 2 classes are placed under this namespace and are not registered in the global namespace.

```PHP
namespace setasign\Fpdi;
```
Tokens:
Raw