لاراول مقدمات و آشنایی با لاراول بررسی پیش‌نیازهای نصب لاراول ۱۳ (PHP 8.2+, Composer, Node.js)

بررسی پیش‌نیازهای نصب لاراول ۱۳

فهرست مطالب

مقدمه و جایگاه لاراول ۱۳ در اکوسیستم PHP

لاراول ۱۳ (Laravel 13) جدیدترین نسخه از محبوب‌ترین فریم‌ورک PHP جهان است که در اوایل سال ۲۰۲۶ منتشر شده است. این نسخه بر پایه Symfony 7.x بنا شده و نیازمندی‌های سخت‌گیرانه‌تری نسبت به نسخه‌های پیشین خود دارد. درک صحیح و فراهم‌سازی دقیق پیش‌نیازها، نه‌تنها از بروز خطاهای مرموز در زمان اجرا جلوگیری می‌کند، بلکه تضمین‌کننده بهره‌مندی از تمام قابلیت‌های جدید مانند کامپایلر JIT بهبودیافته، Type Safety گسترده و عملکرد بهینه‌شده است.

این مستند با رویکردی مهندسی‌شده و گام‌به‌گام طراحی شده تا شما را برای نصب موفق لاراول ۱۳ روی هر پلتفرمی آماده کند. فرقی نمی‌کند روی ویندوز، لینوکس یا macOS کار می‌کنید؛ با پیروی از این راهنما، محیط توسعه شما کاملاً منطبق با استانداردهای رسمی لاراول خواهد بود.

نکته حیاتی: لاراول ۱۳ حداقل نیازمند PHP 8.2 است، اما تیم توسعه به‌شدت توصیه می‌کند از PHP 8.3 یا 8.4 استفاده کنید. PHP 8.2 در تاریخ ۸ دسامبر ۲۰۲۵ به پایان عمر امنیتی (End of Security Support) رسیده و استفاده از آن در محیط Production یک ریسک امنیتی محسوب می‌شود. این مستند بر اساس PHP 8.3 تنظیم شده است.

پیش‌نیازهای سیستمی و سروری

الزامات سخت‌افزاری پیشنهادی

برای یک تجربه توسعه روان و بدون مکث، حداقل‌های سخت‌افزاری زیر پیشنهاد می‌شود:

مؤلفه حداقل (Development) پیشنهادی (Production)
حافظه رم (RAM) ۲ گیگابایت ۴ گیگابایت یا بیشتر
فضای دیسک ۵ گیگابایت فضای خالی ۲۰ گیگابایت SSD
پردازنده (CPU) ۲ هسته‌ای، ۲.۰ گیگاهرتز ۴ هسته‌ای، ۲.۵ گیگاهرتز

لاراول ۱۳ از OpCache و JIT به‌طور پیش‌فرض برای افزایش سرعت استفاده می‌کند. بنابراین، حافظه رم بیشتر مستقیماً بر روی سرعت اجرای کد شما تأثیرگذار است.

سیستم‌عامل‌های پشتیبانی‌شده

لاراول ذاتاً چندسکویی (Cross-Platform) است. با این حال، تجربه توسعه در محیط‌های شبه‌یونیکس (Unix-like) روان‌تر است:

توصیه اکید برای کاربران ویندوز: نصب مستقیم PHP و Composer در ویندوز (Native) اگرچه ممکن است، اما منجر به مشکلات عدیده‌ای در مسیردهی (Path) و Performance فایل‌سیستم می‌شود. قویاً توصیه می‌شود از WSL2 با توزیع Ubuntu استفاده کنید. سرعت اجرای لاراول در WSL2 تا ۵ برابر سریع‌تر از حالت Native ویندوز است.

نیازمندی‌های حیاتی نرم‌افزاری

این بخش به بررسی سه رکن اصلی پیش‌نیازهای نرم‌افزاری می‌پردازد.

PHP 8.2 و بالاتر - قلب تپنده

