SetaPDF_Signer The main class of the SetaPDF-Signer Component

File: /SetaPDF/Signer.php

Class hierarchy

Summary

Constants

CERTIFICATION_LEVEL_FORM_FILLING

Certification level constant

CERTIFICATION_LEVEL_FORM_FILLING_AND_ANNOTATIONS

Certification level constant

CERTIFICATION_LEVEL_NONE

Certification level constant

CERTIFICATION_LEVEL_NO_CHANGES_ALLOWED

Certification level constant

PROP_CONTACT_INFO

const string SetaPDF_Signer::PROP_CONTACT_INFO = 'ContactInfo'

Property constant

PROP_LOCATION

const string SetaPDF_Signer::PROP_LOCATION = 'Location'

Property constant

PROP_NAME

const string SetaPDF_Signer::PROP_NAME = 'Name'

Property constant

PROP_REASON

const string SetaPDF_Signer::PROP_REASON = 'Reason'

Property constant

PROP_TIME_OF_SIGNING

Property constant

VERSION

const string SetaPDF_Signer::VERSION = '2.24.0.1049'

Version


Properties

$_allowSignatureContentLengthChange

Defines if the signatureContentLength property can be changed automatically, if a signature value doesn't fit into the reserved space.

$_byteRange

The byte range value

$_certificationLevel

The certification level

$_document

Document which shall be signed

$_fieldName

protected string SetaPDF_Signer::$_fieldName = 'Signature'

The signature field name

$_offsetEndPlaceholder

protected string SetaPDF_Signer::$_offsetEndPlaceholder = '(<---OFFSET--->)'

A placeholder for the second length value in the ByteRange array

$_placeHolderByteOffset

The byte offset position of the place holder/reserved space

$_secHandlerCallback

protected null|callback SetaPDF_Signer::$_secHandlerCallback

The callback for authenticating at the security handler of the document

$_signatureContentLength

The byte length of the reserved space for the signature content

$_signatureProperties

protected array SetaPDF_Signer::$_signatureProperties = array(...)

The signature properties

$_tempDocument

A temporary instance of the signed document

$_tempWriter

The temporary writer instance

$_timestampModule


Methods

__construct()

public SetaPDF_Signer::__construct ( SetaPDF_Core_Document $document [, callback|null $secHandlerCallback = null ] )

The constructor.

If the passed document is protected by a security handler it is possible to pass a callback as second parameter that will be called if an authentication is needed.

Parameters
$document : SetaPDF_Core_Document

The document instance

$secHandlerCallback : callback|null

A callback which should auth on a security handler (if needed). The callback will be called with two parameters: The first parameter will be the security handler and the second parameter is the current document instance.

_addDocMp()

protected void SetaPDF_Signer::_addDocMp ( SetaPDF_Core_Type_Dictionary $dictionary )

Adds the document modification detection and prevention data.

Parameters
$dictionary : SetaPDF_Core_Type_Dictionary
 

_callSecHandlerCallback()

Calls a defined callback that should authenticate on the documents security handler.

Parameters
$document : SetaPDF_Core_Document

The document instance

_checkCertificationLevel()

protected void SetaPDF_Signer::_checkCertificationLevel ( void )

Checks if a document is already certified.

Exceptions

Throws SetaPDF_Signer_Exception

_createSignatureDictionary()

Creates the signature dictionary.

Parameters
$field : SetaPDF_Signer_SignatureField

The signature field

$module : null|SetaPDF_Signer_Signature_DictionaryInterface
 

_createTimestampSignatureDictionary()

Creates the signature dictionary.

Parameters
$field : SetaPDF_Signer_SignatureField

The signature field

$module : null|SetaPDF_Signer_Signature_DictionaryInterface
 

_ensureSignatureField()

protected null|SetaPDF_Signer_SignatureField SetaPDF_Signer::_ensureSignatureField ( SetaPDF_Core_Document $document [, bool $returnFieldInstance = false ] )

Ensures a valid signature field instance.

Parameters
$document : SetaPDF_Core_Document

The document instance

$returnFieldInstance : bool

If true the field instance will be returned, otherwise null will be returned.

Exceptions

Throws SetaPDF_Signer_Exception

_prepareTmpDocument()

Prepares the temporary document instance.

Parameters
$type : string
 
$tmpDocument : SetaPDF_Signer_TmpDocument
 
$path : string
 
$module : null|SetaPDF_Signer_Signature_DictionaryInterface
 
