Signature Fields

Introduction

A digital signature in a PDF document requires a signature field. This field may be hidden or displayed through a widget annotation on a specific page.

The SetaPDF-Signer component represents a signature field through the SetaPDF_Signer_SignatureField class. This class comes with some static method to add, get or remove signature fields by their names.

Create Hidden Signature Fields

Simple hidden signature fields can be created by just some lines of code. The document instance could be created by an existing document as well! 

PHP
<?php
require_once('library/SetaPDF/Autoload.php');

// create a writer
$writer = new \SetaPDF_Core_Writer_Http('hidden-field.pdf', true);
// create a new document instance
$document = new \SetaPDF_Core_Document($writer);
// create at least a single page
$document->getCatalog()->getPages()->create(\SetaPDF_Core_PageFormats::A4);

// add some hidden signature fields on page 1
\SetaPDF_Signer_SignatureField::add($document, 'Signature field 1');
\SetaPDF_Signer_SignatureField::add($document, 'Signature field 2');

// save and finish
$document->save()->finish();

To automatically get or create a signature field instance the class also offers a get() method, that will create a hidden signature field automatically if no signature field was found: 

PHP
$field = SetaPDF_Signer_SignatureField::get($document, 'Signature');

Creating Visible Signature Fields

The SetaPDF_Signer_SignatureField class allows you to create visible signature fields by absolute or relative positions. 

PHP
<?php
require_once('library/SetaPDF/Autoload.php');

// create a writer
$writer = new \SetaPDF_Core_Writer_Http('visible-field.pdf', true);
// create a new document instance
$document = new \SetaPDF_Core_Document($writer);
// create at least a single page
$document->getCatalog()->getPages()->create(\SetaPDF_Core_PageFormats::A4);

// add a field left top with an offset of 10 points
\SetaPDF_Signer_SignatureField::add(
    $document,
    'Signature field 1',
    1,
    \SetaPDF_Signer_SignatureField::POSITION_LEFT_TOP,
    array('x' => 10, 'y' => -10),
    180,
    70
);


// add a field absolutely position on the bottom left with an offset of 10 points
\SetaPDF_Signer_SignatureField::add($document, 'Signature field 1', 1, 10, 10, 180, 70);

// save and finish
$document->save()->finish();

Naming of Signature Fields

If no name parameter is passed to either the add() or get() methods, the default field name will be used: 

public const string SetaPDF_Signer_SignatureField::DEFAULT_FIELD_NAME = 'Signature'

The default signature field name

If a name that is passed to the add() method already exists it will be suffixed with a numeric incrementing value.

You can check the final name with the getQualifiedName() method.

So a common logic to have a unique signature field would be:

PHP
$field = $signer->addSignatureField();
$signer->setSignatureFieldName($field->getQualifiedName());

Handle Existing Signature Fields

To get the names of existing signature fields, the SetaPDF_Signer class offers the needed method:

Description
public static SetaPDF_Signer::getSignatureFieldNames (): string[]

Returns all signature field names.

Parameters
$document : SetaPDF_Core_Document
 
Exceptions

Throws SetaPDF_Core_SecHandler_Exception

Throws SetaPDF_Core_Type_Exception

Throws SetaPDF_Core_Type_IndirectReference_Exception

Check if a Signature Field is in Use

You can use the getValue() method of a SetaPDF_Signer_SignatureField instance to check if the field is in use or not:

PHP
$signatureFieldNames = \SetaPDF_Signer::getSignatureFieldNames($document);
foreach ($signatureFieldNames as $signatureFieldName) {
    $field = \SetaPDF_Signer_SignatureField::get($document, $signatureFieldName);
    if ($field->getValue() === null) {
        echo "Signature field '" . $signatureFieldName . "' is NOT in use!\n";
    } else {
        echo "Signature field '" . $signatureFieldName . "' is in use!\n";
    }
}

Delete an Existing Signature Field

If you want to delete an existing signature field you can use following static method of the SetaPDF_Signer_SignatureField class:

Description
public static SetaPDF_Signer_SignatureField::delete (
SetaPDF_Core_Document $document, string $fieldName
): bool

Deletes a signature field by its name.

ATTENTION: If there are other signature fields in use their signature will get invalid.

Parameters
$document : SetaPDF_Core_Document
 
$fieldName : string
 
Exceptions

Throws SetaPDF_Core_Exception

Throws SetaPDF_Core_SecHandler_Exception

Throws SetaPDF_Core_Type_Exception

Throws SetaPDF_Core_Type_IndirectReference_Exception

Throws SetaPDF_Signer_Exception

Clear an Existing Signature Field Value

It is an uncommon task but sometimes it is needed to reset or clear the signature value of an existing signature field. For this task the SetaPDF_Signer_SignatureField class comes with an additional static method:

Description
public static SetaPDF_Signer_SignatureField::clear (
SetaPDF_Core_Document $document, string $fieldName [, bool $clearAppearance = true ]
): bool

Clears the signature from a signature field by its name.

Parameters
$document : SetaPDF_Core_Document
 
$fieldName : string
 
$clearAppearance : bool
 
Exceptions

Throws SetaPDF_Core_Exception

Throws SetaPDF_Core_SecHandler_Exception

Throws SetaPDF_Core_Type_Exception

Throws SetaPDF_Core_Type_IndirectReference_Exception

Throws SetaPDF_Signer_Exception