omnisense/omnisign API reference

Omnisign

Config class

final class Config extends ArrayObject Config.php:13

A gateway's configuration while its factory builds it: the options given, the factory's defaults under them, and the keys that must be filled.

Config::defaults()

public function defaults(array $defaults): self

Sets each key not set yet.

Config::validateNotEmpty()

public function validateNotEmpty(array $keys): void

Config::get()

public function get(string $key, mixed $default = null): mixed

Config::bool()

public function bool(string $key): bool

A boolean option, as an environment variable gives it too: "1", "true", "yes", "on".

Config::list()

public function list(string $key): array

A list given as one environment variable arrives as a single comma-separated string: split here, at run time.

Gateway class

final class Gateway implements GatewayInterface Gateway.php:15

A gateway's actions behind one door: the first action supporting a request answers it.

Gateway::__construct()

public function __construct(readonly string $name, readonly string $title, readonly Capabilities $capabilities, readonly array $actions)

Gateway::getName()

public function getName(): string

Gateway::getTitle()

public function getTitle(): string

Gateway::capabilities()

public function capabilities(): Capabilities

Gateway::supports()

public function supports(string $request): bool

Gateway::execute()

public function execute(Request\Request $request): Request\Request

Gateway::create()

public function create(Envelope $envelope): Envelope

Gateway::send()

public function send(Envelope $envelope): Envelope

Gateway::fetch()

public function fetch(Envelope $envelope): Envelope

Gateway::remind()

public function remind(Envelope $envelope, ?string $signer = null): Envelope

Gateway::cancel()

public function cancel(Envelope $envelope, ?string $reason = null): Envelope

Gateway::download()

public function download(Envelope $envelope): Download

Gateway::signingUrl()

public function signingUrl(Envelope $envelope, string $signer, ?string $returnUrl = null): SigningUrl

Gateway::notify()

public function notify(string $body, array $headers = []): Notification

GatewayFactory class

abstract class GatewayFactory implements GatewayFactoryInterface GatewayFactory.php:20

The Omnibus way: a gateway's factory fills a Config - its name, title, capabilities, the options it needs, its client ("omnisign.api", a closure of the Config: a provider's API, a token signer, a store) and its actions ("omnisign.action.<name>") - and the gateway is those actions, the client handed to the ones that ask for it.

Nothing here calls anything: a factory whose provider is reached over HTTP takes its client in its own constructor.

GatewayFactory::getName()

public function getName(): string

GatewayFactory::create()

public function create(array $options = []): GatewayInterface

GatewayFactory::createConfig()

public function createConfig(array $options = []): Config

GatewayFactoryInterface interface

interface GatewayFactoryInterface GatewayFactoryInterface.php:6

