بدء استخدام مجموعة Facebook SDK للغة PHP

سواء كنت تقوم بتطوير موقع ويب باستخدام تسجيل دخول فيسبوك أو إنشاء علامة تبويب صفحة أو تطبيق Canvas على فيسبوك، تتولى مجموعة Facebook SDK للغة PHP كل المهام الصعبة لتجعل التكامل مع منصة فيسبوك أسهل ما يمكن.

التحميل التلقائي ومساحات الأسماء

وضِع الرمز البرمجي للإصدار 5 من مجموعة Facebook SDK للغة PHP بالتوافق مع PSR-4. ويعني ذلك أنها تعتمد اعتمادًا كبيرًا على مساحات الأسماء بحيث يمكن تحميل ملفات الفئات تلقائيًا لك.

ومن المفيد أن تعتاد على مفاهيم مساحات الأسماء والتحميل التلقائي إذا لم تكن على دراية بهما من قبل.

متطلبات النظام

• PHP 5.4 أو أحدث
• امتداد mbstring
• Composer (اختياري)

تثبيت مجموعة Facebook SDK للغة PHP

يمكن تثبيت مجموعة Facebook SDK للغة PHP بطريقتين. تتمثل الطريقة الموصى بها لتثبيت المجموعة في استخدام Composer. إذا تعذر عليك استخدام Composer في مشروعك، يظل بإمكانك تثبيت مجموعة SDK يدويًا بتنزيل الملفات المصدر وتضمين أداة التحميل التلقائي.

التثبيت باستخدام Composer (موصى به)

يعتبر تثبيت مجموعة Facebook SDK للغة PHP باستخدام Composer هو الطريقة الموصى بها. ما عليك سوى إضافة الإدخال "الإلزامي" التالي إلى ملف composer.json في المجلد الجذر لمشروعك.

{
  "require" : {
    "facebook/graph-sdk" : "~5.0"
  }
}

بعد ذلك قم بتشغيل composer install من سطر الأوامر، وسيعمل Composer على تنزيل آخر إصدار من مجموعة SDK ووضعه في مجلد /vendor/.

تأكد من تضمين أداة التحميل التلقائي لـ Composer أعلى النص البرمجي.

require_once __DIR__ . '/vendor/autoload.php';

التثبيت اليدوي (إذا كنت مضطرًا لذلك)

أولاً، قم بتنزيل الرموز البرمجية المصدر وفك ضغطها في المكان الذي تريده داخل مشروعك.

ثم قم بتضمين أداة التحميل التلقائي المصاحبة لمجموعة SDK أعلى النص البرمجي.

require_once __DIR__ . '/path/to/facebook-php-sdk-v4/src/Facebook/autoload.php';

يجب أن تتمكن أداة التحميل التلقائي من اكتشاف المكان المناسب للرمز البرمجي المصدر تلقائيًا.

المحافظة على النظام

يحتوي الرمز البرمجي المصدر على أعداد كبيرة من الملفات التي لا ضرورة لاستخدامها في بيئات الإنتاج. إذا كنت ترغب في إزالة كل شيء باستثناء الملفات الأساسية، فاتبع هذا المثال.

بعد تنزيل الرمز البرمجي المصدر باستخدام الزر المذكور أعلاه، قم بفك ضغط الملفات في مجلد مؤقت.

انقل المجلد src/Facebook إلى جذر تثبيت موقعك على الويب أو إلى أي مكان تريد وضع رمز جهة خارجية به. في هذا المثال، سنعيد تسمية مجلد Facebook إلى facebook-sdk-v5.

من المفترض أن يكون مسار الملفات الأساسية لمجموعة SDK موجودًا الآن في /var/html/facebook-sdk-v5 وسيكون بداخله أيضًا ملف autoload.php.

وبافتراض أن لدينا نصًا برمجيًا باسم index.php في جذر مشروع الويب، فسنحتاج إلى تضمين أداة التحميل التلقائي من أعلى النص البرمجي.

require_once __DIR__ . '/facebook-sdk-v5/autoload.php';

إذا واجهت أداة التحميل التلقائي مشكلة في اكتشاف مسار الملفات المصدر، يمكننا العثور على مكان الرمز البرمجي المصدر قبل عبارة require_once.

define('FACEBOOK_SDK_V4_SRC_DIR', __DIR__ . '/facebook-sdk-v5/');
require_once __DIR__ . '/facebook-sdk-v5/autoload.php';

التكوين والإعداد

ليمكنك إرسال طلبات إلى Graph API، نحتاج إلى تحميل تكوين تطبيقنا إلى خدمة Facebook\Facebook.

$fb = new Facebook\Facebook([
  'app_id' => '{app-id}',
  'app_secret' => '{app-secret}',
  'default_graph_version' => 'v2.5',
]);

ستحتاج إلى استبدال {app-id} و{app-secret} بمعرف تطبيقك على فيسبوك ومفتاحه السري ويمكنك الحصول عليهما من علامة تبويب إعدادات التطبيق.

تعمل خدمة Facebook\Facebook على ربط كل مكونات مجموعة SDK للغة PHP معًا. اطلع على المرجع الكامل لخدمة Facebook\Facebook.

المصادقة والتصريح

يمكن استخدام مجموعة SDK لدعم تسجيل دخول مستخدم فيسبوك إلى موقعك باستخدام تسجيل دخول فيسبوك اعتمادًا على OAuth 2.0.

