code-distortion / clarity-logger
A Laravel package that generates useful logs
Requires
- php: 8.0.* | 8.1.* | 8.2.* | 8.3.*
- code-distortion/staticall: ^0.1.0
Requires (Dev)
- code-distortion/clarity-context: ^0.1.0
- code-distortion/clarity-control: ^0.1.0
- infection/infection: ^0.10 | ^0.11 | ^0.12 | ^0.13 | ^0.14 | ^0.15 | ^0.16 | ^0.17 | ^0.18 | ^0.19 | ^0.20 | ^0.21 | ^0.22 | ^0.23 | ^0.24 | ^0.25 | ^0.26 | ^0.27
- orchestra/testbench: ^6.12 | ^7.0 | ^8.0
- phpstan/phpstan: ^0.9 | ^0.10 | ^0.11 | ^0.12 | ^1.0
- phpunit/phpunit: ~4.8 | ^5.0 | ^6.0 | ^7.0 | ^8.4 | ^9.0 | ^10.0
- squizlabs/php_codesniffer: ^3.8.0
Suggests
- code-distortion/clarity-context: Understand Your Exceptions. Part of the Clarity Suite
- code-distortion/clarity-control: Handle Your Exceptions. Part of the Clarity Suite
README
code-distortion/clarity-logger is a Laravel package that generates useful exception logs.
EXCEPTION (CAUGHT):
exception Illuminate\Http\Client\ConnectionException: "cURL error 6: Could not resolve host: api.example-gateway.com (see https://curl.haxx.se/libcurl/c/libcurl-errors.html) for https://api.example-gateway.com"
- location app/Http/Controllers/CheckoutController.php on line 50 (method "submit")
- vendor vendor/laravel/framework/src/Illuminate/Http/Client/PendingRequest.php on line 856 (closure)
request POST https://my-website.com/checkout
- referrer https://my-website.com/checkout
- route cart.checkout
- middleware web
- action CheckoutController@submit
user 3342 - Bob - bob@example.com (123.123.123.123)
- agent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36
date/time Sunday 2nd April at 7:08pm (Australia/Sydney) 2023-04-02 19:08:23 AEST +10:00
Clarity Suite
Clarity Logger is a part of the Clarity Suite, designed to let you manage exceptions more easily:
- Clarity Context - Understand Your Exceptions
- Clarity Logger - Useful Exception Logs
- Clarity Control - Handle Your Exceptions
Table of Contents
Installation
Install the package via composer:
composer require code-distortion/clarity-logger
Config File
Use the following command if you would like to publish the config/code_distortion.clarity_logger.php
config file:
php artisan vendor:publish --provider="CodeDistortion\ClarityLogger\ServiceProvider" --tag="config"
Update Your Exception Handler
Laravel projects use an exception handler class to log exceptions. You'll need to update this so Clarity Logger can log exceptions.
Add the following to the register()
method of app/Exceptions/Handler.php
.
If you use them, Laravel's own context details can be included by adding $this->exceptionContext($e)
.
By default, Laravel adds the PHP's stacktrace to the log afterwards. You can turn this off if you like by adding ->stop()
.
// app/Exceptions/Handler.php namespace App\Exceptions; use CodeDistortion\ClarityLogger\Logger; // <<< use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler; use Throwable; class Handler extends ExceptionHandler { … /** * Register the exception handling callbacks for the application. */ public function register(): void { $this->reportable(function (Throwable $e) { Logger::log($e, $this->exceptionContext($e)); // <<< })->stop(); // <<< } }
Laravel will now log exceptions using Clarity Logger.
See Laravel's documentation for more information about exception handling.
Manual Logging
If you catch an exception, or would like to just log a message, you can trigger the logging yourself:
Logger::log($exception); Logger::log('message');
You can specify the reporting level:
Logger::debug($exception); // or ::debug('message') Logger::info($exception); // or ::info('message') Logger::notice($exception); // or ::notice('message') Logger::warning($exception); // or ::warning('message') Logger::error($exception); // or ::error('message') Logger::critical($exception); // or ::critical('message') Logger::alert($exception); // or ::alert('message') Logger::emergency($exception); // or ::emergency('message') // or Logger::level(Settings::REPORTING_LEVEL_INFO)->log($exception); // or ->log('message');
If you'd like to log to a particular channel, specify it before triggering the log action:
Logger::channel('slack')->log($exception);
These methods can be chained:
Logger::channel('slack')->debug()->log($exception); Logger::emergency()->channel('slack')->log('message');
Adding Some Context
If you add Clarity Context to your project (which lets you add context details to your code), Clarity Logger will include your context details automatically.
This can be a powerful tool when debugging exceptions. e.g.
EXCEPTION (UNCAUGHT):
exception Illuminate\Http\Client\ConnectionException: "cURL error 6: Could not resolve host: api.example-gateway.com (see https://curl.haxx.se/libcurl/c/libcurl-errors.html) for https://api.example-gateway.com"
- location app/Http/Controllers/CheckoutController.php on line 50 (method "submit")
- vendor vendor/laravel/framework/src/Illuminate/Http/Client/PendingRequest.php on line 856 (closure)
request POST https://my-website.com/checkout
- referrer https://my-website.com/checkout
- route cart.checkout
- middleware web
- action CheckoutController@submit
- trace-id 1234567890
user 3342 - Bob - bob@example.com (123.123.123.123)
- agent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36
date/time Sunday 2nd April at 7:08pm (Australia/Sydney) 2023-04-02 19:08:23 AEST +10:00
CONTEXT:
app/Domain/Checkout/PerformCheckoutAction.php on line 20 (method "handle")
- "Performing checkout"
- user-id = 5
- order-id = 123
app/Domain/Payments/MakePaymentAction.php on line 19 (method "handle") (last application frame)
- "Sending payment request to gateway"
- payment-gateway = 'examplexyz.com'
- card-id = 456
- amount = '10.99'
vendor/laravel/framework/src/Illuminate/Http/Client/PendingRequest.php on line 856 (closure)
- The exception was thrown
Testing This Package
- Clone this package:
git clone https://github.com/code-distortion/clarity-logger.git .
- Run
composer install
to install dependencies - Run the tests:
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
SemVer
This library uses SemVer 2.0.0 versioning. This means that changes to X
indicate a breaking change: 0.0.X
, 0.X.y
, X.y.z
. When this library changes to version 1.0.0, 2.0.0 and so forth, it doesn't indicate that it's necessarily a notable release, it simply indicates that the changes were breaking.
Treeware
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Contributing
Please see CONTRIBUTING for details.
Code of Conduct
Please see CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email tim@code-distortion.net instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.