facebook-php-business-sdk: one package for Meta's advertising and business APIs

One package instead of a family of SDKs

The stated problem is a maintenance one. Partners are using multiple Facebook APIs to serve the needs of their clients, and adopting all of them and keeping them up to date across the various platforms can be time consuming and ultimately prohibitive. Facebook developed the Business SDK to bundle many of its APIs into one SDK, to ease implementation and upkeep.

The README describes it as an upgraded version of the Marketing API SDK that includes the Marketing API as well as many Facebook APIs from different platforms such as Pages, Business Manager and Instagram. So for a team that runs a campaign through the Marketing API and also reads Page content, the value is one dependency to bump rather than three.

That framing also tells you what the SDK is not. It is not a client for the whole Meta platform, and it does not abstract away the Graph API. The object classes map onto Graph API entities, the API surface is the Graph API, and the authentication model is Meta's own. What you get is PHP classes and field constants for a defined set of endpoints, plus the surrounding plumbing for sessions and pagination.

The package is published on Packagist as facebook/php-business-sdk, the project homepage is the Business SDK documentation at developers.facebook.com/docs/business-sdk, and the repository carries a DEVELOPER_GUIDE.md, a CHANGELOG.md and a CODE_OF_CONDUCT.md alongside the source.

The app and its secret are the first prerequisite

The SDK cannot be used without an app. The README states that you must have an app registered on developers.facebook.com, and that to manage the Marketing API you need to visit your App Dashboard and add the Marketing API product to your app.

There is a security instruction in the same section that is easy to skim and important not to. For security, it is recommended that you turn on 'Require App Secret' in your app's Settings and Advanced page. The README does not spell out what the setting does, but it is worth following before you build a workflow around manual tokens from the Graph Explorer.

That is worth understanding before you build a workflow around manual tokens, because it changes where tokens can come from and how a leaked token behaves. The README also points at the Graph Explorer as the tool to get an access token for now, which is a development convenience rather than a production pattern.

The dependency list also includes `fb_ca_chain_bundle.crt` at the repository root. A CA chain bundle shipped with the SDK is how the client trusts the API's certificate, and shipping it inside the package rather than relying on the system trust store is what lets the SDK work on a host with an outdated or minimal CA set.

Access tokens, and the permissions that shape them

The authentication model is Meta's, and the README explains it plainly. When someone connects with an app using Facebook Login and approves the request for permissions, the app obtains an access token that provides temporary, secure access to Facebook APIs. An access token is an opaque string that identifies a User, app or Page.

The permissions are what determine what a token can do, and the README gives the two that matter for this SDK. To access the Marketing API you need a User access token for your app and the `ads_management` permission. To access the Pages API you need a Page access token for your app and the `manage_page` permission.

The distinction between a User token and a Page token is the practical one for an agency: a User token with `ads_management` acts with the permissions of the person who granted it, across the ad accounts that person can reach. A Page token with `manage_page` acts for one specific Page. Choosing the wrong one produces the kind of failure that looks like a permissions bug in your code and is actually a token type mismatch.

The SDK does not change this. It gives you a place to put the token, and the decisions about which token to request, how to refresh it and where to store it stay with your application.

Api::init sets up a Session you then reach through a singleton

The entry point is the `FacebookAds\Api` object, described as the foundation of the Business SDK. It encapsulates a `FacebookAds\Session` and is used to execute requests against the Graph API.

Instantiating it needs a valid access token, and the pattern is a static initialisation followed by singleton access:

use FacebookAds\Api;

// Initialize a new Session and instantiate an Api object
Api::init($app_id, $app_secret, $access_token);

// The Api object is now available through singleton
$api = Api::instance();

So the app id, the app secret and the access token all enter at once, and the resulting object is a singleton. That has a real consequence for anything running more than one tenant. Because the session is global rather than injected, a process that needs to act on behalf of two different advertisers at the same time has to construct sessions differently, and the README does not document a per-request session pattern.

The benefit of the pattern is that it keeps the call sites short. Once the singleton exists, the object classes below use it implicitly, so a read or a create does not need a client passed in. For a single-tenant worker process, which is the common shape of a cron job that syncs campaigns, that is a reasonable trade.

Field enums and object classes replace string keys

The Graph API has a high number of field names, and the SDK's answer is to generate enum-like classes for them. These files are stored under the `FacebookAds/Object/Fields` directory, and they exist so that a field name is a constant rather than a string that a typo can silently break.

Object properties can be accessed in the ordinary PHP way:

use FacebookAds\Object\AdAccount;

$account = new AdAccount();
$account->name = 'My account name';
echo $account->name;

or through the enums:

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

