Refactor Version 1 Code With the release of version 2 there were changes that are not backwards compatible

Overview

SetaPDF 2 was rewritten from scratch. Because of this, code that was written for SetaPDF 1 cannot be used anymore without refactoring it.

Error Handling

While in version 1 error objects were returned, version 2 uses Exceptions throughout. More details can be found here.

Loading the Component

In version 1 it was a requirement that the SetaPDF folder was available through the include_path. In version 2 all class loading is done by an autoload implementation. So only one file has to be required:

PHP
require_once('/absolute/path/to/library/SetaPDF/Autoload.php');

or

PHP
require_once('../relative/path/to/library/SetaPDF/Autoload.php');

General Refactoring

Because most method parameters are changed to object properties old SetaPDF code has to be refactored. For example the call of the factory(), setStamp() and stampit()-method has to be refactored as following. The old code looks like this: 

PHP
$filenameIn = 'pdf-to-stamp.pdf';
$filenameOut = 'stamped-pdf.pdf';
$stream = true;
$update = true;
 
// Old style for SetaPDF 1
$stamper = \SetaPDF_Stamper::factory('I', $stream);
$stamper->setUseUpdate($update);
$stamper->addFile(array(
    'in' => $filenameIn, 
    'out' => $filenameOut,
    'compression' => true 
));

//...

 
// ... stamp it
$stamper->stampit();

Which will become:

PHP
$writer = new \SetaPDF_Core_Writer_Http($filenameOut, $stream);
$document = \SetaPDF_Core_Document::loadByFilename($filenameIn, $writer);

$stamper = new \SetaPDF_Stamper($document);

//...

$stamper->stamp();
$document->save($update)->finish();

In version 2 reading and writing PDF files is done via reader and writer classes throughout.

The default encoding is changed from cp1252 to UTF-8.

The internal caching system is removed, because the classes themselves are serializable now.

Removed Methods

Following public methods are removed in the main SetaPDF_Stamper class:

  • factory()
  • setUseUpdate()
  • addFile()
  • addFiles()
  • addStamp() (see here
  • getPageCount() (see here)
  • getPageBoxes() (see here)
  • getOriginBox() (see here)
  • getPageRotation()
  • stampit()

If your code relies on these methods, make sure you refactor it!

Nearly all methods and their logic are implemented in the new core system of version 2.0.

Refactor Usage of Version 1 Methods

The refactoring of removed or changed methods is described in the following.

Page Count

 A page count can be resolved through the document instance: 

PHP
$document = \SetaPDF_Core_Document::loadByFilename('filename.pdf');
$pages = $document->getCatalog()->getPages();
$pageCount = $pages->count();
// or
$pageCount = count($pages);

Page Properties Accessor Methods

The methods getPageBoxes(), getOriginBox() and getPageRotation() are available through individual getter methods of a page object.

Getting page boxes is possible via getter methods for the desired box type. The returned values could be a PDF array or a SetaPDF_Core_DataStructure_Rectangle object. For more details see SetaPDF_Core_Document_Page::getBoundary().

PHP
// get access to a page instance
$pages = $document->getCatalog()->getPages();
$page = $pages->getPage(1);

The setStamp()-Method is Renamed to addStamp()

The parameter list is almost the same but the behaviour of the $translateY-parameter had changed: A value greater than zero will move the stamp up on the page while a negative value will move the stamp down. In version one this was the other way around. 

Refactor Usage of Stamp Types

As in version 1 the individual stamp classes are extending an abstract class representing a general stamp object.

In version 2 this is still the case but there are incompatible changes which should be communicated.

Generally the new base class implements much more logic which was fragmented into the individual stamp classes in version 1.

The method setAlpha() becomes setOpacity().  

The parameters for the setVisibility() method now should be passed as class constants:SetaPDF_Stamper_Stamp::VISIBILITY_ALL, SetaPDF_Stamper_Stamp::VISIBILITY_PRINT,SetaPDF_Stamper_Stamp::VISIBILITY_VIEW

Text Stamps

Classname changed

The classname changed from SetaPDF_TextStamp to SetaPDF_Stamper_Stamp_Text.

Text Position

In version 2 the origin position for text is calculated by the bounds of the given line-height plus padding values.

In version 1 this was done by the descender and/or ascender (depending on the position on the page). So a translation was needed to get the whole characters into the view.

Position values (at least y-values) have to be redefined in version 2!

Font Handling

In SetaPDF 1 the text stamp class only supports standard PDF fonts which are passed as string parameters to the setFontFamily() or setFont() method.

The new core system of SetaPDF supports a completely new font handling based on objects representing a font. The core system offers classes representing all standard PDF fonts but also allows you to create a separate font instance based on a True Type Font through the SetaPDF_Core_Font_TrueType class. More details can be found here.

Here's an example showing version 1 and version 2 equivalents:

PHP
// old style:
$stamp->setFontFamily('Times');
$stamp->setFontSize(12);
     
// new style:
$font = \SetaPDF_Core_Font_Standard_TimesRoman::create($document);
$stamp->setFont($font, 12);
Color Handling

Color handling is done via color objects. Or passed parameters are forward toSetaPDF_Core_DataStructure_Color::createByComponents() to allow faster, easier initiation.

Removed Methods

Following public methods are removed from the text stamp class:

If your code relies on these methods, make sure you refactor it!

Image Stamps

Classname Changed

The classnames changed from SetaPDF_ImageStamp, SetaPDF_JPGStamp, SetaPDF_PNGStamp to a single class named SetaPDF_Stamper_Stamp_Image, so that the stamp class does not depend on any image type anymore. Both JPEG and PNG files will be handled by separate image classes which are extending the SetaPDF_Core_Image class.

The $aspectRatio Parameter has been removed

In all method signatures of setWidth(), setHeight() and setDimensions() the $aspectRatio parameter is removed. The logic is done internally: If a value is defined and its counterpart is null the counterpart will be calculated automatically by keeping the aspect ratio.

If your code relies on this parameter, make sure you refactor it! 

Removed Methods

The following public method is removed from the image stamp class:

  • setFileName()

If your code relies on this method, make sure you refactor it!

PDF Stamps

Classname Changed

The classname changed from SetaPDF_PdfStamp to SetaPDF_Stamper_Stamp_Pdf.

Removed Methods

Following public methods are removed from the pdf stamp class:

If your code relies on these methods, make sure you refactor it!