BadAssuranceArgs

Description

BadAssuranceArgs is an exception. It is thrown when the list of assurances' arguments passed into EnsureAllOf or EnsureAnyOneOf isn't an array.

Public Interface

BadAssuranceArgs has the following public interface:

// BadAssuranceArgs 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 BadAssuranceArgs
  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 BadAssuranceArgs
     *         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 BadAssuranceArgs
     *         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\BadAssuranceArgs;

throw BadAssuranceArgs::newFromVar($args, '$args');

BadAssuranceArgs provides different factory methods for different situations:

Instead of creating new instances of BadAssuranceArgs 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['BadAssuranceArgs::newFromInputParameter']($args, '$args');

Catching The Exception

BadAssuranceArgs 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 BadAssuranceArgs exceptions
use GanbaroDigital\Defensive\V1\Exceptions\BadAssuranceArgs;

try {
    throw BadAssuranceArgs::newFromVar($args, '$args');
}
catch(BadAssuranceArgs $e) {
    // ...
}

// example 2: catch all exceptions thrown by the Defensive Library
use GanbaroDigital\Defensive\V1\Exceptions\BadAssuranceArgs;
use GanbaroDigital\Defensive\V1\Exceptions\DefensiveException;

try {
    throw BadAssuranceArgs::newFromVar($args, '$args');
}
catch(DefensiveException $e) {
    // ...
}

// example 3: catch all exceptions where there was an unexpected problem
use GanbaroDigital\Defensive\V1\Exceptions\BadAssuranceArgs;
use GanbaroDigital\HttpStatus\Interfaces\HttpRuntimeErrorException;

try {
    throw BadAssuranceArgs::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\BadAssuranceArgs;
use GanbaroDigital\HttpStatus\Interfaces\HttpException;

try {
    throw BadAssuranceArgs::newFromVar($args, '$args');
}
catch(HttpException $e) {
    $httpStatus = $e->getHttpStatus();
    // ...
}

// example 5: catch all runtime exceptions
use GanbaroDigital\Defensive\V1\Exceptions\BadAssuranceArgs;
use RuntimeException;

try {
    throw BadAssuranceArgs::newFromVar($args, '$args');
}
catch(RuntimeException $e) {
    // ...
}

Exception Data

BadAssuranceArgs is a ParameterisedException. It contains extra data for you to write to your logs or inspect in your debugger of choice.

try {
    throw BadAssuranceArgs::newFromInputParameter($args, '$args');
}
catch (BadAssuranceArgs $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.

Here's a list of the extra data added by each factory method.

Class Contract

Here is the contract for this class:

GanbaroDigital\Defensive\V1\Exceptions\BadAssuranceArgs
 [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.

Notes

None at this time.

See Also

• ParameterisedException class
• mapping exceptions onto HTTP status codes