Refactor Version 1 Code With the release of version 2 there were changes that are not backwards compatible
Table of Contents
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:
require_once('/absolute/path/to/library/SetaPDF/Autoload.php');
or
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:
$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:
$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:
$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().
// 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:
// 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:
setFontFamily()(see Font Handling)setFontStyle()(see Font Handling)setFontSize()(see Font Handling)setTextWidth()(replaced bySetaPDF_Stamper_Stamp_Text::setWidth())setFontColor()(replaced bySetaPDF_Stamper_Stamp_Text::setTextColor())setDrawBackground()(replaced by passingnulltoSetaPDF_Stamper_Stamp_Text::setBackgroundColor())
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:
setFileName()setPageNo()(replaced bySetaPDF_Stamper_Stamp_Pdf::setPageNumber())getPageNo()(replaced bySetaPDF_Stamper_Stamp_Pdf::getPageNumber())getPageCount()(see here)readAllPages()getPageBoxes()(see here)getOriginBox()(see here)getPageRotation()(see here)
If your code relies on these methods, make sure you refactor it!