دليل Laravel Telescope: مساعدك الأمثل في التصحيح #
Laravel Telescope هو مساعد تصحيح أخطاء أنيق لإطار عمل Laravel. يوفر رؤى تفصيلية حول الطلبات الواردة إلى تطبيقك، الاستثناءات، إدخالات السجل، استعلامات قاعدة البيانات، الوظائف في قائمة الانتظار، رسائل البريد الإلكتروني، الإشعارات، عمليات التخزين المؤقت، المهام المجدولة، تفريغ المتغيرات، والمزيد. يجعل Telescope تصحيح الأخطاء وفهم سلوك تطبيق Laravel بديهيًا بشكل لا يصدق، خاصة أثناء عملية التطوير.
لماذا Laravel Telescope؟
قبل Telescope، اعتمد المطورون غالبًا على عبارات dd()، ملفات السجل، أو أدوات المطور في المتصفح. على الرغم من فعاليتها، إلا أن هذه الطرق قد تكون مرهقة. يجمع Telescope جميع أنشطة التطبيق الهامة في واجهة ويب مركزية وجميلة، مما يوفر رؤى في الوقت الفعلي وبيانات تاريخية، ويبسط سير عمل التطوير بشكل كبير.
التثبيت
تثبيت Laravel Telescope بسيط ومباشر. ابدأ بسحب الحزمة إلى مشروعك باستخدام Composer:
composer require laravel/telescope
بعد التثبيت، قم بنشر أصول Telescope وتشغيل ترحيلات قاعدة البيانات الخاصة به. سيؤدي هذا إلى إنشاء الجداول اللازمة لتخزين بياناته.
php artisan telescope:install
php artisan migrate
بشكل افتراضي، سيتم تثبيت Telescope لبيئة local فقط. إذا كنت ترغب في استخدامه في بيئات أخرى (مثل staging)، يمكنك تعديل composer.json أو إضافة --dev صراحةً عند طلبها ثم نقلها إلى require. بالنسبة للإنتاج، يوصى عمومًا بإبقائه معطلاً أو مؤمنًا بشدة.
التكوين والوصول
ملف تكوين Telescope هو config/telescope.php. يمكنك نشره للتخصيص إذا لزم الأمر:
php artisan vendor:publish --provider="Laravel\Telescope\TelescopeServiceProvider"
تمكين/تعطيل Telescope
يمكنك التحكم في حالة Telescope النشطة عبر متغير البيئة TELESCOPE_ENABLED في ملف .env الخاص بك:
TELESCOPE_ENABLED=true
ترخيص الوصول إلى Telescope
لأسباب أمنية، خاصة في البيئات غير المحلية، يجب عليك تقييد الوصول إلى لوحة تحكم Telescope. يأتي Laravel Telescope مع gate بسيط لهذا الغرض. بشكل افتراضي، يسمح بالوصول فقط في البيئة المحلية. يمكنك تخصيص هذا في App\Providers\TelescopeServiceProvider الخاص بك:
use Laravel\Telescope\Telescope;
use Illuminate\Support\Facades\Gate;
/**
* Register the Telescope gate.
*
* This gate determines who can access Telescope in non-local environments.
*
* @return void
*/
protected function gate()
{
Gate::define('viewTelescope', function ($user) {
return in_array($user->email, [
'[email protected]',
]);
});
}
استبدل '[email protected]' بعناوين البريد الإلكتروني للمستخدمين الذين يجب أن يكون لديهم حق الوصول. للإنتاج، يوصى بشدة بتعطيل Telescope تمامًا أو ضمان رقابة صارمة للغاية على الوصول.
الغوص في ميزات Telescope
بمجرد التثبيت، يمكنك الوصول إلى لوحة تحكم Telescope بالانتقال إلى /telescope في متصفحك. فيما يلي نظرة على ميزاته الأساسية:
1. الطلبات (Requests)
راقب جميع طلبات HTTP الواردة. يمكنك فحص رؤوس الطلب، بيانات الجلسة، الحمولة، الاستجابة، وحتى مقاييس الأداء مثل المدة الإجمالية، مدة التطبيق، واستخدام الذاكرة.
2. الأوامر (Commands)
تتبع عمليات تنفيذ أوامر Artisan. مفيد لتصحيح أخطاء أوامر الكونسول وفهم دورة حياتها.
3. الجدولة (Schedule)
عرض المهام المجدولة وحالة تنفيذها. يساعد هذا في التحقق مما إذا كانت وظائف cron الخاصة بك تعمل كما هو متوقع.
4. الوظائف (Jobs)
راقب جميع الوظائف في قائمة الانتظار – المعلقة أو المكتملة أو الفاشلة. يمكنك حتى إعادة محاولة الوظائف الفاشلة مباشرة من واجهة المستخدم.
5. التخزين المؤقت (Cache)
راقب عمليات التخزين المؤقت: Hits، Misses، Gets، Puts، Forgets. أساسي لتحسين استخدام ذاكرة التخزين المؤقت.
6. الأحداث (Events)
افحص الأحداث التي يطلقها تطبيقك. تعرف على المستمعين المرفقين وما إذا تم التعامل معهم بشكل صحيح.
7. البريد (Mail)
معاينة رسائل البريد الإلكتروني المرسلة مباشرة في المتصفح دون إرسالها فعليًا. هذا يوفر الكثير من الوقت أثناء التطوير.
8. الإشعارات (Notifications)
على غرار البريد، قم بمعاينة الإشعارات (مثل قاعدة البيانات، البريد، الرسائل النصية القصيرة عبر قنوات مخصصة) التي يرسلها تطبيقك.
9. البوابات (Gates)
تتبع فحوصات الترخيص (Laravel Gates و Policies)، مع إظهار ما تم فحصه والنتيجة (مسموح/مرفوض).
10. التفريغ (Dumps)
ستظهر أي استدعاءات dump() في تطبيقك هنا، مما يوفر عرضًا نظيفًا ومنظمًا للمتغيرات المفروغة دون فوضى في إخراج المتصفح.
11. الاستعلامات (Queries)
افحص جميع استعلامات قاعدة البيانات التي ينفذها تطبيقك، بما في ذلك وقت التنفيذ، الاتصال، وبيان SQL الكامل. يتم تمييز الاستعلامات البطيئة، مما يساعد في تحديد اختناقات الأداء.
12. الاستثناءات (Exceptions)
التقاط وعرض جميع الاستثناءات غير الملتقطة، جنبًا إلى جنب مع تتبع المكدس (stack traces) وبيانات الطلب ذات الصلة.
13. السجلات (Logs)
يتم التقاط جميع إدخالات السجل المكتوبة عبر تسهيلات تسجيل Laravel، مما يسهل مراجعة نشاط التطبيق.
14. Redis
راقب أوامر Redis التي ينفذها تطبيقك، مما يوفر رؤى حول استخدامك لـ Redis.
التخصيص: تصفية الإدخالات
يمكنك تخصيص الإدخالات التي يسجلها Telescope. في TelescopeServiceProvider الخاص بك، داخل طريقة boot، يمكنك استخدام Telescope::filter لتحديد منطقك:
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
* Register any application services.
*/
public function register(): void
{
// ... تسجيلات أخرى
Telescope::filter(function (IncomingEntry $entry) {
if (app()->environment('local')) {
return true;
}
return $entry->isReportableException() ||
$entry->isFailedJob() ||
$entry->isScheduledTask() ||
$entry->hasTag('important'); // مثال: سجل فقط الإدخالات التي تحمل العلامة 'important'
});
}
يوضح هذا المثال كيفية تسجيل أنواع معينة فقط من الإدخالات أو الإدخالات ذات العلامات المخصصة عندما لا تكون في البيئة المحلية.
تقليم الإدخالات (Pruning Entries)
يمكن أن يجمع Telescope الكثير من البيانات. يجب عليك تقليم الإدخالات القديمة بانتظام. يمكنك جدولة أمر Artisan telescope:prune:
// في app/Console/Kernel.php
protected function schedule(Schedule $schedule): void
{
$schedule->command('telescope:prune')->daily(); // التقليم يوميًا (الاحتفاظ الافتراضي 7 أيام)
// أو التقليم بناءً على أيام الاحتفاظ (على سبيل المثال، أقدم من 48 ساعة)
// $schedule->command('telescope:prune --hours=48')->hourly();
}
الخلاصة
يغير Laravel Telescope تجربة تصحيح الأخطاء، حيث يقدم نظرة عامة شاملة وبديهية على تفاصيل تطبيقك الداخلية. من مراقبة طلبات HTTP واستعلامات قاعدة البيانات إلى فحص رسائل البريد الإلكتروني والوظائف في قائمة الانتظار، يوفر Telescope رؤى لا تقدر بثمن تسرع التطوير وتعزز فهم تطبيقات Laravel الخاصة بك. قم بدمجه في سير عمل التطوير الخاص بك اليوم واستمتع بمستوى جديد من الإنتاجية!