Exceptions

Throws SetaPDF_Core_Exception, SetaPDF_Signer_Exception

_updateAcroForm()

Updates the AcroForm dictionary.

Parameters
$document : SetaPDF_Core_Document

The document instance

addSignatureField()

public SetaPDF_Signer_SignatureField SetaPDF_Signer::addSignatureField ( [ string $fieldName = \SetaPDF_Signer_SignatureField::DEFAULT_FIELD_NAME [, int $pageNumber = 1 [, int|string $xOrPosition = 0 [, int|array $yOrTranslate = 0 [, int $width = 0 [, int $height = 0 ]]]]]] )

Proxy method for SetaPDF_Signer_SignatureField::add().

Parameters
$fieldName : string

The field name in UTF-8 encoding

$pageNumber : int

The page number on which the signature field shall appear.

$xOrPosition : int|string

Integer with the x-position or SetaPDF_Signer_SignatureField::POSITION_XXX

$yOrTranslate : int|array

Integer with the y-position (if $xOrPosition is an integer) or an array with the keys 'x' and 'y'

$width : int

Width of the signature field

$height : int

Height of the signature field

See

addTimeStamp()

public string SetaPDF_Signer::addTimeStamp ( string $signature, SetaPDF_Signer_TmpDocument $tmpDocument )

Forwards the signature to a timestamp module and merges the result into the signature container.

Parameters
$signature : string
 
$tmpDocument : SetaPDF_Signer_TmpDocument
 
Exceptions

Throws SetaPDF_Signer_Exception

cleanUp()

public void SetaPDF_Signer::cleanUp ( void )

Release memory and cycled references.

createSignature()

Creates a signature based on a temporary document instance and a signature module.

Parameters
$tmpDocument : SetaPDF_Signer_TmpDocument
 
$module : SetaPDF_Signer_Signature_Module_ModuleInterface
 
Exceptions

Throws SetaPDF_Signer_Exception

See

createTimestampSignature()

Creates a timestamp signature based on a temporary document instance.

The timestamp module has to be added to the signer instance through the setTimeStampModule() method.

Parameters
$tmpDocument : SetaPDF_Signer_TmpDocument
 
Exceptions

Throws SetaPDF_Signer_Exception

See

getAllowSignatureContentLengthChange()

Get the flag specifying whether the signature content length (reserved space) could be changed automatically ot not.

getAppearance()

Get the current appearance module.

getContactInfo()

public bool|string SetaPDF_Signer::getContactInfo ( void )

Get the information provided by the signer to enable a recipient to contact the signer to verify the signature.

Return Values

If no contact info exist FALSE will be returned. Otherwise the value will be returned.

See

getLocation()

public bool|string SetaPDF_Signer::getLocation ( void )

Get the CPU host name or physical location of the signing.

Return Values

If no location exist FALSE will be returned. Otherwise the value will be returned.

See

getName()

public bool|string SetaPDF_Signer::getName ( void )

Get the name of the person or authority signing the document.

Return Values

If no name exist FALSE will be returned. Otherwise the value will be returned.

See

getReason()

public bool|string SetaPDF_Signer::getReason ( void )

Get the reason for the signing.

Return Values

If no name exist FALSE will be returned. Otherwise the value will be returned.

See

getSignatureContentLength()

public integer SetaPDF_Signer::getSignatureContentLength ( void )

Get the signature content length that will be used to reserve space for the final signature.

getSignatureField()

public bool|SetaPDF_Signer_SignatureField SetaPDF_Signer::getSignatureField ( [ string $fieldName = \SetaPDF_Signer_SignatureField::DEFAULT_FIELD_NAME [, bool $create = true ]] )

Proxy method the SetaPDF_Signer_SignatureField::get().

Parameters
$fieldName : string

The field name in UTF-8 encoding

$create : bool

Automatically creates a hidden field if none was found by the specified name

See

getSignatureProperty()

public bool|string SetaPDF_Signer::getSignatureProperty ( string $name )

Get a signature property.

Parameters
$name : string

See and use SetaPDF_Signer::PROP_* constants for valid names

Return Values

If the name is not valid FALSE will be returned. Otherwise the value will be returned.

getTimeOfSigning()

Get the time of signing.

Return Values

If no name exist FALSE will be returned. Otherwise the value will be returned as SetaPDF_Core_DataStructure_Date.

See

getTimestampModule()

Get the current timestamp module.

preSign()

Prepares a temporary document instance to be used further in an asynchronous signature workflow.

