Download the PHP package code-distortion/clarity-control without Composer
On this page you can find all versions of the php package code-distortion/clarity-control. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download code-distortion/clarity-control
More information about code-distortion/clarity-control
Files in code-distortion/clarity-control
Package clarity-control
Short Description A Laravel package to catch and log exceptions with a fluent interface
License MIT
Homepage https://github.com/code-distortion/clarity-control
Informations about the package clarity-control
Clarity Control - Handle Your Exceptions
code-distortion/clarity-control is a Laravel package that lets you catch and log exceptions with a fluent interface.
Clarity Suite
Clarity Control 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
- Config File
- Catching Exceptions
- Configuring The Way Exceptions Are Caught
- Note About Logging
- Log Channel
- Log Level
- Default Return Value
- Catching Selectively
- Recording "Known" Issues
- Disabling Logging
- Re-throwing Exceptions
- Suppressing Exceptions
- Callbacks
- Using The Context Object in Callbacks
- Suppressing Exceptions On The Fly
- Global Callbacks
- Advanced Catching
- Retrieving Exceptions
Installation
Install the package via composer:
Config File
Use the following command if you would like to publish the config/code_distortion.clarity_control.php
config file:
Catching Exceptions
Clarity Control deals with flow control. Which is to say, it provides ways to catch and manage exceptions.
Whilst you can still use try / catch statements of course, you can write them this way instead:
Control will run the callable passed to Control::run(…)
. If an exception occurs, it will be caught and reported using Laravel's report()
helper.
The code following it will continue to run afterwards.
Tip: Laravel's dependency injection system is used to run your callable. Just type-hint your parameters and they'll be resolved for you.
Configuring The Way Exceptions Are Caught
Another way to write this is to call Control::prepare($callable)
, and then ->execute()
afterwards.
These are the same, except that when using Control::prepare($callable)
and ->execute()
, there's an opportunity to set some configuration values in-between…
Here is the list of the methods you can use to configure the way Control catches exceptions (they're explained in more detail below):
Note About Logging
This package uses Clarity Context, and some settings require a logger that's also aware of Clarity Context (such as Clarity Logger) to work. Specifically, the channel, log level, and "known" issue settings won't appear anywhere otherwise.
These details are added to the Context
object that Clarity Context produces when an exception occurs. And it's up to the logger to use its values.
See Clarity Context for more information about this Context
object.
See Clarity Logger for a logger that understands the Context
object.
Log Channel
You can specify which Laravel log-channel you'd like to log to. The possible values come from your projects' config/logging.php
file.
You can specify more than one if you'd like.
Note: This setting requires a logging tool that's aware of Clarity. See the Note About Logging for more information.
See Laravel's documentation about logging for more information about Log Channels.
Log Level
You can specify the reporting level you'd like to use when logging.
Note: This setting requires a logging tool that's aware of Clarity. See the Note About Logging for more information.
See Laravel's documentation about logging for more information about Log Levels.
Default Return Value
You can specify the default value to return when an exception occurs by passing a second parameter to Control::run()
or Control::prepare()
.
You can also call ->default()
after calling Control::prepare()
Tip: If the default value is callable, Control will run it (when needed) to resolve the value.
Catching Selectively
You can choose to only catch certain types of exceptions. Other exceptions will ignored.
You can specify multiple exception classes, match-strings or regexes.
When you specify match()
and matchRegex()
, only one of them needs to match the exception message.
Recording "Known" Issues
If you use an issue management system like Jira, you can make a note of the issue/task the exception relates to:
This gives you an opportunity to label exceptions while the fix is being worked on.
Note: This setting requires a logging tool that's aware of Clarity. See the Note About Logging for more information.
Disabling Logging
You can disable the reporting of exceptions once caught. This will stop report()
from being triggered.
Re-throwing Exceptions
If you'd like caught exceptions to be detected and reported, but re-thrown again afterwards, you can tell Control to rethrow them:
If you'd like to rethrow a different exception, you can pass a closure to make the decision. It must return a Throwable / Exception, or true / false.
Suppressing Exceptions
If you'd like to stop exceptions from being reported and rethrown once caught, you can suppress them altogether.
Callbacks
You can add a custom callback to be run when an exception is caught. This can be used to either do something when an exception occurs, or to decide if the the exception should be "suppressed".
You can add multiple callbacks if you like.
Tip: Laravel's dependency injection is used to run your callback. Just type-hint your parameters, like in the example above.
Extra parameters you can use are:
- The exception: when the parameter is named
$e
or$exception
- The
Context
object: when type-hinted withCodeDistortion\ClarityContext\Context
Using The Context Object in Callbacks
When you type-hint a callback parameter with CodeDistortion\ClarityContext\Context
, you'll receive the Context
object populated with details about the exception.
This is the same Context object from the Clarity Context package, and is designed to be used in app/Exceptions/Handler.php
when reporting an exception. See Clarity Context's documentation for more information.
As well as reading values from the Context object, you can update some of its values inside your callback. This lets you alter what happens on-the-fly.
Suppressing Exceptions On The Fly
You can suppress an exception by calling $context->suppress()
inside your callback.
This will also happen if your callback sets $context->setReport(false)
and $context->setRethrow(false)
.
Tip: Callbacks are run in the order they were specified. Subsequent callbacks won't be called when the exception is suppressed.
Global Callbacks
You can tell Control to run a "global" callback whenever it catches an exception. You can add as many as you need.
These callbacks are run before the regular (non-global) callbacks.
A good place to set one up would be in a service provider. See Laravel's documentation for more information about service providers.
Finally
You can specify a callable to run after the execution of the main $callable
by passing a third parameter to Control::run()
or Control::prepare()
.
You can also call ->finally()
after calling Control::prepare()
Tip: Laravel's dependency injection system is used to run your callable. Just type-hint your parameters and they'll be resolved for you.
Advanced Catching
You can choose to do different things when different exceptions are caught.
To do this, configure a CodeDistortion\ClarityControl\CatchType
object, and pass that to $clarity->catch()
instead of
passing the exception class string.
CatchType
objects can be customised with the same settings as the Control
object. They're all optional, and can be called in any order.
CatchTypes are checked in the order they were specified. The first one that matches the exception is used.
Retrieving Exceptions
If you'd like to obtain the exception, you can call getException()
and pass a variable by reference. When an exception occurs, it will contain the exception afterwards. Otherwise it's set to null.
The exception will be set, even if the exception was suppressed.
Testing This Package
- Clone this package:
git clone https://github.com/code-distortion/clarity-control.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 [email protected] instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.
All versions of clarity-control with dependencies
code-distortion/clarity-context Version ^0.1.0
code-distortion/staticall Version ^0.1.0