لاراول ۱۳ بر پایه PHP 8.2 طراحی شده اما از قابلیت‌های PHP 8.3 و 8.4 نیز بهره می‌برد. ویژگی‌های زیر در هسته لاراول ۱۳ استفاده شده‌اند که بدون آن‌ها فریم‌ورک حتی composer install را هم با خطا مواجه می‌کند:

برای بررسی نسخه PHP نصب‌شده در ترمینال دستور زیر را اجرا کنید:

php -v

خروجی باید مشابه زیر باشد:

PHP 8.3.10 (cli) (built: Aug 15 2024 12:00:00) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.3.10, Copyright (c) Zend Technologies
    with Zend OPcache v8.3.10, Copyright (c), by Zend Technologies

Composer - مدیر وابستگی‌ها

Composer استاندارد طلایی مدیریت پکیج‌ها در PHP است. لاراول ۱۳ برای نصب هسته خود و هزاران پکیج اکوسیستمش به Composer نسخه ۲.۷.۰ یا جدیدتر نیاز دارد. نسخه‌های قدیمی Composer 1.x دیگر پشتیبانی نمی‌شوند و هنگام اجرا با خطای Deprecation Notice مواجه خواهید شد.

برای بررسی نسخه Composer:

composer --version

خروجی نمونه:

Composer version 2.7.9 2024-09-15 10:00:00

Node.js و NPM - موتور فرانت‌اند

اگرچه لاراول یک فریم‌ورک Backend است، اما ابزارهای Frontend آن (به‌ویژه Vite به عنوان Bundler پیش‌فرض) به یک محیط Node.js نیاز دارند. لاراول ۱۳ با Vite 6.x یکپارچه شده است که برای اجرا به Node.js 18.x یا 20.x LTS نیازمند است.

یکپارچگی با Bun: از لاراول ۱۲ به بعد، پشتیبانی رسمی از Bun (روتایم سریع جاوااسکریپت) اضافه شده است. اگرچه در لاراول ۱۳ استفاده از Bun اختیاری است، اما برای پروژه‌های جدید به دلیل سرعت بالای نصب وابستگی‌ها، می‌توانید از Bun به جای Node/NPM استفاده کنید. در این مستند فرض بر استفاده از Node.js استاندارد است.

پایگاه داده‌های سازگار و درایورها

لاراول ۱۳ با چهار خانواده اصلی پایگاه داده سازگار است. اطمینان حاصل کنید که درایور PDO مربوط به پایگاه داده مورد نظر شما در PHP فعال باشد.

پایگاه داده حداقل نسخه پشتیبانی‌شده افزونه PHP مورد نیاز
MySQL ۸.۰+ / MariaDB 10.11+ pdo_mysql
PostgreSQL ۱۳.۰+ pdo_pgsql
SQLite ۳.۳۵.۰+ pdo_sqlite
SQL Server ۲۰۱۹+ pdo_sqlsrv

لاراول ۱۳ دیگر از نسخه‌های MySQL 5.7 پشتیبانی نمی‌کند (دلیل: حذف پشتیبانی از UTF8MB3 و الزام به UTF8MB4).

افزونه‌های اجباری PHP

لیست زیر حداقل افزونه‌هایی است که باید در فایل php.ini فعال باشند. بدون این افزونه‌ها، لاراول ۱۳ اصلاً اجرا نخواهد شد.

