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.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package clarity-control

Clarity Control - Handle Your Exceptions

Latest Version on Packagist PHP Version Laravel GitHub Workflow Status Buy The World a Tree

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:


Table of Contents

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 with CodeDistortion\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

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

PHP Build Version
Package Version
Requires php Version 8.0.* | 8.1.* | 8.2.* | 8.3.*
code-distortion/clarity-context Version ^0.1.0
code-distortion/staticall Version ^0.1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package code-distortion/clarity-control contains the following files

Loading the files please wait ....