phpDocumentor

phpDocumentor

ما هو PHPDocumentor؟

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

بالإضافة إلى براعته في توثيق واجهة برمجة التطبيقات (API)، يذهب phpDocumentor إلى أبعد من ذلك من خلال توفير ميزات إضافية. وهي مجهزة بالقدرة على إنشاء مخططات UML، مما يجعلها أداة متعددة الاستخدامات لتصور بنية التعليمات البرمجية. بالإضافة إلى ذلك، يقدم phpDocumentor محلل لغة ترميزية كامل المواصفات، يدعم كلاً من تركيب RestructuredText وMarkdown. تتيح لك هذه المرونة توثيق مشروعك باستخدام لغة الترميز التي تناسب تفضيلاتك.

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

مستوحى من سابقيه، phpDocumentor 1 وJavaDoc، يواصل phpDocumentor الابتكار والبقاء على اطلاع بأحدث التقنيات وميزات لغة PHP. ويضمن هذا الالتزام حصول المطورين على أفضل تجربة توثيق ممكنة، بما يتماشى مع ممارسات التطوير الحديثة.

في هذا الدليل، سنستكشف الميزات المتنوعة لـ phpDocumentor، بدءًا من وظيفته الأساسية في إنشاء وثائق واجهة برمجة التطبيقات (API) وحتى إمكاناته المتقدمة في تحليل اللغات الترميزية. سواء كنت مطورًا مبتدئًا أو ذو خبرة، فإن phpDocumentor هو حليفك في إنشاء مشاريع PHP موثقة جيدًا وقابلة للصيانة ومفهومة.

phpDocumentor v3 (مستقر)

v3 هو أحدث إصدار مستقر.

التوثيق

لمزيد من المعلومات التفصيلية، يمكنك مراجعة وثائقنا عبر الإنترنت على https://docs.phpdoc.org/.

سمات

يدعم phpDocumentor ما يلي:

• متوافق مع PHP 7.0+ ، ويتم توفير الدعم الكامل لمساحات الأسماء وعمليات الإغلاق والمزيد.

• Docblock over Types ، يمكن أن تكون docblocks أكثر وضوحًا فيما يتعلق بالأنواع التي لا تدعمها جميع التنسيقات بواسطة php الأصلي.

• يعرض أي علامة ، بعض العلامات تضيف وظائف إضافية إلى phpDocumentor (مثل @link).

• استخدام منخفض للذاكرة ، ويبلغ الحد الأقصى لاستخدام الذاكرة للمشروعات الصغيرة أقل من 20 ميجابايت، والمشروعات المتوسطة 40 ميجابايت، والأطر الكبيرة 100 ميجابايت.

• التحليل التزايدي ، إذا احتفظت بملف الهيكل من التشغيل السابق، فستحصل على تعزيز إضافي للأداء يصل إلى 80% بالإضافة إلى زيادة سرعة المعالجة المذكورة أعلاه.

• إنشاء قالب سهل ، إذا كنت تريد إنشاء علامة تجارية، فما عليك سوى استدعاء مهمة واحدة وتحرير 3 ملفات.

• عملية من خطوتين ، يقوم phpDocumentor أولاً بإنشاء ذاكرة تخزين مؤقت مع بنية التطبيق الخاص بك قبل إنشاء الإخراج. إذا كنت ترغب في ذلك، يمكنك استخدام ذلك لتشغيل الأدوات أو المنسقات الخاصة بك!

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

تثبيت

يتطلب PhpDocumentor PHP 8.1 أو أعلى للتشغيل. ومع ذلك، يمكن تحليل كود إصدارات PHP السابقة.

جميع القوالب المتوفرة مع phpDocumentor تدعم الرسوم البيانية للفئات بناءً على قاعدة كود القراءة. سيتطلب ذلك تثبيت التطبيق [PlantUml] على الجهاز الذي يقوم بتشغيل phpDocumentor. يعد عرض الرسوم البيانية للفئة باستخدام [PlantUml] أمرًا اختياريًا، ويمكن تجاهل التحذيرات المتعلقة بفقدان [PlantUml]. ومع ذلك، ستحتوي وثائقك على بعض الروابط الميتة في هذه الحالة. سيتم إنشاء مخطط الفصل باستخدام الخيار --setting=graphs.enabled=true .

هناك أربع طرق لتثبيت phpDocumentor:

1. استخدام phive (مستحسن)

2. استخدام PHAR (التثبيت اليدوي)

3. عبر دوكر

4. عبر الملحن

باستخدام فايف

$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42

لمزيد من المعلومات حول phive قم بإلقاء نظرة على موقعهم على الانترنت. الآن بعد تثبيت phpDocumentor، يمكن تنفيذه على النحو التالي:

php tools/phpDocumentor

باستخدام فار

1. قم بتنزيل ملف phar من https://github.com/phpDocumentor/phpDocumentor/releases

2. يمكنك تنفيذ phar مثل هذا: php phpDocumentor.phar

عبر دوكر

1. $ docker pull phpdoc/phpdoc

2. $ docker run --rm -v $(pwd):/data phpdoc/phpdoc

عبر الملحن (غير مستحسن)

لكن انتظر؟ ماذا عن الملحن؟

اه لقد اكتشفت سرنا توجد حزمة مؤلف phpdocumentor يمكنك استخدامها لتثبيت phpDocumentor.

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

لذلك، بسبب ما سبق: نحن لا نؤيد ولا ندعم بشكل فعال تثبيت phpDocumentor باستخدام Composer.

كيفية استخدام PHPDocumentor؟

أسهل طريقة لتشغيل phpDocumentor هي تشغيل الأمر التالي:

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

سيقوم هذا الأمر بتحليل الكود المصدري المقدم باستخدام الوسيطة -d وإخراجه إلى المجلد المشار إليه بواسطة الوسيطة -t .

يدعم phpDocumentor مجموعة كاملة من الخيارات لتكوين مخرجات وثائقك. يمكنك تنفيذ الأمر التالي، أو مراجعة موقعنا على الويب، للحصول على قائمة أكثر تفصيلاً بخيارات سطر الأوامر المتاحة.

$ phpdoc run -h

ملف (ملفات) التكوين

يدعم phpDocumentor أيضًا استخدام ملفات التكوين (المسماة phpdoc.xml أو phpdoc.dist.xml افتراضيًا). يرجى الرجوع إلى الوثائق لمعرفة التنسيق والخيارات المدعومة.

يبني ليلا

لا يحتوي PhpDocumentor على إصدارات ليلية. ومع ذلك، خلال كل خط أنابيب يتم بناء قطعة أثرية فار. إذا كنت تريد اختبار الإصدار المتقدم من phpDocumentor، فقم بإلقاء نظرة على قسم الإجراءات في هذا المستودع. يحتوي كل سير عمل ناجح لضمان الجودة على قسم مصنوعات في الأسفل مع قطعة أثرية مبنية.

اتصال

إن التواصل معنا أمر سهل، ويمكن القيام به من خلال:

• تويتر: @phpDocumentor

• موقع الكتروني: https://www.phpdoc.org

• جيثب: https://www.github.com/phpDocumentor/phpDocumentor

• البريد الإلكتروني: [email protected]