Builds a gateway from its options (an API key, an account, an instance's address...).

GatewayFactoryInterface::getName()

public function getName(): string

The name gateways are configured with: "yousign", "docusign", "docuseal".

..

GatewayFactoryInterface::create()

public function create(array $options = []): GatewayInterface

GatewayInterface interface

interface GatewayInterface GatewayInterface.php:23

One way to have documents signed, configured - a signature service, an instance of one's own: the same questions for all of them. Each typed method is a shortcut for execute() with its request; a gateway that does not do something throws NotSupportedException, and supports() says so beforehand.

A gateway has documents signed. It keeps nothing for the application - neither the documents nor their proof: the application stores what download() gives it, in its own vault.

GatewayInterface::getName()

public function getName(): string

GatewayInterface::getTitle()

public function getTitle(): string

GatewayInterface::capabilities()

public function capabilities(): Capabilities

What its signatures are: the levels, in the page or by e-mail, in turn, through whom.

GatewayInterface::supports()

public function supports(string $request): bool

GatewayInterface::execute()

public function execute(Request $request): Request

Returns

answered

Throws

Exception\NotSupportedException

Throws

Exception\ProviderException

GatewayInterface::create()

public function create(Envelope $envelope): Envelope

Create the envelope: it comes back with its reference on this gateway, to keep.

GatewayInterface::send()

public function send(Envelope $envelope): Envelope

Send it: the signers are asked.

GatewayInterface::fetch()

public function fetch(Envelope $envelope): Envelope

Where it stands now.

GatewayInterface::remind()

public function remind(Envelope $envelope, ?string $signer = null): Envelope

Ask again who has not signed; one signer by key.

GatewayInterface::cancel()

public function cancel(Envelope $envelope, ?string $reason = null): Envelope

Withdraw it.

GatewayInterface::download()

public function download(Envelope $envelope): Download

The signed documents and their evidence.

GatewayInterface::signingUrl()

public function signingUrl(Envelope $envelope, string $signer, ?string $returnUrl = null): SigningUrl

Where a signer signs in the application's page, now.

GatewayInterface::notify()

public function notify(string $body, array $headers = []): Notification

What the provider is telling us (a webhook): checked against its signature, read as one event.

Throws

Exception\InvalidNotificationException when the signature does not hold

Registry class

final class Registry Registry.php:16

The application's gateways by name, each built once from its factory and options:

new Registry([new DocusealGatewayFactory($http), new YousignGatewayFactory($http)], [ 'contracts' => ['factory' => 'docuseal', 'options' => ['url' => 'https://sign.example.org', 'api_key' => '...']], 'qualified' => ['factory' => 'yousign', 'options' => ['api_key' => '...', 'sandbox' => true]], ]);

Registry::__construct()

public function __construct(iterable $factories, readonly array $config)

Registry::get()

public function get(string $name): GatewayInterface

Registry::has()

public function has(string $name): bool

Registry::options()

public function options(string $name): array

Returns

the options a gateway is configured with

Registry::create()

public function create(string $name, array $overrides = []): GatewayInterface

A gateway built afresh, its configured options with $overrides over them - an instance typed in a back office, say. Not kept: get() still gives the configured one.

Registry::names()

public function names(): array

Returns

the configured gateways' names

Registry::all()

public function all(): array

Registry::factories()

public function factories(): array

Returns

the factories installed: what factory: may name

Omnisign\Action

ActionInterface interface

interface ActionInterface ActionInterface.php:8

One thing a gateway does: answers the requests it supports.

ActionInterface::supports()

public function supports(Request $request): bool

ActionInterface::execute()

public function execute(Request $request): void

Sets the request's result, or throws an Omnisign\Exception\OmnisignException.

ApiAwareInterface interface

interface ApiAwareInterface ApiAwareInterface.php:6

An action that works through the gateway's own client: a provider's API, a signer, a store.

ApiAwareInterface::setApi()

public function setApi(object $api): void

ApiAwareTrait trait

trait ApiAwareTrait ApiAwareTrait.php:10

ApiAwareTrait::setApi()

public function setApi(object $api): void

Omnisign\Bridge\Symfony

OmnisignBundle class

final class OmnisignBundle extends AbstractBundle OmnisignBundle.php:41

Omnisign in a Symfony application: the gateway packages installed (omnisign/yousign, omnisign/docusign, omnisign/docuseal) registered, the gateways built from configuration and injectable by their name:

omnisign: gateways: contracts: factory: docuseal options: { url: 'https://sign.example.org', api_key: '%env(DOCUSEAL_API_KEY)%' } qualified: factory: yousign options: { api_key: '%env(YOUSIGN_API_KEY)%', sandbox: true }

public function __construct(GatewayInterface $contracts, GatewayInterface $qualified) }

Nothing is built, nor checked, when the container compiles: a gateway is built the first time it is asked for, and an option left empty only shows then (InvalidConfigException). A factory is autowired, the application's http_client given to it when it has one. An application's own factories (a GatewayFactoryInterface) are registered too, autoconfigured.

OmnisignBundle::configure()

public function configure(DefinitionConfigurator $definition): void

OmnisignBundle::loadExtension()

public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void

Omnisign\Exception

InvalidConfigException class

final class InvalidConfigException extends LogicException implements OmnisignException InvalidConfigException.php:6

A gateway misconfigured: an option missing, an unknown factory, an envelope without what the gateway needs.

InvalidKeyException class

final class InvalidKeyException extends ProviderException InvalidKeyException.php:6

The provider refused the application's credentials: an API key, a token, an integration.

InvalidNotificationException class

final class InvalidNotificationException extends ProviderException InvalidNotificationException.php:6

A callback that is not the provider's: its signature does not hold, or it is too old.

NotSupportedException class

