Walkthrough: send & store

use App\Http\Controllers\AgreementController;
use Illuminate\Support\Facades\Route;

Route::middleware(['web', 'auth'])->group(function () {
    Route::post('/agreements', [AgreementController::class, 'store'])->name('agreements.store');
    Route::get('/agreements/{agreementId}', [AgreementController::class, 'show'])->name('agreements.show');
    Route::get('/agreements/{agreementId}/sign', [AgreementController::class, 'signingUrl'])->name('agreements.sign');
    Route::get('/agreements/{agreementId}/pdf', [AgreementController::class, 'download'])->name('agreements.pdf');
});

<form method="POST" action="{{ route('agreements.store') }}" enctype="multipart/form-data">
    @csrf
    <input type="file" name="contract" accept="application/pdf" required>
    <input type="text" name="name" value="Master Services Agreement" required>

    {{-- Signing order: one row per signer, top to bottom --}}
    <input type="email" name="signers[]" value="jane@client.example.com">
    <input type="email" name="signers[]" value="legal@example.com">
    <label><input type="checkbox" name="parallel[]" value="legal@example.com"> signs together with the signer above</label>
    <input type="email" name="signers[]" value="ceo@example.com">

    <button type="submit">Send for signature</button>
</form>

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Conceptlz\AdobeSign\AdobeSign;
use Conceptlz\AdobeSign\Builder\AgreementInfo;
use Conceptlz\AdobeSign\Builder\FileInfo;
use Conceptlz\AdobeSign\Builder\ParticipantSetInfo;
use Conceptlz\AdobeSign\Builder\WebhookInfo;
use Conceptlz\AdobeSign\Exception\NotFoundException;
use Conceptlz\AdobeSign\Webhook\EventType;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\StreamedResponse;

final class AgreementController
{
    /**
     * POST /agreements: multipart form with `contract` (PDF), `name`, and `signers[]` in signing order.
     * Signers listed in `parallel[]` sign at the same step as the signer before them.
     */
    public function store(Request $request, AdobeSign $sign): JsonResponse
    {
        $data = $request->validate([
            'contract' => ['required', 'file', 'mimes:pdf', 'max:25600'],
            'name' => ['required', 'string', 'max:255'],
            'signers' => ['required', 'array', 'min:1'],
            'signers.*' => ['required', 'email'],
            'parallel' => ['sometimes', 'array'],
            'parallel.*' => ['email'],
        ]);

        // 1. Upload the PDF (streamed, never fully loaded into memory).
        $file = $request->file('contract');
        $documentId = $sign->transientDocuments()->upload(
            $file->getRealPath(),
            fileName: $file->getClientOriginalName(),
            mimeType: 'application/pdf',
        );

        // 2. Build the signing order: each signer is the next step, unless marked parallel.
        //    Mixing sequential and parallel steps needs "hybrid routing" enabled on the Acrobat Sign
        //    account; otherwise Adobe answers 403 HYBRID_ROUTING_NOT_ALLOWED.
        $agreement = AgreementInfo::create($data['name'])
            ->file(FileInfo::transientDocument($documentId))
            ->message('Please review and sign.');

        $parallel = $data['parallel'] ?? [];
        $order = 0;
        foreach ($data['signers'] as $email) {
            $order = in_array($email, $parallel, true) && $order > 0 ? $order : $order + 1;
            $agreement->participantSet(ParticipantSetInfo::signer($email)->order($order));
        }

        // 3. Create it in IN_PROCESS state (the default) = sent to the first signer(s) now.
        $agreementId = $sign->agreements()->create($agreement);

        // 4. Ask Adobe to notify our webhook endpoint about this agreement (one webhook per
        //    agreement is Adobe's recommendation). The package registers the route.
        $sign->webhooks()->create(
            WebhookInfo::forAgreement('Agreement ' . $agreementId, route('adobe-sign.webhook'), $agreementId)
                ->events(EventType::AGREEMENT_ALL),
        );

        return new JsonResponse(['agreement_id' => $agreementId], 201);
    }

