FilterBacktraceForTwoCodeCallers

Since v1.2016042401

Description

FilterBacktraceForTwoCodeCallers is a data filter. It is a wrapper around FilterBacktrace. It converts FilterBacktrace's return value into an array of two CodeCaller value objects.

FilterBacktraceForTwoCodeCallers was introduced for use in exception error messages in the ganbarodigital/php-mv-defensive package.

Public Interface

FilterBacktraceForTwoCodeCallers has the following public interface:

use GanbaroDigital\ExceptionHelpers\V1\Callers\Filters\FilterBacktraceForTwoCodeCallers;
use GanbaroDigital\ExceptionHelpers\V1\Callers\Values\CodeCaller;

class FilterBacktraceForTwoCodeCallers
{
    /**
     * work out who has called a piece of code, and who (in turn) called that
     * piece of code too
     *
     * @param  array $backtrace
     *         the debug_backtrace() return value
     * @param  array $filterList
     *         a list of namespaces and classes to skip over
     * @return array
     */
    public function __invoke($backtrace, $filterList = []);

    /**
     * work out who has called a piece of code, and who (in turn) called that
     * piece of code too
     *
     * @param  array $backtrace
     *         the debug_backtrace() return value
     * @param  array $filterList
     *         a list of namespaces and classes to skip over
     * @return array
     */
    public static function from($backtrace, $filterList = []);
}

How To Use

FilterBacktraceForTwoCodeCallers can be used as an object, or as a static class method.

// import first
use GanbaroDigital\ExceptionHelpers\V1\Callers\Filters\FilterBacktraceForTwoCodeCallers;

// we need a stack trace
// use DEBUG_BACKTRACE_IGNORE_ARGS to keep the trace very small
$trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);

// we need a list of namespaces to filter out
//
// this can be individual parts of namespaces, or whole classnames
$filterList = [
    'GanbaroDigital\Reflection\V1\Checks',
    'GanbaroDigital\Reflection\V1\Requirements',
    FilterBacktraceForTwoCodeCallers::class,
];

// to use as an object
$filter = new FilterBacktraceForTwoCodeCallers;
$callers = $filter($trace, $filterList);

// to call statically
$callers = FilterBacktraceForTwoCodeCallers::from($trace, $filterList);

Return Value

FilterBacktraceForTwoCodeCallers returns an array of CodeCaller value objects.

  1. The first value object contains details of the code that called you.
  2. The second value object contains details of the code that called that code.

This is very useful in exception messages. It allows your exception to state which bit of code is throwing the exception, and which bit of code caused the exception.

Notes

None at this time.

Changelog

v1.2016052501

See Also