Facebook Business SDK for PHP

To avoid using hardcoded strings and to benefit from validation, use the field definition classes located in the FacebookAds\Object\Fields namespace. You can use these constants with setData() or via direct property assignment.

// Using field definitions with setData
$someObject->setData(array(
  MyObjectFields::ID => 1234,
  MyObjectFields::NAME => 'My Name',
));

// Using field definitions with direct assignation
$someObject->{SomeObjectFields::ID} = 123;

// Equivalent to using string names
$someObject->id = 123;

To maintain code stability and avoid typos, the SDK provides enum-like classes for Graph API field names. These are located in the FacebookAds/Object/Fields directory. You can access object properties using these enums with the curly brace syntax.

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;

$account = new AdAccount();
// Using the enum for the field name
$account->{AdAccountFields::NAME} = 'My account name';
echo $account->{AdAccountFields::NAME};

By default, the SDK uses a static reference to the first Api instance created. To manage multiple sessions (e.g., syncing data for multiple users) in a single script, you have two options:

1. Mutate the default instance: Use Api::instance() to get the current instance or Api::setInstance($api) to replace the global default.
2. Explicitly define the instance per object: Pass the specific Api instance to the constructor of any class extending Object\AbstractCrudObject.

use FacebookAds\Object\Ad;
$my_ad = new Ad($id, $parent_id=null, $api);

To use the SDK, you must first include the Composer autoloader and initialize the FacebookAds\\Api class with your application credentials and an access token. This sets up the global state for making requests.

<?php
define('SDK_DIR', '/path/to/sdk/'); // Path to the SDK directory 

$loader = include SDK_DIR.'/vendor/autoload.php';

use FacebookAds\Api;

Api::init($app_id, $app_secret, $access_token);

The SDK uses a PSR-4 compliant autoloader. If you are using Composer, include the autoloader from your vendor directory to ensure all classes are available.

<?php
define('VENDOR_DIR', '/path/to/sdk/'); // Path to the Vendor directory 
$loader = include VENDOR_DIR.'/vendor/autoload.php';

The Facebook Business SDK requires PHP 8.0 or greater. The recommended way to install the SDK is using Composer. This will install the SDK and its dependencies into the ./vendor directory.

composer require facebook/php-business-sdk

By default, calling read() on an AbstractCrudObject requests no fields. To always request a specific set of fields, extend the target class (e.g., AdAccount) within your own namespace and override the protected static variable $defaultReadFields with an array of desired field constants.

namespace MyNamespace\Object;

use FacebookAds\Object\Fields\AdAccountFields;

class AdAccount extends FacebookAds\Object\AdAccount {

  protected static $defaultReadFields = array(
    AdAccountFields::ID,
    AdAccountFields::NAME,
    AdAccountFields::DAILY_SPEND_LIMIT,
    AdAccountFields::CURRENCY,
  );
}

// Usage:
use MyNamespace\Object\AdAccount;
$adaccount = (new AdAccount($id))->read();

If you are experiencing issues with the SDK, you can determine if the problem lies with the SDK or the Facebook API by inspecting the raw cURL request being sent. You can do this by attaching a CurlLogger to the Api instance. This will print the exact cURL command to your console, which you can then use to test the request independently.

require __DIR__ . '/vendor/autoload.php';
use FacebookAds\Api;
use FacebookAds\Object\AdAccount;
use FacebookAds\Logger\CurlLogger;

// Initialize the API
Api::init($app_id, $app_secret, $access_token);
$api = Api::instance();

// Attach the logger to see the raw cURL request in the console
$api->setLogger(new CurlLogger());

$account = new AdAccount($account_id);
$account->read(array('id'));

If you have extended SDK classes and want to ensure connection helper methods return your custom namespace types instead of the base FacebookAds types, use the generic connection methods: getOneByConnection or getManyByConnection. These allow you to specify the target class name explicitly.

use FacebookAds\Object\AdAccount;
use MyNamespace\Object\Ad;

$account = new AdAccount($id);
$my_adaccount_objects = $account->getManyByConnection(
  Ad::className(), 
  $fields = array(...), 
  $params = array(...)
);

The SDK includes both unit and integration tests. Integration tests require an active Facebook Ad Account, a Facebook Application, and a valid Access Token.

1. Install dependencies:

php composer.phar install --dev

2. Run unit tests only: Use the specific configuration file for unit tests:

./vendor/bin/phpunit -c test/phpunit-travis.xml

3. Run all tests (unit + integration): First, create your integration configuration by copying the template:

cp test/config.php.dist test/config.php

Edit test/config.php with your credentials, then execute:

./vendor/bin/phpunit -c test/