بدء استخدام مكتبة عميل PHP لبيانات Google

تحذير: تتعلق هذه الصفحة بواجهات برمجة التطبيقات القديمة من Google، وهي واجهات برمجة التطبيقات لبيانات Google؛ وهي مرتبطة فقط بواجهات برمجة التطبيقات المدرجة في دليل Google Data APIs، والتي تم استبدال العديد منها بواجهات برمجة تطبيقات أحدث. للحصول على معلومات حول واجهة برمجة تطبيقات جديدة، اطلع على وثائق واجهة برمجة التطبيقات الجديدة. للحصول على معلومات حول تفويض الطلبات باستخدام واجهة برمجة تطبيقات أحدث، اطلع على مصادقة حسابات Google وتفويضها.

فيديو: شاهد تريفور جونز خلال عملية تثبيت مكتبة العميل، وبنية المكتبة، وجولة تفصيلية حول الشفرات.

جوشين هارتمان، فريق Google Data APIs
تم التحديث في تشرين الأول (أكتوبر) 2008 (تمت كتابتها في الأصل بواسطة دانيال هولفوي)

المقدمة

مكتبة برامج Google Data PHP هي مجموعة فعّالة من الفئات التي تسمح لك بالتفاعل مع Google Data APIs. على عكس مكتبات العملاء الأخرى، يتم تجميعها كجزء من إطار عمل Zend الرائج ولكن يمكن تنزيلها أيضًا بشكل منفصل. وعلى غرار مكتبات العملاء الأخرى، فهو أيضًا برنامج مفتوح المصدر ومصمم ليكون بسيطًا وفعالاً، مما يسمح لك ببدء مشروعاتك بسرعة.

التثبيت المسبق

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

<?php phpinfo(); ?>

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

لقطة شاشة لصفحة معلومات php

تعرض لقطة الشاشة صفحة معلومات PHP. تعرض لك هذه الصفحة إصدار PHP الذي تم تثبيته (5.2.6 في هذه الحالة)، إلى جانب الإضافات التي تم تمكينها (في قسم "تهيئة الأمر") وموقع ملف التهيئة الداخلي للغة PHP (في قسم "ملف التهيئة المحمّل"). إذا لم يتم عرض الصفحة أو إذا كان إصدار PHP أقدم من 5.1.4، فستحتاج إلى تثبيت إصدار PHP أو ترقيته. بخلاف ذلك، يمكنك تخطي القسم التالي ومتابعة تثبيت مكتبة برامج PHP.

ملاحظة: إذا كان لديك إذن بالوصول إلى سطر الأوامر وكنت تخطط لاستخدام PHP لتشغيل النصوص البرمجية لسطر الأوامر، يُرجى الاطّلاع على قسم PHP سطر الأوامر من هذه المقالة.

تثبيت PHP

يختلف التثبيت قليلاً حسب النظام الأساسي، لذا من المهم اتباع التعليمات الخاصة بالنظام الأساسي المُحدَّد أثناء التثبيت. وقبل الخوض في التفاصيل، تجدر الإشارة إلى أن الحزم المثبتة مسبقًا التي تتضمن أيضًا خادم الويب Apache وقاعدة بيانات MySQL جنبًا إلى جنب مع PHP أصبحت شائعة. بالنسبة إلى أنظمة التشغيل Windows وMac OS X وLinux، فهناك مشروع XAMPP. ويمكن لمستخدمي نظام التشغيل Mac OS X أيضًا اختيار استخدام مشروع AMP. تعتمد هاتان الحِزمتان OpenSSL بلغة PHP (مطلوبة للتفاعل مع الخلاصات التي تمت مصادقتها).

في حالة تثبيت PHP باستخدام الخطوات التالية، تأكد من تثبيت ودعم OpenSSL أيضًا. ويمكن الاطلاع على مزيد من التفاصيل حول ذلك في قسم OpenSSL من موقع PHP. تركز الأقسام التالية على كيفية تثبيت PHP وحدها.

في نظام التشغيل Windows

تُعد أسهل طريقة لتثبيت PHP أو ترقيتها على نظام التشغيل Windows هي أداة تثبيت PHP المتوفرة على صفحة تنزيلات PHP.

  1. حدد خيار مثبت PHP (في قسم ثنائيات Windows) المناظر لأحدث إصدار من PHP واسمح بتنزيله.
  2. افتح أداة التثبيت واتبع تعليمات معالج التثبيت.
  3. عندما يطلب منك المعالج، اختر خادم الويب الذي تم تثبيته على نظامك، بحيث يهيئ الخادم للعمل مع PHP.
  4. تحقق من التثبيت باتباع الخطوات الموضحة في القسم أعلاه.