تطلب معظم الطلبات المقدمة إلى Graph API رمز وصول. يمكننا الحصول على رموز وصول المستخدمين عن طريق SDK باستخدام فئات المساعدة.

الحصول على رمز وصول من إعادة توجيه

مع معظم مواقع الويب، سوف تستخدم Facebook\Helpers\FacebookRedirectLoginHelper لإنشاء عنوان URL لتسجيل الدخول بطريقة getLoginUrl(). سينقل الرابط المستخدم إلى شاشة تصريح داخل التطبيق، وعند الموافقة، سيعيد توجيهه إلى عنوان URL تقوم بتحديده. في الصفحة التي يتم الوصول إليها بموجب إعادة التوجيه، يمكننا الحصول على رمز وصول المستخدم ككيان AccessToken.

# login.php
$fb = new Facebook\Facebook([/* . . . */]);

$helper = $fb->getRedirectLoginHelper();
$permissions = ['email', 'user_likes']; // optional
$loginUrl = $helper->getLoginUrl('http://{your-website}/login-callback.php', $permissions);

echo '<a href="' . $loginUrl . '">Log in with Facebook!</a>';

# login-callback.php
$fb = new Facebook\Facebook([/* . . . */]);

$helper = $fb->getRedirectLoginHelper();
try {
  $accessToken = $helper->getAccessToken();
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  // When Graph returns an error
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  // When validation fails or other local issues
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}

if (isset($accessToken)) {
  // Logged in!
  $_SESSION['facebook_access_token'] = (string) $accessToken;

  // Now you can redirect to another page and use the
  // access token from $_SESSION['facebook_access_token']
}

الحصول على رمز الوصول من سياق Facebook Canvas

في حالة وجود تطبيقك على Facebook Canvas، فاستخدم طريقة getAccessToken() في Facebook\Helpers\FacebookCanvasHelper للحصول على كيان AccessToken للمستخدم.

# example-canvas-app.php
$fb = new Facebook\Facebook([/* . . . */]);

$helper = $fb->getCanvasHelper();
try {
  $accessToken = $helper->getAccessToken();
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  // When Graph returns an error
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  // When validation fails or other local issues
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}

if (isset($accessToken)) {
  // Logged in.
}

الحصول على رمز وصول من SDK للغة JavaScript

إذا كنت تستخدم مجموعة Facebook SDK للغة JavaScript لمصادقة المستخدمين، يمكنك الحصول على رمز الوصول في PHP باستخدام FacebookJavaScriptHelper. ستعيد طريقة getAccessToken() كيان AccessToken.

# example-obtain-from-js-cookie-app.php
$fb = new Facebook\Facebook([/* . . . */]);

$helper = $fb->getJavaScriptHelper();
try {
  $accessToken = $helper->getAccessToken();
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  // When Graph returns an error
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  // When validation fails or other local issues
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}

if (isset($accessToken)) {
  // Logged in
}

تمديد رمز الوصول

عند تسجيل دخول المستخدم إلى تطبيقك، يكون رمز الوصول الذي يحصل عليه تطبيقك قصير الأجل ولا يعمل سوى لمدة ساعتين. يجدر بوجه عام استبدال رمز الوصول قصير الأجل بآخر طويل الأجل يستمر لمدة 60 يومًا.

لتمديد رمز وصول، يمكنك الاستفادة من OAuth2Client.

// OAuth 2.0 client handler
$oAuth2Client = $fb->getOAuth2Client();

// Exchanges a short-lived access token for a long-lived one
$longLivedAccessToken = $oAuth2Client->getLongLivedAccessToken('{access-token}');

تعرف على المزيد من المعلومات عن رموز الوصول طويلة الأجل وقصيرة الأجل.

تقديم طلبات إلى Graph API

بمجرد وجود مثيل خدمة Facebook\Facebook والحصول على رمز وصول، يمكنك بدء إجراء عمليات استدعاء لـ Graph API.

في هذا المثال، سنرسل طلب GET إلى نقطة نهاية Graph API /me. تعد نقطة نهاية /me اسمًا مستعارًا لـنقطة نهاية عقدة المستخدم التي تشير إلى المستخدم أو الصفحة مقدمة الطلب.

$fb = new Facebook\Facebook([/* . . . */]);

// Sets the default fallback access token so we don't have to pass it to each request
$fb->setDefaultAccessToken('{access-token}');

try {
  $response = $fb->get('/me');
  $userNode = $response->getGraphUser();
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  // When Graph returns an error
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  // When validation fails or other local issues
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}

echo 'Logged in as ' . $userNode->getName();

ستؤدي طريقة get() إلى إرجاع Facebook\FacebookResponse وهي عبارة عن كيان يمثل استجابة HTTP من Graph API.

للحصول على الاستجابة في صورة مجموعة مفيدة، نقوم باستدعاء getGraphUser() تعيد كيان Facebook\GraphNodes\GraphUser يمثل عقدة المستخدم.

إذا كنت لا تولي اهتمامًا كبيرًا بجودة شكل المجموعات وتريد أن تكون الاستجابة في صورة المصفوفات البسيطة المعتادة، يمكنك استدعاء طريقة getDecodedBody() بكيان FacebookResponse.

try {
  $response = $fb->get('/me');
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  // . . .
  exit;
}

$plainOldArray = $response->getDecodedBody();

للاطلاع على قائمة كاملة بكل المكونات التي تتألف منها مجموعة SDK للغة PHP، راجع صفحة مرجع مجموعة SDK للغة PHP.