setasign/setafpdf

A clone of FPDF with an almost compatible interface while using SetaPDF-Core internally for the PDF generation.

SetaFPDF

SetaFPDF is a clone of FPDF with an almost compatible interface while using SetaPDF-Core internally for the PDF generation.

Motivation

The main motivation for this project was to be able to create PDF/A documents in PHP without changing all existing PDF generation scripts which rely on FPDF.

FPDF is a wide spread and very common PHP library for PDF generation. It is small, well tested and runs on millions of websites. It also comes with several extensions and an active forum.

The SetaPDF-Core component is a PHP component which allows PHP developers to interact with existing PDF documents on a low level. While there is no high-level API for PDF generation it comes with all low-level features which are required to create PDF/A documents:

• TrueType font sub-setting
• Access to XMP metadata
• Color profiles
• Support for embedded files / attachments

Additionally it comes with other nice features which would be available automatically:

• Access to document outlines
• Access to page labels
• Support for annotations
• Support for creating and handling destinations (also named destinations)
• Support for individual actions
• Support for other colors and color spaces
• Standard and public key encryption (up to AES256)
• ...and much more...

Bringing both SetaPDF and FPDF together result in SetaFPDF: An almost identical interface of FPDF backed up by SetaPDF on the lower level.

Future of this project

This project is not a start of a new PDF generation project in PHP but it is a temporary solution to improve existing projects which rely on FPDF.

Requirements

• PHP >= 5.6
• SetaPDF-Core (All SetaPDF products include SetaPDF-Core)
  • iconv or Multibyte String
  • OpenSSL
  • Zlib

Installation

Add following to your composer.json:

{
    "require": {
        "setasign/setafpdf": "^1.0"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://www.setasign.com/downloads/"
        }
    ]
}

and execute composer update. You need to define the repository to evaluate the dependency to the SetaPDF-Core component (see here for more details).

Evaluation version

By default this packages depends on a licensed version of the SetaPDF-Core component. If you want to use it with an evaluation version please use following in your composer.json:

{
    "require": {
        "setasign/setafpdf": "dev-evaluation"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://www.setasign.com/downloads/"
        }
    ]
}

Notice that the evaluation branch depends on the version for PHP 7.1 and up.

Without Composer

Make sure, that the SetaPDF-Core component is installed and its autoloader is registered correctly.

Then simply require the src/autoload.php file or register following namespaces in your own PSR-4 compatible autoload implementation:

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

Usage

You can use SetaFPDF the same way as FPDF. Their interfaces are almost identically. So just use another constructor and be aware of following differences:

• The AddFont() method was changed to allow only TrueType fonts instead of FPDF font definition files.
• The method AliasNbPages() will throw an \SetaPDF_Exception_NotImplemented exception throughout. It is removed in favor of a more clean solution by re-accessing the pages afterwards through the SetPage() method. By doing this e.g. the alignment is more consistent than with the marker.
• The $isUTF8 parameter is removed from the Output() method. The HTTP header is always send with an UTF-8 variant by SetaPDF.
• The $isUTF8 parameter is removed from following methods: SetAuthor(), SetCreator(), SetKeywords(), SetSubject() and SetTitle(). You need to pass the parameters in UTF-8 throughout.
• The method SetCompression() will throw an SetaPDF_Exception_NotImplemented exception if called with false as its argument (SetaPDF has no option to turn compression off).
• There's no Error() method anymore. Exceptions are thrown where the errors occur.

Improved and new methods:

• The SetDrawColor(), SetTextColor() and SetFillColor() accept 1 argument (0-255) for grayscale colors, 3 arguments (each 0-255) for RGB and 4 arguments (each 0-100) for CMYK now by default.
• A new method SetPage() is introduced to allow you to navigate between pages. With it you can e.g. write page numbers and the final page count into the pages footer or header. This was done before with AliasNbPages().
• The new getPageCount() method is self-explaining.
• The getManager() method allows you to get access to the underlaying object structure.

Examples and update information

A simple example will look like:

<?php
use \setasign\SetaFpdf\SetaFpdf;

require_once 'vendor/autoload.php';

$pdf = new SetaFpdf();
$pdf->AddPage();
$pdf->AddFont('DejaVuSans', '', '/path/to/DejaVuSans.ttf');
$pdf->SetFont('DejaVuSans', '', 20);
$pdf->Write(20, 'Love & Ζω!'); // Write in UTF-8
$pdf->Output();

Nothing new here. It's code you already know from FPDF. And that's it. In the normal cases you only need to replace the constructor with \setasign\SetaFpdf\SetaFpdf, update the AddFont(), ensure UTF-8 input and you're done!

Page numbering (previously done by FPDF::AliasNbPages())

If your script relies on page numbering which is implemented by the use of AliasNbPages() in e.g. the Header() or Footer() methods you need to refactor your script. With FPDF it was done e.g. this way:

class Pdf extends FPDF
{
    public function Footer()
    {
        $this->SetY(-15);
        $this->Cell(0, 10, 'Page ' . $this->PageNo() . '/{nb}', 0, 0, 'R');
    }
}

$pdf = new Pdf();
$pdf->AddPage();
// ...
$pdf->AddPage();
// ...
$pdf->AddPage();
// ...
$pdf->AddPage();
// ...
$pdf->Output();

With SetaFPDF you need to iterate over the created pages and write the footer manually:

