Document Signer Validsign Laravel Package

Product Decisions This Supports

• Build vs. buy for e-signature: This package is the "buy/adapt" half of the decision — it lets the product consume ValidSign rather than build signing, identity verification, and evidence capture in-house. The PM decision it unlocks is which provider, not whether to integrate.
• Vendor lock-in strategy: Because it implements la-souris/document-signer-sdk's SignatureProvider contract, signing is behind an abstraction. This supports a roadmap where ValidSign is the first provider, not the only one — a second provider (DocuSign, Adobe Sign, or a qualified eIDAS provider) can be added without touching product code.
• EU/Netherlands go-to-market: ValidSign is a strong fit for Dutch and EU customers needing eIDAS-recognised signatures and evidence. This release directly supports roadmap items around EU contract execution, hiring/HR documents, and customer onboarding flows.
• Audit and compliance positioning: downloadAudit() returning the Evidence Summary Report as PDF supports a compliance/audit-trail feature — useful for procurement questionnaires, SOC2/ISO evidence packs, and legal hold workflows. This is a differentiator to surface in sales material.
• Webhook-driven status UX: EventType mapping for ValidSign callbacks enables real-time envelope status in-product (sent, viewed, signed, declined, expired). Supports decisions on notification design, SLA dashboards, and customer-facing tracking pages.
• Reliability decisions: The decision to map HTTP 404-during-unfinalized-envelope to the SDK's retryable SignedDocumentUnavailableException is a product-relevant choice — it means download flows must be queued/retried, not treated as hard failures. This shapes job/queue architecture and customer-facing "document not ready yet" states.
• Placeholder templating UX: Anchor-based replacement (ValidSignPlaceholderReplacer) supports a self-serve template feature where ops define anchor tags and the product fills them. This informs whether we invest in a template management UI vs. hard-coded documents.
• Platform baseline: PHP 8.3+ and SDK ^1.0 constrain the supported deployment matrix — a decision input for hosting, CI images, and upgrade cadence.

When to Consider This Package

Adopt when:

• The product is a Laravel application on PHP 8.3+ and you have already selected (or are strongly leaning toward) ValidSign as your e-signature provider.
• You are already using, or willing to adopt, la-souris/document-signer-sdk as the provider-agnostic signing layer.
• You need EU/eIDAS-relevant signing with a retrievable evidence/audit PDF for compliance.
• You want webhook-driven envelope status without hand-rolling ValidSign callback parsing and event mapping.
• You need template-based documents where values are injected into anchored placeholders.
• You value keeping the signing provider replaceable — the contract implementation is the main asset here.

Look elsewhere or defer when:

• You are not on ValidSign, or the provider decision is still open and likely to land on DocuSign/Adobe Sign (check whether the SDK ships those providers before committing).
• You need a complete, drop-in signing UX (fields, signer pages, embedded flows) — this is a server-side provider adapter, not an end-user signing experience.
• You run PHP < 8.3 or cannot take a dependency on SDK ^1.0.
• Your flows depend on advanced ValidSign capabilities (qualified signatures, signer authentication methods, custom branding) that the current contract surface does not expose.
• You require the audit report in a machine-readable format — this release returns PDF only, so downstream analytics or automated compliance checks would need OCR/parsing.
• Template anchors are likely to change frequently without a controlled authoring process — anchor-based replacement is powerful but brittle if templates are edited freely.

How to Pitch It (Stakeholders)

For executives: This is a small, well-scoped adapter that lets us offer legally recognised e-signatures in the EU — particularly the Netherlands — without building signing infrastructure ourselves. The strategic value is twofold: we get to market faster with a compliant provider, and because signing sits behind a common interface, we are not locked in — we can swap or add providers later without reworking the product. It also gives us an audit evidence PDF per envelope, which is directly useful in security reviews and enterprise sales. Cost is low and the risk is contained to a single integration layer.

For engineering: The package implements the SDK's SignatureProvider contract cleanly, so it slots in as a replaceable module rather than a cross-cutting concern. Notable behaviours to design around: downloadSignedDocument() passes the caller's Document::$id through verbatim and converts a 404 on a not-yet-finalised envelope into the SDK's retryable SignedDocumentUnavailableException — so download must run on a queue with retry/backoff, not synchronously. downloadAudit() returns a PDF blob. Webhook handling is reduced to an EventType mapping, which keeps our callback controller thin. Baseline requirements are PHP 8.3+ and SDK ^1.0; pin the SDK and watch it for breaking changes, since this package is at its initial release and the contract surface is still young.

For the wider business: Think of this as the plumbing that makes "sign this document online" work for EU customers — status updates arrive via webhooks, signed documents are retrievable, and every envelope carries an evidence report we can hand to auditors or enterprise buyers.