دليل تفصيلي لتثبيت وإعداد Laravel
الإعداد هو "لوحة أجهزة" Laravel — فهم العلاقة بين .env وconfig/ يشبه الوصول إلى لوحة أجهزة السيارة، مما يسمح لك بتعديل معلمات المحرك في أي وقت.
1. ما ستتعلمه
- ملفات البيئة
.envوآلية تحميل الإعدادconfig/*.php - تبديل البيئة: سياسة إعداد local/staging/production
- إعداد اتصال قاعدة البيانات (MySQL و PostgreSQL)
- إعداد محركات التخزين المؤقت والجلسة
php artisan config:cacheإعداد التخزين المؤقت في بيئة الإنتاج
2. قصة حقيقية من عالم العمليات
(1) المشكلة: إعداد بيئة تطوير فوضوية
كانت Alice تستخدم MySQL أثناء تطوير ShopMetrics محلياً، لكن بعد نشره على خادم staging، لم تستطع الاتصال بقاعدة البيانات — لأنها كانت قد كتبت DB_PASSWORD بشكل ثابت في الكود، وعندما دفعته إلى Git، تم استبداله بكلمة مرور زميلها Bob المحلية. لزيادة الطين بلة، قام Charlie عن طريق الخطأ بعمل commit لـ APP_DEBUG=true لبيئة الإنتاج إلى المستودع، مما كشف تتبع مكدس الأخطاء بالكامل للمستخدمين. استغرق الثلاثة يومين لاستكشاف جميع مشاكل الإعداد وإصلاحها.
(2) حل إعداد .env
يستخدم Laravel ملفات .env لعزل متغيرات البيئة — واحد لكل من المحلي وstaging والإنتاج — ولا يكتب أبداً القيم الحساسة بشكل ثابت في الكود.
BASH
# .env (محلي — لا تقم أبداً بعمل commit لهذا الملف)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics_local
DB_USERNAME=root
DB_PASSWORD=secret
APP_DEBUG=true
(3) النتيجة
بعد أن أدارت Alice الإعداد باستخدام .env، لم تعد البيئات المحلية والإنتاج تتداخل مع بعضها، وAPP_DEBUG يتوقف تلقائياً في بيئة الإنتاج، لذلك لن يواجه Bob مشكلة استبدال كلمة المرور مرة أخرى.
3. آلية إعداد البيئة
يتكون نظام إعداد Laravel من طبقتين: ملف .env يخزن متغيرات البيئة، وملف config/*.php يقرأ وينظم هذه المتغيرات.
graph TD
A[ملف .env] -->|dotenv يحمل| B[$_ENV / $_SERVER]
B -->|config يقرأ| C[config/database.php]
C -->|helper env| D["env('DB_HOST', 'localhost')"]
D -->|fallback| E[القيمة الافتراضية إذا لم يتم تعيينها]
(1) شرح تفصيلي لملف .env
توجد ملفات .env في الدليل الجذري للمشروع وتستخدم تنسيق KEY=VALUE؛ لا تقم أبداً بإرسالها إلى Git.
| القاعدة | الوصف |
|---|---|
| التنسيق | KEY=VALUE، بدون مسافات على جانبي علامة التساوي |
| علامات الاقتباس | استخدم علامات اقتباس للقيم التي تحتوي على مسافات: APP_NAME="My App" |
| التعليقات | الأسطر التي تبدأ بـ # هي تعليقات |
| النوع | جميع القيم هي سلاسل نصية؛ يجب تحويل النوع يدوياً في الكود |
| الأولوية | متغير البيئة الفعلي > قيمة ملف .env |
(2) هيكل دليل config
config/ يُرجع مصفوفة إعداد لكل ملف PHP ويقرأ متغيرات البيئة باستخدام دالة env().
| الملف | الغرض |
|---|---|
app.php |
اسم التطبيق، المنطقة الزمنية، مفتاح التشفير، وضع التصحيح |
database.php |
اتصال قاعدة البيانات، ترحيل اسم الجدول |
cache.php |
محركات التخزين المؤقت (file/redis/database) |
session.php |
محركات الجلسة ودورة الحياة |
mail.php |
إعداد خدمة البريد الإلكتروني |
filesystems.php |
محرك تخزين الملفات |
(1) ▶ مثال:عرض قيم الإعداد الحالية
BASH
# التحقق من قيمة إعداد محددة
php artisan tinker
# في REPL الخاص بـ tinker:
config('app.name')
# => "Laravel"
config('database.default')
# => "mysql"
config('cache.default')
# => "file"
الناتج:
TEXT
# تم تنفيذ الأمر بنجاح
4. إعداد قاعدة البيانات
(1) إعداد MySQL
PHP
// config/database.php — اتصال 'mysql'
'mysql' => [
'driver' => 'mysql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
'database' => env('DB_DATABASE', 'shopmetrics'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
],
(2) إعداد PostgreSQL
PHP
// config/database.php — اتصال 'pgsql'
'pgsql' => [
'driver' => 'pgsql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '5432'),
'database' => env('DB_DATABASE', 'shopmetrics'),
'username' => env('DB_USERNAME', 'postgres'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8',
],
| البُعد | MySQL | PostgreSQL |
|---|---|---|
| المنفذ الافتراضي | 3306 | 5432 |
| دعم JSON | أصلي في 5.7+ | أصلي وأكثر قوة |
| البحث النصي الكامل | أساسي | متقدم (tsvector) |
| القابلية للتوسعة | متوسطة | عالية (PostGIS، إلخ) |
| حالات الاستخدام | التجارة الإلكترونية/المحتوى | الجغرافيا/التحليلات |
(1) ▶ مثال:إعداد اتصال MySQL لـ ShopMetrics
BASH
# .env — إعداد MySQL لـ ShopMetrics
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics
DB_USERNAME=shopmetrics_user
DB_PASSWORD=Str0ngP@ssw0rd!
# إنشاء قاعدة البيانات
mysql -u root -p -e "CREATE DATABASE shopmetrics;"
mysql -u root -p -e "CREATE USER 'shopmetrics_user'@'localhost' IDENTIFIED BY 'Str0ngP@ssw0rd!';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON shopmetrics.* TO 'shopmetrics_user'@'localhost';"
mysql -u root -p -e "FLUSH PRIVILEGES;"
# اختبار الاتصال
php artisan db:show
# Database: shopmetrics | MySQL 8.x | Tables: 0
الناتج:
TEXT
# تم تنفيذ الأمر بنجاح
5. محركات التخزين المؤقت والجلسة
(1) مقارنة محركات التخزين المؤقت
| المحرك | حالات الاستخدام | الأداء | الاستمرارية |
|---|---|---|---|
file |
التطوير/المشاريع الصغيرة | بطيء | ✅ |
database |
بدون Redis | متوسط | ✅ |
redis |
بيئة الإنتاج | سريع | ✅ |
memcached |
قراءات متزامنة عالية | سريع | ❌ |
array |
اختبار | سريع جداً | ❌ |
(2) مقارنة محركات الجلسة
| المحرك | السيناريوهات المطبقة | الوصف |
|---|---|---|
file |
التطوير | مخزن في storage/framework/sessions/ |
database |
متوسط الحجم | يتطلب إنشاء جدول "sessions" |
redis |
الإنتاج | أداء عالي، دعم TTL |
cookie |
خفيف الوزن | مخزن على العميل بعد التشفير، محدود بـ 4KB |
array |
اختبار | يختفي عند انتهاء الطلب |
(1) ▶ مثال:إعداد التخزين المؤقت والجلسات باستخدام Redis
BASH
# .env — إعداد Redis للتخزين المؤقت والجلسة
CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
# تثبيت امتداد Redis PHP
pecl install redis
# اختبار اتصال Redis
php artisan tinker
# Cache::put('test_key', 'hello', 60)
# => true
# Cache::get('test_key')
# => "hello"
الناتج:
TEXT
# تم تنفيذ الأمر بنجاح
6. استراتيجية تبديل البيئة
(1) حلول الإعداد متعدد البيئات
| الحل | النهج | المزايا والعيوب |
|---|---|---|
| ملفات .env متعددة | .env.local / .env.staging / .env.production |
بسيط لكن يتطلب تبديلاً يدوياً |
| تكامل CI/CD | تعيين متغيرات البيئة في نص النشر | آمن لكن يتطلب منصة CI |
| Laravel Envoyer | إدارة .env من جانب الخادم | أداة رسمية، لكن مدفوعة |
(2) الاختلافات في متغيرات البيئة الرئيسية
| المتغير | المحلي | Staging | الإنتاج |
|---|---|---|---|
APP_ENV |
local | staging | production |
APP_DEBUG |
true | true | false |
CACHE_DRIVER |
file | redis | redis |
SESSION_DRIVER |
file | redis | redis |
LOG_LEVEL |
debug | info | warning |
(1) ▶ مثال:إعداد ملفات .env لبيئات مختلفة
BASH
# .env.local (التطوير)
APP_ENV=local
APP_DEBUG=true
DB_DATABASE=shopmetrics_dev
CACHE_DRIVER=file
LOG_LEVEL=debug
# .env.staging (خادم staging)
APP_ENV=staging
APP_DEBUG=true
DB_DATABASE=shopmetrics_staging
CACHE_DRIVER=redis
LOG_LEVEL=info
# .env.production (خادم الإنتاج)
APP_ENV=production
APP_DEBUG=false
DB_DATABASE=shopmetrics
CACHE_DRIVER=redis
LOG_LEVEL=warning
الناتج:
TEXT
# تم تنفيذ الأمر بنجاح
7. إعداد التخزين المؤقت
في بيئة الإنتاج، يمكن لـ Laravel دمج وتخزين جميع ملفات الإعداد مؤقتاً في ملف PHP واحد، مما يتجنب الحاجة لقراءة .env وتحليل config/*.php مع كل طلب.
(1) ▶ مثال:استخدام أمر التخزين المؤقت للإعداد
BASH
# تخزين جميع الإعدادات مؤقتاً (الإنتاج)
php artisan config:cache
# Configuration cached successfully!
# بعد التخزين المؤقت، env() تُرجع null — استخدم config() دائماً
# هذا خطأ شائع!
# مسح تخزين الإعداد المؤقت
php artisan config:clear
# Configuration cache cleared!
# التحقق مما إذا كان الإعداد مخزناً مؤقتاً
php artisan config:status
# Config is cached.
الناتج:
TEXT
# تم تنفيذ الأمر بنجاح
⚠️ ملاحظة: بعد تنفيذ
config:cache، ستُرجع دالة env() القيمة null في الملفات غير الإعدادية. استخدم env() فقط في config/*.php؛ استخدم config() في كل مكان آخر.
| الأمر | الوظيفة | حالة الاستخدام |
|---|---|---|
config:cache |
تخزين الإعداد مؤقتاً | نشر الإنتاج |
config:clear |
مسح التخزين المؤقت | بعد تعديل الإعدادات |
config:show |
عرض قيم الإعداد | التصحيح |
env |
عرض قيم .env | أثناء التطوير |
8. مثال شامل: إعداد بيئة كامل لـ ShopMetrics
PHP
// ============================================
// شامل: إعداد .env الكامل لـ ShopMetrics
// المحتوى: التطبيق، قاعدة البيانات، التخزين المؤقت، الجلسة، البريد، التسجيل
// ============================================
// ملف .env لـ ShopMetrics (التطوير المحلي)
/*
APP_NAME=ShopMetrics
APP_ENV=local
APP_KEY=base64:generated-key-here
APP_DEBUG=true
APP_URL=http://localhost:8000
LOG_CHANNEL=stack
LOG_LEVEL=debug
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics
DB_USERNAME=shopmetrics_user
DB_PASSWORD=Str0ngP@ssw0rd!
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=database
MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=shopmetrics-uploads
*/
BASH
# بعد إعداد .env، قم بتشغيل هذه الأوامر:
php artisan key:generate
php artisan config:clear
php artisan migrate
php artisan db:seed
php artisan serve
الناتج:
TEXT
Application key set successfully.
Configuration cache cleared!
Info: Using MySQL database: shopmetrics
Migration table created successfully.
Starting Laravel development server: http://127.0.0.1:8000
❓ أسئلة شائعة
س ما الفرق بين env() و config()؟
ج env() يقرأ متغيرات البيئة مباشرة من ملف .env؛ config() يقرأ قيم الإعداد المنظمة في ملفات config/*.php. في بيئة الإنتاج، بعد تشغيل
config:cache، يُرجع env() القيمة null عند الوصول إلى ملفات غير إعدادية؛ لذلك يجب عليك دائماً استخدام config().س هل يجب إرسال ملف .env إلى Git؟
ج بالتأكيد لا. يحتوي ملف .env على معلومات حساسة مثل كلمات مرور قاعدة البيانات ومفاتيح API. أرسل فقط .env.example كقالب؛ يجب إنشاء ملف .env الفعلي بواسطة العمليات على الخادم.
س هل أحتاج إلى إعادة تشغيل الخادم بعد تعديل .env؟
ج نعم.
php artisan serve سيعيد تحميل التغييرات تلقائياً، لكن php-fpm يتطلب php artisan config:clear أو إعادة تشغيل الخدمة. في بيئات الإنتاج حيث تم تشغيل config:cache، يجب إعادة بناء التخزين المؤقت.س متى يجب استخدام SQLite ومتى MySQL؟
ج استخدم SQLite للتعلم والنماذج الأولية (بدون إعداد)؛ استخدم MySQL لبيئات الإنتاج (ميزات المؤسسات مثل التزامن والنسخ الاحتياطي والنسخ المتماثل)؛ اختر PostgreSQL عندما تكون الاستعلامات المتقدمة (البحث النصي الكامل، GIS) مطلوبة.
س ما الغرض من APP_KEY؟
ج APP_KEY يُستخدم لجميع عمليات التشفير (تشفير الجلسة، رموز إعادة تعيين كلمة المرور، رموز CSRF، إلخ). إذا قمت بتغيير APP_KEY، ستصبح جميع البيانات المشفرة غير قابلة لفك التشفير. لا تقم بتغييره بعد النشر في بيئة الإنتاج.
س كيف تصبح تغييرات .env سارية المفعول بعد تشغيل
config:cache؟ج ما عليك سوى تشغيل
php artisan config:cache لإعادة إنشاء التخزين المؤقت. سيؤدي هذا إلى إعادة قراءة .env وجميع ملفات config وإنشاء ملفات تخزين مؤقت جديدة.📖 ملخص
- إعداد Laravel منظم في طبقتين: .env يخزن متغيرات البيئة، وconfig/*.php ينظم قيم الإعداد
- استخدم
env()فقط في ملفات الإعداد؛ استخدمconfig()في كل مكان آخر - MySQL مناسب لسيناريوهات التجارة الإلكترونية، PostgreSQL لسيناريوهات التحليلات، وSQLite للتطوير
- يُوصى بـ Redis لبيئات الإنتاج كحل للتخزين المؤقت وإدارة الجلسة
- يجب تعيين APP_DEBUG على false في بيئة الإنتاج
- config:cache يحسن الأداء، لكن بعد التخزين المؤقت، env() لم يعد يعمل خارج ملفات الإعداد
📝 تمارين
-
تمرين أساسي (⭐): قم بإعداد مشروع ShopMetrics لاستخدام قاعدة بيانات MySQL. عدّل معلومات اتصال قاعدة البيانات في ملف
.env، ثم شغّلphp artisan migrateللتحقق من نجاح الاتصال. -
تمرين متقدم (⭐⭐): أنشئ ملفي إعداد بيئة،
.env.localو.env.staging، باستخدام أسماء قواعد بيانات ومحركات تخزين مؤقت مختلفة، واكتب نصاً للتبديل السريع بين البيئات. -
تحدي (⭐⭐⭐): ابحث في مبادئ تنفيذ
config:cache(اقرأIlluminate/Foundation/Console/ConfigCacheCommand.php)، واشرح لماذا تصبحenv()غير صالحة بعد التخزين المؤقت، وصف كيفية استخدام التخزين المؤقت للإعداد بأمان في بيئة الإنتاج.
