BadAssurance
Since v1.2016062801
Description
BadAssurance
is an exception. It is thrown when one of the assurances passed into EnsureAllOf
or EnsureAnyOneOf
isn't an Assurance
.
Public Interface
BadAssurance
has the following public interface:
// BadAssurance lives in this namespace
namespace GanbaroDigital\Defensive\V1\Exceptions;
// our base class and interface(s)
use GanbaroDigital\ExceptionHelpers\V1\BaseExceptions\ParameterisedException;
use GanbaroDigital\HttpStatus\Interfaces\HttpRuntimeErrorException;
// return types from our method(s)
use GanbaroDigital\HttpStatus\StatusValues\RuntimeError\UnexpectedErrorStatus;
class BadAssurance
extends ParameterisedException
implements DefensiveException, HttpRuntimeErrorException
{
// we map onto HTTP 500
use UnexpectedErrorStatusProvider;
/**
* create a new exception about your function / method's input parameter
*
* @param mixed $fieldOrVar
* the input parameter that you're throwing an exception about
* @param string $fieldOrVarName
* the name of the input parameter in your code
* @param array $extraData
* extra data that you want to include in your exception
* @param int|null $typeFlags
* do we want any extra type information in the final
* exception message?
* @param array $callStackFilter
* are there any namespaces we want to filter out of
* the call stack?
* @return BadAssurance
* an fully-built exception for you to throw
*/
public static function newFromInputParameter(
$fieldOrVar,
$fieldOrVarName,
array $extraData = [],
$typeFlags = null,
array $callStackFilter = []
);
/**
* create a new exception about a value generated by / returned to your
* function or method
*
* @param mixed $fieldOrVar
* the value that you're throwing an exception about
* @param string $fieldOrVarName
* the name of the value in your code
* @param array $extraData
* extra data that you want to include in your exception
* @param int|null $typeFlags
* do we want any extra type information in the final
* exception message?
* @param array $callStackFilter
* are there any namespaces we want to filter out of
* the call stack?
* @return BadAssurance
* an fully-built exception for you to throw
*/
public static function newFromVar(
$fieldOrVar,
$fieldOrVarName,
array $extraData = [],
$typeFlags = null,
array $callStackFilter = []
);
/**
* what was the data that we used to create the printable message?
*
* @return array
*/
public function getMessageData();
/**
* what was the format string we used to create the printable message?
*
* @return string
*/
public function getMessageFormat();
/**
* which HTTP status code do we map onto?
*
* @return UnexpectedErrorStatus
*/
public function getHttpStatus();
}
How To Use
Creating Exceptions To Throw
Call one of the factory methods to create a new throwable exception:
// how to import
use GanbaroDigital\Defensive\V1\Exceptions\BadAssurance;
throw BadAssurance::newFromVar($assurance, '$assurance');
BadAssurance
provides different factory methods for different situations:
Factory Method | When To Use |
---|---|
BadAssurance::newFromInputParameter() |
when $fieldOrVar was passed to your function or method as a parameter |
BadAssurance::newFromVar() |
when $fieldOrVar is the return value from calling a function or method, or is a value created by your function or method |
Instead of creating new instances of BadAssurance
directly, you should use the DefensiveExceptions
dependency-injection container instead. This helps other libraries with their encapsulation support.
// how to import
use GanbaroDigital\Defensive\V1\Exceptions\DefensiveExceptions;
$diContainer = new DefensiveExceptions;
throw $diContainer['BadAssurance::newFromInputParameter']($assurance, '$assurance');
Catching The Exception
BadAssurance
extends or implements a rich set of classes and interfaces. You can use any of these to catch thrown exceptions.
// example 1: we catch only BadAssurance exceptions
use GanbaroDigital\Defensive\V1\Exceptions\BadAssurance;
try {
throw BadAssurance::newFromVar($assurance, '$assurance');
}
catch(BadAssurance $e) {
// ...
}
// example 2: catch all exceptions thrown by the Defensive Library
use GanbaroDigital\Defensive\V1\Exceptions\BadAssurance;
use GanbaroDigital\Defensive\V1\Exceptions\DefensiveException;
try {
throw BadAssurance::newFromVar($assurance, '$assurance');
}
catch(DefensiveException $e) {
// ...
}
// example 3: catch all exceptions where there was an unexpected problem
use GanbaroDigital\Defensive\V1\Exceptions\BadAssurance;
use GanbaroDigital\HttpStatus\Interfaces\HttpRuntimeErrorException;
try {
throw BadAssurance::newFromVar($assurance, '$assurance');
}
catch(HttpRuntimeErrorException $e) {
$httpStatus = $e->getHttpStatus();
// ...
}
// example 4: catch all exceptions that map onto a HTTP status
use GanbaroDigital\Defensive\V1\Exceptions\BadAssurance;
use GanbaroDigital\HttpStatus\Interfaces\HttpException;
try {
throw BadAssurance::newFromVar($assurance, '$assurance');
}
catch(HttpException $e) {
$httpStatus = $e->getHttpStatus();
// ...
}
// example 5: catch all runtime exceptions
use GanbaroDigital\Defensive\V1\Exceptions\BadAssurance;
use RuntimeException;
try {
throw BadAssurance::newFromVar($assurance, '$assurance');
}
catch(RuntimeException $e) {
// ...
}
Exception Data
BadAssurance
is a ParameterisedException
. It contains extra data for you to write to your logs or inspect in your debugger of choice.
try {
throw BadAssurance::newFromInputParameter($data, '$data');
}
catch (BadAssurance $e) {
// extract the extra data
// getMessageData() returns a PHP array
$exData = $e->getMessageData();
}
Here's the full list of the extra data available in this exception.
Parameter | Type | Description |
---|---|---|
thrownBy |
CodeCaller |
details of the function or method that is throwing the exception |
thrownByName |
string | human-readable summary of thrownBy |
calledBy |
CodeCaller |
details of the function or method that has called the thrownBy function or method |
calledByName |
string | human-readable summary of calledBy |
fieldOrVarName |
string | the $fieldOrVarName passed into the factory method |
fieldOrVar |
mixed | the $fieldOrVar passed into the factory method |
dataType |
string | human-readable description of $fieldOrVar |
Here's a list of the extra data added by each factory method.
Factory Method | Extra Data Added |
---|---|
BadAssurance::newFromInputParameter() |
thrownBy , thrownByName , calledBy , calledByName , fieldOrVarName , fieldOrVar , dataType |
BadAssurance::newFromVar() |
thrownBy , thrownByName , fieldOrVarName , fieldOrVar , dataType |
Class Contract
Here is the contract for this class:
GanbaroDigital\Defensive\V1\Exceptions\BadAssurance
[x] Can instantiate
[x] is DefensiveException
[x] is RuntimeException
[x] is HttpStatusProvider
[x] maps to HTTP 500 UnexpectedError
[x] Can create from bad assurance
Class contracts are built from this class's unit tests.
Future releases of this class may add to this contract. New additions may include:
- clarifying existing behaviour (e.g. stricter contract around input or return types)
- add new behaviours (e.g. extra class methods)
When you use this class, you can only rely on the behaviours documented by this contract.
If you:
- find other ways to use this class,
- or depend on behaviours that are not covered by a unit test,
- or depend on undocumented internal states of this class,
... your code may not work in the future.
Notes
None at this time.