في نظام التشغيل Mac OS X

PHP مضمن في نظام التشغيل OS X، ولكن قبل استخدامه، يجب عليك الترقية إلى أحدث إصدار من PHP. للترقية، يمكنك تثبيت أي حزمة من حزم البرامج الثنائية المجانية، أو تجميعها بنفسك. لمزيد من التفاصيل، راجع صفحة مستندات PHP حول التثبيت على نظام التشغيل Mac OS X.

بعد تثبيت نظام التشغيل OS X أو إعداده، يمكنك التحقق من التثبيت باتباع الخطوات الموضّحة في قسم التثبيت المسبق لهذا المستند.

في نظام التشغيل Linux

وبناءً على توزيع Linux، قد يتوفر خيار إعداد مضمَّن أو سهل الاستخدام لتثبيت ملفات PHP. على سبيل المثال، يمكنك استخدام مدير الحزم في Ubuntu أو كتابة الآتي في نافذة طرفية:

sudo apt-get install php5

في حالة عدم توفر تثبيت مجمّع مع توزيع Linux، يجب التثبيت من شفرة المصدر. هناك تعليمات تفصيلية حول تجميع PHP للإصدار Apache 1.3 وتجميع PHP للإصدار Apache 2. كما أن PHP.net يحتوي على تعليمات للخوادم الأخرى.

تثبيت مكتبة عميل PHP لبيانات Google

الآن بعد تثبيت إصدار صالح من لغة PHP، حان وقت تثبيت مكتبة العميل. تعتبر مكتبة العميل جزءًا من إطار عمل Zend مفتوح المصدر ولكن يمكن تنزيلها كإصدار مستقل أيضًا. إذا كان لديك إصدار مثبت من إطار عمل Zend من قبل (الإصدار 1.6 أو إصدار أحدث)، يمكنك تخطي التثبيت، نظرًا لأنه يتم تضمين مكتبة عميل بيانات Google. ومع ذلك، فإنّ التأكُّد من استخدام أحدث إصدار من إطار العمل سيضمن حصولك على أحدث الميزات وإصلاحات الأخطاء المتاحة لك، لذا ننصح عادةً باستخدامه.

ولن يمنحك تنزيل إطار العمل الكامل إمكانية الوصول إلى مكتبة عميل بيانات Google فحسب، بل وإلى بقية إطار العمل أيضًا. وتستخدم مكتبة العملاء نفسها بعض الفئات الأخرى التي تعتبر جزءًا من إطار عمل Zend الكامل، ولكن ليست هناك حاجة لتنزيل إطار العمل بأكمله، حيث تم تجميعها في التنزيل المستقل.

  1. نزِّل ملفات مكتبة بيانات العميل في Google. (ابحث في هذه الصفحة عن "Google Data APIs").
  2. فك ضغط الملفات التي تم تنزيلها. يجب إنشاء أربعة أدلة فرعية:
    • demos — نماذج من التطبيقات
    • documentation — وثائق لملفات مكتبة العميل
    • library: الملفات المصدر الفعلية لمكتبة العميل
    • tests — ملفات اختبار الوحدة للاختبار التلقائي.
  3. أضف موقع مجلد library إلى مسار PHP (راجع القسم التالي)

جارٍ التحقّق للتأكّد من أنه يمكنك الوصول إلى ملفات مكتبة العميل.

الخطوة الأخيرة هي التأكد من أنه يمكنك الرجوع إلى ملفات مكتبة عميل PHP وتضمينها من الدليل الذي تبني مشروعك. يمكن تحقيق ذلك من خلال ضبط المتغيّر include_path في ملف إعداد PHP (php.ini). يحتوي المتغيّر include_path على عدد من المواقع الجغرافية التي يبحث فيها PHP عند إصدار عبارة require أو include تسحب الفئات أو المكتبات أو الملفات الخارجية إلى النص البرمجي الحالي، على غرار عبارة import في JavaScript. يجب إلحاق موقع ملفات مكتبة العميل بما تم تعيينه في include_path. ويمكن تنفيذ ذلك بطريقتين (يتم شرح كل منهما بالتفصيل أدناه):

  • يمكنك ضبط توجيه include_path نهائيًا في ملف الإعداد php.ini من سطر الأوامر، علمًا بأنّه يتطلّب إذن الوصول إلى واجهة النظام والكتابة.
  • ضبط متغيّر المسار include_path على مستوى "لكل دليل"، ويتطلب ذلك توفُّر خادم ويب Apache وإمكانية إنشاء ملفات .htaccess.
  • استخدم الدالة set_include_path() لتعيين مسار التضمين في النصوص البرمجية ديناميكيًا، ويمكن تعيينه ديناميكيًا في كل ملف من ملفات .php.

