SetaPDF v2 API Reference

): ?int

Check a PDF document for a certification signature and its level

Parameters

$document : \setasign\SetaPDF2\Core\Document

Return Values

The certification level or null if the document has no certification signature.

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

getSignatureFieldNames()

public static Signer::getSignatureFieldNames (

): string[]

Returns all signature field names.

Parameters

$document : \setasign\SetaPDF2\Core\Document

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

sanitizeSaveMethod()

public static Signer::sanitizeSaveMethod (

int $document,
$saveMethod

): int

Sanitize the $saveMethod parameter for the intermediate save() call

This method checks if the $saveMethod parameter can be kept or if it has to be changed to Document::SAVE_METHOD_UPDATE.

It has to be changed to "update" as soon as an existing signature exists or the document includes usage rights.

Parameters

$document : int
$saveMethod

Exceptions

Throws Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Methods

__construct()

public Signer::__construct (

\setasign\SetaPDF2\Core\Document $document,
?callback $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 : \setasign\SetaPDF2\Core\Document: The document instance
$secHandlerCallback : ?callback: 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. It should return true or false whether the authentication was successful or not.

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

_addDocMp()

protected Signer::_addDocMp (

\setasign\SetaPDF2\Core\Type\PdfDictionary $dictionary

): void

Adds the document modification detection and prevention data.

Parameters

$dictionary : \setasign\SetaPDF2\Core\Type\PdfDictionary

_callSecHandlerCallback()

protected Signer::_callSecHandlerCallback (

): void

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

Parameters

$document : \setasign\SetaPDF2\Core\Document: The document instance

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

_checkCertificationLevel()

protected Signer::_checkCertificationLevel (

void

): void

Verifies if the defined certification level can be applied.

Certification signatures can only be applied if the document has no other existing signature.

Exceptions

Throws Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

): \setasign\SetaPDF2\Core\Type\PdfIndirectObject

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

_createSignatureDictionary()

protected Signer::_createSignatureDictionary (

SignatureField $field,
?Signature\Module\DictionaryInterface $module = null

Creates the signature dictionary.

Parameters

$field : SignatureField: The signature field
$module : ?Signature\Module\DictionaryInterface

Exceptions

Throws \Exception

_createTimestampSignatureDictionary()

protected Signer::_createTimestampSignatureDictionary (

SignatureField $field,
?Signature\Module\DictionaryInterface $module = null

): void

Creates the signature dictionary.

Parameters

$field : SignatureField: The signature field
$module : ?Signature\Module\DictionaryInterface

_ensureSignatureField()

protected Signer::_ensureSignatureField (

\setasign\SetaPDF2\Core\Document $document,
bool $returnFieldInstance = false

): ?SignatureField

Ensures a valid signature field instance.

Parameters

$document : \setasign\SetaPDF2\Core\Document: The document instance
$returnFieldInstance : bool: If true the field instance will be returned, otherwise null will be returned.

Exceptions

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws Exception

_prepareTmpDocument()

protected Signer::_prepareTmpDocument (

string $type,
TmpDocument $tmpDocument,
string $path,
?Signature\Module\DictionaryInterface $module = null

): TmpDocument

Prepares the temporary document instance.

Parameters

$type : string
$tmpDocument : TmpDocument
$path : string
$module : ?Signature\Module\DictionaryInterface

Exceptions

Throws Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Core\Document\ObjectNotDefinedException

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

_updateAcroForm()

protected Signer::_updateAcroForm (

): void

Updates the AcroForm dictionary.

Parameters

$document : \setasign\SetaPDF2\Core\Document: The document instance

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

addSignatureField()

public Signer::addSignatureField (

string $fieldName = SignatureField ::DEFAULT_FIELD_NAME,
int $pageNumber = 1,
int|string $xOrPosition = 0,
int|array $yOrTranslate = 0,
int $width = 0,
int $height = 0

): SignatureField

Proxy method for 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 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

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

See

SignatureField::add()

addTimeStamp()

public Signer::addTimeStamp (

string $signature,
TmpDocument $tmpDocument

): string

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

Parameters

$signature : string
$tmpDocument : TmpDocument

Exceptions

Throws Asn1 \Exception

Throws Exception

cleanUp()

public Signer::cleanUp (

void

): void

Release memory and cycled references.

createSignature()

public Signer::createSignature (

TmpDocument $tmpDocument,
Signature\Module\ModuleInterface $module

): string

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

Parameters

$tmpDocument : TmpDocument
$module : Signature\Module\ModuleInterface

Exceptions

Throws Exception

See

createTimestampSignature()

public Signer::createTimestampSignature (

TmpDocument $tmpDocument

): string

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 : TmpDocument

Exceptions

Throws Exception

): Signature\Appearance\AbstractAppearance

