Coder Social home page Coder Social logo

facebook-php-business-sdk's Introduction

Facebook Business SDK for PHP

Packagist License Build Status Scrutinizer Scrutinizer Coverage

Introduction

The Facebook Business SDK is a one-stop shop to help our partners better serve their businesses. Partners are using multiple Facebook API's to server the needs of their clients. Adopting all these API's and keeping them up to date across the various platforms can be time consuming and ultimately prohibitive. For this reason Facebook has developed the Business SDK bundling many of its APIs into one SDK to ease implementation and upkeep. The Business SDK is 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, Instagram, etc.

Quick Start

Business SDK Getting Started Guide

Pre-requisites

Register An App

To get started with the SDK, you must have an app registered on developers.facebook.com.

To manage the Marketing API, please visit your App Dashboard and add the Marketing API product to your app.

IMPORTANT: For security, it is recommended that you turn on 'Require App Secret' in your app's Settings->Advanced page.

Obtain An Access Token

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.

For example, to access the Marketing API, you need to generate a User access token for your app and ask for the ads_management permission; to access Pages API, you need to generate a Page access token for your app and ask for the manage_page permission.

Refer to our Access Token Guide to learn more.

For now, we can use the Graph Explorer to get an access token.

Installation

The Facebook Business SDK requires PHP 5.6 or greater.

Composer

The Facebook Business SDK uses composer to manage dependencies. Visit the composer documentation to learn how to install composer.

Add the following to your composer.json file:

{
    "require": {
        "facebook/php-business-sdk": "12.0.*"
    }
}

then install it through composer:

php composer.phar install --no-dev

This SDK and its dependencies will be installed under ./vendor.

Alternatives

This repository is written following the psr-4 autoloading standard. Any psr-4 compatible autoloader can be used.

Usage

Api main class

The FacebookAds\Api object is the foundation of the Business SDK which encapsulates a FacebookAds\Session and is used to execute requests against the Graph API.

To instantiate an Api object you will need a valid access token:

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();

Once instantiated, the Api object will allow you to start making requests to the Graph API.

Fields names

Due to the high number of field names in the Graph API existing objects, in order to facilitate your code maintainability, enum-like classes are provided. These files are stored under the FacebookAds/Object/Fields directory. You can access object properties in the same manner you would usually do in php:

use FacebookAds\Object\AdAccount;

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

or using the enums:

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

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

Object classes

Facebook Ads entities are defined as classes under the FacebookAds/Object directory.

Read Objects

use FacebookAds\Object\AdAccount;

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

For some objects, the Ads API doesn't return all available fields by default. The first argument of the object's read method is an array of field names to be requested.

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

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

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

Requesting an high number of fields may cause the response time to visibly increase, you should always request only the fields you really need.

Create Objects

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;

Update Objects

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);

Delete Objects

use FacebookAds\Object\AdSet;

$ad_set_id = '123456';

$set = new AdSet($ad_set_id);
$set->deleteSelf();

Cursors

Since the release of the Facebook Graph API 2.0, pagination is handled through cursors. Here cursors are defined as in \FacebookAds\Cursor. Cursors are generally returned from connection methods:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\CampaignFields;

$account = new AdAccount('<ACT_ID>');
$cursor = $account->getCampaigns(['id','name']);

// Loop over objects
foreach ($cursor as $campaign) {
  echo $campaign->{CampaignFields::NAME}.PHP_EOL;
}

// Access objects by index
if ($cursor->count() > 0) {
  echo "The first campaign in the cursor is: ".$cursor[0]->{CampaignFields::NAME}.PHP_EOL;
}

// Fetch the next page
$cursor->fetchAfter();
// New Objects will be appended to the cursor

Implicit Fetching

