آموزش مدیریت خطاها و ثبت وقایع / logging در لاراول

آموزش مدیریت خطاها و ثبت وقایع / logging در لاراول

1. مقدمه
2. تنظیم و کانفیگ
3. Exception Handler (کلاس مدیریت کننده ی خطاها)
   • متد report
   • متد render
4. خطاها و exception های HTTP
   • صفحات نمایش خطاهای سفارشی HTTP
5. ثبت وقایع (Logging)

مقدمه

زمانی که یک پروژه جدید Laravel راه اندازی می کنید، می بینید که قابلیت های مدیریت خطا (exception/error handling) از پیش برای شما تنظیم شده و آماده ی استفاده می باشند. بعلاوه، Laravel با یک کتابخانه ی پرطرفدار ثبت گزارش و ایجاد لاگ (logging) به نام Monolog ادغام شده که امکان استفاده از چندین log handler کارآمد را در این چارچوب نرم افزاری فراهم می آورد.

تنظیم و کانفیگ

نمایش جزئیات خطا

مقدار جزئیات خطایی که اپلیکیشن شما در پنجره ی مرورگر به نمایش می گذارد را می توان از گزینه ی debug در فایل تنظیماتconfig/app.phpمدیریت نمود. به صورت پیش فرض، این گزینه مقدارش را از متغیر محیطی (environment variable) به نام APP_DEBUG مقیم در فایل.env دریافت می کند (متغیرهای محیطی: مجموعه‌ای از مقادیر نام‌گذاری‌شده که می‌توانند نحوه س عملکرد فرایندهای در حال اجرا را تغییر داده یا بر روی آنها اثر بگذارند).
برای توسعه اپلیکیشن در محیط محلی (در ماشین خود)، بایستی مقدار متغیر محیطی APP_DEBUG را بر روی true تنظیم کنید. بیاد داشته باشید که مقدار این متغیر بایستی در زمان نصب برنامه به صورت سراسری در محیط تولید (تجاری)، همیشه بر روی false تنظیم باشد.

Log mode ها

Laravel به صورت پیش فرض از مدهای ثبت گزارش single، daily، syslog و errorlog پشتیبانی می کند. به عنوان مثال، اگر می خواهید از فایل های ثبت روزانه ی گزارش (daily log) بجای یک فایل واحد استفاده نمایید، بایستی log را در فایل تنظیماتconfig/app.php با پارامترdaily مقداردهی کنید:

                    'log' => 'daily'

تنظیم اختصاصی Monolog

اگر می خواهید کتابخانه ی Monolog را مطابق نیاز اپلیکیشن خود تنظیم کنید، در آن صورت کافی است متد configureMonologUsing را در برنامه ی خود فراخوانی نمایید. این متد را بایستی در فایل bootstrap/app.php و پیش از اینکه فایل مزبور متغیر $app را برگرداند، صدا بزنید:

$app->configureMonologUsing(function($monolog) {
   $monolog->pushHandler(...);
});
return $app;

کلاس مدیریت کننده ی خطا (Exception Handler)

تمامی خطاهای برنامه را کلاسApp\Exceptions\Handler مدیریت می کند. این کلاس دو متد به نام های report و render را ارائه می دهد. در زیر هر یک از دو متد نام برده را به تفصیل شرح می دهیم.

متد Report

این متد به منظور ثبت خطاها (exception logging) یا ارسال آن ها به سرویس های خارجی نظیر BugSnag یا Sentry بکار می رود. به طور پیش فرض تابع نام برده exception را به کلاس پایه ای که خطای مورد نظر در آن ثبت می شود، ارسال می کند (خطا را به کلاس والد می فرستد و کلاس والد نیز آن را ثبت می کند). با این همه شما آزادید خطاها را مطابق میل خود و به هر روشی که دوست دارید، ثبت (log) کنید.
اگر می خواهید انواع exception را به روش های مختلف با متد report گزارش کنید، در آن صورت می توانید عملگر مقایسه ای instanceof زبانPHP به صورت زیر استفاده نمایید:

/**
 * Report or log an exception.
 *
 * This is a great spot to send exceptions to Sentry, Bugsnag, etc.
 *
 * @param \Exception $e
 * @return void
 */
public function report(Exception $e)
{
   if ($e instanceof CustomException) {
       //
   }
   return parent::report($e);
}

نادیده گرفتن و عدم ثبت خطاهای با نوع خاص

متغیر (property) $dontReport از کلاس exception handler آرایه ای از نوع خطایی است که نباید ثبت شوند را در خود نگه می دارد.
به صورت پیش فرض exception های ناشی از خطاهای 404 داخل فایل های ثبت گزارش (log) نوشته نمی شوند. می توانید نوع خطاهایی (exception type) که نمی خواهید در فایل های لاگ ثبت شوند را به این آرایه اضافه نمایید.

