SetaPDF-Signer Manual

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 \setasign\SetaPDF2\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

use setasign\SetaPDF2\Core\Document;
use setasign\SetaPDF2\Core\PageFormats;
use setasign\SetaPDF2\Core\Writer\HttpWriter;
use setasign\SetaPDF2\Signer\SignatureField;

require_once('library/SetaPDF/Autoload.php');

// create a writer
$writer = new HttpWriter('hidden-fields.pdf', true);
// create a new document instance
$document = new Document($writer);
// create at least a single page
$document->getCatalog()->getPages()->create(PageFormats::A4);

// add some hidden signature fields on page 1
SignatureField::add($document, 'Signature field 1');
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: 

$field = \setasign\SetaPDF2\Signer\SignatureField::get($document, 'Signature');

Creating Visible Signature Fields

The \setasign\SetaPDF2\Signer\SignatureField class allows you to create visible signature fields by absolute or relative positions. 

<?php

use setasign\SetaPDF2\Core\Document;
use setasign\SetaPDF2\Core\PageFormats;
use setasign\SetaPDF2\Core\Writer\HttpWriter;
use setasign\SetaPDF2\Signer\SignatureField;

require_once('library/SetaPDF/Autoload.php');

// create a writer
$writer = new HttpWriter('visible-fields.pdf', true);
// create a new document instance
$document = new Document($writer);
// create at least a single page
$document->getCatalog()->getPages()->create(PageFormats::A4);

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


// add a field absolutely position on the bottom left with an offset of 10 points
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: 

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:

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

Handle Existing Signature Fields

To get the names of existing signature fields, the \setasign\SetaPDF2\Signer\Signer class offers the needed method:

Check if a Signature Field is in Use

You can use the getValue() method of a \setasign\SetaPDF2\Signer\SignatureField instance to check if the field is in use or not:

use setasign\SetaPDF2\Signer\Signer;
use setasign\SetaPDF2\Signer\SignatureField;

$signatureFieldNames = Signer::getSignatureFieldNames($document);
foreach ($signatureFieldNames as $signatureFieldName) {
    $field = 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 \setasign\SetaPDF2\Signer\SignatureField class:

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 \setasign\SetaPDF2\Signer\SignatureField class comes with an additional static method: