إطار Laravel
التثبيت وإعداد البيئة
المتطلبات الأساسية
قبل تثبيت لارافيل، تأكد من أن نظامك يلبي المتطلبات التالية:
متطلبات النظام
- PHP 8.1 أو أعلى مع الامتدادات التالية:
- BCMath PHP Extension
- Ctype PHP Extension
- cURL PHP Extension
- DOM PHP Extension
- Fileinfo PHP Extension
- JSON PHP Extension
- Mbstring PHP Extension
- OpenSSL PHP Extension
- PCRE PHP Extension
- PDO PHP Extension
- Tokenizer PHP Extension
- XML PHP Extension
- Composer - مدير اعتماديات PHP
- Node.js و NPM - لتجميع أصول الواجهة الأمامية
- قاعدة البيانات - MySQL 5.7+، PostgreSQL 10+، SQLite 3.8.8+، أو SQL Server 2017+
فحص سريع: قم بتشغيل
php -v للتحقق من إصدار PHP الخاص بك، وcomposer -V للتحقق من تثبيت Composer. إذا رأيت أرقام الإصدارات، فأنت جاهز للبدء!
تثبيت Composer
Composer هو مدير اعتماديات لـ PHP، مشابه لـ npm في Node.js. يستخدم لارافيل Composer لإدارة اعتمادياته وحزمه.
تثبيت Composer على منصات مختلفة
Windows
1. قم بتنزيل Composer-Setup.exe من https://getcomposer.org/download/
2. قم بتشغيل المثبت
3. اتبع معالج التثبيت
4. تحقق من التثبيت بفتح موجه الأوامر وكتابة:
composer --version
macOS
# باستخدام Homebrew
brew install composer
# أو التنزيل والتثبيت يدوياً
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
php -r "unlink('composer-setup.php');"
# التحقق من التثبيت
composer --version
Linux
# تنزيل وتثبيت Composer عالمياً
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer
# التحقق من التثبيت
composer --version
إنشاء مشروع لارافيل جديد
هناك طريقتان رئيسيتان لإنشاء مشروع لارافيل جديد: استخدام مثبت لارافيل أو استخدام Composer مباشرة.
الطريقة 1: استخدام مثبت لارافيل (موصى به)
مثبت لارافيل هو أداة مريحة تنشئ مشاريع لارافيل جديدة بسرعة.
# تثبيت مثبت لارافيل عالمياً عبر Composer
composer global require laravel/installer
# تأكد من أن مجلد bin العالمي لـ Composer موجود في PATH الخاص بك
# أضف هذا إلى ~/.bashrc أو ~/.zshrc:
export PATH="$HOME/.composer/vendor/bin:$PATH"
# إنشاء مشروع لارافيل جديد
laravel new blog
# ينشئ هذا مجلداً جديداً يسمى "blog" مع تثبيت لارافيل
الطريقة 2: استخدام Composer Create-Project
بدلاً من ذلك، يمكنك إنشاء مشروع لارافيل جديد مباشرة باستخدام Composer:
# إنشاء مشروع لارافيل جديد باسم "blog"
composer create-project laravel/laravel blog
# الانتقال إلى مجلد المشروع
cd blog
# بدء خادم التطوير
php artisan serve
ماذا حدث للتو؟ قام Composer بتنزيل لارافيل وجميع اعتمادياته في مجلد جديد يسمى "blog". قد تستغرق هذه العملية بضع دقائق حسب سرعة اتصالك بالإنترنت.
تحديد إصدار لارافيل
لتثبيت إصدار محدد من لارافيل:
# تثبيت Laravel 10.x (أحدث إصدار 10.x)
composer create-project laravel/laravel:^10.0 blog
# تثبيت Laravel 9.x
composer create-project laravel/laravel:^9.0 blog
# تثبيت أحدث إصدار (افتراضي)
composer create-project laravel/laravel blog
نظرة عامة على بنية المشروع
بعد إنشاء مشروع لارافيل الخاص بك، سترى البنية التالية:
blog/
├── app/ # كود التطبيق الأساسي
├── bootstrap/ # ملفات بدء تشغيل الإطار
├── config/ # جميع ملفات التكوين
├── database/ # الترحيلات والمصانع والبذور
├── public/ # الأصول العامة و index.php
├── resources/ # العروض و CSS/JS الخام وملفات اللغة
├── routes/ # جميع تعريفات المسارات
├── storage/ # السجلات والذاكرة المؤقتة والعروض المجمعة
├── tests/ # الاختبارات الآلية
├── vendor/ # اعتماديات Composer (لا تعدل)
├── .env # تكوين البيئة
├── artisan # Artisan CLI
├── composer.json # اعتماديات PHP
├── package.json # اعتماديات Node
└── vite.config.js # تكوين Vite
تكوين البيئة (.env)
يحتوي ملف .env على تكوين خاص بالبيئة. هذا هو المكان الذي تقوم فيه بتكوين اتصالات قاعدة البيانات وإعدادات البريد والمعلومات الحساسة الأخرى.
فهم متغيرات .env
# إعدادات التطبيق
APP_NAME=Laravel # اسم تطبيقك
APP_ENV=local # البيئة: local, production, staging
APP_KEY=base64:xxx... # مفتاح التشفير (تم إنشاؤه تلقائياً)
APP_DEBUG=true # وضع التصحيح (false في الإنتاج!)
APP_URL=http://localhost # عنوان URL للتطبيق
# اتصال قاعدة البيانات
DB_CONNECTION=mysql # برنامج تشغيل قاعدة البيانات
DB_HOST=127.0.0.1 # مضيف قاعدة البيانات
DB_PORT=3306 # منفذ قاعدة البيانات
DB_DATABASE=laravel # اسم قاعدة البيانات
DB_USERNAME=root # اسم مستخدم قاعدة البيانات
DB_PASSWORD= # كلمة مرور قاعدة البيانات
# الذاكرة المؤقتة والجلسة
CACHE_DRIVER=file # برنامج تشغيل الذاكرة المؤقتة: file, redis, memcached
SESSION_DRIVER=file # برنامج تشغيل الجلسة
QUEUE_CONNECTION=sync # برنامج تشغيل الطابور
# إعدادات البريد
MAIL_MAILER=smtp # برنامج تشغيل البريد
MAIL_HOST=mailhog # خادم البريد
MAIL_PORT=1025 # منفذ البريد
MAIL_USERNAME=null # اسم مستخدم البريد
MAIL_PASSWORD=null # كلمة مرور البريد
MAIL_ENCRYPTION=null # تشفير البريد
توليد مفتاح التطبيق
يُستخدم APP_KEY للتشفير. يقوم لارافيل بإنشاء هذا تلقائياً عند إنشاء مشروع جديد، ولكن إذا كان مفقوداً:
# توليد مفتاح تطبيق جديد
php artisan key:generate
# يقوم هذا بتحديث APP_KEY في ملف .env الخاص بك
تحذير الإنتاج: لا تقم أبداً بإرسال ملف
.env إلى نظام التحكم في الإصدارات! يحتوي على بيانات اعتماد حساسة. استخدم دائماً .env.example كنموذج للآخرين لإنشاء ملف .env الخاص بهم.
تكوين قاعدة البيانات
يدعم لارافيل أنظمة قواعد بيانات متعددة. دعنا نقوم بتكوين MySQL كمثال:
إنشاء قاعدة بيانات
# باستخدام سطر أوامر MySQL
mysql -u root -p
# إنشاء قاعدة البيانات
CREATE DATABASE laravel_blog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# إنشاء مستخدم قاعدة البيانات (اختياري)
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON laravel_blog.* TO 'laravel_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
تحديث .env ببيانات اعتماد قاعدة البيانات
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_blog
DB_USERNAME=laravel_user
DB_PASSWORD=secure_password
اختبار اتصال قاعدة البيانات
# تشغيل الترحيلات لاختبار الاتصال
php artisan migrate
# إذا نجح، سترى جداول الترحيل التي تم إنشاؤها
# إذا فشل، تحقق من بيانات اعتماد قاعدة البيانات في .env
استخدام SQLite للتطوير
SQLite مثالي للتطوير المحلي السريع دون إعداد خادم قاعدة بيانات كامل:
# إنشاء ملف قاعدة بيانات SQLite
touch database/database.sqlite
# تحديث .env
DB_CONNECTION=sqlite
# إزالة أو التعليق على متغيرات DB_ الأخرى
# تشغيل الترحيلات
php artisan migrate
بدء خادم التطوير
يتضمن لارافيل خادم تطوير مدمج مدعوم بـ PHP:
# بدء الخادم على المنفذ الافتراضي (8000)
php artisan serve
# الإخراج:
# Starting Laravel development server: http://127.0.0.1:8000
# بدء الخادم على منفذ مخصص
php artisan serve --port=8080
# بدء الخادم على مضيف مخصص
php artisan serve --host=0.0.0.0 --port=8000
# هذا يجعل تطبيقك متاحاً من الأجهزة الأخرى على شبكتك
الوصول إلى تطبيقك: افتح متصفحك وقم بزيارة
http://localhost:8000. يجب أن ترى صفحة ترحيب لارافيل. إذا رأيت هذا، تهانينا! تم تثبيت لارافيل وتشغيله بنجاح.
البديل: استخدام خادم PHP المدمج
# الانتقال إلى مجلد public
cd public
# بدء خادم PHP المدمج
php -S localhost:8000
# ملاحظة: هذه الطريقة لا تدعم أوامر artisan
تثبيت اعتماديات الواجهة الأمامية
يستخدم لارافيل Vite لتجميع الأصول. ستحتاج إلى تثبيت Node.js و NPM.
تثبيت Node.js
# التحقق من تثبيت Node.js
node -v
npm -v
# إذا لم يكن مثبتاً، قم بالتنزيل من https://nodejs.org/
# أو استخدم مدير حزم:
# macOS (باستخدام Homebrew)
brew install node
# Ubuntu/Debian
sudo apt install nodejs npm
# Windows: قم بتنزيل المثبت من nodejs.org
تثبيت اعتماديات NPM
# تثبيت جميع الاعتماديات من package.json
npm install
# ينشئ هذا مجلد node_modules ويثبت:
# - Vite (أداة البناء)
# - Laravel Vite Plugin
# - PostCSS
# - Axios (عميل HTTP)
تشغيل خادم تطوير Vite
# بدء خادم تطوير Vite (استبدال الوحدة الساخن)
npm run dev
# في محطة منفصلة، ابدأ خادم لارافيل
php artisan serve
# ستجمع أصولك الآن تلقائياً عند إجراء التغييرات
بناء الأصول للإنتاج
# بناء وتصغير الأصول للإنتاج
npm run build
# ينشئ هذا أصولاً محسّنة ومُصدّرة في public/build/
Laravel Sail (بيئة تطوير Docker)
يوفر Laravel Sail بيئة تطوير قائمة على Docker مع MySQL و Redis و Mailhog وغيرها مُكوَّنة مسبقاً.
إنشاء مشروع مع Sail
# إنشاء مشروع لارافيل جديد مع Sail
curl -s "https://laravel.build/blog" | bash
# اختر الخدمات عند المطالبة (MySQL، Redis، إلخ)
# الانتقال إلى المشروع
cd blog
# بدء حاويات Sail
./vendor/bin/sail up
# الوصول إلى التطبيق على http://localhost
استخدام أوامر Sail
# بدء Sail في الخلفية
./vendor/bin/sail up -d
# إيقاف Sail
./vendor/bin/sail down
# تشغيل أوامر artisan عبر Sail
./vendor/bin/sail artisan migrate
# تشغيل أوامر composer
./vendor/bin/sail composer require package/name
# الوصول إلى غلاف MySQL
./vendor/bin/sail mysql
# إنشاء اسم مستعار shell للراحة (أضف إلى ~/.bashrc أو ~/.zshrc)
alias sail='./vendor/bin/sail'
# يمكنك الآن استخدام: sail up, sail artisan, إلخ
متى تستخدم Sail؟ استخدم Laravel Sail إذا كنت تريد بيئة تطوير متسقة عبر فريقك، أو إذا كنت تفضل حاويات Docker على تثبيت PHP و MySQL وغيرها مباشرة على جهازك.
مهام التكوين الشائعة
إعداد أذونات الملفات
# على Linux/macOS، يحتاج لارافيل إلى أذونات الكتابة إلى storage و cache
chmod -R 775 storage bootstrap/cache
# إذا واجهت مشاكل في الأذونات، قد تحتاج إلى:
sudo chown -R $USER:www-data storage bootstrap/cache
إنشاء رابط رمزي لـ Storage
لجعل الملفات المرفوعة متاحة من الويب:
# إنشاء رابط رمزي من public/storage إلى storage/app/public
php artisan storage:link
# يتيح لك هذا الوصول إلى الملفات مثل:
# http://yourapp.com/storage/user-avatars/avatar.jpg
تكوين المنطقة الزمنية
# في config/app.php
'timezone' => 'UTC', // غيّر إلى منطقتك الزمنية
# المناطق الزمنية الشائعة:
# 'America/New_York'
# 'Europe/London'
# 'Asia/Tokyo'
# 'Australia/Sydney'
# أو اضبط في .env (Laravel 11+)
APP_TIMEZONE=America/New_York
تكوين اللغة
# في config/app.php
'locale' => 'en', // اللغة الافتراضية
'fallback_locale' => 'en', // اللغة الاحتياطية
أدوات التطوير وإعداد IDE
بيئات التطوير الموصى بها
- PhpStorm: IDE PHP كامل الميزات مع دعم ممتاز للارافيل
- VS Code: محرر مجاني وخفيف الوزن مع امتدادات لارافيل
- Sublime Text: محرر سريع مع حزم خاصة بلارافيل
امتدادات VS Code للارافيل
# امتدادات VS Code الموصى بها:
1. Laravel Extension Pack (by Winnie Lin)
2. Laravel Blade Snippets
3. Laravel Snippets
4. PHP Intelephense
5. Laravel Artisan
6. DotENV
7. Laravel goto view
8. Laravel Extra Intellisense
مساعد Laravel IDE
قم بإنشاء ملفات مساعد IDE للحصول على إكمال تلقائي أفضل و intellisense:
# تثبيت حزمة IDE Helper (للتطوير فقط)
composer require --dev barryvdh/laravel-ide-helper
# توليد ملفات المساعد
php artisan ide-helper:generate
php artisan ide-helper:models
php artisan ide-helper:meta
# أضف إلى .gitignore
_ide_helper.php
_ide_helper_models.php
.phpstorm.meta.php
تمرين عملي 1: تثبيت جديد
أكمل هذه المهام لممارسة تثبيت لارافيل:
- أنشئ مشروع لارافيل جديد يسمى "my-blog"
- قم بتكوين اتصال قاعدة البيانات في .env
- قم بتشغيل الترحيلات لإنشاء الجداول الافتراضية
- ابدأ خادم التطوير وتحقق من أنه يعمل
- قم بتثبيت اعتماديات NPM وقم بتشغيل خادم dev
تمرين عملي 2: تكوين البيئة
قم بتعديل ملف .env الخاص بك:
- غيّر APP_NAME إلى "My Awesome Blog"
- اضبط APP_DEBUG على false مؤقتاً وقم بزيارة الموقع (ثم أعده إلى true)
- غيّر قاعدة البيانات من MySQL إلى SQLite وقم بتشغيل الترحيلات
- أنشئ رابطاً رمزياً للتخزين
تمرين عملي 3: استكشاف Artisan
قم بتشغيل أوامر artisan هذه ولاحظ النتائج:
php artisan list- انظر جميع الأوامر المتاحةphp artisan route:list- عرض جميع المسارات المسجلةphp artisan tinker- ادخل الغلاف التفاعلي، جرب:App\Models\User::count()php artisan about- عرض نظرة عامة على التطبيق
استكشاف الأخطاء الشائعة
مشكلة: "No application encryption key has been specified"
# الحل: توليد مفتاح التطبيق
php artisan key:generate
مشكلة: أخطاء اتصال قاعدة البيانات
# تحقق من بيانات اعتماد قاعدة البيانات في .env
# تحقق من تشغيل خادم قاعدة البيانات
# اختبر الاتصال يدوياً:
php artisan tinker
>>> DB::connection()->getPdo();
مشكلة: أخطاء رفض الإذن
# إصلاح أذونات التخزين
chmod -R 775 storage bootstrap/cache
sudo chown -R $USER:www-data storage bootstrap/cache
مشكلة: "Vite manifest not found"
# الحل: تشغيل خادم تطوير Vite
npm run dev
# أو بناء الأصول
npm run build
الملخص
في هذا الدرس، تعلمت كيفية:
- تثبيت Composer والتحقق من متطلبات النظام
- إنشاء مشروع لارافيل جديد باستخدام طرق متعددة
- تكوين ملف .env لإعدادات قاعدة البيانات والتطبيق
- بدء خادم تطوير لارافيل
- تثبيت وتجميع أصول الواجهة الأمامية باستخدام Vite
- إعداد Laravel Sail للتطوير القائم على Docker
- تكوين الإعدادات الشائعة مثل المنطقة الزمنية وأذونات الملفات
- استكشاف مشكلات التثبيت الشائعة
الآن بعد أن تم إعداد بيئة التطوير الخاصة بك، أنت جاهز لبدء بناء تطبيقات لارافيل! في الدرس التالي، سنتعمق في أساسيات التوجيه.