إذا كان لديك إذن دخول إلى ملف php.ini والكتابة به (أو إذا كنت تكتب رمزًا على جهازك المحلي)، يُرجى اتّباع التعليمات الواردة في الملحق أ. إذا كنت تستخدم خادم الويب Apache وكانت لديك القدرة على إنشاء ملفات بتنسيق .htaccess، فيمكنك تعيين المتغير include_path على مستوى "لكل دليل"، مما يعني أن جميع الملفات في الدليل الذي تعمل فيه تكون قادرة تلقائيًا على الرجوع إلى دليل مكتبة العميل.

يمكنك تحديد خيارات تهيئة PHP كما هو موضح في المقتطف أدناه:

# This works for PHP5 in both Apache versions 1 and 2
<IfModule mod_php5.c>
  php_value include_path        ".:/usr/local/lib/php:/path/to/ZendGdata/library"
</IfModule>

ملاحظة: راجع دليل PHP لمعرفة المزيد عن تغيير إعدادات التهيئة.

إذا لم يكن لديك حق الدخول إلى الخادم وتعذّر عليك تعديل ملفات htaccess .أو إنشائها، فيمكنك دائمًا استخدام الدالة set_include_path. لاحظ أنه قد تكون لديك بعض القيم المعيّنة لـ include_path، لذا قد يكون من الأفضل اتّباع النموذج أدناه لإلحاق القيم الجديدة بدلاً من استبدال المسار بالكامل:

$clientLibraryPath = '/path/to/ZendGdata/library';
$oldPath = set_include_path(get_include_path() . PATH_SEPARATOR . $clientLibraryPath);

ملاحظة: يُرجى الرجوع إلى الصفحات اليدوية بتنسيق PHP للحصول على مزيد من التفاصيل حول الدالة set_include_path.

تشغيل مدقق تثبيت PHP

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

لقطة شاشة لمدقق فحص تثبيت php

إذا ظهرت لك أخطاء (كما هو موضّح في لقطة الشاشة أدناه)، احرص على اتّباع التوجيهات. قد تكون تفتقد إلى إضافات أو ربما لم يتم تعيين مسارك بشكل صحيح. تذكر أنك قد تحتاج إلى إعادة تشغيل الخادم لكي تصبح التغييرات سارية المفعول. وينطبق هذا فقط إذا كنت تجري تعديلاً فعليًا لملف php.ini. توضح لقطة الشاشة أدناه أنه تم ضبط include_path على /path/to/nowhere:

لقطة شاشة لمدقق فحص تثبيت php

ملاحظة: يُرجى ملاحظة أن "أداة فحص تثبيت PHP" تتحقق مما يلي: (1) هي إضافات PHP المطلوبة، و(2) تشير إلى include_path إلى "مكتبة عميل PHP"، و(3) يمكن إجراء اتصالات طبقة المقابس الآمنة، وأخيرًا، يمكن إجراء اتصال بـ YouTube Data API. وإذا تعذّر اختبار محدّد، لن يتم تنفيذ الاختبارات المتبقية.

الآن بعد أن تم تثبيت مكتبة العميل، حان الوقت لتجربة تشغيل النماذج.

تشغيل النماذج

يتوفّر في جذر الدليل Zend/Gdata مجلد يضم عروضًا توضيحية، وهو نماذج لمساعدتك في البدء. بعض هذه النماذج مصممة ليتم تشغيلها من سطر الأوامر مثل demos/Zend/Gdata/Blogger.php وdemos/Zend/Gdata/Spreadsheet-ClientLogin.php، ويمكنك تنفيذها باستخدام php /path/to/example. ويمكن تشغيل العينات المتبقية من كل من سطر الأوامر ومتصفح الويب. إذا كنت تريد عرضها في أحد المتصفحات، فيجب وضعها في أي دليل تستخدمه لعرض صفحات الويب. من المفترض أن تقدم لك هذه العينات فكرة أساسية حول كيفية كتابة وتشغيل تطبيق بيانات Google، ولكن عندما تكون مستعدًا للاطلاع على المزيد من المعلومات، هناك موارد أخرى للمبرمج الفضولي.

ملاحظة: إذا كنت مهتمًا بمشاهدة العروض التوضيحية المستندة إلى الويب على الإنترنت، يرجى زيارة googlecodesamples.com والبحث عن تطبيقات PHP.

مكان معرفة المزيد

