في هذا الدرس 6تصفّح المواضيع
في الإصدارين 11 و 12 من Laravel، تُدار معالجة الاستثناءات مركزياً داخل دالة withExceptions في ملف bootstrap/app.php. يمكنك تسجيل دوال report مخصصة لإرسال الأخطاء الحرجة إلى خدمات المراقبة، ودوال render لإرجاع استجابات ويب أو JSON مخصصة، بالإضافة إلى دالة abort لإطلاق أخطاء HTTP مباشرة.
- الإعداد المركزي (Centralized Configuration): استخدم دالتي report و render على كائن الاستثناءات داخل ملف bootstrap/app.php.
- دوال الإيقاف السريعة (HTTP Exception Helpers): استدع دالة abort أو abort_if داخل المتحكمات لإيقاف التنفيذ وإرجاع رمز الخطأ فوراً.
- المخرجات الآمنة في الإنتاج (Safe Production Output): عند تعطيل وضع التصحيح APP_DEBUG، يخفي Laravel تفاصيل الكود ويعرض صفحة خطأ آمنة.
// bootstrap/app.php
->withExceptions(function (Exceptions $exceptions) {
$exceptions->render(function (DomainException $e) {
return response()->json(['err' => 'Bad'], 400);
});
})يتيح Laravel استبدال شاشات أخطاء HTTP الافتراضية بقوالب Blade مخصصة تحمل الهوية البصرية لموقعك بسهولة تامة. يكفي إنشاء ملف قالب يحمل رقم رمز الحالة مثل resources/views/errors/404.blade.php أو 500.blade.php لكي يعرضه الإطار تلقائياً عند حدوث ذلك الخطأ.
- نشر القوالب الافتراضية (Publish Default Views): نفذ الأمر vendor:publish --tag=laravel-errors لنسخ قوالب الأخطاء المدمجة وتعديلها.
- التسمية برمز الحالة (Status Code Naming): أنشئ ملفات 403.blade.php و 404.blade.php و 500.blade.php داخل مجلد resources/views/errors.
- كائن الاستثناء المدمج (Injected Exception Instance): يمكنك قراءة رسالة الخطأ عبر المتغير $exception المتاح تلقائياً داخل قالب الخطأ.
// Publish customizable error templates:
// php artisan vendor:publish --tag=laravel-errors
// Trigger a custom 404 error page in controller:
abort_unless($post->is_published, 404);يعتمد تشخيص الأعطال الفعال في بيئة الإنتاج على تدوين سجلات منظمة بدلاً من طباعة الأخطاء على الشاشة. تطبق واجهة Log معيار PSR-3 القياسي، وتوفر دوال لمستويات الخطورة مثل Log::info و Log::warning و Log::error مع قبول مصفوفة ترابطية لبيانات السياق.
- مستويات الخطورة القياسية (PSR-3 Severity Levels): اختر المستوى المناسب للحدث مثل info للعمليات الطبيعية و warning للتحذيرات و error للأعطال.
- مصفوفات السياق (Contextual Arrays): مرر مصفوفة تحتوي على معرف المستخدم أو الطلب كوسيط ثانٍ لتسهيل البحث الجنائي في السجلات.
- مسار الحفظ الافتراضي (Default Storage Location): تُكتب السجلات المحلية داخل ملف storage/logs/laravel.log بالاعتماد على مكتبة Monolog.
use Illuminate\Support\Facades\Log;
Log::info('Checkout started', ['uid' => $user->id]);
Log::error('Payment gateway timeout', [
'order_id' => $order->id,
]);إن كتابة جميع السجلات في ملف واحد يؤدي بمرور الوقت لتضخم ملف laravel.log واستهلاك مساحة القرص. يتيح ضبط LOG_STACK=daily تدوير ملفات السجل يومياً بالتاريخ وتنظيف القديم منها، كما تسمح دالة Log::channel بتوجيه سجلات محددة كالمدفوعات إلى قناة مستقلة.
- التدوير اليومي للسجلات (Daily Log Rotation): تنشئ سواقة daily ملفاً منفصلاً لكل يوم وتحذف الملفات الأقدم من 14 يوماً تلقائياً.
- التوجيه لقناة مخصصة (Targeted Channel Routing): استدع دالة Log::channel لتسجيل العمليات الحساسة كالمدفوعات في ملف مستقل.
- دمج القنوات عبر Stack (Stack Multi-Channel Driver): اجمع بين الحفظ اليومي في الملفات وإرسال تنبيهات Slack الفورية عبر قناة stack موحدة.
// .env: LOG_CHANNEL=stack & LOG_STACK=daily
use Illuminate\Support\Facades\Log;
Log::channel('daily')->warning('Disk above 80%', [
'server' => 'web-01',
]);يبدأ بناء تطبيقات ثنائية اللغة تدعم العربية والإنجليزية في Laravel بنشر مجلد اللغات عبر الأمر php artisan lang:publish. احفظ مفاتيح الترجمة داخل ملفي lang/en/messages.php و lang/ar/messages.php، واسترجعها بالدالة المساعدة __ مع تبديل اللغة النشطة برمجياً عبر دالة App::setLocale.
- نشر مجلد اللغات (Publishing Language Files): نفذ الأمر php artisan lang:publish لإظهار مجلد lang في جذر مشروع Laravel 12.
- المتغيرات النصية الديناميكية (Dynamic Placeholders): عرّف متغيرات مسبوقة بنقطتين مثل :name داخل النص ومرر قيمتها كمصفوفة لدالة الترجمة.
- تبديل اللغة أثناء التشغيل (Runtime Locale Switching): استدع دالة App::setLocale('ar') داخل برمجية وسيطة لضبط لغة الواجهة حسب تفضيل المستخدم.
use Illuminate\Support\Facades\App;
App::setLocale('ar');
$welcome = __('messages.welcome', ['name' => 'Ahmad']);
// Reads key 'welcome' from lang/ar/messages.phpيضمن الجمع بين المعالجة الأنيقة للاستثناءات وتدوين السجلات اليومية المهيكلة ودعم اللغتين العربية والإنجليزية جاهزية تطبيق Laravel 12 لبيئة الإنتاج العالمية. راجع أهم دوال التشخيص والتوطين المرجعية في المثال التالي.
| وجه المقارنة الهندسي | الأسلوب المتزامن أو التقليدي | معيار Laravel 12 الحديث |
|---|---|---|
| معالجة الاستثناءات | تكرار كتل try/catch يدوياً داخل كل دالة في المتحكمات | إدارة مركزية عبر دالة withExceptions في ملف bootstrap/app.php |
| تدوين سجلات التشخيص | الاعتماد على دوال الطباعة العشوائية أو ملف سجل واحد متضخم | واجهة Log القياسية مع مصفوفات السياق والتدوير اليومي daily |
| صفحات أخطاء HTTP | عرض صفحات خطأ الخادم الافتراضية التي تفتقر للهوية البصرية | قوالب Blade مخصصة لكل رمز خطأ داخل مجلد resources/views/errors |
| دعم تعدد اللغات | كتابة النصوص العربية أو الإنجليزية بشكل ثابت داخل القوالب | ملفات ترجمة منظمة في مجلد lang يتم جلبها عبر الدالة __ |
// Publish lang directory:
// php artisan lang:publish
App::setLocale('ar');
Log::info('Locale set', [
'locale' => App::getLocale(),
]);ملخص الدرس
حصاد الدرسمراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي
ماذا تعلّمت في هذا الدرس؟
أتقنت في هذا الدرس حول «معالجة الاستثناءات وقنوات التسجيل وتعدد اللغات في Laravel» مفاهيم معالجة الاستثناءات في Bootstrap App، وتخصيص واجهات أخطاء HTTP المخصصة، وتدوين السجلات التشخيصية عبر Log وفق معايير Laravel 12 الحديثة.
الخطوة التالية والدرس القادم
انتقل الآن إلى الدرس التالي «أساسيات الاختبارات الآلية في Laravel عبر PHPUnit و Pest» للبناء التراكمي على ما تعلمته.
سجّل الدخول لحفظ تقدمك
تابع إنجاز المواضيع والمصطلحات والمهام، وكمّل من آخر خطوة على أي جهاز.
المصطلحات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 Error Logging الأخطاء والتوطين
- تخصيص معالجة الاستثناءات وتدوين السجلات عبر قنوات Log وبناء تطبيقات ثنائية اللغة بملفات الترجمة Localization.
- للمراجعة
- 02 Handling Exceptions in Bootstrap App معالجة الاستثناءات في Bootstrap App
- المفهوم الهندسي والتطبيق العملي المباشر لقسم معالجة الاستثناءات في Bootstrap App في إطار العمل Laravel 12.
- للمراجعة
- 03 Customizing HTTP Error Blade Views تخصيص واجهات أخطاء HTTP المخصصة
- المفهوم الهندسي والتطبيق العملي المباشر لقسم تخصيص واجهات أخطاء HTTP المخصصة في إطار العمل Laravel 12.
- للمراجعة
- 04 Writing Structured Diagnostic Logs تدوين السجلات التشخيصية عبر Log
- المفهوم الهندسي والتطبيق العملي المباشر لقسم تدوين السجلات التشخيصية عبر Log في إطار العمل Laravel 12.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
الاختصارات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 MVC MVC
- Model View Controller
- النمط المعماري الذي يفصل بين نماذج البيانات Models، وطبقات العرض Views، والمتحكمات Controllers في Laravel.
- للمراجعة
- 02 CLI CLI
- Command Line Interface
- واجهة سطر الأوامر التي تعمل عبر أداة php artisan لتوليد الملفات وإدارة التطبيق.
- للمراجعة
- 03 HTTP HTTP
- Hypertext Transfer Protocol
- بروتوكول نقل النص الفائق الذي ينظم طلبات المتصفح واستجابات خادم Laravel.
- للمراجعة
- 04 PSR PSR
- PHP Standards Recommendations
- المعايير القياسية للغة PHP مثل التحميل التلقائي PSR-4 التي يلتزم بها إطار العمل Laravel.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
مهامك قبل الاختبار
خطوة صغيرة كل مرة. وإنجاز تقدر ترجع له.
-
اكتب ونفّذ المثال البرمجي المشروح في قسم «معالجة الاستثناءات في Bootstrap App» داخل مشروع Laravel 12 المحلي وتحقق من النتيجة.
-
بدّل بين الحالات الثلاث في المحاكي التفاعلي ضمن قسم «تخصيص واجهات أخطاء HTTP المخصصة» وقارن مخرجات التنفيذ.
تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.
اختبر فهمك.
ووصلها للإتقان.
كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.
أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.
الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.
لمحة عن التحدي8 أسئلة تنتظرك ＋
ما الهدف الهندسي الأساسي من معالجة الاستثناءات في Bootstrap App في إطار العمل Laravel 12؟
يسهم معالجة الاستثناءات في Bootstrap App في تنظيم منطق التطبيق بأسلوب معياري آمن وقابل للصيانة في Laravel 12.
يساعد الالتزام باصطلاحات Laravel 12 الرسمية في قسم «تخصيص واجهات أخطاء HTTP المخصصة» على رفع جودة الكود وسهولة اختباره آلياً.
صواب؛ الالتزام بالمعايير القياسية في Laravel 12 يجعل الكود واضحاً وسهل الفحص والصيانة.
أي آلية في Laravel 12 تتولى إدارة تدوين السجلات التشخيصية عبر Log بشكل مباشر ومنظم؟
توفر طبقة إطار العمل وحاوية الخدمات في Laravel 12 الأدوات القياسية لإدارة تدوين السجلات التشخيصية عبر Log.
لماذا يُعد تطبيق إعداد قنوات السجلات اليومية والمخصصة مهماً عند بناء تطبيقات Laravel 12 جاهزة للإنتاج؟
لأنه يمنع الأخطاء البرمجية الخفية ويوحد سلوك التطبيق بين بيئتي التطوير والإنتاج.
في Laravel 12، يُنصح بكتابة مفاتيح الإنتاج السرية مباشرة داخل ملفات الكود المصدري المرفوعة إلى Git بدلاً من ملفات البيئة.
خطأ؛ يجب حفظ المفاتيح والبيانات السرية في متغيرات البيئة وعدم رفعها أبداً إلى مستودع Git.
ما المزايا الهندسية التي يحققها تطبيق توطين النصوص وتبديل لغة التطبيق في Laravel 12؟ (اختر كل ما ينطبق)
يوفر فصلاً واضحاً للمسؤوليات، وأماناً أعلى أثناء التنفيذ، وتعاوناً أسهل بين أفراد الفريق.
يوظف إطار العمل Laravel 12 ميزات PHP 8 الحديثة مثل تحديد أنواع القيم المرجعة لجعل الكود أكثر وضوحاً وأماناً.
صواب؛ يعتمد Laravel 12 بشكل كامل على الصياغة الحديثة للغة PHP 8.2+ وسلامة الأنواع.
ما الفرق الجوهري بين معيار Laravel 12 الحديث والملفات اليدوية التقليدية في مرجع الأخطاء والسجلات وتعدد اللغات؟
يوفر Laravel 12 واجهات قياسية موحدة وحماية مدمجة تغني عن الكود اليدوي المعرض للأخطاء.