توثيق المشاريع البرمجية باستخدام phpDocumentor

كثير مايتحدث المبرمجين عن أهمية كتابة التعليقات للمشاريع البرمجية وانها احد اهم عوامل نجاح المشاريع حيث تسهل عمل المبرمجين لفهم ملفات المشروع والبدء بالتطوير بشكل اسرع وانها تعمل على تذكير المبرمج مايعني هذا الجزء من الكود جميعنا عملنا على مشاريع كبيره او صغيره واحتجنا بعد عدة اشهر لتطوير جزء مهم منها ونقف عند ماكتبنا منفجعين وحائرين مايعني هذا ومامعنى هذاك ماذا كنت اقصد بهذا وماهية عمل هذا الكود وبعد عدة ساعات من المحاولات نبدأ التطوير الفعلي لهذا قام المبرمجين بتطوير وتوحيد نظام التعليقات للملفات البرمجية واعتماد قوانين وتنضيمات لها للحد من هذه الظاهرة وتكون نقطة بداية عند فتح اي ملف برمجي هي قراءة التعليق مباشرة لفهم عمل الأكواد المكتوبة في PHP يطلق عليها اسم DocBlock وتم شرحها وتفصيلها في مقالة سابقة يمكنك الإستفادة منها

https://3alam.pro/articles/php/comment-in-php-with-docblocks/

الآن اصبحت مبرمج جيد يهتم بكتابة التعليقات وتنظيمها ووضع امثله لها ماذا بعد ذلك هل يمكن الإستفادة من هذه التعليقات بشكل افضل ومطور عن الوضع التقليدي التي تتطلب مني فتح الملف ثم قراءة التعليق لفهمه ماذا لو اخبرتك انه تم تطوير أداة تقوم بعمل فحص وقرائة ملفاتك البرمجية ثم تحويل هذه التعليقات DocBlock الى مستندات توثيق منسقة ومرتبة وحتى رسم Class diagrams وبكثير من الأمكانيات بأوامر بسيطة ويمكنك مشاركة هذه المستندات مع من ترغب من المطورين في فريقك ليكون الوصول الى المعلومه اسهل وارتب من السابق دون الحاجه لفتح اي ملف لقراءة تعليقاته وفهم عمله هذه الأداة اسمها phpDocumentor واختصارها phpDoc 

من يستخدم phpDocumentor:

يستخدم phpDocumentor العديد من الشركات والمطورين حول العالم والكثير من المشاريع الناجحة تستخدمه لتوثيق مشاريعها وتقديمها للمطورين لفهم المشاريع والبدء بالتطوير سوف نذكر البعض هنا

     

  

متطلبات التثبيت:

قبل البدء بتثبيت phpDocumentor تأكد ان جهازك يحتوي على كل من

• PHP 5.5 أو أعلى

• intl extension for PHP

• Graphviz اختياري في حال كنت ترغب بتوليد Class diagrams فقط

• تاكد من اعدادات الوقت والتاريخ داخل ملف php.ini بالذات تاكد من timezone انه مفعل وتم تحديد منطقة زمنية صحيحه مثال UTC

طريقة التثبيت:

لتثبيت phpDocumentor لدينا عدة طرق تستطيع استخدام مايناسبك من هذه الطرق سوف يتم تثبيت phpDocumentor اما بشكل عام Global بجاهزك او بشكل محلي Local على مستوى ملفات مشروعك ويفضل دائما تثبيت phpDocumentor بشكل عام Global حيث هذه الطريقة تسمح لك الوصول وتنفيذ جميع اوامر هذه الأداة بشكل عام ومن اي مكان باستخدام Terminal على عكس التثبيت المحلي Local لن تسطيع تنفيذ اوامر الأداة الا عن طريق الملجد الذي تم تثبيت الأداة بداخله

يمكنك استخدام احد هذه الطرق لتثبيت phpDocumentor

بواسطة PEAR (تثبيت عام)

اذا كنت تستخدم PEAR يمكنك تثبيت phpDocumentor بواسطة تنفيذ هذا الأمر في Terminal

pear channel-discover pear.phpdoc.org

ثم تنفيذ هذا الأمر 

pear install phpdoc/phpDocumentor

بعدها تستطيع تنفيذ اوامر phpDocumentor بشكل عام Global باستخدام الأمر phpdoc عن طريق Terminal

بواسطة Composer (تثبيت محلي)

اذا كنت تستخدم Composer في مشاريعك يمكنك تثبيت phpDocumentor بطريقتين

اول طريقة: عن طريق تحديث ملف composer.json تحت قسم require-dev قم باضافة المكتبة كالتالي

{
    "require-dev": {
        "phpdocumentor/phpdocumentor": "2.*"
    }
}