See

getAllowSignatureContentLengthChange()

public Signer::getAllowSignatureContentLengthChange (

void

): bool

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

getAppearance()

public Signer::getAppearance (

void

Get the current appearance module.

getCertificationLevel()

public Signer::getCertificationLevel (

void

): int

Get the certification level.

Possible values are defined in the Signer::CERTIFICATION_LEVEL_* constants.

See

getContactInfo()

public Signer::getContactInfo (

void

): bool|string

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

Signer::getSignatureProperty()

getLocation()

public Signer::getLocation (

void

): bool|string

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

Signer::getSignatureProperty()

getName()

public Signer::getName (

void

): bool|string

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

Signer::getSignatureProperty()

getReason()

public Signer::getReason (

void

): bool|string

Get the reason for the signing.

Return Values

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

See

Signer::getSignatureProperty()

getSignatureContentLength()

public Signer::getSignatureContentLength (

void

): int

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

getSignatureField()

public Signer::getSignatureField (

string $fieldName = SignatureField ::DEFAULT_FIELD_NAME,
bool $create = true

): bool|SignatureField

Proxy method to 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

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws Exception

): \setasign\SetaPDF2\Core\DataStructure\Date

See

SignatureField::get())

getSignatureProperty()

public Signer::getSignatureProperty (

string $name

): bool|string

Get a signature property.

Parameters

$name : string: See and use 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()

