Capi Param Builder Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require facebook/capi-param-builder-php
   

   Add to composer.json under require or require-dev if testing.

2. First Use Case Build a basic PageView event for Facebook's Conversions API:

   use Facebook\Capi\ParamBuilder\ParamBuilder;
   
   $builder = new ParamBuilder();
   $params = $builder->pageView()
       ->setEventId('12345')
       ->setEventTime('2023-10-01T12:00:00+00:00')
       ->setData(array(
           'currency' => 'USD',
           'value' => 99.99,
       ))
       ->build();
   

3. Where to Look First

   • Official Documentation
   • src/ParamBuilder.php (core class)
   • src/EventTypes/ (event-specific builders like Purchase, Lead, etc.)

Implementation Patterns

Core Workflow

1. Event Initialization Use fluent methods to chain event-specific configurations:

   $purchase = $builder->purchase()
       ->setEventId('purchase_789')
       ->setEventSourceUrl('https://example.com/checkout')
       ->setData(array(
           'contents' => array(
               array(
                   'id' => 'prod_123',
                   'quantity' => 2,
               ),
           ),
       ));
   

2. Data Validation & Sanitization The builder auto-sanitizes inputs (e.g., trims strings, validates dates). Example:

   $builder->custom()
       ->setEventId('custom_123')
       ->setCustomData(array(
           'user_property' => array(
               'email' => 'user@example.com', // Auto-sanitized
           ),
       ));
   

3. Batch Processing For bulk events (e.g., server-to-server API calls):

   $batch = [];
   foreach ($orders as $order) {
       $batch[] = $builder->purchase()
           ->setEventId($order['id'])
           ->setData($order['data'])
           ->build();
   }
   // Send $batch to Facebook API in one request.
   

4. Integration with Laravel

   • Service Provider Binding:

     // app/Providers/AppServiceProvider.php
     public function register()
     {
         $this->app->singleton(ParamBuilder::class, function () {
             return new ParamBuilder();
         });
     }
     

   • Request Handling (e.g., middleware for webhook validation):

     use Facebook\Capi\ParamBuilder\ParamBuilder;
     
     public function handle(Request $request, Closure $next)
     {
         $builder = app(ParamBuilder::class);
         $params = $builder->fromRequest($request)->build();
         // Validate/process $params...
         return $next($request);
     }
     

5. Testing Mock the builder in unit tests:

   $builder = $this->createMock(ParamBuilder::class);
   $builder->method('purchase')
       ->willReturnSelf()
       ->method('setEventId')
       ->willReturnSelf()
       ->method('build')
       ->willReturn(['valid' => 'params']);
   

Gotchas and Tips

Pitfalls

1. Event-Specific Requirements

   • Some events (e.g., Lead) require mandatory fields. The builder throws exceptions for missing data:

     try {
         $builder->lead()->build(); // Fails if no 'lead_data' is set.
     } catch (InvalidArgumentException $e) {
         // Handle missing fields.
     }
     

   • Fix: Always check the Facebook docs for event-specific rules.

2. Date/Time Formatting

   • The builder expects ISO 8601 strings (e.g., 2023-10-01T12:00:00+00:00). Invalid formats throw errors.
   • Tip: Use Carbon for consistency:

     use Carbon\Carbon;
     $eventTime = Carbon::now()->toIso8601String();
     

3. Nested Data Structures

   • Arrays like contents (for Purchase) must follow Facebook’s schema. Malformed data (e.g., missing id or quantity) causes validation failures.
   • Debugging: Use json_encode($builder->getData(), JSON_PRETTY_PRINT) to inspect raw output.

4. Rate Limits

   • Facebook’s API has strict rate limits. Batch processing helps, but test with small payloads first.

5. Deprecation Warnings

   • The package is lightweight but may lag behind Facebook’s API updates. Check the changelog for breaking changes.

Tips

1. Reuse Builders Create reusable builder instances for common events:

   class PurchaseBuilder
   {
       public function __construct(private ParamBuilder $builder) {}
   
       public function buildFromOrder(Order $order): array
       {
           return $this->builder->purchase()
               ->setEventId($order->id)
               ->setData($order->toArray())
               ->build();
       }
   }
   

2. Custom Validation Extend the builder for project-specific rules:

   class ExtendedParamBuilder extends ParamBuilder
   {
       public function validateEmail(string $email): void
       {
           if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
               throw new InvalidArgumentException("Invalid email: $email");
           }
       }
   
       public function customEventWithEmail(): self
       {
           return $this->custom()
               ->setCustomData(['email' => $this->validateEmail(...));
       }
   }
   

3. Logging Log built parameters for debugging/auditing:

   $params = $builder->purchase()->build();
   \Log::debug('Facebook CAPI params', ['params' => $params]);
   

4. Performance

   • For high-volume apps, pre-validate data before passing it to the builder to avoid runtime exceptions.
   • Cache builder instances if reused frequently (e.g., in a singleton service).

5. Client-Side Sync If using both server-side (PHP) and client-side (JS) builders, ensure consistent parameter naming across platforms. Example:

   // PHP
   $builder->purchase()->setData(['contents' => [...]]);
   

   // JavaScript
   meta.capiParamBuilder.purchase().setData({ contents: [...] });