laravel maintained by formfeed
formfeed/laravel
Formfeed for Laravel: PDFs and
images from templates, HTML, URLs or Markdown, and tools for existing PDFs. It wraps the PHP SDK,
formfeed/sdk, and adds what a Laravel application
wants with it:
- the client in the container, set up from
.env; - the
Formfeedfacade; - the
formfeed.webhookmiddleware, which checks a delivery's signature; Formfeed::fake()for tests.
Laravel 12 or 13, PHP 8.3 or newer.
composer require formfeed/laravel
Settings
FORMFEED_API_KEY=ff_test_...
FORMFEED_WEBHOOK_SECRET=whsec_...
The key comes from the app's Keys page. An ff_test_ key renders without counting against the
plan, an ff_live_ key for real. FORMFEED_REGION (eu) and FORMFEED_BASE_URL (another gateway)
are there when you need them. To change the retries, the time limit or the webhook tolerance,
publish the file:
php artisan vendor:publish --tag=formfeed-config
php artisan about shows whether the key and the secret arrived, never their values.
Render a document
use Formfeed\Laravel\Facades\Formfeed;
use Illuminate\Support\Facades\Storage;
$render = Formfeed::renders()->create([
'template' => 'invoice',
'data' => [
'number' => 'RE-2026-0042',
'customer' => ['name' => 'Olvarest GmbH', 'city' => 'Musterstadt'],
],
'meta' => ['order_id' => $order->id],
]);
Storage::put("invoices/{$order->id}.pdf", Formfeed::renders()->download($render));
The facade has the SDK's services as methods: renders(), jobs(), pdf(), einvoices(),
files(), templates(), webhooks() and account(). request() reaches any other call of the
API. A class can also take Formfeed\Client in its constructor; it is the same client.
use Formfeed\Client;
final class InvoiceDocuments
{
public function __construct(private readonly Client $formfeed) {}
public function merged(array $renders): string
{
return $this->formfeed->renders->download($this->formfeed->pdf->merge($renders));
}
}
Webhooks
The middleware lets a delivery through only when its Webhook-Signature matches the body as it
arrived, signed with FORMFEED_WEBHOOK_SECRET no more than five minutes from the server's clock.
Anything else gets 401, which Formfeed retries. After it, the event is the request's JSON:
// routes/api.php, so the address is /api/formfeed/webhook
Route::post('/formfeed/webhook', function (Request $request) {
if ($request->input('type') === 'render.completed') {
StoreDocument::dispatch($request->input('data.id'), $request->input('data.meta.order_id'));
}
return response()->noContent();
})->middleware('formfeed.webhook');
A route in routes/web.php also needs an exception from the CSRF check. Formfeed sends no CSRF
token. In bootstrap/app.php:
->withMiddleware(function (Middleware $middleware): void {
$middleware->validateCsrfTokens(except: ['formfeed/webhook']);
})
Answer within ten seconds, so put slow work on a queue. A delivery can arrive twice; its id
tells duplicates apart. During development,
formfeed listen --forward-to http://localhost:8000/api/formfeed/webhook forwards the events of
test renders to your machine and prints the secret to put in .env. The
webhooks guide lists the events and their retries.
Tests
Formfeed::fake() swaps the client for one that never reaches the network. It answers renders,
batches, jobs and the PDF tools as the API would. A sync render is finished. An async render is
queued until it is first read. Behind every link is a real file, a PDF with the render's pages.
The fake keeps every request for the assertions:
use Formfeed\Laravel\Facades\Formfeed;
public function test_an_order_gets_its_invoice(): void
{
Formfeed::fake();
$this->post('/orders/8812/invoice')->assertOk();
Formfeed::assertRendered('invoice');
Formfeed::assertRendered(fn (array $request) => $request['data']['number'] === 'RE-8812', times: 1);
Formfeed::assertNotRendered('reminder');
}
Answers go by METHOD /path, and * matches anything:
use Formfeed\Laravel\Testing\FormfeedFake;
use Formfeed\Laravel\Testing\FormfeedRequest;
Formfeed::fake([
// the keys of an array replace those of the fake's own answer: a render of three pages
'POST /renders' => ['page_count' => 3],
// a problem, which the SDK throws as Formfeed\FormfeedException
'POST /pdf/protect' => FormfeedFake::problem('forbidden', 403, 'PDF tools need the Starter plan'),
// an async render that fails once it is read
'GET /renders/*' => FormfeedFake::failed('render_timeout', 'Render exceeded 30000 ms'),
// one answer per request, then the fake's own
'POST /renders/batch' => FormfeedFake::sequence(FormfeedFake::problem('rate_limited', 429)),
// per request; null leaves it to the fake
'POST /pdf/merge' => fn (FormfeedRequest $request) => in_array('terms.pdf', $request->input('sources'), true)
? FormfeedFake::problem('source_not_found', 422, 'No file terms.pdf in the library')
: null,
// a call the fake does not answer by itself needs its answer
'GET /account' => ['id' => 'org_1', 'name' => 'Fennlor Studio GmbH'],
]);
Here are the assertions:
assertRendered,assertNotRenderedandassertNothingRenderedtake a template's slug or a callback over the request's body.assertBatchedis the same for batches.assertSent,assertNotSent,assertNothingSentandassertSentCountcover any call.Formfeed::recorded()returns the requests themselves.
Call fake() before the code under test asks the container for the client.
A webhook route is tested through its real signature check:
use Formfeed\Laravel\Testing\InteractsWithFormfeedWebhooks;
final class FormfeedWebhookTest extends TestCase
{
use InteractsWithFormfeedWebhooks;
public function test_a_finished_render_is_stored(): void
{
Queue::fake();
$this->postFormfeedWebhook('/api/formfeed/webhook', 'render.completed', [
'id' => 'rnd_7da09ab6cd9946b798c187c2a9350852',
'status' => 'succeeded',
'meta' => ['order_id' => '8812'],
])->assertNoContent();
Queue::assertPushed(StoreDocument::class);
}
}
It signs with FORMFEED_WEBHOOK_SECRET at the time of Laravel's clock, so $this->travel() reaches
both sides.
More
The documentation describes the API, the template languages and the PDF tools. The SDK's README describes every call. Questions go to support@formfeed.dev.
MIT licensed.