final class NotSupportedException extends LogicException implements OmnisignException NotSupportedException.php:12

The gateway does not do that: no reminder from a provider that sends none, no envelope built from a PDF on DocuSeal's free edition. supports() says so beforehand.

NotSupportedException::for()

public static function for(Request $request, string $gateway): self

OmnisignException interface

interface OmnisignException extends Throwable OmnisignException.php:6

Every exception Omnisign throws.

ProviderException class

class ProviderException extends RuntimeException implements OmnisignException ProviderException.php:6

The provider refused the request, or answered with an error.

public readonly string $provider

public readonly ?string $providerCode

The provider's own error code, when it gave one

ProviderException::__construct()

public function __construct(public readonly string $provider, string $message, public readonly ?string $providerCode = null, ?\Throwable $previous = null)

UnreachableException class

final class UnreachableException extends ProviderException UnreachableException.php:9

The provider did not answer: no connection, a timeout, a server error, a quota exceeded. Nothing was done, as far as can be told: fetch, then try again.

Omnisign\Http

Answer class

final readonly class Answer Answer.php:21

A provider's answer, read whole: its status, headers (lower-case names) and body. send() is the one place the family's gateways call through: no connection, a timeout, a server error or a quota exceeded is an UnreachableException - the provider said nothing about the request - and anything else comes back for the gateway to read. The request's secrets stay out of what it throws: the HTTP client's message with the key's parameters masked (Redaction::text(), api_key=***), its exception wrapped as a copy (Redaction::copy()), no trace keeping the arguments where the options stood.

public int $status

public array $headers

public string $body

Answer::__construct()

public function __construct(public int $status, public array $headers, public string $body, string $provider)

Answer::send()

public static function send(HttpClientInterface $http, string $provider, string $method, string $url, array $options = []): self

$options

the HTTP client's options: body, json, query, headers, timeout

Answer::header()

public function header(string $name): ?string

Answer::json()

public function json(): array

The body as a JSON object.

Multipart class

final class Multipart Multipart.php:9

A multipart/form-data body, built here: no MIME library needed for a file and a few fields.

Multipart::build()

public static function build(array $fields, array $files): array

Redaction class

final class Redaction Redaction.php:22

What a failed call may carry of its credentials, taken out before the failure leaves the package: an HTTP client's exception quotes the URL called (a key in its query, a password in its user part), and every exception's trace keeps the arguments of the calls under it (the request options, headers and query with the key) unless PHP runs with zend.exception_ignore_args.

copy() gives the previous exception to wrap instead of the client's own: the same class and code, its message with the key's parameters, the user part and every secret value replaced by ***, its trace without arguments, its own previous copied the same way. Properties of the client's class beyond those of \Exception are not copied (a Symfony HttpException's response, a PSR-18 exception's request: their URL holds the key). withoutArguments() takes the arguments out of the trace of the exception thrown in its place.

const MASK = '***'

Redaction::secrets()

public static function secrets(string $url, array $options = []): array

The secrets a request carries: the values of its query parameters, headers and body fields named as credentials (key, token, secret, password, signature, auth...), a bearer token, a basic password, the URL's user part.

$options

the HTTP client's options

Redaction::sensitive()

public static function sensitive(string $name): bool

Whether a parameter, header or field of this name holds a credential.

Redaction::text()

public static function text(string $text, array $secrets = []): string

A text without credentials: in every address, the user part and the parameters named as credentials masked (api_key=***); then every secret given, raw or URL-encoded, masked wherever it stands.

Redaction::copy()

public static function copy(\Throwable $failure, array $secrets = []): \Throwable

A copy of a failure to wrap in its place: its class, code, file and line, its message through text(), its trace without arguments, its previous copied the same way.

Redaction::withoutArguments()

public static function withoutArguments(\Throwable $failure): \Throwable

