BuildThrownAndCalledBy

Description

Use BuildThrownAndCalledBy to build the $formatString and initial $data parameters for ParameterisedException::__construct().

BuildThrownAndCalledBy will add details about:

• the code that is throwing the exception
• and the code that is calling that code

to both the $formatString and $data.

It's intended for use when applying robustness checks to a function or method's input parameters.

Public Interface

BuildThrownAndCalledBy has the following public interface:

// BuildThrownAndCalledBy lives in this namespace
namespace GanbaroDigital\ExceptionHelpers\V1\ParameterBuilders;

class BuildThrownAndCalledBy
{
    /**
     * build an exception message and data, including details of
     * - who is throwing the exception
     * - who called the code that is throwing the exception
     *
     * @param  string $formatString
     *         the message for your exception
     * @param  array $backtrace
     *         the output of debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)
     * @param  array $callerFilter
     *         list of classes to ignore in the backtrace
     * @return array
     *         - [0] is the modified format string
     *         - [1] is the message data
     */
    public static function from(
        $formatString,
        array $backtrace,
        array $callerFilter = []
    );
}

Return Values

BuildThrownAndCalledBy::from() returns an array containing two values:

1. the modified $formatString
2. an array of named parameters to use as ParameterisedException's $data

Use list() to unpack these values:

list($newFormat, $data) = BuildThrownAndCalledBy::from($format, $backtrace);

Modified Format String

The first parameter that you pass to BuildThrownAndCalledBy::from() is a vnsprintf() format string. BuildThrownAndCalledBy::from() takes your format string, and adds the following to the front of it:

%calledByName$s: %thrownByName$s says

For example, if you called BuildThrownAndCalledBy::from() with the format string:

'%fieldOrVarName$s' is less than zero

then BuildThrownAndCalledBy::from() will return a modified format string:

%calledByName$s: %thrownByName$s says '%fieldOrVarName$s' is less than zero

Both %thrownByName$s and %calledByName$s are named parameters. Internally, ParameterisedException::__construct() calls vnsprintf() to expand your final format string. The values of %thrownByName$s and %calledByName$s are in the parameter data. This is the second value returned by BuildThrownAndCalledBy::from().

Parameter Data

The second parameter that you pass to BuildThrownAndCalledBy::from() is a PHP debug_backtrace() result. BuildThrownAndCalledBy::from() examines the backtrace that you provide, and returns an array of named parameters.

How To Use

In A ParameterisedException

The steps are:

1. define your format string
2. create your backtrace
3. pass the format string and backtrace into BuildThrownAndCalledBy::from()
4. BuildThrownAndCalledBy::from() returns an array containing
   • your new format string
   • an array of named parameters and their values
5. add any additional named parameters to the list
6. call ParameterisedException::__construct() to finish building the exception

Here's what this looks like as code:

use GanbaroDigital\ExceptionHelpers\V1\BaseExceptions\
    ParameterisedException;
use GanbaroDigital\ExceptionHelpers\V1\ParameterBuilders\
    BuildThrownAndCalledBy;

class BadInputParameter extends ParameterisedException
{
    /**
     * create a new exception
     *
     * @param  mixed $var
     *         the variable that has the unsupported type
     * @param  string $fieldOrVarName
     *         the name of the input field, PHP variable or
     *         function/method parameter that contains $data
     * @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 BadInputParameter
     *         an fully-built exception for you to throw
     */
    public static function newFromInputParameter(
        $var,
        $fieldOrVarName,
        $typeFlags = null,
        array $callerFilter = []
    )
    {
        // what is our format string?
        $formatString = "'%fieldOrVarName\$s' is a bad input";

        // who called us?
        $backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);

        // build the basic message and data
        list($formatString, $data) = BuildThrownAndCalledBy::from(
            $formatString, $backtrace
        );

        // add in what's unique to us
        $data['dataType'] = GetPrintableType::of($var, $typeFlags);
        $data['fieldOrVarName'] = $fieldOrVarName;

        // all done
        return new static($message, $data);
    }
}

Class Contract

Here is the contract for this class:

GanbaroDigital\ExceptionHelpers\V1\ParameterBuilders\BuildThrownAndCalledBy
 [x] will prepend caller and thrower to message
 [x] will return caller and thrower in data block

Class contracts are built from this class's unit tests.

Notes

None at this time.

See Also

• ParameterisedException - the exception class that this helper builds information for