PHPackages                             ebrigham1/cakephp-error-email - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. ebrigham1/cakephp-error-email

AbandonedArchivedCakephp-plugin[Mail & Notifications](/categories/mail)

ebrigham1/cakephp-error-email
=============================

CakePHP3.x ErrorEmail Plugin

1.3.0(6y ago)1613.4k4[4 issues](https://github.com/ebrigham1/cakephp-error-email/issues)MITPHPPHP >=5.6

Since Jan 13Pushed 6y ago2 watchersCompare

[ Source](https://github.com/ebrigham1/cakephp-error-email)[ Packagist](https://packagist.org/packages/ebrigham1/cakephp-error-email)[ Docs](https://github.com/ebrigham1/cakephp-error-email/)[ RSS](/packages/ebrigham1-cakephp-error-email/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (8)Dependencies (3)Versions (9)Used By (0)

ErrorEmail plugin for CakePHP 3.x
=================================

[](#erroremail-plugin-for-cakephp-3x)

[![Build Status](https://camo.githubusercontent.com/a7380d439c6cf1419a780ef6bf141976fcfa2069c18d169527a5fba986e6f5f9/68747470733a2f2f7472617669732d63692e636f6d2f656272696768616d312f63616b657068702d6572726f722d656d61696c2e7376673f6272616e63683d6d6173746572)](https://travis-ci.com/ebrigham1/cakephp-error-email)[![codecov](https://camo.githubusercontent.com/f9d2d9c7f6eab3f9b0f7452c93f10a0c5118540b5727db14da485111a440f911/68747470733a2f2f636f6465636f762e696f2f67682f656272696768616d312f63616b657068702d6572726f722d656d61696c2f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/ebrigham1/cakephp-error-email)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE.txt)

The ErrorEmail plugin is designed to enhance CakePHP's error handling system by adding the ability to conditionally email the dev team when errors or exceptions are thrown by your application with useful debugging information such as:

- Exception/Error Url
- Exception/Error Class
- Exception/Error Message
- Exception/Error Code
- Client IP
- File and Line Number
- Stack Trace

[![Screenshot](https://cloud.githubusercontent.com/assets/7337543/26083097/b3c0aebe-39a1-11e7-8721-ab3301a281cf.png)](https://cloud.githubusercontent.com/assets/7337543/26083097/b3c0aebe-39a1-11e7-8721-ab3301a281cf.png)

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Configuration](#configuration)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
    - [Overriding Views](#overriding-views)
    - [Extending/Overriding Core Functions](#extendingoverriding-core-functions)
        - [Advanced Installation](#advanced-installation)
        - [Adding Arbitrary Logic to Skip Emails](#adding-arbitrary-logic-to-skip-emails)
        - [Adding Arbitrary Logic to Skip Throttling](#adding-arbitrary-logic-to-skip-throttling)
        - [Overriding Emailing Functionality](#overriding-emailing-functionality)
- [Bugs and Feedback](#bugs-and-feedback)
- [License](#license)

Installation
------------

[](#installation)

You can install this plugin into your CakePHP application using [composer](http://getcomposer.org).

Run the following command

```
composer require ebrigham1/cakephp-error-email
```

You can then load the plugin using the shell command:

```
bin/cake plugin load -b ErrorEmail
```

Or you can manually add the loading statement in the **config/boostrap.php** file of your application:

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

In your **config/Bootstrap.php** replace:

```
use Cake\Error\ErrorHandler;
```

With:

```
use ErrorEmail\Error\ErrorHandler;
```

In your **src/Application.php** replace:

```
use Cake\Error\Middleware\ErrorHandlerMiddleware;
```

With:

```
use ErrorEmail\Middleware\ErrorHandlerMiddleware;
```

Configuration
-------------

[](#configuration)

Default configuration:

```
'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'
    ],
],
```

This configuration is automatically merged with your application specific configuration preferentially using any keys you define.

- email (bool) - Enable or disable emailing of errors/exceptions
- emailLevels (array) - The email levels that should be used to determine what errors/exceptions are emailed. Valid levels are \['exception', 'error', 'warning', 'notice', 'strict', 'deprecated'\]. Each level is used to capture the following exceptions/php errors:
    - 'exception' - \\Exception (all user/framework thrown exceptions)
    - '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) - The email delivery profile (defined in config/app.php under the Email key) to use "default" is the default
- skipEmail (array) - An array of exception/error classes that should never be emailed even if they are thrown Ex: \[Cake\\Network\\Exception\\NotFoundException::class, Cake\\Network\\Exception\\InvalidCsrfTokenException::class\]
- throttle (bool) - Enable or disable throttling of error/exception emails. Throttling is only performed if its been determined the exact same exception/error has already been emailed by checking the cache. Errors/Exceptions are determined to be unique by exception/error class + exception/error message + exception/error code
- throttleCache (string) - The cache configuration to use for throttling emails, the default is using the file cache driver with a 5 minute duration
- skipThrottle (array) - An array of exception/error classes that should never be throttled even if they are thrown more than once within the normal throttling window Ex: \['App\\Exception\\FullfillmentException'\] These should be exceptions/errors you always want an email about every single time even if it spams your inbox.
- toEmailAddress (string) - The email address to send these error/exception emails to, typically the dev team. This will override the to address provided by the email delivery profile if both are present.
- fromEmailAddress (string) - The email address these emails should be sent from ex: . This will override the from address provided by the email delivery profile if both are present.
- environment (string) - Optional, with the default template this will be placed in both the subject and the body of the email so its easy to identify what environment the email was sent from Ex: local/staging/production.
- siteName (string) - Optional, with the default template this will be placed in both the subject and the body of the email so its easy to identify what site the email was sent from.

**Note:** the skipLog key from Error in your **config/app.php** file is also used. Exception/Error classes that are in that list will not be emailed out as it is assumed if they aren't important enough to even log they shouldn't be important enough to receive an email about.

**Important:** If email => true you must provide a valid email delivery profile to the emailDeliveryProfile config key. Typically the default will work fine unless you've renamed your application's default email delivery profile. If your email delivery profile doesn't define a to address and a from address you must also define the toEmailAddress and fromEmailAddress config values. If throttle => true then throttleCache must also be a valid cache configuration. The default should work fine as long as you don't redefine throttleCache in your config.

A configuration exception will be thrown if the config is detected to be invalid with an explination of what is incorrect.

Basic Usage
-----------

[](#basic-usage)

Typically you define these keys in your **config/app.php** file:

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

With this configuration you would get emails whenever any fatal error or exception happened on your site with detailed debugging information in the email. If say you had an error on a popular page that many users were hitting that error would only be sent to you once every 5 minutes for the duration of the error being in existence. If a different error was thrown as well you would get that error right away the first time but then again it would be throttled to a maximum of once every 5 minutes.

If you found that you were receiving a lot of emails for exceptions/errors that you can not do anything about for instance Cake\\Network\\Exception\\NotFoundException you can simply add it to the skipEmail config and you will no longer be bothered with those exceptions.

If you want to throttle emails in general to avoid spamming your team, but you have some exceptions that you must always receive an email about then you can use the skipThrottle list. For instance maybe a customer has paid for something on your site, but you were unable to fulfill their purchase after they paid because it requires an API call to a service that was temporarily down. Then you can add the exception you throw in that instance to the skip throttle list. This will result in all exceptions aside from the exceptions you define in the skipThrottle list being throttled to only email once per every 5 minutes while your FullfillmentException will email you every single time it happens.

Advanced Usage
--------------

[](#advanced-usage)

### Overriding Views

[](#overriding-views)

The default plugin email templates can be overridden by creating your own template files at:

- **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**

### Extending/Overriding Core Functions

[](#extendingoverriding-core-functions)

In order to extend/override core functionality of this plugin you will have to create your own classes which extend this plugin's classes.

#### Advanced Installation

[](#advanced-installation)

Create **src/Traits/EmailThrowableTrait.php**:

```