Laravel Typeform Laravel Package

Getting Started

Install and wire it up

composer require jeffersongoncalves/laravel-typeform
php artisan vendor:publish --tag=typeform-config   # publishes config/typeform.php

Laravel package discovery registers the service provider and the Typeform facade automatically — no manual config/app.php edits. Drop your credentials into .env:

TYPEFORM_TOKEN=your-personal-access-token

Generate the token in Typeform under Settings → Personal tokens, and grant only the scopes you need (forms:read, responses:read, webhooks:write, etc.). Scope selection at creation time is the single biggest source of first-day confusion, so decide up front whether the app is read-only (reporting) or write-capable (webhook registration, form duplication).

Where to look first

1. config/typeform.php — confirm the token key name and whether a base URL override exists (useful for pointing at a sandbox/proxy).
2. The facade accessor and the bound client class — that's the object you'll type-hint when you want to avoid the facade.
3. The package's resource methods: they map 1:1 to Typeform API resources (forms, responses, themes, images, workspaces, webhooks).

First use case: pull responses for a form

use JeffersonGoncalves\Typeform\Facades\Typeform;

$form = Typeform::forms()->get('abc123');
$page = Typeform::responses()->all('abc123', ['page_size' => 100]);

That's the 80% path: read a form's schema, then page through its responses. Build this in a tinker session or an artisan command before touching controllers — it verifies the token, scopes, and network path in one shot.

Implementation Patterns

Keep the client behind your own boundary

Don't sprinkle Typeform:: calls through controllers. Wrap it in an application service (App\Services\Typeform\TypeformGateway) that exposes intent-named methods (syncResponses(string $formId), formSchema(string $formId)). This gives you three wins: a single place to add retries/logging, a trivial seam for tests, and insulation from any future API or package reshuffle.

final class TypeformGateway
{
    public function __construct(private \JeffersonGoncalves\Typeform\Typeform $client) {}

    public function formFields(string $formId): array { /* ... */ }
}

Sync responses idempotently

Webhooks and scheduled pulls will overlap. Key your table on Typeform's response_id (not token, not landing_id) and use upsert():

Response::upsert($rows, ['response_id'], ['answers', 'submitted_at', 'updated_at']);

Store the raw payload in a json column alongside the parsed columns. When Typeform adds a field type you didn't anticipate, you'll still have the source data and can backfill without re-fetching.

Cursor pagination, not page numbers

Typeform pagination is token-based. Write a generator that loops on the after cursor and yields items so memory stays flat:

$after = null;
do {
    $page = $this->client->responses()->all($formId, array_filter([
        'page_size' => 1000,
        'after'     => $after,
    ]));
    foreach ($page['items'] as $item) { yield $item; }
    $after = $page['items'] ? end($page['items'])['token'] : null;
} while ($after);

Push long syncs onto the queue

A form with 50k responses will blow past PHP's time limit and Typeform's rate limits. Dispatch one job per page, and chain/self-dispatch on the cursor. Apply Illuminate\Queue\Middleware\RateLimited with a limiter tuned below Typeform's ceiling.

Webhooks instead of polling

For "new submission" triggers, register a webhook once and route it:

// routes/api.php — no CSRF, no auth middleware
Route::post('/webhooks/typeform/{secret}', TypeformWebhookController::class);

The controller should do nothing but validate the secret, dispatch(new IngestTypeformResponse($request->all())), and return 200 fast. Typeform retries on non-2xx, so a slow or failing handler turns into duplicate deliveries and a disabled webhook.

Cache the schema, not the submissions

Form definitions change rarely; responses change constantly. Cache::remember("typeform.form.{$id}", now()->addHours(6), fn () => $client->forms()->get($id)). You need the schema anyway to map field refs to human labels and to resolve variables.

Testing

Bind a fake gateway in the container and assert your application logic, not the HTTP call. If you want to exercise the package itself, Http::fake() around the client works when the package is built on Laravel's HTTP client; otherwise inject a stubbed resource object.

Gotchas and Tips

Webhooks are not signed. Typeform does not send an HMAC header. Treat the endpoint as unauthenticated: put a long random secret in the path, compare with hash_equals(), and — for anything security-sensitive — re-fetch the response by ID from the API before trusting the payload.

Answers are keyed by ref, falling back to a random field ID. If the form author didn't set refs in the builder, your mapping code is reading opaque IDs that change when the form is duplicated. Set refs in Typeform, or maintain a ref/id resolution table built from the form schema.

token ≠ response_id ≠ landing_id. landing_id identifies a form session (one per view), token is the pagination cursor, response_id is the submission. Use response_id as your primary key and landing_id only if you're joining partial/abandoned sessions.

Rate limits are real and per-form. You'll see 429s under parallel workers. Catch them, honour Retry-After, and use exponential backoff — don't just retry immediately. Centralise this in the gateway so every call benefits.

401/403 usually means scopes, not code. A token created with only forms:read will fail on the responses endpoint with a message that doesn't obviously say "missing scope." Check the token's scope list before debugging your own code.

File upload answers expire. Answers of type file_url point at temporary storage. Download and persist them during ingestion; a nightly job re-reading old payloads will find dead links.

Empty and hidden answers. Unanswered questions are frequently absent from the answers array rather than present with a null — defensive ?? access everywhere. Hidden fields and calculated variables appear under variables, not answers.

Config cache bites after .env edits. php artisan config:clear (or config:cache again) is required, or you'll spend twenty minutes on a stale token.

This is 1.0.0 — the first stable tag. Pin "jeffersongoncalves/laravel-typeform": "^1.0" and read the changelog link in the release before bumping minors; the package is young enough that pre-1.0 instability habits may persist for a release or two. There's no migration burden today, but keep your gateway boundary thin so a 1.x API adjustment costs you one file.