class Pdf extends SetaFpdf
{
    public function writeFooters()
    {
        $this->SetAutoPageBreak(false);
        
        $pageCount = $this->getPageCount();
        // iterate through the pages and draw the footer
        for ($pageNo = 1; $pageNo <= $pageCount; $pageNo++) {
            $this->SetPage($pageNo);
            $this->SetY(-15);
            $this->Cell(0, 10, 'Page ' . $this->PageNo() . '/' . $pageCount, 0, 0, 'R');
        }
        
        $this->SetAutoPageBreak(true);
    }
}

$pdf = new Pdf();
$pdf->AddPage();
// ...
$pdf->AddPage();
// ...
$pdf->AddPage();
// ...
$pdf->AddPage();
// ...
// write the footers
$pdf->writeFooters();
// ...
$pdf->Output();

Import existing pages from existing PDF documents

There is also a clone for FPDI available. If you need the methods of FPDI just use the class SetaFpdi and you can use methods like setSourceFile(), importPage() and useTemplate():

<?php
use \setasign\SetaFpdf\SetaFpdi;

require_once 'vendor/autoload.php';

$pdf = new SetaFpdi();

$pageCount = $pdf->setSourceFile('/path/to/template.pdf');

for ($pageNo = 1; $pageNo <= $pageCount; $pageNo++) {
    $tpl = $pdf->importPage($pageNo);
    $pdf->AddPage();
    $pdf->useTemplate($tpl, ['adjustPageSize' => true]);
}

$pdf->Output();

Generating PDF/A documents

With SetaFPDF you are able to create PDF/A documents. Anyhow it's up to you to not use features which are not allowed in PDF/A. Also it's up to you to add the missing puzzle pieces through the underlaying SetaPDF functionallities. There's a simple example available in demos/pdf-a-3b.php that adds the required pieces to make the PDF PDF/A conform.

If you want to create PDF/A documents while importing other files, you need to make sure, that these documents are PDF/A already.

License

This package is open-sourced software licensed under the MIT license.

setafpdf's Issues

Support named destinations in $link parameters

We should transform links such as #doc-1 to GoTo actions for named destinations.

autoload.php is invalid

Needs to be:

spl_autoload_register(function ($class) {
    if (strpos($class, 'setasign\\SetaFpdf') === 0) {
        $filename = str_replace('\\', DIRECTORY_SEPARATOR, substr($class, 17)) . '.php';
        $fullpath = __DIR__ . DIRECTORY_SEPARATOR . $filename;

        if (is_file($fullpath)) {
            /** @noinspection PhpIncludeInspection */
            require_once $fullpath;
        }
    }
});

Invalid doc block type hint for SetFont $size

The current doc block for the $size param of \setasign\SetaFpdf\SetaFpdf::SetFont() is:

@param string $size Font size in points. The default value is the current size. If no size has been specified 
                    since the beginning of the document, the value taken is 12.

Which calls internally \setasign\SetaFpdf\Modules\Font::set() which has the following doc block for $size:

@param string $size

But the size will be written into \setasign\SetaFpdf\StateBuffer\Font::$currentFontSize (without casting) which expects int|float.

The default of Fpdf for this method is also the integer 0 and not an empty string. This should be fixed.

Setting links is possible if we create a template but the result is faulty

It is possible to create links during the creation of a template (beginTemplate() / endTemplate()):

$pdf->beginTemplate();
$pdf->Write(12, 'LINK', 'https://www.setasign.com');
$pdf->endTemplate();

but the link is missplaced then. We should prohibit links in template as we do in FPDI.

Can not install this package

Hello, we have bought the SetaPDF-Core and I'm trying to install this package, but it gives me an error because the composer tries to install the next:

Installing setasign/eval/setapdf-core/ioncube (1.0.2237252): Downloading (failed)

and we get

  [Composer\Downloader\TransportException]
  The "https://www.setasign.com/downloads/eval/{someId}/ioncube/SetaPDF-Core-License.zip" file could not be downloaded (HTTP/1.1 404 Not Found)

We have the latest core version.

And could you let me know if with this library we can work with utf-8 text and fonts?

Behavior of Write() with line-feed at its end is different/faulty

Following visible test will show the faulty behavior:

$proxy = $this->getProxy('P', 'pt', 'A4');
$proxy->AddPage();
$proxy->SetFont('arial', '', 10);
$proxy->Write(8, "A\n");
$proxy->Write(8, "B");
$this->assertProxySame($proxy, 0.15, 72);

Exception 1536

Hello, i have an error exception :

" Exception reçue : Security handler not authenticated, so no encryption key is known. Authenticate first!. N° d'exception : 1536 "

Could you help me to find the error? Missing library on the server?

Thx

Composer download throttling recommendations

Hi Dear Maintainers,

We currently use your application solution setapdf-stampe and ran into a throttling limitation. What would be the recommendation to download the library? We're using the composer reference as recommended in this repository.

Error details

In CurlDownloader.php line 617:

The "https://www.setasign.com/downloads/2854243/SetaPDF-Core_2.36.0.1597-without-demos.zip" file could not be downloaded (HTTP/1.1 429 You have downloaded more than 200 files! Please wait 24 hours to download more.)

Composer reference

"setasign/setapdf-stamper": "2.36.0.1597"
...
"repositories": [
        {
            "type": "composer",
            "url": "https://www.setasign.com/downloads/"
        }
    ],