متد Render

این متد وظیفه ی تبدیل exception به پاسخ HTTP را بر عهده دارد. پاسخ HTTP نیز متعاقبا به مرورگر برگردانده می شود. به صورت پیش فرض خطاهای برنامه به کلاس پایه ای که پاسخ را تولید می کند، فرستاده می شود.
با این همه شما آزادید نوع exception را بررسی کرده یا پاسخ اختصاصی خود را به مرورگر بازگردانید:

/**
 * Render an exception into an HTTP response.
 *
 * @param \Illuminate\Http\Request $request
 * @param \Exception $e
 * @return \Illuminate\Http\Response
 */
public function render($request, Exception $e)
{
   if ($e instanceof CustomException) {
       return response()->view('errors.custom', [], 500);
   }
   return parent::render($request, $e);
}

خطاهای HTTP

برخی از exception ها کد خطاهای HTTP از سرویس دهنده (Server) را شرح می دهند. حال این خطا می تواند exception با کد وضعیت 404"page not found"، خطایی با کد "unauthorized error" 401 یا یک خطا با کد وضعیت 500 باشد که به صورت اختصاصی توسط برنامه نویس تنظیم شده. به منظور تولید پاسخ خطا و برگرداندن آن به مرورگر، کافی است متد abort را فراخوانی نمایید:

                    abort(404);

متد abort() بلافاصله یک خطا صادر کرده و در پی آن خطای مورد نظر توسط exception handler در صفحه به نمایش در می آید (render می شود). در صورت تمایل می توانید متن پاسخ را به عنوان آرگومان دوم به این متد پاس داده و از این طریق در صفحه نمایش دهید:

                    abort(403, 'Unauthorized action.');

این متد می تواند در هر لحظه ای در طول چرخه ی حیات درخواست (request lifecycle) مورد استفاده قرار گیرد.

صفحات سفارشی نمایش خطاهای HTTP

لاراول این امکان را به شما می دهد تا صفحات سفارشی نمایش خطا ویژه ی هر یک از کدهای وضعیت HTTP ایجاد نمایید. برای مثال می توانید صفحات نمایش خطاهای دارای کد 404 اچ تی تی پی را سفارشی تنظیم نمایید. برای بازگردانی یک صفحه سفارشی برای خطاهای با کد 404 بایستی یک فایل resources/views/errors/404.blade.php ایجاد نمایید. این فایل با هر خطای 404 که برنامه ی کاربردی شما تولید می کند، فراخوانده و در صفحه ی مرورگر به نمایش در می آید.
فایل های view مقیم در این پوشه را بایستی طوری نام گذاری کنید که با کد وضعیت HTTP مربوطه منطبق باشند.

ثبت وقایع (Logging)

Laravel از کتابخانه ی پر طرفدار و قدرتمند Monolog استفاده می کند. به صورت پیش فرض، این فریم ورک طوری تنظیم شده که در هر روز یک فایل log برای اپلیکیشن شما در پوشه یstorage/logs ایجاد کند. می توانید با بهره گیری از facade ای به نام Log در برنامه ی تحت وب خود، اطلاعات و گزارشات را در فایل های لاگ درج نمایید:

<?php
namespace App\Http\Controllers;
use Log;
use App\User;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
   /**
    * Show the profile for the given user.
    *
    * @param int $id
    * @return Response
    */
   public function showProfile($id)
   {
       Log::info('Showing user profile for user: '.$id);
       return view('user.profile', ['user' => User::findOrFail($id)]);
   }
}

ثبت کننده ی گزارشات (logger) هر هشت سطح Logging معرفی شده در 5424 RFC را ارائه می کند:

1. emergency
2. alert
3. critical
4. error
5. warning
6. notice
7. info
8. debug

Log::emergency($error);
Log::alert($error);
Log::critical($error);
Log::error($error);
Log::warning($error);
Log::notice($error);
Log::info($error);
Log::debug($error);

ارسال اطلاعات وابسته به بستر خاص (contextual info)

آرایه ای از اطلاعات و داده های وابسته به context خاص را می توانید به توابع log ارسال کنید. داده های ارسالی توسط متدهای log فرمت دهی شده و به نمایش گذاشته می شوند:

                    Log::info('User failed to login.', ['id' => $user->id]);

دسترسی به نمونه ی زیرساختی و پایه ای تر کلاس Monolog

کتابخانه ی Monolog تعداد زیادی handler برای ثبت گزارش و لاگ کردن در اختیار برنامه نویس قرار می دهد. در صورت لزوم، می توانید به نمونه ی زیرین و پایه ی کلاس Monolog که مورد استفاده ی خود فریم ورک Laravel می باشد، دسترسی داشته باشید:

                    $monolog = Log::getMonolog();