    /**
     * GET /agreements/{agreementId}: current status, e.g. OUT_FOR_SIGNATURE or SIGNED.
     */
    public function show(string $agreementId, AdobeSign $sign): JsonResponse
    {
        $agreement = $sign->agreements()->get($agreementId);

        return new JsonResponse([
            'id' => $agreement->id,
            'name' => $agreement->name,
            'status' => $agreement->status,
        ]);
    }

    /**
     * GET /agreements/{agreementId}/sign: the signer's e-sign page (embedded signing).
     */
    public function signingUrl(Request $request, string $agreementId, AdobeSign $sign): JsonResponse
    {
        $user = $request->user() ?? abort(401);

        try {
            $url = $sign->agreements()->signingUrlFor($agreementId, $user->email);
        } catch (NotFoundException $e) {
            // Right after creation Adobe may still be processing the PDF (AGREEMENT_NOT_SIGNABLE).
            return new JsonResponse(['message' => 'Not ready for signing yet, try again shortly.'], 409);
        }

        return $url === null
            ? new JsonResponse(['message' => "It isn't your turn to sign."], 403)
            : new JsonResponse(['url' => $url]);
    }

    /**
     * GET /agreements/{agreementId}/pdf: stream the current PDF straight from Adobe to the browser.
     */
    public function download(string $agreementId, AdobeSign $sign): StreamedResponse
    {
        $pdf = $sign->agreements()->combinedDocument($agreementId);

        return new StreamedResponse(function () use ($pdf) {
            while (!$pdf->eof()) {
                echo $pdf->read(65536);
            }
        }, 200, [
            'Content-Type' => 'application/pdf',
            'Content-Disposition' => 'attachment; filename="' . $agreementId . '.pdf"',
        ]);
    }
}

<?php

declare(strict_types=1);

namespace App\Listeners;

use App\Jobs\DownloadSignedAgreement;
use Conceptlz\AdobeSign\Laravel\Events\WebhookReceived;
use Conceptlz\AdobeSign\Webhook\AgreementEvent;
use Conceptlz\AdobeSign\Webhook\EventType;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Log;

final class ProcessAdobeSignWebhook implements ShouldQueue
{
    public function handle(WebhookReceived $received): void
    {
        $event = $received->event;

        if (!$event instanceof AgreementEvent) {
            return; // web form, Send in Bulk or library events: handle them here if you subscribe to them
        }

        Log::info('Acrobat Sign: ' . $event->event, [
            'agreement' => $event->agreementId(),
            'by' => $event->actingUserEmail,
        ]);

        match (true) {
            // Every participant has acted: fetch and keep the signed PDF.
            $event->isWorkflowCompleted() => DownloadSignedAgreement::dispatch((string) $event->agreementId()),

            // One signer finished; others may still be pending.
            $event->is(EventType::AGREEMENT_ACTION_COMPLETED) => null,

            // Declined or cancelled: update your records / notify someone.
            $event->is(EventType::AGREEMENT_REJECTED, EventType::AGREEMENT_RECALLED, EventType::AGREEMENT_EXPIRED) => null,

            default => null,
        };
    }
}

<?php

declare(strict_types=1);

namespace App\Jobs;

use Conceptlz\AdobeSign\AdobeSign;
use Conceptlz\AdobeSign\Exception\RateLimitException;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Support\Facades\Storage;

final class DownloadSignedAgreement implements ShouldQueue
{
    use Dispatchable;
    use InteractsWithQueue;
    use Queueable;

    public int $tries = 5;

    public function __construct(public readonly string $agreementId)
    {
    }

    public function handle(AdobeSign $sign): void
    {
        try {
            // Webhook payloads aren't signed, so confirm the status with the API before acting on it.
            $agreement = $sign->agreements()->get($this->agreementId);
            if (!$agreement->isSigned()) {
                return;
            }

            // A PSR-7 stream: written to storage in chunks, never held in memory as a whole.
            $pdf = $sign->agreements()->combinedDocument($this->agreementId, attachAuditReport: true);
        } catch (RateLimitException $e) {
            $this->release($e->retryAfter ?? 60);

            return;
        }

        $resource = $pdf->detach() ?? throw new \RuntimeException('Download stream is not readable.');

        Storage::disk(config('filesystems.default'))->writeStream("agreements/{$this->agreementId}.pdf", $resource);
    }
}