SetaPDF-Signer 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 the factory()-method is removed and the sign()-method's signature changed. The old code looks like this: 

$sourcefile = 'source.pdf';
$target = 'signed.pdf';
$tempDirectory = 'path/to/temp/directory/';
$certificate = file_get_contents('path/to/certificate.pem');
$password = 'thePassword';
$dest = 'I';

// Old style for SetaPDF 1
$module = new \SetaPDF_Signer_Module_OpenSsl();
$module->setSignCert($certificate);
$module->setPrivateKey(array($certificate, $password));

$signer= \SetaPDF_Signer::factory(
    $sourcefile,
    $tempDirectory
);
 
// ...sign 
$signer->sign($module, $target, $dest);

Which will become:

$reader = new \SetaPDF_Core_Reader_File($sourcefile);
$writer = new \SetaPDF_Core_Writer_Http($target, true /*$dest == 'I'*/);

\SetaPDF_Core_Writer_TempFile::setTempDir($tempDirectory);
 
$document = \SetaPDF_Core_Document::load($reader, $writer);
$signer = new \SetaPDF_Signer($document);

$module = new \SetaPDF_Signer_Signature_Module_OpenSsl();
$module->setCertificate($certificate);
$module->setPrivateKey(array($certificate, $password));

// ...sign
$signer->sign($module);

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

The signer component will not handle temporary files by its own in version 2 but it will use a temporary file writer of the Core component. This writer has to be configured at least with a writeable temporary path. 

The parameters for the setSignatureProperty() and getSignatureProperty() methods should be passed as class constants now: SetaPDF_Signer::PROP_NAME, SetaPDF_Signer::PROP_LOCATION, SetaPDF_Signer::PROP_REASON, SetaPDF_Signer::PROP_TIME_OF_SIGNING, SetaPDF_Signer::PROP_CONTACT_INFO. Alternatively the properties can be set through getter and setter methods. 

Removed Methods

The following methods have been removed from the main SetaPDF_Signer class:

• factory()
• setSourceFileName()
• setAppearance() (see here)
• setTmpDirectory() (see here)
• setFieldName() (has been replaced by setSignatureFieldName())
• setSignatureContentMinLength() (has been replaced by setSignatureContentLength())
• setRemoveNeedAppearancesFlag() (see here)
• createNewTmpFileName()
• cleanTmpDirectory()
• getPageCount() (see here)
• getPageBoxes() (see here)
• getOriginBox() (see here)
• setTsModule() (has been replaced by setTimestampModule())
• unsetParser()

Refactor Version 1 Methods

The setAppearance() Method

In version 1 the setAppearance() method allows you to define a page of an existing PDF to be used as the visible signature appearance. In version 2 the same bahviour could be achieved with the SetaPDF_Signer_Signature_Appearance_XObject class.

While version 1 automatically creates a form field in version 2 the field has to be created "manually" or an existing field has to be used.

$sourcefile = 'source.pdf';
$appFile = 'appDocument.pdf';
$target = 'signed.pdf';
$tempDirectory = 'path/to/temp/directory/';
$certificate = file_get_contents('path/to/certificate.pem');
$password = 'thePassword';
$dest = 'I';

// Old style for SetaPDF 1
$module = new \SetaPDF_Signer_Module_OpenSsl();
$module->setSignCert($certificate);
$module->setPrivateKey(array($certificate, $password));

$signer = \SetaPDF_Signer::factory(
    $sourcefile,
    $tempDirectory
);

$signer->setAppearance(
    $appFile,                     // PDF appearance
    'LT',                         // LeftTop
    array('x' => 50, 'y' => -50), // Translate the position
    180,                          // Set the width to 180 points
    60,                           // Set the height to 60 points
    1                             // put appearance on page 1
);

$signer->sign($module, $target, $dest);

This code will become:

$reader = new \SetaPDF_Core_Reader_File($sourcefile);
$writer = new \SetaPDF_Core_Writer_Http($target, true /*$dest == 'I'*/);

\SetaPDF_Core_Writer_TempFile::setTempDir($tempDirectory);
 
$document = \SetaPDF_Core_Document::load($reader, $writer);
$signer= new \SetaPDF_Signer($document);

