BadCheckArgs
Since v1.2016082401
Description
BadCheckArgs
is an exception. It is thrown when the list of arguments passed into IsAllOf
or IsAnyOneOf
isn't an array.
Public Interface
BadCheckArgs
has the following public interface:
// BadCheckArgs 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 BadCheckArgs
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 BadCheckArgs
* 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 BadCheckArgs
* 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\BadCheckArgs;
throw BadCheckArgs::newFromVar($args, '$args');
BadCheckArgs
provides different factory methods for different situations:
Factory Method | When To Use |
---|---|
BadCheckArgs::newFromInputParameter() |
when $fieldOrVar was passed to your function or method as a parameter |
BadCheckArgs::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 BadCheckArgs
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['BadCheckArgs::newFromInputParameter']($args, '$args');
Catching The Exception
BadCheckArgs
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 BadCheckArgs exceptions
use GanbaroDigital\Defensive\V1\Exceptions\BadCheckArgs;
try {
throw BadCheckArgs::newFromVar($args, '$args');
}
catch(BadCheckArgs $e) {
// ...
}
// example 2: catch all exceptions thrown by the Defensive Library
use GanbaroDigital\Defensive\V1\Exceptions\BadCheckArgs;
use GanbaroDigital\Defensive\V1\Exceptions\DefensiveException;
try {
throw BadCheckArgs::newFromVar($args, '$args');
}
catch(DefensiveException $e) {
// ...
}
// example 3: catch all exceptions where there was an unexpected problem
use GanbaroDigital\Defensive\V1\Exceptions\BadCheckArgs;
use GanbaroDigital\HttpStatus\Interfaces\HttpRuntimeErrorException;
try {
throw BadCheckArgs::newFromVar($args, '$args');
}
catch(HttpRuntimeErrorException $e) {
$httpStatus = $e->getHttpStatus();
// ...
}
// example 4: catch all exceptions that map onto a HTTP status
use GanbaroDigital\Defensive\V1\Exceptions\BadCheckArgs;
use GanbaroDigital\HttpStatus\Interfaces\HttpException;
try {
throw BadCheckArgs::newFromVar($args, '$args');
}
catch(HttpException $e) {
$httpStatus = $e->getHttpStatus();
// ...
}
// example 5: catch all runtime exceptions
use GanbaroDigital\Defensive\V1\Exceptions\BadCheckArgs;
use RuntimeException;
try {
throw BadCheckArgs::newFromVar($args, '$args');
}
catch(RuntimeException $e) {
// ...
}
Exception Data
BadCheckArgs
is a ParameterisedException
. It contains extra data for you to write to your logs or inspect in your debugger of choice.
try {
throw BadCheckArgs::newFromInputParameter($args, '$args');
}
catch (BadCheckArgs $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 |
---|---|
BadCheckArgs::newFromInputParameter() |
thrownBy , thrownByName , calledBy , calledByName , fieldOrVarName , fieldOrVar , dataType |
BadCheckArgs::newFromVar() |
thrownBy , thrownByName , fieldOrVarName , fieldOrVar , dataType |
Class Contract
Here is the contract for this class:
GanbaroDigital\Defensive\V1\Exceptions\BadCheckArgs
[x] Can instantiate
[x] is DefensiveException
[x] is RuntimeException
[x] is HttpStatusProvider
[x] maps to HTTP 500 UnexpectedError
[x] Can create from bad assurance args
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.