PHP-CS-Fixer لـ PHP: دليل شامل مع أمثلة عملية

1. ما هو PHP-CS-Fixer ولماذا تحتاجه؟

PHP-CS-Fixer (PHP Coding Standards Fixer) هو أداة قوية لتنسيق كود PHP تلقائيًا وفقًا لمعايير البرمجة المحددة. يقوم بتحليل الكود المصدري، واكتشاف مخالفات التنسيق (المسافات البادئة، الفراغات، فواصل الأسطر، ترتيب الاستيرادات، استخدام الصيغ المختصرة، وغيرها) وتصحيحها تلقائيًا. هذه الأداة لا غنى عنها في مشاريع PHP الحديثة، خاصة عند العمل ضمن فريق.

لماذا تحتاجها؟ أولاً، لتوحيد أسلوب الكود في الفريق. عندما يعمل عدة مطورين على مشروع واحد، قد يكون لكل منهم عاداته في التنسيق. PHP-CS-Fixer يحل هذه المشكلة بتوحيد الكود بأكمله وفق معيار واحد. ثانيًا، يوفر الوقت في مراجعة الكود (code review): بدلاً من مناقشة المسافات والفراغات، يمكن للمطورين التركيز على المنطق والهندسة. ثالثًا، التنسيق التلقائي يمنع ظهور تغييرات "ضوضائية" في الالتزامات (commits)، حيث أن تعديل سطر واحد قد يؤدي إلى تغيير تنسيق الملف بأكمله.

يدعم PHP-CS-Fixer أكثر من 100 قاعدة مدمجة، كما يسمح بإنشاء قواعد مخصصة. يمكن دمج الأداة بسهولة في خطوط CI/CD، وأنظمة التحكم بالإصدارات (عبر pre-commit hooks)، وبيئات التطوير المتكاملة (IDE). وهو متوافق مع PSR-1 وPSR-2 وPSR-12 وSymfony وDoctrine وغيرها من معايير البرمجة الشائعة.

2. التثبيت

يتم تثبيت PHP-CS-Fixer عبر Composer - مدير الحزم الخاص بـ PHP. يُنصح بتثبيته بشكل عام (global) أو كاعتماد تطويري (dev-dependency) في المشروع.

# التثبيت بشكل عام (موصى به للاستخدام في أي مشروع)
composer global require friendsofphp/php-cs-fixer

# التثبيت كاعتماد تطويري في مشروع معين
composer require --dev friendsofphp/php-cs-fixer

# التحقق من التثبيت
php-cs-fixer --version

بعد التثبيت العام، تأكد من إضافة المسار ~/.composer/vendor/bin (أو %USERPROFILE%\AppData\Roaming\Composer\vendor\bin في ويندوز) إلى متغير البيئة PATH.

3. البداية السريعة - مثال عملي بسيط

أنشئ ملفًا باسم example.php يحتوي على كود "غير منسق":

<?php
$name = "John";
$age=25;
function greet($name){
echo "Hello, ".$name;
}
greet($name);

الآن قم بتنسيقه باستخدام PHP-CS-Fixer:

php-cs-fixer fix example.php --rules=@PSR12

بعد التنفيذ، سيصبح الملف كالتالي:

<?php

$name = 'John';
$age = 25;

function greet($name): void
{
    echo 'Hello, '.$name;
}

greet($name);

كما ترى، أضاف PHP-CS-Fixer مسافات حول عامل الإسناد، واستبدل علامات الاقتباس المزدوجة بالمفردة (عند عدم وجود تداخل متغيرات)، وأضاف نوع الإرجاع : void، ونسق الأقواس المتعرجة، وأضاف أسطرًا فارغة لتحسين قابلية القراءة.

4. الدوال/الكلاسات الأساسية

4.1. PhpCsFixer\Config::create()

التوقيع: public static Config::create(): Config

الوظيفة: إنشاء نسخة جديدة من الإعدادات لتخصيص قواعد التنسيق.

<?php
use PhpCsFixer\Config;

$config = Config::create()
    ->setRules([
        '@PSR12' => true,
        'array_syntax' => ['syntax' => 'short'],
    ])
    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__ . '/src')
    );

4.2. PhpCsFixer\Finder::create()

التوقيع: public static Finder::create(): Finder

الوظيفة: إنشاء كائن للبحث عن ملفات PHP التي تحتاج إلى تنسيق.

<?php
use PhpCsFixer\Finder;

$f