افزونه (Extension) علت نیاز در لاراول ۱۳
ctype اعتبارسنجی نوع کاراکترها (مورد استفاده در Validator)
curl ارسال درخواست‌های HTTP (HTTP Client, Http Facade)
dom پردازش HTML و XML (ابزارهای Blade و Notifications)
fileinfo تشخیص MIME Type فایل‌های آپلودی (File Storage)
filter فیلتر و اعتبارسنجی ایمیل و URL
hash رمزنگاری و هش کردن پسوردها (Bcrypt/Argon2)
intl بین‌المللی‌سازی و فرمت اعداد و تاریخ‌ها (برای Number::spell)
mbstring پشتیبانی از کاراکترهای UTF-8 چندبایتی (در تمام String Helperها)
openssl رمزنگاری امن (Encrypter و Session Cookies)
pcre عبارات باقاعده (Regex) - هسته مسیریاب (Router)
pdo لایه انتزاع دیتابیس
session مدیریت نشست کاربران
tokenizer تحلیلگر واژگانی کد PHP (مورد نیاز برای php artisan optimize)
xml خواندن فایل‌های XML (Config و Translation Loader)
zip بازکردن بسته‌های Composer و آپلود فایل‌های Zip
افزونه مزیت
redis برای Cache و Queue Driver فوق سریع (جایگزین file/database)
imagick یا gd پردازش و تغییر اندازه تصاویر (Intervention Image)
pcntl اجرای پردازش‌های موازی و Queue Workerها در Horizon (فقط CLI/Linux)
swoole / openswoole اجرای لاراول به صورت Asynchronous (با Laravel Octane)

پیکربندی پیشرفته و تنظیمات توصیه‌شده

تنظیمات php.ini برای محیط توسعه

برای توسعه، فایل php.ini (معمولاً در مسیر /etc/php/8.3/cli/php.ini یا مشابه) باید با مقادیر زیر تنظیم شود تا خطاها به‌وضوح نمایش داده شوند و از محدودیت‌های حافظه جلوگیری نشود:

; نمایش تمام خطاها (بسیار مهم در توسعه)
display_errors = On
display_startup_errors = On
error_reporting = E_ALL

; افزایش محدودیت حافظه برای اجرای Composer
memory_limit = 512M

; افزایش زمان اجرا برای عملیات زمان‌بر (Queue Worker یا Migrations سنگین)
max_execution_time = 300

; تنظیمات آپلود فایل
upload_max_filesize = 64M
post_max_size = 64M

; فعال‌سازی OpCache برای شبیه‌سازی محیط Production (اختیاری در توسعه)
opcache.enable = 1
opcache.enable_cli = 0

; تنظیم منطقه زمانی پیش‌فرض
date.timezone = Asia/Tehran

تنظیمات php.ini برای محیط تولید

در محیط Production، فلسفه برعکس است: هیچ خطایی نباید به کاربر نمایش داده شود، اما باید Log شود.

; مخفی‌سازی خطاها از دید کاربر
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /var/log/php_errors.log

; حافظه کافی برای فرآیندهای پس‌زمینه
memory_limit = 256M

; محدود کردن زمان اجرا برای جلوگیری از مصرف بی‌رویه منابع
max_execution_time = 30

; فعال‌سازی اجباری OpCache برای افزایش سرعت (تا ۵۰٪ بهبود عملکرد)
opcache.enable = 1
opcache.memory_consumption = 256
opcache.interned_strings_buffer = 16
opcache.max_accelerated_files = 10000
opcache.revalidate_freq = 2
opcache.fast_shutdown = 1

نصب و راه‌اندازی گام‌به‌گام ابزارها

نصب PHP 8.3 بر روی اوبونتو ۲۴.۰۴

اوبونتو معمولاً نسخه‌های قدیمی PHP را در ریپازیتوری پیش‌فرض دارد. برای دریافت آخرین نسخه PHP 8.3 باید از PPA معروف ondrej/php استفاده کنید.

# 1. به‌روزرسانی لیست پکیج‌ها و نصب ابزارهای کمکی
sudo apt update && sudo apt upgrade -y
sudo apt install software-properties-common apt-transport-https -y

# 2. افزودن PPA Ondrej (نگهدارنده رسمی PHP برای اوبونتو)
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# 3. نصب PHP 8.3 به همراه افزونه‌های اجباری لاراول
sudo apt install php8.3 php8.3-cli php8.3-common php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip php8.3-pgsql php8.3-sqlite3 php8.3-mysql php8.3-intl php8.3-bcmath php8.3-gd php8.3-redis -y

# 4. بررسی نصب
php -v

