منسّق PHP

ما الذي تفعله هذه الأداة

يحوّل منسّق PHP شيفرة PHP الفوضوية أو المصغّرة أو غير المتسقة في مسافاتها البادئة إلى شيفرة نظيفة تتبع معيار المجتمع. ويتعامل مع الصياغات الحديثة، بما فيها الخصائص المحددة النوع وخصائص readonly، وترقية معاملات المُنشئ (constructor promotion)، والدوال السهمية، وenums، وتعابير match، والسمات (attributes).

يشغّل Prettier مع إضافة PHP الرسمية، وهي التركيبة نفسها التي تستخدمها فرق كثيرة تعمل بـ Laravel وSymfony في محرراتها وخطافات pre-commit، لذا تطابق النتيجة ما ستنتجه أدواتك.

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

1. الصق شيفرة PHP، أو افتح ملف .php. الوسم الافتتاحي <?php اختياري في المقتطفات القصيرة.
2. تظهر الشيفرة المنسّقة على اليسار أثناء الكتابة.
3. اضبط الخيارات:
   • المسافة البادئة: 4 مسافات هي معيار PSR؛ وتتوفر أيضًا مسافتان وعلامات Tab.
   • عرض السطر: تُلَفّ الأسطر الأطول من هذا العرض حيث تسمح الصياغة.
   • الأقواس المعقوصة: ضع أقواس الأصناف والدوال في السطر التالي (PER / PSR-12) أو في السطر نفسه.
   • إصدار PHP: أقدم إصدار يجب أن تعمل عليه الشيفرة.
   • علامات اقتباس مفردة وفواصل لاحقة للقوائم متعددة الأسطر.
4. انسخ النتيجة أو نزّلها.

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

مثال

المثال وحدة تحكم بأسلوب Laravel حُشر فيها كل شيء معًا: عبارة use مجمّعة، ومصفوفة خصائص، وترقية معاملات المُنشئ، واستدعاء تحقق، وعبارة if مكتوبة في سطر واحد، وarray_map مع دالة سهمية. بعد التنسيق ينتقل قوس كل دالة إلى سطر مستقل، وتحصل العوامل و=> على مسافات، ويُوسَّع جسم if، وتُلَفّ استدعاءات response()->json() الطويلة بعنصر مصفوفة واحد في كل سطر مع فواصل لاحقة.

ما الذي لا تغيّره

لا يغيّر المنسّق إلا التخطيط. فهو لا يعيد تسمية المتغيرات، ولا يعيد ترتيب عبارات use، ولا يحوّل array() إلى الصياغة القصيرة، ولا يصلح المنطق. وتُحفظ التعليقات، بما فيها كتل PHPDoc، ويُعاد ضبط مسافاتها البادئة مع الشيفرة المحيطة بها.

نصائح

• استخدم عرض السطر وإصدار PHP نفسيهما المضبوطين في إعدادات Prettier أو PHP-CS-Fixer في مشروعك لتجنّب التغييرات غير الضرورية في الفروقات (diffs).
• تنسيق مقتطف منسوخ من سجل أو من تتبّع مكدس (stack trace) يجعله أسهل قراءة بكثير.
• إذا كنت ستشارك شيفرة في issue، فنسّقها أولًا كي يركّز المراجعون على ما تفعله.