Whenever all object connected to a parent are required (carelessly from the number of HTTP requests) implicit fetching can help reducing the amount of code required. If cursor has Implicit Fetching enabled, while iterating (foreach, Cursor::next(), Cursor::prev()) the page end is reached, the SDK will automatically fetch and append a new page, until cursor end. Implicit Fetching will make you lose control of the number of HTTP request that will be sent and, for this reason, is disabled by default. Implicit Fetching can be enabled for a specific cursor:

$cursor->setUseImplicitFetch(true);

Or globally:

use FacebookAds\Cursor;

Cursor::setDefaultUseImplicitFetch(true);

Reverse Iterations

Cursors are bi-directional, and can be iterated in reverse order:

use FacebookAds\Object\AbstractCrudObject;

/** @var \FacebookAds\Cursor $cursor */
$cursor->setUseImplicitFetch(true);

$cursor->end();
while ($cursor->valid()) {
  echo $cursor->current()->{AbstractCrudObject::FIELD_ID}.PHP_EOL;
  $cursor->prev();
}

Tests

The 'test' folder contains the test cases. These are logically divided in unit and integration tests. Integration tests require an active Facebook Ad Account, a Facebook Application and a valid Access Token.

Note: we are currently unable to securely and reliably run integration tests on a public CI system. Our integrations with Travis and Scrutinizer (including badges at the top of this file) include only unit tests.

Install dependencies

From the root folder run:

php composer.phar install --dev

Execute unit tests only

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

To run tests individually (be sure not to be pointing to an integration test file):

./vendor/bin/phpunit -c test/phpunit-travis.xml path/to/class/file

Execute all tests (unit + integration)

Setup your integration config:

1 - Copy the config file template.

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

2 - Edit test/config.php with your informations.

Execute:

./vendor/bin/phpunit -c test/

To run tests individually:

./vendor/bin/phpunit -c test/ path/to/class/file

Debug

If this SDK is not working as expected, it may be either a SDK issue or API issue.

This can be identified by constructing a raw cURL request and seeing if the response is as expected

for example:

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

Api::init($app_id, $app_secret, $access_token);
$api = Api::instance();

use FacebookAds\Logger\CurlLogger;
$api->setLogger(new CurlLogger());
$account = new AdAccount($account_id);
$account->read(array('id'));

When running this code, this cURL request will be printed to the console as:

curl -G \
  -d 'fields=id' \
  -d 'access_token=<access_token>' \
  https://graph.facebook.com/v3.1/<act_accountid>

SDK Codegen

Our SDK is autogenerated from SDK Codegen. If you want to learn more about how our SDK code is generated, please check this repository.

Issue

Since we want to handle bugs more efficiently, we've decided to close issue reporting in Github and move to our dedicated bug reporting channel. If you encounter a bug with Business SDK (PHP), please report the issue at our developer bug reporting channel.

facebook-php-business-sdk's People

Contributors

jingping2015 avatar duliomatos avatar paulbain avatar pruno avatar HeyMultiverse avatar donglinw-fb avatar jordanrs avatar kelnei avatar vicdus avatar kongxinzhu avatar davit-y avatar Tekill avatar neovdr avatar alexlupu avatar nicobn avatar w43l avatar shootingsyh avatar Daniel15 avatar LeorentKelmendi avatar xiaotchen avatar zoonman avatar andreladocruz avatar christinelu avatar ellentao avatar cordoval avatar Mxiim avatar suzuki avatar owust avatar avastamin avatar vl-lapikov avatar

Stargazers