نصب PHP 8.3 بر روی ویندوز

راه‌حل بهینه: همانطور که قبلاً اشاره شد، استفاده از WSL2 توصیه می‌شود. با این حال اگر اصرار بر نصب Native دارید:

  1. به وبسایت windows.php.net/download مراجعه کنید.
  2. نسخه Non-Thread Safe (NTS) مخصوص x64 را با پسوند Zip دانلود کنید.
  3. فایل Zip را در مسیر C:\php8.3 استخراج کنید.
  4. فایل php.ini-development را به php.ini تغییر نام دهید و آن را با Notepad++ یا VSCode باز کنید.
  5. خطوط مربوط به افزونه‌های extension=curl و extension=mbstring و extension=openssl و extension=pdo_mysql را از کامنت خارج کنید (علامت ; اول خط را حذف کنید).
  6. مسیر C:\php8.3 را به Environment Variables ویندوز (بخش Path) اضافه کنید.
  7. یک Command Prompt جدید باز کنید و دستور php -v را اجرا کنید.

نصب PHP 8.3 بر روی macOS

استفاده از Homebrew ساده‌ترین روش است:

# 1. به‌روزرسانی Homebrew
brew update

# 2. نصب PHP 8.3
brew install php@8.3

# 3. لینک کردن PHP به عنوان نسخه پیش‌فرض سیستم
brew link --overwrite --force php@8.3

# 4. ریستارت ترمینال و بررسی نسخه
php -v

نصب Composer به‌صورت سراسری

Composer یک فایل phar. است که باید در مسیر سیستم قرار گیرد.

لینوکس / macOS / WSL2:

# 1. دانلود نصب‌کننده و تأیید امضای دیجیتال (برای امنیت)
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === file_get_contents('https://composer.github.io/installer.sig')) { echo 'Installer verified'.PHP_EOL; } else { echo 'Installer corrupt'.PHP_EOL; unlink('composer-setup.php'); exit(1); }"

# 2. اجرای نصب‌کننده
php composer-setup.php

# 3. حذف فایل نصب‌کننده
php -r "unlink('composer-setup.php');"

# 4. انتقال فایل اجرایی به پوشه سیستم
sudo mv composer.phar /usr/local/bin/composer

ویندوز: فایل Composer-Setup.exe را از وبسایت رسمی دانلود و اجرا کنید. در حین نصب، مسیر php.exe را به آن معرفی کنید.

نصب Node.js و NPM

  1. به Nodejs.org مراجعه کنید.
  2. نسخه LTS (مثلاً ۲۰.x Iron) را دانلود کنید. از دانلود نسخه Current (مثلاً ۲۲.x) برای پروژه‌های لاراول خودداری کنید مگر اینکه مطمئن باشید وابستگی‌های Vite با آن سازگار است.
  3. نصب‌کننده را اجرا کنید (در ویندوز گزینه نصب ابزارهای Build Tools را نیز تیک بزنید).
  4. پس از نصب، دستورات زیر را تست کنید:
node -v
npm -v

بررسی صحت نصب و عیب‌یابی اولیه

اسکریپت تشخیص سلامت (Health Check Script)

قبل از اجرای دستور composer create-project laravel/laravel، یک فایل PHP با نام check.php در جایی خارج از پروژه ایجاد کنید و محتوای زیر را در آن قرار دهید. این اسکریپت به شما می‌گوید کدام بخش از سیستم مشکل دارد.

<?php

declare(strict_types=1);

// لیست افزونه‌های اجباری بر اساس مستندات رسمی لاراول ۱۳
$requiredExtensions = [
    'ctype', 'curl', 'dom', 'fileinfo', 'filter', 'hash', 'intl',
    'mbstring', 'openssl', 'pcre', 'pdo', 'session', 'tokenizer', 'xml', 'zip'
];

$recommendedExtensions = ['redis', 'gd', 'imagick'];

