SetaPDF-FormFiller Manual

From Version 1.x to 2.0 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: 

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() and fillForms()-method has to be refactored as following. The old code looks like this:

$sourcefile = 'source.pdf';
$target = 'filled.pdf';
$password = 'theOwnerPassword';
$dest = 'I';
$stream = true;
$renderAppearancesByViewer = true;
$useUpdate = false;
 
// Old style for SetaPDF 1
$formFiller = \SetaPDF_FormFiller::factory(
    $sourcefile,
    $password,
    $dest,
    $stream,
    $renderAppearancesByViewer
);
$formFiller->setUseUpdate($useUpdate);
 
// ...fill in fields
 
$formFiller->fillForms($target);

Which will become:

$reader = new \SetaPDF_Core_Reader_File($sourcefile);
$writer = new \SetaPDF_Core_Writer_HttpStream($target, true /*$dest == 'I'*/); // $stream == true
 
$document = \SetaPDF_Core_Document::load($reader, $writer);
if ($document->hasSecHandler()) {
    $secHandler = $document->getSecHandler();
    $authenticated = $secHandler->authByOwnerPassword($password);
}
 
$formFiller = new \SetaPDF_FormFiller($document);
$formFiller->setNeedAppearances($renderAppearancesByViewer);
 
// ...fill in fields
 
$document->save($useUpdate)->finish();

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

Refactor Handling of Fields

As already written the complete component was rewritten. Because of this class names and methods were removed or changed.

In version one each form field extends the class SetaPDF_FormField. This class does not exists in version 2 anymore but the field classes implement the SetaPDF_FormFiller_Field_FieldInterface interface. 

The method SetaPDF_FormField::getMD5Name() is not available in version 2. 

Text Fields

No Rich-Text Field Support

This feature will be available through an additional field class in the future again.

The $dontReCreateAppearance Parameter Changed

Second parameter of setValue() changed to $encoding. The $dontReCreateAppearance parameter is removed.

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

Encoding

Both getValue() and setValue() accept an encoding parameter in version 2. The encoding is not defined in the constructor anymore. 

Removed Methods

 Following public methods are removed from the text field class:

• setTranslateLeading()
• setLink()
• getMD5Name() 

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

Check Box Fields

Changed getValue() Method

The getValue() method returns a boolean value, saying if the button is checked or not. In SetaPDF 1 a string of a name object was returned.

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

Radiobutton Groups

No Named Buttons

The getButtons()-method still returns the buttons but the returned array is an array with numeric indizes. This change was needed to introduce the handling of buttons with the same export values.

In SetaPDF 1 the indices were the plain export value name objects.

In the same turn the setValue()-method does not accept the button name or index anymore but accepts the real export value (not a name object) or a button instance. 

List and Combo Box Fields

Own Class For List and Combo Box Fields

In SetaPDF 1 both choice field types (list and combo) are handled in one class. They are splittet into individual classes in SetaPDF 2 now.

Optimized setValue() Method

The setValue() method accepts string values now. The selected option will be resolved by comparing the options export-value with the given string.