Typeform Laravel Package

Getting Started

Minimal Setup

1. Installation Ensure your project meets the PHP 7.2+ requirement (BREAKING CHANGE in v1.0). Add the package via Composer (if available in a private repo or fork):

   composer require beloop/typeform
   

   Note: Since the package is archived and not on Packagist, ensure you have access to the source (e.g., Git subtree or private repo).

2. Service Provider & Facade Register the service provider in config/app.php:

   'providers' => [
       Beloop\Typeform\TypeformServiceProvider::class,
   ],
   

   Publish config (if available):

   php artisan vendor:publish --provider="Beloop\Typeform\TypeformServiceProvider"
   

3. First Use Case: Fetching a Form Use the facade to retrieve a Typeform form by ID:

   use Beloop\Typeform\Facades\Typeform;
   
   $form = Typeform::form('your_form_id')->get();
   

Implementation Patterns

Core Workflows

1. Form Management

   • Create/Update Forms:

     $form = Typeform::form()->create([
         'title' => 'Customer Survey',
         'fields' => [...],
     ]);
     

   • List Forms:

     $forms = Typeform::forms()->all();
     

2. Submission Handling

   • Fetch Submissions:

     $submissions = Typeform::form('form_id')->submissions()->all();
     

   • Webhook Integration: Configure a Laravel route to handle Typeform webhooks:

     Route::post('/typeform-webhook', [TypeformWebhookController::class, 'handle']);
     

     Use the package to validate payloads:

     $payload = Typeform::validateWebhook(request()->all());
     

3. Field-Specific Logic

   • Dynamically access form fields:

     $emailField = Typeform::form('form_id')->field('email')->get();
     

Integration Tips

• API Rate Limiting: Cache responses aggressively (e.g., Cache::remember).
• Error Handling: Wrap API calls in try-catch blocks for Beloop\Typeform\Exceptions\TypeformException.
• Testing: Mock the Typeform facade in unit tests:

  $this->partialMock(Beloop\Typeform\Facades\Typeform::class, function ($mock) {
      $mock->shouldReceive('form')->andReturnSelf();
      $mock->shouldReceive('get')->andReturn($formData);
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated API

   • The package was last updated in 2019 and may not support Typeform’s current API (v202x). Verify endpoints (e.g., /forms vs /forms?page_size=100) in the Typeform API docs.
   • Workaround: Extend the package or use Guzzle directly for unsupported endpoints.

2. No Official Documentation

   • Assume undocumented methods may break. Inspect the source (vendor/beloop/typeform/src/) for undocumented features.

3. Webhook Validation

   • Typeform’s webhook signatures require a secret_key. Ensure it’s set in config:

     'webhook_secret' => env('TYPEFORM_WEBHOOK_SECRET'),
     

   • Debugging: Log raw payloads to compare with Typeform’s test signatures.

4. PHP Version Requirement (v1.0)

   • BREAKING CHANGE: Minimum PHP version is now 7.2. Update your environment if using PHP < 7.2.

Debugging

• Enable Debug Mode:

  Typeform::setDebug(true); // Logs API requests/responses
  

• Common Issues:
  • 401 Errors: Check TYPEFORM_API_TOKEN in .env.
  • Rate Limits: Add retries with exponential backoff:

    use Symfony\Component\HttpClient\RetryableHttpClient;
    
    $client = new RetryableHttpClient(
        HttpClient::create(['base_uri' => 'https://api.typeform.com']),
        [
            'max_retries' => 3,
            'delay_factor' => 100,
        ]
    );
    

Extension Points

1. Custom API Clients Override the default HTTP client in the service provider:

   $this->app->singleton(\Http\Client\Common\ClientInterface::class, function () {
       return new \GuzzleHttp\Client(['base_uri' => 'https://api.typeform.com']);
   });
   

2. Event Listeners Extend submission handling by listening to typeform.submission.received events (if supported).

3. Form Builder Create a Laravel form builder wrapper:

   class TypeformBuilder {
       public function __construct(private Typeform $typeform) {}
   
       public function build(array $fields) {
           return $this->typeform->form()->create($fields);
       }
   }
   

Config Quirks

• Environment Variables: Ensure .env includes:

  TYPEFORM_API_TOKEN=your_token_here
  TYPEFORM_WEBHOOK_SECRET=your_webhook_secret
  

• Default Endpoints: The package may hardcode https://api.typeform.com/v1. Override in config:

  'api' => [
      'base_uri' => 'https://api.typeform.com/v2', // Example override
  ],
  

Performance

• Pagination: Use ->paginate(100) for large datasets to avoid memory issues.
• Async Processing: Offload submission processing to a queue (e.g., Laravel Queues) for webhooks.