أفضل مكان للبحث عن معلومات حول الفئات التي هي جزء من مكتبة العميل هي الدليل المرجعي لواجهة برمجة التطبيقات على موقع Zend Framework. تأكد من تحديد حزمة Zend_Gdata من القائمة المنسدلة.

في هذه المرحلة، يجب أن تكون مستعدًا لبدء الترميز. هيا، اكتب بعض التطبيقات الرائعة. نتطلّع إلى رؤية نتائجك.

يمكنك العثور على أدلة مطوري لغة PHP للخدمات التالية:

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

إذا كنت بحاجة إلى مساعدة لتحديد المشاكل وحلّها في طلبات البيانات من واجهة برمجة التطبيقات، يمكنك الاطّلاع على المقالات المتوفّرة حول تصحيح أخطاء طلبات البيانات من واجهة برمجة التطبيقات باستخدام أدوات التقاط حركة بيانات الشبكة واستخدام الخوادم الوكيلة مع Google Data APIs. كما تتوفر أيضًا بعض المقالات الخارجية حول تثبيت XAMPP على نظام التشغيل Linux وتثبيت XAMPP على نظام التشغيل Windows. بالإضافة إلى جميع هذه المقالات، تأكد من الاطلاع على المشاركات حول مكتبة برامج PHP على مدونة نصائح واجهة برمجة التطبيقات لبيانات Google.

الملحق أ: تعديل مسار PHP في ملف إعداد php.ini

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

ملاحظة: إذا وجدت أنك تستخدم ملف php من سطر الأوامر، قد تحتاج إلى تعديل متغيّر مسار إضافي. تأكد من مراجعة الملحق ب: استخدام PHP من سطر الأوامر.

بعد العثور على الملف php.ini، اتبع الخطوات التالية لإلحاقه بالمسار.

  1. افتح الملف php.ini في محرِّر النصوص المفضَّل لديك.
  2. حدِّد موقع السطر الذي يشير إلى مسار PHP، ويجب أن يبدأ بـ include_path.
  3. ألحق المسار الذي خزنته إطار عمل Zend بقائمة المواقع الموجودة من قبل، مع انتظار المسار الجديد بفاصل مخصص لنظام التشغيل (: على الأنظمة التي تشبه Unix، ; على Windows). أما المسار الصحيح على الأنظمة التي تشبه نظام التشغيل Unix فسيبدو كما يلي: 
    /path1:/path2:/usr/local/lib/php/library
    في نظام التشغيل Windows، سيظهر بالشكل التالي: 
    \path1;\path2;\php\library
  4. احفظ الملف وأغلقه.

ملاحظة: في نظام التشغيل Mac OS X، لا يسمح الباحث بالوصول إلى الملفات الموجودة في مواقع النظام مثل الدليل /etc. ولذلك، قد يكون من الأسهل تعديلها باستخدام محرِّر سطر أوامر، مثل vi أو pico. لإجراء ذلك، استخدِم أمرًا مثل: pico /path/to/php.ini.

الملحق ب: استخدام PHP من سطر الأوامر

بدءًا من الإصدار 5 من PHP، تتوفر أداة سطر أوامر في PHP والتي يشار إليها بـ CLI لـ "مترجم خط الأوامر". يسمح استخدام هذه الأداة بتشغيل النصوص البرمجية php من سطر الأوامر. قد يكون هذا مفيدًا إذا كنت تستخدم لغة PHP محليًا على جهازك وتبحث عن طرق لاختبار بعض النصوص البرمجية بسرعة. سيتطلب هذا بالطبع الوصول إلى الخادم التابع لك على الخادم. تجدر الإشارة إلى أمر واحد مهم وهو أنّ PHP تستخدم عادةً ملفَين (php.ini) منفصلَين، أحدهما يتضمّن خيارات ضبط PHP التي تعمل على الخادم، والآخر للتهيئات التي تستخدمها PHP عند تشغيلها من سطر الأوامر. إذا كنت مهتمًا بتشغيل التطبيقات التجريبية لسطر الأوامر من مكتبة العميل، عليك تعديل ملف سطر الأوامر php.ini أيضًا.

للعثور عليه، اكتب الأوامر التالية على أنظمة تشبه نظام التشغيل Unix (Mac OS X وLinux وغيرها):

php -i | grep php.ini

من المفترض أن يؤدي هذا الأمر إلى عرض المعلومات التالية في الوحدة الطرفية:

Configuration File (php.ini) Path => /etc/php5/cli
Loaded Configuration File => /etc/php5/cli/php.ini

ملاحظة: بالطبع قد تختلف مواقع المسار الفعلية (/etc/php...) على نظامك.

