NotAFactory
Since v1.2016050901
Description
NotAFactory
is an exception. It is thrown when we were expecting a factory (a PHP callable
) but were given something else instead.
Public Interface
NotAFactory
has the following public interface:
// NotAFactory lives in this namespace
namespace GanbaroDigital\DIContainers\V1\Exceptions;
// our base classes and interfaces
use GanbaroDigital\ExceptionHelpers\V1\BaseExceptions\ParameterisedException;
use GanbaroDigital\DIContainers\V1\Exceptions\DIContainersException;
use GanbaroDigital\HttpStatus\Interfaces\HttpRuntimeErrorException;
// return type(s) for our methods
use GanbaroDigital\HttpStatus\StatusValues\RuntimeError\UnexpectedErrorStatus;
class NotAFactory
extends ParameterisedException
implements DIContainersException, HttpRuntimeErrorException
{
// adds 'getHttpStatus()' that returns a HTTP 500 status value object
use UnexpectedErrorStatusProvider;
/**
* create a new exception
*
* @param string $factoryName
* the name that the bad factory was given
* @param mixed $badFactory
* the non-callable that we were given
* @param int|null $typeFlags
* do we want any extra type information in the final exception message?
* @param array $callerFilter
* are there any namespaces we want to filter out of the call stack?
* @return NotAFactory
* an fully-built exception for you to throw
*/
public static function newFromNonCallable(
$factoryName,
$badFactory,
$typeFlags = null,
array $callerFilter = []
);
/**
* 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 NotAFactory::newFromNonCallable()
to create a new exception that you can throw:
use GanbaroDigital\ExceptionHelpers\V1\Exceptions\NotAFactory;
throw NotAFactory::newFromNonCallable("trout");
Catching The Exception
NotAFactory
implements a rich set of classes and interfaces. You can use any of these to catch this exception.
// example 1: we catch only NotAFactory exceptions
use GanbaroDigital\DIContainers\V1\Exceptions\NotAFactory;
try {
throw NotAFactory::newFromNonCallable("trout");
}
catch(NotAFactory $e) {
// ...
}
// example 2: catch all exceptions thrown by the Dependency-Injection Containers Library
use GanbaroDigital\DIContainers\V1\Exceptions\NotAFactory;
use GanbaroDigital\DIContainers\V1\Exceptions\DIContainersException;
try {
throw NotAFactory::newFromNonCallable("trout");
}
catch(DIContainersException $e) {
// ...
}
// example 3: catch all exceptions where something went wrong that
// should never happen
use GanbaroDigital\DIContainers\V1\Exceptions\NotAFactory;
use GanbaroDigital\HttpStatus\Interfaces\HttpRuntimeErrorException;
try {
throw NotAFactory::newFromNonCallable("trout");
}
catch(HttpRuntimeErrorException $e) {
$httpStatus = $e->getHttpStatus();
// ...
}
// example 4: catch all exceptions that map onto a HTTP status
use GanbaroDigital\DIContainers\V1\Exceptions\NotAFactory;
use GanbaroDigital\HttpStatus\Interfaces\HttpException;
try {
throw NotAFactory::newFromNonCallable("trout");
}
catch(HttpException $e) {
$httpStatus = $e->getHttpStatus();
// ...
}
// example 5: catch all runtime exceptions
use GanbaroDigital\DIContainers\V1\Exceptions\NotAFactory;
use RuntimeException;
try {
throw NotAFactory::newFromNonCallable("trout");
}
catch(RuntimeException $e) {
// ...
}
Class Contract
Here is the contract for this class:
GanbaroDigital\DIContainers\V1\Exceptions\NotAFactory
[x] Can instantiate
[x] Is d i containers exception
[x] Is parameterised exception
[x] Is runtime exception
[x] Is http runtime error exception
[x] Maps to unexpected error status
[x] Can build from non callables
[x] Exception message contains caller
[x] Exception message contains exception alias
[x] Exception message contains type of bad factory
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.
Changelog
v1.2016060601
-
$callerFilter
signature changedThe
$callerFilter
parameter is now type-hinted as an array, and can no longer beNULL
.If no
$callerFilter
parameter is provided, it now defaults to an empty list. It no longer defaults toFilterCodeCaller::$DEFAULT_PARTIALS
; that list no longer exists.These changes were made to make this class compatible with the latest
Exception Helpers Library
.
See Also
FactoryList
- interface for a dependency-injection container for factoriesFactoryListContainer
- dependency-injection container for factories