كيف تشغّل ملف PHP: سطر الأوامر وخادم php -S

لتشغيل ملف PHP، افتح طرفية في مجلده واكتب php index.php. تنفّذ PHP الملف وتطبع مخرجاته في الطرفية. ولرؤية صفحة PHP في المتصفح، ابدأ الخادم المدمج بالأمر php -S localhost:8000 وافتح http://localhost:8000.

php index.php

يمكن أن يكون أول ملف index.php سطرًا واحدًا. اضغط Run: هذا بالضبط ما يطبعه php index.php.

<?php
echo "Hello from PHP " . PHP_VERSION . "\n";
echo "2 + 3 = " . (2 + 3) . "\n";

يأتي كود PHP بعد الوسم <?php. أي شيء قبل هذا الوسم يُطبع نصًا عاديًا، وبهذه الطريقة تمزج PHP الكود مع HTML.

تشغيل ملف PHP من سطر الأوامر

واجهة سطر أوامر PHP (CLI) تنفّذ السكربت مرة واحدة ثم تخرج. تحتاج إلى تثبيت PHP، فإذا طبع php -v خطأً، فراجع تثبيت PHP أولًا.

cd ~/projects/hello
php index.php          # run the file
php -l index.php       # only check the syntax ("lint")
php index.php > out.txt   # save the output to a file

الأمر php -l مفيد قبل رفع ملف: يعرض خطأ التحليل مع رقم السطر، أو No syntax errors detected in index.php.

تمرير الوسائط عبر $argv

الكلمات التي تأتي بعد اسم الملف تصل في $argv. العنصر $argv[0] هو دائمًا اسم السكربت نفسه، و$argc هو العدد بما فيه هذا الاسم. هنا يعمل المثال دون وسائط إضافية، فلا يوجد إلا الاسم:

<?php
echo "Script: " . $argv[0] . "\n";
echo "Argument count: " . $argc . "\n";

// Run as: php index.php Ada 3
$name  = $argv[1] ?? 'world';
$times = (int) ($argv[2] ?? 1);

for ($i = 0; $i < $times; $i++) {
    echo "Hello, $name\n";
}

على جهازك، يطبع php index.php Ada 3 التحية ثلاث مرات. وتحافظ القيم الاحتياطية عبر ?? على عمل السكربت عندما يغيب وسيط. وللخيارات المسماة مثل --name=Ada، استخدم getopt:

<?php
// php index.php --name=Ada --verbose
$opts = getopt('', ['name:', 'verbose']);
echo "Hello, " . ($opts['name'] ?? 'world') . "\n";
if (isset($opts['verbose'])) {
    echo "Verbose mode\n";
}

تشغيل PHP في المتصفح باستخدام php -S

لدى PHP خادم ويب مدمج للتطوير. ابدأه في المجلد الذي يحتوي على ملفاتك:

php -S localhost:8000

[Sat Oct  3 07:21:34 2026] PHP 8.3.19 Development Server (http://localhost:8000) started

الآن يشغّل http://localhost:8000/ الملف index.php، ويشغّل http://localhost:8000/about.php الملف about.php. كل تحميل للصفحة ينفّذ الملف من جديد، مع سلسلة الاستعلام في $_GET. المثال أدناه يتصرف بالطريقة نفسها: شغّله، ثم انقر رابطًا، فيُنفَّذ السكربت مرة أخرى مع تعيين $_GET['page'].

<?php
$pages = [
    'home'    => 'Welcome to the bakery.',
    'menu'    => 'Bread, pastries and coffee.',
    'contact' => 'Call us at 555 0100.',
];
$page = $_GET['page'] ?? 'home';
$text = $pages[$page] ?? 'Page not found.';
?>
<nav>
    <a href="?page=home">Home</a> |
    <a href="?page=menu">Menu</a> |
    <a href="?page=contact">Contact</a>
</nav>
<h1><?= htmlspecialchars(ucfirst($page)) ?></h1>
<p><?= htmlspecialchars($text) ?></p>

خيارات مفيدة:

php -S localhost:8000 -t public        # serve the public/ folder as the web root
php -S 0.0.0.0:8000                    # reachable from other devices on your network
php -S localhost:8000 router.php       # send every request through router.php

يعالج الخادم المدمج طلبًا واحدًا في كل مرة، وهو مخصص للتطوير فقط. في بيئة الإنتاج تعمل PHP خلف Nginx أو Apache، عادةً عبر PHP-FPM.

معرفة طريقة تشغيل السكربت

يخبرك PHP_SAPI بواجهة الخادم (server API) التي تشغّل السكربت: cli في الطرفية، وcli-server تحت php -S، وfpm-fcgi أو apache2handler خلف خادم ويب حقيقي. السكربتات التي يجب ألا تعمل إلا من الطرفية تتحقق منه أولًا:

<?php
echo "Running under: " . PHP_SAPI . "\n";
echo "Script name: " . basename(__FILE__) . "\n";

if (PHP_SAPI === 'cli') {
    echo "Command line: plain text output, no HTML needed\n";
} else {
    echo "<p>Web request: send HTML</p>\n";
}

تشغيل سطر واحد باستخدام php -r

للتجربة السريعة لا تحتاج إلى ملف. ينفّذ php -r الكود الذي تمرره، دون الوسم <?php:

php -r 'echo date("Y-m-d"), PHP_EOL;'
php -r 'var_dump(0.1 + 0.2 == 0.3);'

في cmd على ويندوز، ضع الكود بين علامتي تنصيص مزدوجتين واستخدم علامات التنصيص المفردة داخله. ولعدة أسطر، يفتح php -a صدفة تفاعلية تُنفَّذ فيها كل تعليمة عند ضغط Enter.

جعل السكربت قابلًا للتنفيذ على macOS ولينكس

أضف سطر shebang قبل <?php واجعل الملف قابلًا للتنفيذ. سطر shebang لا يُطبع:

#!/usr/bin/env php
<?php
echo "Backup started\n";

chmod +x backup.php
./backup.php

بهذه الطريقة تعمل سكربتات PHP من cron: 0 3 * * * /usr/bin/php /home/me/backup.php.

رموز الخروج للسكربتات

يُبلغ سكربت سطر الأوامر عن النجاح أو الفشل عبر رمز الخروج، الذي تستطيع سكربتات الصدفة وcron التحقق منه. exit(0) تعني النجاح، وأي رقم آخر يعني الفشل:

<?php
$file = $argv[1] ?? '';
if (!is_file($file)) {
    fwrite(STDERR, "File not found: $file\n");
    exit(1);
}
echo "Processing $file\n";
exit(0);

خطأ شائع: تشغيل الملف أو المجلد الخطأ

تعني Could not open input file: index.php أن PHP لا تجد الملف من موقع الطرفية الحالي. تحقق من المجلد الحالي بالأمر pwd (أو cd على ويندوز)، ثم انتقل إلى المشروع بـ cd أو أعطِ المسار الكامل: php ~/projects/hello/index.php. ومع php -S، فإن الخطأ 404 لصفحة تعرف أنها موجودة يعني غالبًا أن الخادم بدأ في مجلد مختلف، فأوقفه بـ Ctrl+C وابدأه مرة أخرى في المكان الصحيح، أو مرّر المجلد عبر -t. وعندما يعمل الملف لكنه يعرض صفحة فارغة، فعّل إظهار الأخطاء لترى ما الخطأ.