EnsureAnyOneOf

Description

EnsureAnyOneOf allows you to apply a list of assurances to a piece of data. If none of the assurances are met, an exception is thrown.

EnsureAnyOneOf is a customisable function object.

Public Interface

EnsureAnyOneOf has the following public interface:

// EnsureAnyOneOf lives in this namespace
namespace GanbaroDigital\Defensive\V1\Assurances;

// EnsureAnyOneOf is an Assurance
use GanbaroDigital\Defensive\V1\Interfaces\Assurance;
// EnsureAnyOneOf is a ListAssurance
use GanbaroDigital\Defensive\V1\Interfaces\ListAssurance;

// our input and return type(s)
use GanbaroDigital\DIContainers\V1\Interfaces\FactoryList;

class EnsureAnyOneOf implements Assurance, ListAssurance
{
    /**
     * create an Assurance that is ready to execute
     *
     * @param array $assurances
     *        a list of the assurances to apply
     * @param FactoryList|null $exceptions
     *        the functions to call when we want to throw an exception
     * @return EnsureAnyOneOf
     */
    public static function apply($assurances, FactoryList $exceptions = null);

    /**
     * throws exception if none of our assurances are met
     *
     * @param  mixed $data
     *         the data to be examined by each assurance in turn
     * @param  string $fieldOrVarName
     *         what is the name of $data in the calling code?
     * @return void
     */
    public function __invoke($data, $fieldOrVarName = "value");

    /**
     * throws exception if none of our assurances are met
     *
     * @param  mixed $data
     *         the data to be examined by each assurance in turn
     * @param  string $fieldOrVarName
     *         what is the name of $data in the calling code?
     * @return void
     */
    public function to($data, $fieldOrVarName = "value");

    /**
     * throws exceptions if any of our assurances are not met
     *
     * this is an alias of toList() for readability
     *
     * @param  mixed $list
     *         the data to be examined by each assurance in turn
     * @param  string $fieldOrVarName
     *         what is the name of $list in the calling code?
     * @return void
     */
    public function inspectList($list, $fieldOrVarName = "value");

    /**
     * throws exceptions if any of our assurances are not met
     *
     * the inspection defined in the to() method is applied to every element
     * of the list passed in
     *
     * @param  mixed $list
     *         the data to be examined by each assurance in turn
     * @param  string $fieldOrVarName
     *         what is the name of $list in the calling code?
     * @return void
     */
    public function toList($list, $fieldOrVarName = "value");
}

How To Use

Applying Assurances

Use the ::apply()->to() pattern:

$assurances = [
    // a list of objects that implement the 'Assurance' interface
];
EnsureAnyOneOf::apply($assurances)->to($data, '$data');

Use EnsureAnyOneOf to catch bugs in your code:

function doSomething($arg1)
{
    // do some work
    // ...

    // assurance!
    $assurances = [
        new EnsureString(),
        new EnsureNull()
    ];
    EnsureAnyOneOf::apply($assurances)->to($retval, '$retval');

    // if we get here, then we can return $retval
    return $retval;
}

If none of the assurances are met, EnsureAnyOneOf will throw an exception.

Applying Assurances To Lists Of Data

Use the ::apply()->toList() pattern:

$assurances = [
    // a list of objects that implement the 'Assurance' interface
];
EnsureAnyOneOf::apply($assurances)->toList($list, '$list');

Use EnsureAnyOneOf to catch bugs in your code:

function doSomething($arg1)
{
    // do some work
    // ...

    // assurance!
    $assurances = [
        new EnsureString(),
        new EnsureNull()
    ];
    EnsureAnyOneOf::apply($assurances)->toList($retval, '$retval');

    // if we get here, then we can return $retval
    return $retval;
}

If none of the assurances are met, EnsureAnyOneOf will throw an exception.

Class Contract

Here is the contract for this class:

GanbaroDigital\Defensive\V1\Assurances\EnsureAnyOneOf
 [x] Can instantiate
 [x] is Assurance
 [x] Can use as object
 [x] Can call statically
 [x] Must provide a list of assurances
 [x] Assurances list must contain valid assurances
 [x] Will match any assurance given
 [x] Throws exception if nothing matches
 [x] can apply to a data list
 [x] throws InvalidArgumentException if non list passed to toList

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

Notes

None at this time.

Changelog

v1.2016081301

• now implements ListAssurance

See Also

• Assurance interface
• ListAssurance interface