The failure given, the arguments out of its trace (and out of its previous ones'), as zend.exception_ignore_args would have left it.

Omnisign\Model

Capabilities class

final readonly class Capabilities Capabilities.php:11

What a gateway's signatures are, said before anything is sent: the levels it offers, whether a signer may sign in the application's page, in turn, after proving who they are, and through whom. The operations it answers are asked of the gateway itself (supports()).

public array $levels

public bool $embedded

public bool $ordered

public bool $identityCheck

public bool $thirdParty

public bool $documents

public bool $templates

Capabilities::__construct()

public function __construct(public array $levels = [Level::SIMPLE], public bool $embedded = false, public bool $ordered = true, public bool $identityCheck = false, public bool $thirdParty = true, public bool $documents = true, public bool $templates = false)

Capabilities::offers()

public function offers(Level $level): bool

Capabilities::toArray()

public function toArray(): array

Document class

final readonly class Document Document.php:9

A document of an envelope: its file, and the application's key for it - what fields point at.

public string $key

public File $file

public bool $signable

false: attached for reading, not signed

Document::__construct()

public function __construct(public string $key, public File $file, public bool $signable = true)

Download class

final readonly class Download Download.php:6

What a completed envelope leaves: the signed documents, and the evidence of their signing (the audit trail).

public array $documents

public ?File $evidence

Download::__construct()

public function __construct(public array $documents, public ?File $evidence = null)

Envelope class

final readonly class Envelope Envelope.php:10

Documents to sign, by whom, where: what the application asks a provider, and - once created - what the provider made of it: its reference, its status, each signer's state.

public string $title

public array $documents

public array $signers

public array $fields

public Level $level

public bool $ordered

each signer in turn (Signer::$order), rather than all at once

public bool $embedded

the signers sign in the application's page (SigningUrl), the provider sends them nothing

public ?\DateTimeImmutable $expiresAt

public ?string $message

public ?string $redirectUrl

public ?string $template

a template of the provider's, instead of documents and fields (DocuSeal's free edition)

public ?string $key

the application's own name for it, kept by providers that keep one

public ?string $reference

the provider's, once created: keep it

public Status $status

public array $states

by signer key

public array $documentReferences

the provider's ids of the documents, by key

public ?\DateTimeImmutable $completedAt

public array $data

what else the provider answered

Envelope::__construct()

public function __construct(public string $title, public array $documents = [], public array $signers = [], public array $fields = [], public Level $level = Level::SIMPLE, public bool $ordered = false, public bool $embedded = false, public ?\DateTimeImmutable $expiresAt = null, public ?string $message = null, public ?string $redirectUrl = null, public ?string $template = null, public ?string $key = null, public ?string $reference = null, public Status $status = Status::DRAFT, public array $states = [], public array $documentReferences = [], public ?\DateTimeImmutable $completedAt = null, public array $data = [])

$ordered

each signer in turn (Signer::$order), rather than all at once

$embedded

the signers sign in the application's page (SigningUrl), the provider sends them nothing

$template

a template of the provider's, instead of documents and fields (DocuSeal's free edition)

$key

the application's own name for it, kept by providers that keep one

$reference

the provider's, once created: keep it

$states

by signer key

$documentReferences

the provider's ids of the documents, by key

$data

what else the provider answered

Envelope::with()

public function with(?string $reference = null, ?Status $status = null, ?array $states = null, ?array $documentReferences = null, ?\DateTimeImmutable $completedAt = null, ?array $data = null): self

The same envelope as the provider has it now.

Envelope::reference()

public function reference(): string

The provider's reference; an InvalidConfigException on an envelope never created.

Envelope::signer()

public function signer(string $key): Signer

Envelope::state()

public function state(string $key): ?SignerState

Envelope::fieldsOf()

public function fieldsOf(string $signer): array

Event enum

enum Event Event.php:5

case SENT = 'sent'

case OPENED = 'opened'

case SIGNED = 'signed'

case DECLINED = 'declined'

case COMPLETED = 'completed'

case EXPIRED = 'expired'

case CANCELED = 'canceled'

case OTHER = 'other'

Field class

final readonly class Field Field.php:10

Where a signer signs, initials or writes: a document's page and a position on it, in points from the top left corner - or an anchor, a text of the document the provider looks for.

public string $signer

public string $document

public FieldType $type

public int $page

public int $x

public int $y

public ?int $width

public ?int $height

public ?string $anchor

public ?string $label

the mention's text, a text field's label

Field::__construct()

public function __construct(public string $signer, public string $document, public FieldType $type = FieldType::SIGNATURE, public int $page = 1, public int $x = 0, public int $y = 0, public ?int $width = null, public ?int $height = null, public ?string $anchor = null, public ?string $label = null)

