BadAssurancesList

Description

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

Public Interface

BadAssurancesList has the following public interface:

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

throw BadAssurancesList::newFromVar($list, '$list');

BadAssurancesList provides different factory methods for different situations:

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

Catching The Exception

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

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

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

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

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

try {
    throw BadAssurancesList::newFromVar($list, '$list');
}
catch(HttpRuntimeErrorException $e) {
    $httpStatus = $e->getHttpStatus();
    // ...
}

// example 4: catch all exceptions that map onto a HTTP status
use GanbaroDigital\Defensive\V1\Exceptions\BadAssurancesList;
use GanbaroDigital\HttpStatus\Interfaces\HttpException;

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

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

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

Exception Data

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

try {
    throw BadAssurancesList::newFromInputParameter($list, '$list');
}
catch (BadAssurancesList $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\BadAssurancesList
 [x] Can instantiate
 [x] is DefensiveException
 [x] is RuntimeException
 [x] is HttpRuntimeErrorException
 [x] maps to HTTP 500 UnexpectedError
 [x] Can create from bad assurances list
 [x] exception states that list must contain callables

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