echo "=========================================\n";
echo "🔍 بررسی پیش‌نیازهای لاراول ۱۳\n";
echo "=========================================\n\n";

// ۱. بررسی نسخه PHP
echo "📌 نسخه PHP: " . phpversion() . "\n";
if (version_compare(phpversion(), '8.2.0', '<')) {
    echo "❌ خطای بحرانی: لاراول ۱۳ به PHP 8.2 یا جدیدتر نیاز دارد. شما نسخه " . phpversion() . " را دارید.\n";
    exit(1);
} else {
    echo "✅ نسخه PHP قابل قبول است.\n";
}

echo "\n📦 بررسی افزونه‌های اجباری:\n";
foreach ($requiredExtensions as $ext) {
    if (extension_loaded($ext)) {
        echo "   ✅ افزونه '{$ext}' نصب و فعال است.\n";
    } else {
        echo "   ❌ افزونه '{$ext}' پیدا نشد! لطفاً در php.ini فعالش کنید.\n";
    }
}

echo "\n📦 بررسی افزونه‌های اختیاری (توصیه‌شده):\n";
foreach ($recommendedExtensions as $ext) {
    if (extension_loaded($ext)) {
        echo "   ⭐ افزونه '{$ext}' نصب است. (عالی)\n";
    } else {
        echo "   ⚠️ افزونه '{$ext}' نصب نیست. (برای بهینه‌سازی Cache و Image توصیه می‌شود)\n";
    }
}

echo "\n⚙️ بررسی تنظیمات php.ini:\n";
$memoryLimit = ini_get('memory_limit');
echo "   • memory_limit = {$memoryLimit} " . (return_bytes($memoryLimit) >= 128 * 1024 * 1024 ? '✅' : '⚠️ (حداقل ۱۲۸ مگابایت توصیه می‌شود)') . "\n";

$maxExec = ini_get('max_execution_time');
echo "   • max_execution_time = {$maxExec} " . ($maxExec >= 30 ? '✅' : '⚠️') . "\n";

echo "\n🛠️ بررسی ابزارهای خط فرمان:\n";
exec('composer --version 2>&1', $composerOutput, $composerCode);
if ($composerCode === 0) {
    echo "   ✅ Composer نصب است: " . $composerOutput[0] . "\n";
} else {
    echo "   ❌ Composer در PATH سیستم پیدا نشد.\n";
}

exec('node --version 2>&1', $nodeOutput, $nodeCode);
if ($nodeCode === 0) {
    echo "   ✅ Node.js نصب است: " . $nodeOutput[0] . "\n";
} else {
    echo "   ⚠️ Node.js نصب نیست یا در PATH نیست. (برای Vite نیاز دارید)\n";
}

echo "\n=========================================\n";
echo "✅ بررسی کامل شد. در صورت عدم وجود خطا، آماده نصب لاراول هستید.\n";
echo "=========================================\n";

/**
 * تبدیل مقدار حافظه string به byte
 */
function return_bytes(string $val): int {
    $val = trim($val);
    $last = strtolower($val[strlen($val)-1]);
    $val = (int)substr($val, 0, -1);
    switch($last) {
        case 'g': $val *= 1024;
        case 'm': $val *= 1024;
        case 'k': $val *= 1024;
    }
    return $val;
}

این اسکریپت را با دستور php check.php اجرا کنید.

رفع خطاهای رایج

خطای رایج ۱: Could not open input file: artisan

علت: شما در مسیر ریشه پروژه لاراول نیستید.

راه‌حل: دستور cd /path/to/your/laravel-project را اجرا کنید و سپس دوباره تلاش کنید.

خطای رایج ۲: The stream or file ".../storage/logs/laravel.log" could not be opened: Permission denied

علت: وب سرور (مثلاً www-data) دسترسی نوشتن روی پوشه storage ندارد.

راه‌حل (لینوکس/macOS): chmod -R 775 storage bootstrap/cache و chown -R $USER:www-data storage

خطای رایج ۳: Composer detected issues... require php ^8.2 -> your php version (8.1.x) does not satisfy...