FieldType enum

enum FieldType FieldType.php:5

case SIGNATURE = 'signature'

case INITIALS = 'initials'

case DATE = 'date'

case TEXT = 'text'

case MENTION = 'mention'

A handwritten mention: "lu et approuvé", "bon pour accord"

File class

final readonly class File File.php:6

A file: a document to sign, a signed one, the evidence of the signature.

public string $content

public string $filename

public string $mimeType

File::__construct()

public function __construct(public string $content, public string $filename, public string $mimeType = 'application/pdf')

File::fromPath()

public static function fromPath(string $path, ?string $mimeType = null): self

File::sha256()

public function sha256(): string

Level enum

enum Level Level.php:6

How strong a signature is, in eIDAS's terms (Regulation (EU) 910/2014).

case SIMPLE = 'simple'

Simple electronic signature: an e-mail, a code by e-mail or SMS

case ADVANCED = 'advanced'

Advanced: uniquely linked to the signer, who is identified (an identity document)

case QUALIFIED = 'qualified'

Qualified: on a qualified certificate - the equivalent of a handwritten signature

Notification class

final readonly class Notification Notification.php:10

What a provider told the application's webhook, its signature checked: an event about one envelope - and a signer, for SIGNED, OPENED, DECLINED.

Fetch the envelope for the rest.

public Event $event

public string $type

the provider's own name for the event

public ?string $reference

the envelope, as create() named it

public ?string $signer

the provider's id of the signer, or their e-mail

public ?\DateTimeImmutable $at

public ?string $id

the same for a callback sent twice: what to deduplicate on

public array $data

the provider's payload

Notification::__construct()

public function __construct(public Event $event, public string $type, public ?string $reference = null, public ?string $signer = null, public ?\DateTimeImmutable $at = null, public ?string $id = null, public array $data = [])

$type

the provider's own name for the event

$reference

the envelope, as create() named it

$signer

the provider's id of the signer, or their e-mail

$id

the same for a callback sent twice: what to deduplicate on

$data

the provider's payload

Signer class

final readonly class Signer Signer.php:10

Who signs: the application's key for them, a name, an e-mail - a phone for a code by SMS -, their place in the order, how they prove who they are. Never an account of the application's.

public string $key

the application's own name for this signer: what fields and states point at

public string $name

public string $email

public ?string $phone

public string $locale

public int $order

their turn, from 1, when the envelope is ordered

public ?string $authentication

none, email or sms: a code before signing, where the provider sends one

public ?string $role

the role a provider's template knows them by (DocuSeal)

Signer::__construct()

public function __construct(public string $key, public string $name, public string $email, public ?string $phone = null, public string $locale = 'fr', public int $order = 1, public ?string $authentication = null, public ?string $role = null)

$key

the application's own name for this signer: what fields and states point at

$order

their turn, from 1, when the envelope is ordered

$authentication

none, email or sms: a code before signing, where the provider sends one

$role

the role a provider's template knows them by (DocuSeal)

Signer::names()

public function names(): array

Returns

the first name and the last name, from $name: the last word is the last name

SignerState class

final readonly class SignerState SignerState.php:10

A signer as the provider has them: its own id for them, where they stand, and - for a signature in the application's page - the link that opens their signing, when the provider gave one.

public string $key

public ?string $reference

public SignerStatus $status

public ?\DateTimeImmutable $signedAt

public ?string $link

public ?\DateTimeImmutable $linkExpiresAt

public ?string $reason

SignerState::__construct()

public function __construct(public string $key, public ?string $reference = null, public SignerStatus $status = SignerStatus::WAITING, public ?\DateTimeImmutable $signedAt = null, public ?string $link = null, public ?\DateTimeImmutable $linkExpiresAt = null, public ?string $reason = null)

SignerStatus enum

enum SignerStatus SignerStatus.php:5

case WAITING = 'waiting'

Not asked yet: a draft, or not their turn

case NOTIFIED = 'notified'

Asked: a link was sent, or can be given

case OPENED = 'opened'

Opened the document, or proving who they are

case SIGNED = 'signed'

case DECLINED = 'declined'

case FAILED = 'failed'