$module = new \SetaPDF_Signer_Signature_Module_OpenSsl();
$module->setCertificate($certificate);
$module->setPrivateKey(array($certificate, $password));

$signer->addSignatureField(
    \SetaPDF_Signer_SignatureField::DEFAULT_FIELD_NAME, // = 'Signature'
    1,                                                 // Create field on page 1
    \SetaPDF_Signer_SignatureField::POSITION_LEFT_TOP,  // Left Top
    array('x' => 50, 'y' => -50),                      // Translate the position
    180,                                               // Set the width to 180 points
    60                                                 // Set the height to 60 points
);

$appDocument = \SetaPDF_Core_Document::loadByFilename($appFile);
$pageXObject = $appDocument->getCatalog()->getPages()->getPage(1)->toXObject($document);
$appearance = new \SetaPDF_Signer_Signature_Appearance_XObject($module, $pageXObject);

$signer->sign($appearance);

The setTmpDirectory() Method

The logic for handling temporary files is encapsulated in the SetaPDF_Core_Writer_TempFile class as of version 2. A simliar static method exists in that class:

$signer->setTmpDirectory('path/to/tmp/directory');
// becomes
\SetaPDF_Core_Writer_TempFile::setTempDir('path/to/tmp/directory');

Page 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);

Refactor Usage of Signature Modules

In version one each signature module extends the class SetaPDF_Signer_Module. In version 2 this class does not exist anymore, but all signature modules implement the SetaPDF_Signer_Signature_Module_ModuleInterface interface.

The new class names are as follows:

• SetaPDF_Signer_Signature_Module_OpenSsl
• SetaPDF_Signer_Signature_Module_OpenSslCli
• SetaPDF_Signer_Signature_Module_OpenSslCliCms 

The method setSignCert() has been replaced by the setCertificate() method in each signature module.

The method setExtraCerts() has been replaced by the setExtraCertificates() method in each signature module.

Refactor Usage of Signature Appearances

Version 2 comes with signature appearances, so you do not need an own implementation anymore. It is possible to use a dynamic appearance with the possibility to configure the graphic, the background and the shown information.

The other way is to use a static appearance throug a XObject.

Both appearance classes extend the abstract class SetaPDF_Signer_Signature_Appearance_AbstractAppearance that also implements the SetaPDF_Signer_Signature_Module_ModuleInterface.

You have to refactor your code when you are using a visible signature.

Refactor Usage of Timestamp Modules

The class hierarchy of timestamp modules completely changed in version 2.

In version 1 the timestamp module extends the class SetaPDF_Signer_Module_Ts_Abstract.
This class has been removed and is replaced by the SetaPDF_Signer_Timestamp_Module_AbstractModule class to provide more flexibility in creating own timestamp modules.  

In version 2 the RFC 3161 standard is represented by the abstract class SetaPDF_Signer_Timestamp_Module_Rfc3161 that implements the interface SetaPDF_Signer_Timestamp_Module_ModuleInterface.

The class SetaPDF_Signer_Module_Ts_Curl does not exists anymore and its functionality is provided by the SetaPDF_Signer_Timestamp_Module_Rfc3161_Curl class that implements the timestamp interface too. 

$tsUrl = 'http://zeitstempel.dfn.de';
$tsUsername = null;                     // The username (if required)
$tsPassword = '';                       // The password (if required)

// old SetaPDF 1 code
$tsModule = new \SetaPDF_Signer_Module_Ts_Curl($tsUrl, $tsUsername, $tsPassword);

$signer->setTsModule($tsModule);
// ...


// becomes to:
$tsModule = new \SetaPDF_Signer_Timestamp_Module_Rfc3161_Curl('http://zeitstempel.dfn.de');
if (isset($tsUsername)) {
    $tsModule->setCurlOption(\CURLOPT_USERPWD, $tsUsername . ':' . $tsPassword);
}

$signer->setTimestampModule($tsModule);
// ...

Removed Methods

 The following methods have been removed:

• setSignature()  
• getSignature()
• getParsedSignature()
• getHash()
• setCertReq()
• getCertReq()
• _getTsq() (has been replaced by _getTimestampRequest)
• _getFinalSignature()
• onSet()

If your code relies on these methods you have to refactor.