Andrew Henke avatar Anatolii avatar Anderson Müller avatar Fahad Ali Khan avatar  avatar José Cage  avatar 庞浩然&Paul avatar  avatar Yusuf Neeson avatar Reinhardt Zündorf avatar  avatar Arvin Loripour avatar Diego avatar EiraChris avatar Muhammet ŞAFAK avatar  avatar Agent.47 avatar  avatar JunChen avatar Miša Brežanac avatar Pushpen Singh avatar Chernov Artem avatar  avatar Jack avatar Jaco Groenewald avatar  avatar  avatar Jackthedev avatar Dmitry Korolev avatar Ho avatar Abdul Rehman avatar Dian Afiff Rusydan avatar Tamás Tóth (ebola) avatar  avatar Lenne Nicolas avatar  avatar QuanTrieuPCYT avatar Geoff Maddock avatar Ahmed Hdeawy avatar uybe avatar Alex Bogias avatar moneya avatar Colton Eakins avatar kuma avatar Fabio Pinto avatar Yanis avatar Nasirou Wagana avatar Łukasz Golonka avatar xtechnology avatar Patryk Chowratowicz avatar James Taylor avatar Taras avatar adil chbada avatar Matteo Mercuri avatar Dustin Boling avatar  avatar  avatar  avatar Cody Person avatar  avatar Christian Rauchenwald avatar Reg avatar  avatar  avatar Bayram Ali avatar Andrzej Erenc avatar Nirjhar Lo avatar Daniel Huidobro avatar Fernando Gutiérrez avatar Alejandro Jesus del Campillo Jaime avatar Huub avatar  avatar Márcio Possani Marques avatar Eyal Gantz avatar Jonathan avatar Theodis Butler avatar  avatar Jorge Fco.™ avatar Ekin Karadeniz avatar Ginbert avatar  avatar Jordan Charters avatar Alex Sáenz avatar Kennedy Tedesco avatar  avatar Greatfar avatar Dmi avatar Steve Edson avatar Flávio H. Ferreira avatar Eele avatar Diego Casetti avatar Alvaro Isorna avatar Keany Vy KHUN avatar @GOUAIC avatar fang qiang avatar Callum Macalast avatar jpiment_spicee avatar Fabiano Couto avatar Timothy Marois avatar  avatar

Watchers

Sergey N. Poulikov avatar Thomas LÉVEIL avatar Alessandro Fiore avatar  avatar Max Castro avatar Florian Bräuer avatar David Pio avatar  avatar Jawwad Ahmad avatar wizcap avatar  avatar  avatar Paul Bain avatar LPasslack avatar Kenjiro Yasui avatar Nate Wiebe avatar Andrey Popov avatar James Cloos avatar Carlos Buzato avatar  avatar Theodis Butler avatar Stefano Gargiulo avatar Jack avatar Aaron Kushner avatar Flarnie Marchan avatar Michele Venturi avatar quality bargain  avatar Cloud Xu avatar Panagiotis avatar  avatar John Franco avatar  avatar  avatar Omid Saadati avatar Zeus avatar  avatar  avatar pramod pandey avatar Mark Broersen avatar Shuotian Cheng avatar sasikumar avatar  avatar Dexter avatar Dulio Matos avatar Chaipat avatar Leandro Panegassi avatar Matt Felser avatar Josh Murphy avatar Sari Salmi avatar Pedro Alves avatar Le Tuan Minh avatar  avatar Cody Winton avatar Nabin Chaulagain avatar 易达(易于达成)-erpadmin avatar  avatar Eyal Gantz avatar  avatar Francisco Camargos avatar liuxiaojian avatar  avatar paultofman avatar Peihua Zhou avatar  avatar Vijaysinh Parmar avatar Vincent Chen avatar Hitesh Sethiya avatar Yuval Aviyam avatar  avatar Stefan avatar Adam Raposo avatar younes avatar  avatar Faisal Shabir Jan avatar  avatar  avatar Nuno Edgar Nunes Fernandes avatar Mouwu Lin avatar Stanislav Stoynov avatar Leon avatar BenettZhang avatar Jing Ping avatar Gautam Mehra avatar KillerKiwi avatar Cody Person avatar  avatar  avatar  avatar Moyang avatar  avatar  avatar norbertomoreau avatar Jiaming avatar  avatar  avatar Neil Olson avatar Arun Sathiya avatar Kids Shop Online  avatar  avatar DAVID TIM avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.