راه‌حل: نسخه PHP خط فرمان (CLI) شما با نسخه وب سرور متفاوت است. از دستور which php برای پیدا کردن مسیر و اصلاح Alias استفاده کنید. معمولاً با نصب صحیح از PPA این مشکل حل می‌شود.

Laravel Herd

اگر روی ویندوز یا macOS هستید و نمی‌خواهید درگیر پیکربندی دستی PHP و Nginx شوید، Laravel Herd یک انتخاب فوق‌العاده است. Herd تمام پیش‌نیازها (PHP 8.3, Composer, Nginx, DNSMasq) را در یک بسته جادویی ارائه می‌دهد و با لاراول ۱۳ کاملاً سازگار است.

Laravel Valet

برای کاربران macOS که به دنبال مینیمالیسم (Minimalism) هستند، Valet یک محیط توسعه فوق‌العاده سبک مبتنی بر Nginx فراهم می‌کند. پس از نصب PHP 8.3 با Homebrew، کافی است دستور composer global require laravel/valet را اجرا کنید.

Docker و Laravel Sail

اگر در تیم کار می‌کنید و نیاز به محیط‌های توسعه یکسان دارید، Laravel Sail گزینه بی‌نظیری است. Sail یک compose.yaml آماده برای Docker دارد که شامل PHP 8.3، MySQL 8.0، Redis و Mailpit می‌شود. نصب لاراول ۱۳ با Sail:

curl -s "https://laravel.build/example-app?php=83" | bash

تفاوت‌های کلیدی پیش‌نیازها نسبت به لاراول ۱۱ و ۱۲

توجه به تغییرات عمده: اگر از لاراول ۱۰ یا ۱۱ به ۱۳ مهاجرت می‌کنید، توجه به نکات زیر حیاتی است:

  1. پایان پشتیبانی از PHP 8.1 و 8.2 (امنیتی): در حالی که لاراول ۱۲ روی PHP 8.2 اجرا می‌شد، لاراول ۱۳ به‌طور فعال شما را به سمت PHP 8.3 سوق می‌دهد. پکیج‌های Symfony 7.x دیگر کامپایلر PHP 8.2 را بهینه نمی‌کنند.
  2. حذف درایور PDO SQL Server 2017: تنها SQL Server 2019 و جدیدتر پشتیبانی می‌شوند.
  3. Node.js 16 منسوخ شده است: Vite 6 دیگر از Node 16 پشتیبانی نمی‌کند. اگر در پروژه قدیمی npm run dev خطا می‌گیرد، Node را به ۱۸ یا ۲۰ ارتقا دهید.
  4. افزونه intl اجباری‌تر از همیشه: قابلیت جدید Number::spell() برای تبدیل عدد به حروف (فارسی و انگلیسی) مستقیماً به این افزونه وابسته است. در نسخه ۱۱ و ۱۲ این افزونه «توصیه‌شده» بود، اما در ۱۳ «اجباری» است.

جمع‌بندی و قدم بعدی

اکنون شما یک محیط توسعه کامل، استاندارد و آماده برای لاراول ۱۳ در اختیار دارید. با اطمینان از صحت نسخه‌های PHP، Composer و Node.js، مسیر شما برای اجرای دستور جادویی زیر هموار است:

composer create-project laravel/laravel my-fresh-app "13.*"

قدم بعدی شما پیکربندی فایل env. و اتصال به پایگاه داده خواهد بود. این مستند به‌گونه‌ای تنظیم شده که تقریباً نیاز به جستجوی خارجی برای فهم مطلب را به صفر می‌رساند.

منابع تکمیلی و لینک‌های مفید

محتوای فوق به‌گونه‌ای تنظیم شده که تقریباً نیاز به جستجوی خارجی برای فهم مطلب را به صفر می‌رساند؛ اما منابع زیر صرفاً برای تعمیق بیشتر و دیدن کاربردهای عملی پیشنهاد شده‌اند: