README

错误邮件插件旨在通过添加条件发送开发者团队电子邮件的功能来增强 CakePHP 的错误处理系统，该电子邮件包含有用的调试信息，例如

异常/错误 URL
异常/错误类
异常/错误消息
异常/错误代码
客户端 IP
文件和行号
堆栈跟踪

安装

您可以使用 composer 将此插件安装到您的 CakePHP 应用程序中。

运行以下命令

composer require ebrigham1/cakephp-error-email

然后，您可以使用 shell 命令加载插件

bin/cake plugin load -b ErrorEmail

或者，您可以在应用程序的 config/boostrap.php 文件中手动添加加载语句

Plugin::load('ErrorEmail', ['bootstrap' => true]);

在您的 config/Bootstrap.php 中替换

use Cake\Error\ErrorHandler;

为

use ErrorEmail\Error\ErrorHandler;

在您的 src/Application.php 中替换

use Cake\Error\Middleware\ErrorHandlerMiddleware;

为

use ErrorEmail\Middleware\ErrorHandlerMiddleware;

配置

默认配置

'ErrorEmail' => [
    'email' => false,
    'emailLevels' => ['exception', 'error'],
    'emailDeliveryProfile' => 'default',
    'skipEmail' => [],
    'throttle' => false,
    'throttleCache' => '_error_email_',
    'skipThrottle' => [],
    'toEmailAddress' => null,
    'fromEmailAddress' => null,
    'environment' => null,
    'siteName' => null
],
'Cache' => [
    '_error_email_' => [
        'className' => 'File',
        'prefix' => 'error_email_',
        'path' => CACHE . 'error_emails/',
        'duration' => '+5 minutes'
    ],
],

此配置将自动与您的应用程序特定配置合并，优先使用您定义的任何键。

email (bool) - 启用或禁用错误/异常的电子邮件发送
emailLevels (array) - 应用于确定要发送哪些错误/异常的电子邮件级别的电子邮件级别。有效级别为 ['exception', 'error', 'warning', 'notice', 'strict', 'deprecated']。每个级别都用于捕获以下异常/php 错误
- 'exception' - \Exception (所有用户/框架抛出的异常)
- 'error' - \Error, E_PARSE, E_ERROR, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR
- 'warning' - E_WARNING, E_USER_WARNING, E_COMPILE_WARNING, E_RECOVERABLE_ERROR
- 'notice' - E_NOTICE, E_USER_NOTICE
- 'strict' - E_STRICT
- 'deprecated' - E_DEPRECATED, E_USER_DEPRECATED,
emailDeliveryProfile (string) - 要使用的电子邮件投递配置文件（在 config/app.php 下的 Email 键中定义）"default" 是默认值
skipEmail (array) - 应始终发送电子邮件的异常/错误类数组，即使它们被抛出。例如：[Cake\Network\Exception\NotFoundException::class, Cake\Network\Exception\InvalidCsrfTokenException::class]
throttle (bool) - 启用或禁用错误/异常电子邮件的节流。仅在确定缓存中已通过检查已通过相同异常/错误发送电子邮件时执行节流。错误/异常通过异常/错误类 + 异常/错误消息 + 异常/错误代码来确定是否唯一
throttleCache (string) - 用于节流电子邮件的缓存配置，默认使用文件缓存驱动程序，持续时间为 5 分钟
skipThrottle (数组) - 应当永远不被节流（即使它们在正常节流窗口内被多次抛出）的异常/错误类数组。例如：['App\Exception\FullfillmentException'] 这些应该是您希望每次都发送邮件的异常/错误，即使这会填满您的邮箱。
toEmailAddress (字符串) - 发送这些错误/异常邮件的电子邮件地址，通常是开发团队。如果两个都存在，这将覆盖电子邮件投递配置文件提供的收件人地址。
fromEmailAddress (字符串) - 应当发送这些邮件的电子邮件地址，例如：noreply@yoursite.com。如果两个都存在，这将覆盖电子邮件投递配置文件提供的发送人地址。
environment (字符串) - 可选，使用默认模板，此参数将被放置在邮件的主题和正文中，以便轻松识别发送邮件的环境。例如：local/staging/production。
siteName (字符串) - 可选，使用默认模板，此参数将被放置在邮件的主题和正文中，以便轻松识别发送邮件的网站。

注意：在您的 config/app.php 文件中，Error 的 skipLog 键也被使用。在该列表中的异常/错误类不会被发送邮件，因为它假设如果它们不够重要以至于不值得记录，那么它们也不值得收到邮件通知。

重要：如果 email => true，则必须为 emailDeliveryProfile 配置键提供一个有效的电子邮件投递配置文件。通常默认设置将正常工作，除非您已重命名应用程序的默认电子邮件投递配置文件。如果您的电子邮件投递配置文件没有定义收件人地址和发送人地址，您还必须定义 toEmailAddress 和 fromEmailAddress 配置值。如果 throttle => true，则 throttleCache 也必须是有效的缓存配置。默认设置应该正常工作，只要您不在配置中重新定义 throttleCache。

如果检测到配置无效，将抛出配置异常，并解释错误原因。

基本用法

通常您在这些键中定义您的 config/app.php 文件

'ErrorEmail' => [
    'email' => true,
    'skipEmail' => [],
    'throttle' => true,
    'skipThrottle' => [],
    'toEmailAddress' => 'devteam@yoursite.com',
    'fromEmailAddress' => 'noreply@yoursite.com',
    'environment' => 'production',
    'siteName' => 'yoursite.com'
],

使用此配置，您将在网站上发生任何致命错误或异常时收到邮件，并在邮件中包含详细的调试信息。例如，如果您有一个热门页面上的错误，许多用户都会遇到该错误，那么错误将每5分钟发送一次，直到错误存在。如果同时抛出了不同的错误，您将立即收到该错误的通知，但之后它将每5分钟最多发送一次。

如果您发现您收到了很多您无法处理的异常/错误邮件，例如 Cake\Network\Exception\NotFoundException，您可以简单地将其添加到 skipEmail 配置中，您将不再收到这些异常的打扰。

如果您想一般性地节流邮件以避免邮件垃圾，但您有一些必须始终收到邮件通知的异常，则可以使用 skipThrottle 列表。例如，可能有一个客户在您的网站上支付了某些东西，但由于需要调用一个临时关闭的服务，您无法在客户支付后履行他们的购买。然后您可以将这种情况中抛出的异常添加到 skip throttle 列表中。这将导致除了您在 skipThrottle 列表中定义的异常之外的所有异常，每5分钟只发送一次邮件，而您的 FullfillmentException 将每次发生时都发送邮件。

高级使用

覆盖视图

默认插件电子邮件模板可以通过在以下位置创建自己的模板文件来覆盖：

src/Template/Plugin/ErrorEmail/Email/html/error.ctp
src/Template/Plugin/ErrorEmail/Email/text/error.ctp
src/Template/Plugin/ErrorEmail/Email/html/exception.ctp
src/Template/Plugin/ErrorEmail/Email/text/exception.ctp

扩展/覆盖核心函数

为了扩展/覆盖此插件的内置功能，您需要创建自己的类，这些类将扩展此插件的类。

高级安装

创建 src/Traits/EmailThrowableTrait.php

<?php
namespace App\Traits;

trait EmailThrowableTrait
{
}

创建 src/Error/ErrorHandler.php

<?php
namespace App\Error;

use App\Traits\EmailThrowableTrait;
use ErrorEmail\Error\ErrorHandler as ErrorEmailErrorHandler;

class ErrorHandler extends ErrorEmailErrorHandler
{
    use EmailThrowableTrait;
}

创建 src/Middleware/ErrorHandlerMiddleware.php

<?php
namespace App\Middleware;

use App\Traits\EmailThrowableTrait;
use ErrorEmail\Middleware\ErrorHandlerMiddleware as ErrorEmailErrorHandlerMiddleware;

class ErrorHandlerMiddleware extends ErrorEmailErrorHandlerMiddleware
{
    use EmailThrowableTrait;
}

现在您已经有了自己的类，您需要更新应用程序以使用它们。

在您的 config/Bootstrap.php 中替换

use Cake\Error\ErrorHandler; // Or use ErrorEmail\Error\ErrorHandler;

为

use App\Error\ErrorHandler;

在您的 src/Application.php 中替换

use Cake\Error\Middleware\ErrorHandlerMiddleware; // Or use ErrorEmail\Middleware\ErrorHandlerMiddleware;

为

use App\Middleware\ErrorHandlerMiddleware;

添加任意逻辑以跳过电子邮件

在您的 src/Traits/EmailThrowableTrait.php 中添加此函数

protected function _appSpecificSkipEmail($throwable)
{
    // Add any logic here to skip emailing throwables that requires more complicated checking
    // than instanceof class provided by plugin config, return true to skip emailing, false to not skip emailing
}

添加任意逻辑以跳过节流

在您的 src/Traits/EmailThrowableTrait.php 中添加此函数

protected function _appSpecificSkipThrottle($throwable)
{
    // Add any logic here to skip throttling throwables that requires more complicated checking
    // than instanceof class provided by plugin config, return true to skip throttling, false to not skip throttling
}

覆盖电子邮件功能

在您的 src/Traits/EmailThrowableTrait.php 中添加此函数

protected function _setupEmail(\Cake\Mailer\Email $email, $throwable)
{
   // Add logic here to pick the email template, layout,
   // set the to address, from address, viewVars, ect.
   // Make sure to return your email object at the end of the function
   // so the plugin can send the email.
   return $email;
}

错误和反馈

http://github.com/ebrigham1/cakephp-error-email/issues

许可协议

特此免费授予任何获得本软件及其相关文档文件（“软件”）副本的任何人无限制地处理软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许软件提供方进行此类操作，前提是以下条件

ebrigham1 / cakephp-error-email

维护者

详细信息

README

目录

安装

配置

基本用法

高级使用

覆盖视图

扩展/覆盖核心函数

高级安装

添加任意逻辑以跳过电子邮件

添加任意逻辑以跳过节流

覆盖电子邮件功能

错误和反馈

许可协议