PHPackages                             understand/understand-laravel - 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. [Logging & Monitoring](/categories/logging)
4. /
5. understand/understand-laravel

ActiveLibrary[Logging & Monitoring](/categories/logging)

understand/understand-laravel
=============================

Laravel 5, 6, 7, 8, 9, 10, 11 and 12 service provider for Understand.io

v2.9.0(11mo ago)24106.2k↓37.9%15[1 PRs](https://github.com/understand/understand-laravel/pulls)MITPHPPHP ^5.5 || ^7.0 || ^8.0 || ^8.1 || ^8.2 || ^8.3CI passing

Since Mar 25Pushed 11mo ago2 watchersCompare

[ Source](https://github.com/understand/understand-laravel)[ Packagist](https://packagist.org/packages/understand/understand-laravel)[ RSS](/packages/understand-understand-laravel/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (49)Used By (0)

Laravel 5, 6, 7, 8, 9, 10, 11 and 12 integration for Understand.io
------------------------------------------------------------------

[](#laravel-5-6-7-8-9-10-11-and-12-integration-for-understandio)

[![Latest Version on Packagist](https://camo.githubusercontent.com/f498caff6bbdbba42d315899f8f283142df58e9ddd4df1430a1b12cf54901a03/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f756e6465727374616e642f756e6465727374616e642d6c61726176656c352e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/understand/understand-laravel5)[![Quality Score](https://camo.githubusercontent.com/981684bf97b63d9d35135d4c77cefb9a05b0fcc6edd7d7af5dd1bab52fc97a69/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f756e6465727374616e642f756e6465727374616e642d6c61726176656c352e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/understand/understand-laravel5)[![Total Downloads](https://camo.githubusercontent.com/77a7ed148371b592b0b34cd737f4a7018beabff41120903dd250570b539fef73/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f756e6465727374616e642f756e6465727374616e642d6c61726176656c352e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/understand/understand-laravel5)

### Introduction

[](#introduction)

This packages provides a full abstraction for Understand.io and provides extra features to improve Laravel's default logging capabilities. It is essentially a wrapper around Laravel's event handler to take full advantage of Understand.io's data aggregation and analysis capabilities.

### Quick start

[](#quick-start)

1. Add the package to your project

```
composer require understand/understand-laravel

```

2. Add the ServiceProvider to the `providers` array in `config/app.php`

```
Understand\UnderstandLaravel5\UnderstandLaravel5ServiceProvider::class,
```

3. Set your Understand.io input token in your `.env` file

```
UNDERSTAND_ENABLED=true
UNDERSTAND_TOKEN=your-input-token-from-understand-io
```

4. Send your first error

```
// anywhere inside your Laravel app
\Log::error('Understand.io test error');
```

- We recommend that you make use of a async handler - [How to send data asynchronously](#how-to-send-data-asynchronously)
- If you are using Laravel 5.0 (`>= 5.0, < 5.1`) version, please read about - [How to report Laravel 5.0 exceptions](#how-to-report-laravel-50--50--51-exceptions).
- For advanced configuration please read about - [Advanced configuration](#advanced-configuration)
- JavaScript Error Tracking for Laravel - [Understand.io JavaScript library](https://www.understand.io/docs/1.0/laravel/js)

### How to send events/logs

[](#how-to-send-eventslogs)

#### Laravel logs

[](#laravel-logs)

By default, Laravel automatically stores its [logs](http://laravel.com/docs/errors#logging) in `storage/logs`. By using this package, your log data will also be sent to your Understand.io channel. This includes error and exception logs, as well as any log events that you have defined (for example, `Log::info('my custom log')`).

```
\Log::info('my message', ['my_custom_field' => 'my data']);
```

#### PHP/Laravel exceptions

[](#phplaravel-exceptions)

By default, all errors and exceptions with code fragments and stack traces will be sent to Understand.io.

The following extra information will be collected:

TypeDefaultConfig KeyConfig OptionsSQL queriesEnabled`UNDERSTAND_SQL=``true` or `false`SQL query values/bindingsDisabled`UNDERSTAND_SQL_BINDINGS=``true` or `false`HTTP request query string dataEnabled`UNDERSTAND_QUERY_STRING=``true` or `false`HTTP request form or JSON dataEnabled`UNDERSTAND_POST_DATA=``true` or `false`Additionally, you can specify which HTTP request field values should not be sent to Understand.io. By default, the following field values will be hidden:

```
UNDERSTAND_HIDDEN_REQUEST_FIELDS=password,password_confirmation,access_token,secret_key,token,access_key

```

If you wish you can publish the configuration file and make desired adjustments. See [Advanced configuration](#advanced-configuration)

### How to send data asynchronously

[](#how-to-send-data-asynchronously)

##### Async handler

[](#async-handler)

By default each log event will be sent to Understand.io's api server directly after the event happens. If you generate a large number of logs, this could slow your app down and, in these scenarios, we recommend that you make use of an async handler. To do this, set the config parameter `UNDERSTAND_HANDLER` to `async` in your `.env` file.

```
# Specify which handler to use - sync, queue or async.
#
# Note that the async handler will only work in systems where
# the CURL command line tool is installed
UNDERSTAND_HANDLER=async
```

The async handler is supported in most systems - the only requirement is that the CURL command line tool is installed and functioning correctly. To check whether CURL is available on your system, execute following command in your console:

```
curl -h

```

If you see instructions on how to use CURL then your system has the CURL binary installed and you can use the `async` handler.

> Keep in mind that Laravel allows you to specify different configuration values in different environments. You could, for example, use the async handler in production and the sync handler in development.

### How to report Laravel 5.0 (`>= 5.0, < 5.1`) exceptions

[](#how-to-report-laravel-50--50--51-exceptions)

Laravel's (`>= 5.0, < 5.1`) exception logger doesn't use event dispatcher ([laravel/framework#10922](https://github.com/laravel/framework/pull/10922)) and that's why you need to add the following line to your `Handler.php` file (otherwise Laravel's exceptions will not be sent Understand.io).

- Open `app/Exceptions/Handler.php` and put this line `\UnderstandExceptionLogger::log($e)` inside `report` method.

    ```
    public function report(Exception $e)
    {
        \UnderstandExceptionLogger::log($e);

        return parent::report($e);
    }
    ```

### Advanced Configuration

[](#advanced-configuration)

1. Publish configuration file

```
php artisan vendor:publish --provider="Understand\UnderstandLaravel5\UnderstandLaravel5ServiceProvider"

```

### Log Filter

[](#log-filter)

To filter out specific log types a custom log filter can be provided.

**Example filter class**

```
// app/Logging/UnderstandLogFilter.php