The provider gave up on them: an error, an identity not verified

SigningUrl class

final readonly class SigningUrl SigningUrl.php:6

Where one signer signs, in the application's page (a frame) or a tab: made for them, ask again each time.

public string $url

public ?\DateTimeImmutable $expiresAt

SigningUrl::__construct()

public function __construct(public string $url, public ?\DateTimeImmutable $expiresAt = null)

Status enum

enum Status Status.php:6

Where an envelope stands.

case DRAFT = 'draft'

Created on the provider, not sent: still editable

case SENT = 'sent'

Sent: the signers may sign

case COMPLETED = 'completed'

Every signer signed

case DECLINED = 'declined'

A signer declined

case EXPIRED = 'expired'

Past its deadline, unsigned

case CANCELED = 'canceled'

Cancelled by the sender, or by the provider after an error

case UNKNOWN = 'unknown'

Status::isOver()

public function isOver(): bool

Omnisign\Request

Cancel class

final class Cancel extends Request Cancel.php:8

Withdraw an envelope that is not over. Result: the Envelope, CANCELED.

public readonly Envelope $envelope

public readonly ?string $reason

Cancel::__construct()

public function __construct(public readonly Envelope $envelope, public readonly ?string $reason = null)

Cancel::getEnvelope()

public function getEnvelope(): ?Envelope

Create class

final class Create extends Request Create.php:8

Create the envelope on the provider: its documents, signers and fields. Result: the Envelope with its reference - a DRAFT, unless the provider sends at once.

public readonly Envelope $envelope

Create::__construct()

public function __construct(public readonly Envelope $envelope)

Create::getEnvelope()

public function getEnvelope(): ?Envelope

Download class

final class Download extends Request Download.php:8

The signed documents and the evidence of their signing, once COMPLETED. Result: a Download.

public readonly Envelope $envelope

Download::__construct()

public function __construct(public readonly Envelope $envelope)

Download::getDownload()

public function getDownload(): ?\Omnisign\Model\Download

Fetch class

final class Fetch extends Request Fetch.php:8

The envelope as the provider has it now: its status, each signer's. Result: the Envelope.

public readonly Envelope $envelope

Fetch::__construct()

public function __construct(public readonly Envelope $envelope)

Fetch::getEnvelope()

public function getEnvelope(): ?Envelope

Notify class

final class Notify extends Request Notify.php:12

What the provider sent to the application's webhook: the raw body and the request's headers, for the signature. Result: the Notification, or InvalidNotificationException when the signature does not hold.

public readonly string $body

public readonly array $headers

Notify::__construct()

public function __construct(public readonly string $body, public readonly array $headers = [])

Notify::header()

public function header(string $name): ?string

A header, whatever the case it came in.

Notify::getNotification()

public function getNotification(): ?Notification

Remind class

final class Remind extends Request Remind.php:8

Ask again the signers who have not signed - or one of them, by key. Result: the Envelope.

public readonly Envelope $envelope

public readonly ?string $signer

Remind::__construct()

public function __construct(public readonly Envelope $envelope, public readonly ?string $signer = null)

Remind::getEnvelope()

public function getEnvelope(): ?Envelope

Request class

abstract class Request Request.php:9

A question put to a gateway. The action that supports it answers by setting the result; the gateway hands the request back.

Request::setResult()

public function setResult(mixed $result): void

Request::getResult()

public function getResult(): mixed

Request::isAnswered()

public function isAnswered(): bool

Send class

final class Send extends Request Send.php:8

Send a created envelope: the signers are asked (or, embedded, may sign). Result: the Envelope, SENT.

public readonly Envelope $envelope

Send::__construct()

public function __construct(public readonly Envelope $envelope)

Send::getEnvelope()

public function getEnvelope(): ?Envelope

SigningUrl class

final class SigningUrl extends Request SigningUrl.php:8

Where a signer signs in the application's page, now. Result: a SigningUrl.

public readonly Envelope $envelope

public readonly string $signer

public readonly ?string $returnUrl

SigningUrl::__construct()

public function __construct(public readonly Envelope $envelope, public readonly string $signer, public readonly ?string $returnUrl = null)

SigningUrl::getSigningUrl()

public function getSigningUrl(): ?\Omnisign\Model\SigningUrl