Parameters
$writer : SetaPDF_Core_Writer_FileInterface
 
$module : null|SetaPDF_Signer_Signature_DictionaryInterface
 
Exceptions

Throws SetaPDF_Signer_Exception

See

preTimestamp()

Prepares a temporary document instance to be used further in an asynchronous timestamp workflow.

Parameters
$writer : SetaPDF_Core_Writer_FileInterface
 
$module : null|SetaPDF_Signer_Signature_DictionaryInterface
 
Exceptions

Throws SetaPDF_Signer_Exception

See

saveSignature()

public void SetaPDF_Signer::saveSignature ( SetaPDF_Signer_TmpDocument $tmpDocument, string $signature )

Add a signature result to the temporary document instance and saves it to the main documents writer instance.

Parameters
$tmpDocument : SetaPDF_Signer_TmpDocument
 
$signature : string

The PKCS7 byte string to be added to the temporary document.

Exceptions

Throws SetaPDF_Signer_Exception, SetaPDF_Signer_Exception_ContentLength

setAllowSignatureContentLengthChange()

public void SetaPDF_Signer::setAllowSignatureContentLengthChange ( bool $allowSignatureContentLengthChange )

Set a flag specifying whether the signature content length (reserved space) could be changed automatically or not.

If this value is set to true and the resulting signature is bigger than the reserved space (defined by SetaPDF_Signer::setSignatureContentLength()) the signature content length will be increased and the signature process will restart.

Parameters
$allowSignatureContentLengthChange : bool

The flag status

setAppearance()

Set an appearance instance.

Parameters
$appearance : SetaPDF_Signer_Signature_Appearance_AbstractAppearance

The appearance instance

setCertificationLevel()

setContactInfo()

public void SetaPDF_Signer::setContactInfo ( string $contactInfo )

Set the information provided by the signer to enable a recipient to contact the signer to verify the signature.

Parameters
$contactInfo : string

The contact info in UTF-8 encoding

See

setLocation()

public void SetaPDF_Signer::setLocation ( string $location )

Set the host name or physical location of the signing.

Parameters
$location : string

The physical location or host name in UTF-8 encoding

See

setName()

public void SetaPDF_Signer::setName ( string $name )

Set the name of the person or authority signing the document.

Parameters
$name : string

The value in UTF-8 encoding

See

setReason()

public void SetaPDF_Signer::setReason ( string $reason )

Set the reason for the signing.

Parameters
$reason : string

The reason for the signing in UTF-8 encoding

See

setSignatureContentLength()

public void SetaPDF_Signer::setSignatureContentLength ( integer $length )

Set the signature content length that will be used to reserve space for the final signature.

Parameters
$length : integer

The length of the signature content.

setSignatureFieldName()

public void SetaPDF_Signer::setSignatureFieldName ( string $fieldName )

Set the signature field name.

This can be the name of an existing signature field or an individual name which will be used to create a hidden field automatically.

Parameters
$fieldName : string

The field name in UTF-8 encoding

setSignatureProperty()

public void SetaPDF_Signer::setSignatureProperty ( string $name, string $value )

Set a signature property.

Parameters
$name : string

See and use SetaPDF_Signer::PROP_* constants for valid names

$value : string

The value in UTF-8 encoding

Exceptions

Throws InvalidArgumentException if the name is not valid

setTimeOfSigning()

public void SetaPDF_Signer::setTimeOfSigning ( string $timeOfSigning )

Set the time of signing.

Parameters
$timeOfSigning : string

The time of signing in UTF-8 encoding

See

setTimestampModule()

Set a timestamp module.

Parameters
$module : SetaPDF_Signer_Timestamp_Module_ModuleInterface

The timestamp module instance

sign()

Digital signs the initial document.

The SetaPDF_Core_Document instance will be temporary saved and finished. It is not possible to work on it further. The final PDF will be passed to the previously attached writer instance, so that the final signed document will be written to the correct writer.

Parameters
$module : SetaPDF_Signer_Signature_Module_ModuleInterface

The module instance

Exceptions

Throws SetaPDF_Signer_Exception

timestamp()

public void SetaPDF_Signer::timestamp ( void )

Adds a document level timestamp.

The SetaPDF_Core_Document instance will be temporary saved and finished. It is not possible to work on it further. The final PDF will be passed to the previously attached writer instance, so that the final signed document will be written to the correct writer.

Exceptions

Throws InvalidArgumentException