public Signer::getTimeOfSigning (

void

Get the time of signing.

Exceptions

Throws \Exception

See

Signer::getSignatureProperty()

getTimestampModule()

public Signer::getTimestampModule (

void

): Timestamp\Module\ModuleInterface

Get the current timestamp module.

preSign()

public Signer::preSign (

\setasign\SetaPDF2\Core\Writer\FileInterface $writer,
?Signature\Module\DictionaryInterface $module = null,
int $saveMethod = \setasign\SetaPDF2\Core\Document ::SAVE_METHOD_UPDATE

): TmpDocument

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

Parameters

$writer : \setasign\SetaPDF2\Core\Writer\FileInterface
$module : ?Signature\Module\DictionaryInterface
$saveMethod : int: The $method parameter passed to sanitizeSaveMethod() and finally passed to the main \setasign\SetaPDF2\Core\Document::save() call of the document instance.

Exceptions

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Core\Document\ObjectNotDefinedException

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws Exception

See

Signer::createSignature()

preTimestamp()

public Signer::preTimestamp (

\setasign\SetaPDF2\Core\Writer\FileInterface $writer,
?Signature\Module\DictionaryInterface $module = null,
int $saveMethod = \setasign\SetaPDF2\Core\Document ::SAVE_METHOD_UPDATE

): TmpDocument

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

Parameters

$writer : \setasign\SetaPDF2\Core\Writer\FileInterface

$module : ?Signature\Module\DictionaryInterface

$saveMethod : int

The $method parameter passed to sanitizeSaveMethod() and finally

                     passed to the main <a href="/api-reference/setapdf/c/setasign.SetaPDF2.Core.Document#method_save">\setasign\SetaPDF2\Core\Document::save()</a> call of the

                     document instance.

Exceptions

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Core\Document\ObjectNotDefinedException

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws Exception

See

Signer::createSignature()

saveSignature()

public Signer::saveSignature (

TmpDocument $tmpDocument,
string $signature

): void

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

Parameters

$tmpDocument : TmpDocument
$signature : string: The PKCS7 byte string to be added to the temporary document.

Exceptions

Throws Exception

setAllowSignatureContentLengthChange()

public Signer::setAllowSignatureContentLengthChange (

bool $allowSignatureContentLengthChange

): void

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 Signer::setSignatureContentLength() the signature content length will be increased and the signature process will restart.

Parameters

$allowSignatureContentLengthChange : bool: The flag status

setAppearance()

public Signer::setAppearance (

?Signature\Appearance\AbstractAppearance $appearance = null

): void

Set an appearance instance.

Parameters

$appearance : ?Signature\Appearance\AbstractAppearance: The appearance instance

setCertificationLevel()

public Signer::setCertificationLevel (

int $certificationLevel

): void

Set the certification level.

Parameters

$certificationLevel : int: Possible values are defined in the Signer::CERTIFICATION_LEVEL_XXX constants.

See

setContactInfo()

public Signer::setContactInfo (

string $contactInfo

): void

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

Signer::setSignatureProperty()

setLocation()

public Signer::setLocation (

string $location

): void

Set the host name or physical location of the signing.

Parameters

$location : string: The physical location or host name in UTF-8 encoding

See

Signer::setSignatureProperty()

setName()

public Signer::setName (

string $name

): void

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

Parameters

$name : string: The value in UTF-8 encoding

See

Signer::setSignatureProperty()

setReason()

public Signer::setReason (

string $reason

): void

Set the reason for the signing.

Parameters

$reason : string: The reason for the signing in UTF-8 encoding

See

Signer::setSignatureProperty()

setSignatureContentLength()

public Signer::setSignatureContentLength (

int $length

): void

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

Parameters

$length : int: The length of the signature content.

setSignatureFieldName()

public Signer::setSignatureFieldName (

string $fieldName

): void

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 Signer::setSignatureProperty (

string $name,
string $value

): void

Set a signature property.

Parameters

$name : string: See and use 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 Signer::setTimeOfSigning (

string|\DateTime|\setasign\SetaPDF2\Core\DataStructure\Date $timeOfSigning

): void

Set the time of signing.

Parameters

$timeOfSigning : string|\DateTime|\setasign\SetaPDF2\Core\DataStructure\Date: The time of signing in UTF-8 encoding

See

Signer::setSignatureProperty()

setTimestampModule()

public Signer::setTimestampModule (

?Timestamp\Module\ModuleInterface $module = null

): void

Set a timestamp module.

Parameters

$module : ?Timestamp\Module\ModuleInterface: The timestamp module instance

sign()

public Signer::sign (

Signature\Module\ModuleInterface $module,
int $saveMethod = \setasign\SetaPDF2\Core\Document ::SAVE_METHOD_UPDATE

): void

Digital signs the initial document.

The \setasign\SetaPDF2\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 : Signature\Module\ModuleInterface: The module instance
$saveMethod : int: The $method parameter passed to sanitizeSaveMethod() and finally passed to the main \setasign\SetaPDF2\Core\Document::save() call of the document instance.

Exceptions

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Core\Document\ObjectNotDefinedException

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws Exception

timestamp()

public Signer::timestamp (

int $saveMethod = \setasign\SetaPDF2\Core\Document ::SAVE_METHOD_UPDATE

): string

Adds a document level timestamp.

Parameters

$saveMethod : int: The $method parameter passed to sanitizeSaveMethod() and finally passed to the main \setasign\SetaPDF2\Core\Document::save() call of the document instance.

Return Values

The timestamp token/signature

Exceptions

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Core\Document\ObjectNotDefinedException

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\SecHandler\Exception