Php Business Sdk Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require facebook/php-business-sdk
   

   Requires PHP 8.0+.

2. Initialize SDK:

   use FacebookAds\Api;
   
   Api::init($appId, $appSecret, $accessToken);
   $api = Api::instance();
   

3. First Use Case: Fetch an ad account:

   use FacebookAds\Object\AdAccount;
   
   $account = (new AdAccount($accountId))->getSelf();
   echo $account->name;
   

Where to Look First

• Documentation: Facebook Business SDK Docs
• Object Fields: FacebookAds/Object/Fields/ for enum-like field names.
• Examples: SDK’s test/ directory for integration patterns.

Implementation Patterns

Core Workflows

1. CRUD Operations:

   • Create: Use createAdSet(), createAd(), etc., with required fields.

     $adSet = $account->createAdSet([], [
         AdSetFields::NAME => 'Test AdSet',
         AdSetFields::DAILY_BUDGET => 100,
     ]);
     

   • Read: Fetch objects with optional field selection.

     $campaigns = $account->getCampaigns([CampaignFields::ID, CampaignFields::NAME]);
     

   • Update: Modify objects via updateSelf().

     $adSet->updateSelf([], [AdSetFields::NAME => 'Updated Name']);
     

   • Delete: Remove objects with deleteSelf().

2. Pagination with Cursors:

   • Iterate through paginated results:

     foreach ($cursor as $campaign) {
         echo $campaign->{CampaignFields::NAME};
     }
     

   • Enable implicit fetching for large datasets:

     $cursor->setUseImplicitFetch(true);
     

3. Conversions API:

   • Batch events for efficiency:

     $batchProcessor = new BatchProcessor($api);
     $batchProcessor->addEvent($eventRequest);
     $batchProcessor->send();
     

   • Async operations:

     $eventRequestAsync = new EventRequestAsync($api, $eventRequest);
     $eventRequestAsync->send();
     

Integration Tips

• Laravel Service Provider: Bind the SDK to Laravel’s container for dependency injection:

  public function register()
  {
      $this->app->singleton(Api::class, function () {
          return Api::instance();
      });
  }
  

• Configuration: Store credentials in .env and load them dynamically:

  Api::init(
      env('FACEBOOK_APP_ID'),
      env('FACEBOOK_APP_SECRET'),
      env('FACEBOOK_ACCESS_TOKEN')
  );
  

• Logging: Enable debug logging for API issues:

  $api->setLogger(new CurlLogger());
  

Gotchas and Tips

Pitfalls

1. Access Tokens:

   • Short-lived tokens (1 hour) require re-authentication. Use long-lived tokens or implement token refresh logic.
   • Tip: Store tokens securely (e.g., Laravel’s encrypter) and avoid hardcoding.

2. Field Selection:

   • Over-fetching fields slows responses. Always specify required fields:

     $account->getSelf([AdAccountFields::ID, AdAccountFields::NAME]);
     

3. Implicit Fetching:

   • Enabled by default in tests but disabled globally in production to avoid excessive API calls.
   • Tip: Use sparingly and monitor HTTP requests.

4. Conversions API:

   • Batch Limits: Max 500 events per batch. Larger batches require splitting.
   • Async Delays: Async events may take minutes to process. Avoid relying on immediate feedback.

5. Deprecations:

   • Graph API versions change frequently (e.g., v9.0+). Update SDK and test thoroughly after major releases.

Debugging

• CurlLogger: Output raw API requests for debugging:

  $api->setLogger(new CurlLogger());
  

• Error Handling: Catch FacebookAds\Exceptions\FacebookAdsException for API errors:

  try {
      $account->getSelf();
  } catch (FacebookAdsException $e) {
      log::error($e->getMessage());
      log::debug($e->getHeaders());
  }
  

Extension Points

1. Custom HTTP Clients: Override default HTTP requests for Conversions API:

   $api->setHttpClient(new CustomHttpClient());
   

2. Event Validation: Extend FacebookAds\Object\AbstractObject to add custom validation logic before API calls.
3. Webhooks: Use the SDK to verify and parse webhook signatures (e.g., for ad performance updates).

Config Quirks

• App Secret Proof: Required for some API calls (e.g., Conversions API). Generate via:

  $appSecretProof = hash_hmac('sha256', $accessToken, $appSecret);
  

• Data Processing Options: Required for GDPR compliance. Configure via:

  $pixel->setDataProcessingOptions(['business_verification' => true]);