$account = new AdAccount();
$account->{AdAccountFields::NAME} = 'My account name';
echo $account->{AdAccountFields::NAME};

Facebook Ads entities are defined as classes under the `FacebookAds/Object` directory, and the CRUD surface is uniform. Reading uses `getSelf`, optionally with a list of fields, because for some objects the Ads API does not return all available fields by default:

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

$fields = array(
  AdAccountFields::ID,
  AdAccountFields::NAME,
);

$account = (new AdAccount($account_id))->getSelf($fields);

The README warns that requesting a high number of fields may cause the response time to visibly increase, and that you should always request only the fields you really need. That is a Graph API property rather than an SDK one, but the SDK makes it easy to fall into, because the field constants make listing every field effortless.

Writes are method calls on the parent object

Creates are expressed as methods on the parent entity rather than as generic calls, which is the API design that makes ad objects feel like objects.

An ad set is created through its account:

use FacebookAds\Object\AdSet;
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdSetFields;

$account_id = 'act_123123';
$campaign_id = '123456';

$account = new AdAccount($account_id);
$adset = $account->createAdSet(
    array(),
    array(
      AdSetFields::NAME => 'My Test AdSet',
      AdSetFields::CAMPAIGN_ID => $campaign_id,
      AdSetFields::DAILY_BUDGET => 150,
      AdSetFields::START_TIME => (new \DateTime("+1 week"))->format(\DateTime::ISO8601),
      AdSetFields::END_TIME => (new \DateTime("+2 week"))->format(\DateTime::ISO8601),
      AdSetFields::BILLING_EVENT => 'IMPRESSIONS',
      AdSetFields::TARGETING => array('geo_locations' => array('countries' => array('US'))),
      AdSetFields::BID_AMOUNT => '1000',
    )
);

echo $adset->id;

Updates and deletes use `updateSelf` and `deleteSelf` on the object itself:

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;

$ad_set_id = '123456';

$set = new AdSet($ad_set_id);
$fields = array(
);
$params = array(
  AdSetFields::NAME => 'My new AdSet name',
);
$set->updateSelf($fields, $params);

The pattern is consistent: construct with an id, pass fields and params, and the SDK handles the HTTP. The parameters are plain PHP arrays keyed by the field constants, and the date values are ISO 8601 strings, which is the shape the Graph API expects for `START_TIME` and `END_TIME`.

For pagination, the README notes that since the release of the Graph API 2.0, pagination is handled through cursors, which are defined in `\FacebookAds\Cursor` and are generally returned from connection methods. The `examples/` directory is extensive and shows the range of endpoints, with files named after the edge they call, such as `AdAccountAdSetsPostCreateAdSet.php` and `AdAccountAdCreativesPostCreateAdCreative.php`.

A custom licence, PHP 8, and a calendar version

The licence field on the repository says it is a custom licence that GitHub cannot classify, with a pointer to the LICENSE file, and the README badge labels it Facebook Platform. This is not a standard open source licence such as MIT or Apache-2.0, and it is the first thing to check before you vendor the code into a product or redistribute it.

The runtime requirement is PHP 8.0 or greater, which is the practical adoption constraint for an existing PHP estate.

Installation is Composer, and the SDK and its dependencies are installed under `./vendor`:

composer require facebook/php-business-sdk

If Composer is not an option, the README notes that the repository is written following the psr-4 autoloading standard, so any psr-4 compatible autoloader can be used.

The versioning is calendar based. The releases are 26.0.0, tagged as Meta Business SDK v26.0.0, on 2026-08-06, then 26.0.1 on 2026-08-25 and 26.0.2 on 2026-09-21, with the last push on 2026-09-21, the same day as the latest tag. A major version each year with patch releases inside it means you should expect a breaking change when the year rolls over, and the CHANGELOG.md is where you would look before that happens.

The repository also carries a `bin/` directory, a `test/` directory and the `src/` tree, and the CI workflow is referenced by a build status badge in the README.

Editorial conclusion

Adopt the Facebook Business SDK for PHP when you already run PHP 8 or newer and your application touches the Marketing API alongside Pages, Business Manager or Instagram, since the value is in having one package and one release train rather than several. Skip it if your stack is not PHP, or if you make a small number of Graph API calls that a plain HTTP client with an access token would handle as well. Verify first that your app has the Marketing API product added and that Require App Secret is switched on in Settings, then confirm your access token carries the `ads_management` or `manage_page` permission your call needs. The repository licence is a custom Facebook Platform licence rather than a standard open source one, so read the LICENSE file before you vendor it.

Frequently asked questions

Official sources

1. facebook/facebook-php-business-sdk on GitHub
2. Issues
3. Project website
4. README
5. Releases