وبعدها قم بتحديث ملفات مشروعك باستخدام composer update او ثبت المكتبات باستخدام composer install

ثاني طريقة: باستخدام اوامر Composer نقوم بتثبيت phpDocumentor بواسطة تنفيذ هذا الأمر في Terminal

composer require --dev phpdocumentor/phpdocumentor

بعد تثبيت المكتبة بنجاح نستطيع الوصول وتنفيذ اوامر المكتبة عن طريق ملف phpdoc.php الموجود داخل مجلد /vendor/bin داخل مجلدات مشروعك باستخدام هذا الأمر

مستخدمي MAC OSX و Linux

php vendor/bin/phpdoc

مستخدمي Windows

php vendor\bin\phpdoc.bat

ملاحظة: phpDocumentor تستهلك وتعتمد على العديد من المكتبات اذا لم تكن هذه الطريقة مناسبة لك قم بتجربة احد الطرق الأخرى

بواسطة PHAR (تثبيت محلي)

كل ماعليك هو تحميل ملف PHAR الخاص بالمكتبة phpDocumentor فقط ووضعه داخل مجلد مشروعك 

بواسطة HomeBrew (تثبيت عام)

لمستخدمي انظمة الماك تستطيع تثبيت واستخدام phpDocumentor باستخدام homeBrew بكل بساطة قم بتنفيذ هذا الامر 

brew install phpdocumentor

وهي من اسهل الطرق والتي استخدمها و تسمح لك بالوصول لجميع اوامر phpDocumentor بشكل عام Global عن طريق الأمر phpdoc في Terminal

طريقة الإستخدام:

للتاكد من تثبيت phpDocumentor بجهازك وعرض جميع الأوامر والمساعدة قم بتنفيذ هذا الأمر في Terminal 

phpdoc run -h

اذا تم تثبيت phpDocumentor بنجاح سوف يعرض لك التالي 

هذا الأمر يعرض لك طرق الإستخدام وجميع انواع الخيارات الممكن استخدامها بواسطة الأمر phpdoc

ابسط صورة لكيفية استخدام المكتبة هي نتوجه لمجلد المشروع المراد توثيقه وبعدها نقوم بتنفيذ هذا الأمر في Terminal

phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

لاحظ في هذا الأمر استخدمنا الأمر phpdoc run وبعدها تسطيع استخدام اي من الخيارات او الإعدادات التي توفرها الأداة وهنا استخدمنا d- لتحديد المجلد المراد توثيقه وثم استخدمنا t- لتحديد الملجد المراد حفظ ناتج التوثيق على شكل ملفات HTML 

لنفرض ان مشاريعك البرمجية داخل مجلد htdocs انا استخدم MAMP PRO ويمكن الوصول لهذا المجلد بواسطة الأمر cd عن طريق Terminal 

cd /Applications/MAMP/htdocs

بعدها ننفذ الأمر phpdoc وتزويده بالمجلد المراد توثيقه والمجلد المراد حفظ ناتج التوثيق بواسطة هذا الأمر 

phpdoc -d ./3alampro -t ./3alampro/docs/api

ستقوم الأداة بتحليل جميع ملفات مشروعك والبحث عن مايمكن توثيقه عن طريق قراءة DocBlock المستخدمه داخل ملفاتك ثم عمل موقع HTML داخل الملجد المحدد لتخزين ناتج التوثيق هذه العمليه سرعتها تعتمد على كبر ملفات مشروعك وممكن ان تاخذ وقت فلا تخاف وارتح واشرب كوبا من القهوة ☕️ وانتظر باستمتاع لانتهاء عملية التوثيق سيكون الناتج كالتالي بعد تصفحك لمجلد التوثيق من متصفحك

وتدعم اداة phpDocumentor العديد من الخيارات والأمكانيات حيث تسطيع انشاء ملف phpdoc.xml داخل مجلد مشروع وتضع جميع الإعدادات المراد تنفيذها عند تنفيذ الأمر phpdoc داخل مجلد المشروع وهي جدا بسيطة ممكن الإستفادة من هذه الصفحة phpdoc configuration

في الختام:

يمكن الاستفادة من التعليقات المكتوبة والمنسقة وتحويلها الى مستندات توثيق باستخدام phpDocumentor ويوجد ادوات منافسة لها مثل الأداة Sami ولك حرية استخدام مايناسبك وفريقك وجدت هذه الأدوات للتسهيل من حياة المبرمج وتسهيل فهم الملفات البرمجية وتبسيطها ليستمع بقية يومه بالتطوير بدون صداع ومحاولة فهم خربشات بقية المبرمجين او حتى خربشاته القديمه

كلمات دليلية: