Skip to content

document.md

Latest commit

 

History

History
135 lines (108 loc) · 6 KB

document.md

File metadata and controls

135 lines (108 loc) · 6 KB
Raw

Documents

The document object represents (and contains) the document file. Creating documents via the SDK currently supports PDF only (signable document or annex). The API uses a generic file field; setFile() is the preferred way to supply the path, while setPdfFile() remains for compatibility.

A document can either be a signable document or an unsignable annex. Documents are always linked to a case file and can't exist on their own.

Creating a document

Creating a document requires that you have a case file first since a document can't exist on its own. The case file must be passed to the Document constructor and the document will be linked to the case file. Per default, a document is an annex that can't be signed. To make a document signable, the makeSignable() method must be called. The following example shows how to create a signable document linked to $myCaseFile:

// Create a new document object
$myDocument = new Document($myCaseFile);

// Set the document title
$myDocument->setTitle('My brand new document');

// Add the PDF file (generic `file` field on the API)
$myDocument->setFile('/path/to/document.pdf');

// Make the document signable
$myDocument->makeSignable();

// Optionally set the display order (0-indexed; controls the order signers see documents)
$myDocument->setDocumentOrder(0);

// Finally, persist the object
Document::persist($myDocument);

Note: setPdfFile() still works but is deprecated. Use setFile() for new code — same behaviour today (PDF), aligned with the API’s file parameter for future formats.

Retrieve existing documents

There is several ways to retrieve document from Penneo. Available methods for retrieving documents are:

  • Document::find($id) Find one specific document by its ID.
  • Document::findAll() Find all documents accessible by the authenticated user.
  • Document::findBy(array $criteria, array $orderBy, $limit, $offset) Find all documents matching $criteria ordered by $orderBy. If $limit is set, only $limit results are returned. If $offset is set, the $offset first results are skipped. Criteria can either be title or metaData.
  • Document::findOneBy(array $criteria, array $orderBy) Same as findBy setting $limit = 1 and $offset = null
  • Document::findByTitle($title, array $orderBy, $limit, $offset) Same as findBy using title as criteria.
  • Document::findOneByTitle($title, array $orderBy) Same as findOneBy using title as criteria.
  • Document::findByMetaData($metaData, array $orderBy, $limit, $offset) Same as findBy using metaData as criteria.
  • Document::findOneByMetaData($metaData, array $orderBy) Same as findOneBy using metaData as criteria.

Below is a couple of examples:

// Retrieve all documents
$myDocuments = Document:findAll();

// Retrieve a specific document (by id)
$myDocument = Document::find(7382393);

// Retrieve all documents that contains the word "the" in their title and sort descending by creation date
$myDocuments = Document::findByTitle(
	'the',
	array('created' => 'desc')
);

// Retrieve documents from offset 10 until 110 ordered by title in ascending order
$myDocuments = Document::findBy(
	array(),
	array('title' => 'asc'),
	10,
	100
);

Downloading the document content

When the signing process is completed (when getStatus() returns "completed"), the signed document can be downloaded by calling getContent():

// Download the signed document (binary)
$binary = $myDocument->getContent();
file_put_contents('signed-document.pdf', $binary);

// Download the unsigned version
$unsigned = $myDocument->getContent(false);

// Document format as returned by the API (typically "pdf" today)
$format = $myDocument->getFormat();

The getContent() method accepts one optional parameter:

Parameter Type Default Description
$signed bool true Return the signed version when available

Note: getPdf() still works but is deprecated. Use getContent() for new code — raw binary from /content without base64 JSON.

Retrieving linked objects

A signable document contains signature lines. These objects can be retrieved using the following methods:

  • getSignatureLines() Returns the signature lines linked to the document as an array of signature line objects.
  • findSignatureLine($id) Find and return a specific signature line by $id.

State variables

A series state variables are used to describe the document state over the course of its life time. The methods for retrieving the state variables are described below:

  • getStatus() Returns the status of the document as a string. Possible status values are:
  • new: The document hasn't been sent out for signing yet
  • pending: The document is out for signing
  • rejected: One of the signers has rejected to sign
  • deleted: The document has been out for signing but have since been deleted
  • signed: The document is signed, but the signed document is not generated yet
  • completed: The signing process is completed
  • getCreatedAt() Returns the date and time when the document was created as a DateTime object.
  • getModifiedAt() Returns the date and time when the document was last modified as a DateTime object.
  • getCompletedAt() Returns the date and time when the document signing process was finalized as a DateTime object.
  • getDocumentId() Returns the unique ID that is stamped on every page in the document for identification purposes.
  • getDocumentOrder() Returns the display order of the document (integer, 0-indexed). Controls the order in which signers see documents within a case file.
  • setDocumentOrder($order) Sets the display order. Can be called before persist() (create) or before Document::persist($doc) on an existing document (update).
  • getFormat() Returns the document format as a string (typically "pdf"). Returns null for locally created documents that have not been persisted yet.
  • getOptions() Returns the option values assigned to the document.