الملحق (ج): نصائح وحلول

يحتوي هذا القسم على ملخص موجز لبعض المشكلات التي اكتشفها مطورو البرامج عند التعامل مع PHP والحلول المناسبة.

مشكلة في امتداد dom-xml في XAMPP

تستخدم مكتبة عميل PHP فئات DOMDocument لتحويل طلبات XML واستجاباته إلى كائنات PHP. يمكن أن تتسبب الإضافة dom-xml في حدوث مشاكل في معالجة XML وقد تؤدي إلى إحالات ناجحة غير صحيحة. وقد اكتشف بعض مطوّري البرامج أنه عند استخدام XAMPP، يتم تجاوز دالة إنشاء DOMDocument مع استدعاء دالة قديم، كما هو موضح على موقع PHP. لحل هذه المشكلة، تأكد من عدم استبدال معالجة XML في ملف php.ini. تأكَّد من إزالة المراجع إلى php_domxml.dll من ملف الإعداد.

تنتهي مهلة الطلبات عند استخدام مكتبة العميل

إذا كنت تستخدم مكتبة العميل لتنفيذ طلبات كبيرة نسبيًا، مثل تحميل الفيديوهات إلى YouTube Data API، قد تحتاج إلى تغيير المعلَمة timeout في صفك على Zend_Http_Client. ويمكن إجراء ذلك بسهولة من خلال تمرير معلَمة $config أثناء إنشاء مثيل، والذي يضبط قيمة timeout على قيمة أخرى غير القيمة التلقائية التي تبلغ 10 ثوانٍ:

// assuming your Zend_Http_Client already exists as $httpClient
// and that you want to change the timeout from the 10 second default to 30 seconds

$config = array('timeout' => 30);
$httpClient->setConfig($config);

لا يسمح بعض المستضيفين بإجراء اتصالات https من الخوادم التابعة لهم

لقد بلغنا أنّ بعض المستضيف لا يسمح لك بإجراء اتصالات https من الخوادم التلقائية. إذا تلقيت رسالة خطأ مشابهة لما هو موضح أدناه، فقد تحتاج إلى إجراء اتصالات https من خلال خادم وكيل آمن:

Unable to Connect to sslv2://www.google.com:443. Error #110: Connection timed out

يجب أن يكون لدى المستضيف معلومات عن العنوان الفعلي للخادم الوكيل لاستخدامه. يوضح المقتطف أدناه كيفية استخدام تهيئة خادم وكيل مخصصة مع مكتبة عميل PHP:

// Load the proxy adapter class in addition to the other required classes
Zend_Loader::loadClass('Zend_Http_Client_Adapter_Proxy');

// Configure the proxy connection with your hostname and portnumber
$config = array(
    'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
    'proxy_host' => 'your.proxy.server.net',
    'proxy_port' => 3128
);

// A simple https request would be an attempt to authenticate via ClientLogin
$proxiedHttpClient = new Zend_Http_Client('http://www.google.com:443', $config);

$username = 'foo@example.com';
$password = 'barbaz';

// The service name would depend on what API you are interacting with, here
// we are using the Google DocumentsList Data API
$service = Zend_Gdata_Docs::AUTH_SERVICE_NAME;

// Try to perform the ClientLogin authentication using our proxy client.
// If there is an error, we exit since it doesn't make sense to go on.
try {

  // Note that we are creating another Zend_Http_Client
  // by passing our proxied client into the constructor.

  $httpClient = Zend_Gdata_ClientLogin::getHttpClient(
      $username, $password, $service, $proxiedHttpClient);

} catch (Zend_Gdata_App_HttpException $httpException) {

  // You may want to handle this differently in your application
  exit("An error occurred trying to connect to the proxy server\n" .
      $httpException->getMessage() . "\n");

}

سِجل النُسخ السابقة

1 تشرين الأول (أكتوبر) 2008

تم التحديث بواسطة يوخن هارتمان. يحتوي هذا التحديث على التغييرات التالية:

  • جعل تهيئة PHP لخوادم الويب أكثر وضوحًا من خلال نقل الأقسام التي تشير إلى PHP لسطر الأوامر في ملحق.
  • تمت إضافة ملاحظة حول ملفات إعداد php.ini المتعددة.
  • تمت إضافة أقسام حول كيفية ضبط include_path ديناميكيًا.
  • تمت إضافة قسم على النص البرمجي للتحقق من التثبيت.
  • تمت إضافة رابط إلى نماذج على الإنترنت.
  • تمت إضافة روابط لـ XAMPP وMAMP.
  • تمت إضافة الملحق "تلميحات وحلول".