SetaPDF-Signer Manual

Migrating

From Version 2.46 to >=2.47 (Namespaces)

In version 2.47 we finally introduce namespaces into the code base which results in a complete new class structure and class names.

All classes were renamed and we added a backwards compatiblity layer with the use of class aliases to support the old class names. So there's no real need to refactor but it's simply a cosmetic change and a matter of style. All our demos and documentation will use the namespaced version in the future.

The new root namespace for the SetaPDF-Signer component is: setasign\SetaPDF2\Signer

You can find the new class names by following the class alias definition in your IDE or simply search for the old class name in the manual.

We intensively tested the namespaced version with projects or our own test-suite using the old class names and an upgrade is possible without touching any code.

Anyhow we found very rare and special situations which you need to pay attention on and which we documented in the manual of the SetaPDF-Core component.

If you encounter any problem or question, do not hesitate to contact us at support@setasign.com.

From Version 2.0 to 2.1

What has changed

In version 2.1 a timestamp signature feature was implemented which results in separating the appearance classes from the main signature modules. This change ends in a backward incompatible change. 

Backward Incompatible Changes

In version 2.0 the \setasign\SetaPDF2\Signer\Signature\Appearance\AbstractAppearance class implements the
\setasign\SetaPDF2\Signer\Signature\Module\ModuleInterface interface to allow chaining of appearance and signature modules. Since version 2.1 the appearance classes are decoupled from the signature modules and need to be passed separately to the signer instance.

Furthermore the constructor arguments have changed in the \setasign\SetaPDF2\Signer\Signature\Appearance\XObject class.

Dynamic Appearance

Refactoring code that uses the dynamic appearance class has to be done as follows:

// create an OpenSSL module instance
$module = new \SetaPDF_Signer_Signature_Module_OpenSsl();
...
// create a Signature appearance
$visibleAppearance = new \SetaPDF_Signer_Signature_Appearance_Dynamic($module);
...
// sign the document with the appearance
$signer->sign($visibleAppearance);

becomes:

// create an OpenSSL module instance
$module = new \SetaPDF_Signer_Signature_Module_OpenSsl();
...
// create a Signature appearance
$visibleAppearance = new \SetaPDF_Signer_Signature_Appearance_Dynamic($module);
// Attach the visible appearance to the signer instance
$signer->setAppearance($visibleAppearance); // NEW
...
// sign the document with the appearance
$signer->sign($module); // PASS THE SIGNATURE MODULE INSTEAD OF THE APPEARANCE

XObject Appearance

Refactoring code that uses the XObject appearance class has to be done as follows:

// create an OpenSSL module instance
$module = new \SetaPDF_Signer_Signature_Module_OpenSsl();
...
// create a static visible appearance from the xObject
$visibleAppearance = new \SetaPDF_Signer_Signature_Appearance_XObject($module, $xObject);
...
// sign the document with the appearance
$signer->sign($visibleAppearance);

becomes:

// create an OpenSSL module instance
$module = new \SetaPDF_Signer_Signature_Module_OpenSsl();
...
// create a static visible appearance from the xObject
$visibleAppearance = new \SetaPDF_Signer_Signature_Appearance_XObject($module, $xObject);
// Attach the visible appearance to the signer instance
$signer->setAppearance($visibleAppearance); // NEW
...
// sign the document with the appearance
$signer->sign($module); // PASS THE SIGNATURE MODULE INSTEAD OF THE APPEARANCE