Laravel - The Basics - Error Handling (官方文件原子化翻譯筆記)

# 前言

學習一個框架, Ray 的想法是, 在深入理解底層實作的原理之前, 應該先知道這個框架的 使用方法; 先學習怎麼使用這個前人造的輪子, 再學習怎麼樣造一個輪子。
所以本篇文章重點在於細讀官方文件, 並將內容理解後以 Q&A 的方式記錄下來, 加速學習以及查詢。

# Configuration

Laravel 中, 哪個設定會決定當遇到錯誤時, 是否印出 stack of trace information？

config/app.php 中的 APP_DEBUG option

# The Exception Handler

# Report Method

Laravel 中, 所有的 exceptions 都是由哪一個 class 所處理？

App\Exceptions\Handler

Laravel 中, 如果我要 log exceptions 或傳送到外部服務, 可以使用 哪一個 class 的 哪一個 method

• App\Exceptions\Handler class
• report method

以下的 Laravel example code 的意思是？

• Example:

  <?php
  public function report(Throwable $exception)
  {
      if ($exception instanceof CustomException) {
          //
      }
  
      parent::report($exception);
  }

• Answer:
  如果 exception 為自定義的某個 exception, 那就執行特別邏輯, 若否, 則執行預設的 log 邏輯

# Global Log Context

Laravel 預設會將目前的 user id 加到 exception 的 log message 當中, 如果我想要增加新的資訊到預設輸出, 我可以在 哪個 class 的 哪個 method 定義這件事？

• App\Exceptions\Handler class
• context method

以下位於 App\Exceptions\Handler 的 Laravel example code 的意思是？

• Example:

  <?php
  protected function context()
  {
      return array_merge(parent::context(), [
          'foo' => 'bar',
          'ray' => 'owner'
      ]);
  }

• Answer:
  將 ['foo' => 'bar', 'ray' => 'owner'] 加到預設的 context, 即 exception 的 log message 中
  

# The Report Helper

以下的 Laravel example code 的意思是？

• Example:

  <?php
  public function isValid($value)
  {
      try {
          // Validate the value...
      } catch (Throwable $e) {
          report($e);
  
          return false;
      }
  }

• Answer:
  catch Throwable error, 將之 report 之後, return false, 原本的行為為 throw($e), 讓 Laravel 預設的 handler 去 render

# Ignoring Exceptions By Type

Laravel 中, 解釋以下的 example

• Example:

  <?php
  protected $dontReport = [
      \Illuminate\Auth\AuthenticationException::class,
      \Illuminate\Auth\Access\AuthorizationException::class,
      \Symfony\Component\HttpKernel\Exception\HttpException::class,
      \Illuminate\Database\Eloquent\ModelNotFoundException::class,
      \Illuminate\Validation\ValidationException::class,
  ];

• Answer:
  定義你不想要記錄到 log file 的 exceptions

# Render Method

解釋以下的 Laravel example

• Example:

  <?php
  public function render($request, Throwable $exception)
  {
      if ($exception instanceof CustomException) {
          return response()->view('errors.custom', [], 500);
      }
  
      return parent::render($request, $exception);
  }

• Answer:

  <?php
  // 使用 render method 來定義 exception 的 response
  public function render($request, Throwable $exception)
  {
      // 如果 exception 為指定的
      if ($exception instanceof CustomException) {
          // 做相對應的客製化 response
          return response()->view('errors.custom', [], 500);
      }
  
      // 若非指定 exception, 採用預設 response
      return parent::render($request, $exception);
  }

# Reportable & Renderable Exceptions

Laravel 中, 如果我想要建立客製化的 exception, 可以在哪個資料夾內建立？

app/Exceptions

解釋以下 Laravel example

• Example:

  <?php
  
  namespace App\Exceptions;
  
  use Exception;
  
  class RenderException extends Exception
  {
      public function report()
      {
          //
      }
  
      public function render($request)
      {
          return response(...);
      }
  }

• Answer:

  <?php
  
  namespace App\Exceptions;
  
  use Exception;
  
  // 使用客製化 exception, 並 extend Exeeption, 另一個方法是在 Exception Handler 中的 render() 使用 type hint catch 指定的 exception
  class RenderException extends Exception
  {
      // 可在 report 內定義該 exception 被 throw 時的行為, 即該 log exception 或是導向外部 service, 預設是 log
      public function report()
      {
          //
      }
  
      // 可在 render 內定義該 exception 被 throw 時的行為
      public function render($request)
      {
          return response(...);
      }
  }

# HTTP Exceptions

Laravel 中, 如果我要立即的回傳一個 exception, 帶著我指定的 error code, 那我可以使用哪一個 global helper?

abort helper

以下的 Laravel example code 的意思是？

• Example:

  <?php
  abort(403, 'Unauthorized action.');

• Answer:
  回傳 exception 403, 並帶著 exception message

# Custom HTTP Error Pages

Laravel 中, 如果我想要客製化 HTTP Error pages, 可以將檔案至於哪個資料夾下？

resources/views/errors/

Laravel 中, 如果我想要客製化 HTTP Error pages, 假設我要客製化的 error code 為 404, 那在資料夾 resources/views/errors/ 中, 我的檔案名稱為？

404.blade.php

以下的 Laravel example code 的意思是？

• Example:

  <h2>{{ $exception->getMessage() }}</h2>

• Answer:
  在 view 中取出 exception message

以下的 Laravel example command 的意思是？

• Example:

  php artisan vendor:publish --tag=laravel-errors

• Answer:
  會將 vendor 中的 error view publish 到 resources/views 資料夾內, 可以完全自定義