RequireValidAssurances

Description

Use RequireValidAssurances to ensure that you have a list that only contains valid assurances. If this requirement is not met, an exception is thrown.

RequireValidAssurances is a customisable function object.

Public Interface

RequireValidAssurances has the following public interface:

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

// RequireValidAssurances is a ListRequirement
use GanbaroDigital\Defensive\V1\Interfaces\ListRequirement;

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

class RequireValidAssurances implements ListRequirement
{
    /**
     * create a ListRequirement that is ready to execute
     *
     * @param  FactoryList|null $exceptions
     *         the functions to call when we want to throw an exception
     * @return RequireValidAssurances
     */
    public function __construct(FactoryList $exceptions = null);

    /**
     * create a Requirement that is ready to execute
     *
     * @param  FactoryList|null $exceptions
     *         the functions to call when we want to throw an exception
     * @return RequireValidAssurances
     */
    public static function apply(FactoryList $exceptions = null);

    /**
     * throws exception if our inspection fails
     *
     * @inheritedFrom ListRequirement
     *
     * @param  mixed $fieldOrVar
     *         the data to be examined
     * @param  string $fieldOrVarName
     *         what is the name of $fieldOrVar in the calling code?
     * @return void
     */
    public function to($fieldOrVar, $fieldOrVarName = "value");

    /**
     * throws exception if our inspection fails
     *
     * the inspection defined in the to() method is applied to every element
     * of the list passed in
     *
     * @inheritedFrom ListRequirement
     *
     * @param  mixed $fieldOrVar
     *         the data to be examined
     *         must be a traversable list
     * @param  string $fieldOrVarName
     *         what is the name of $fieldOrVar in the calling code?
     * @return void
     */
    public function toList($fieldOrVar, $fieldOrVarName = "value");

    /**
     * throws exception if our inspection fails
     *
     * this is an alias of toList() for better readability when your
     * inspection is an object
     *
     * @inheritedFrom ListRequirement
     *
     * @param  mixed $fieldOrVar
     *         the data to be examined
     *         must be a traversable list
     * @param  string $fieldOrVarName
     *         what is the name of $fieldOrVar in the calling code?
     * @return void
     */
    public function inspectList($fieldOrVar, $fieldOrVarName = "value");
}

Requirements Enforced

RequireValidAssurances enforces the following:

1. $assurances must be a list
2. every value in $assurances must implement the Assurance interface

If any of the assurances aren't met, RequireValidAssurances will throw an exception.

How To Use

Applying Requirements

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

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

If any of the requirements aren't met, RequireValidAssurances will throw an exception.

Class Contract

Here is the contract for this class:

GanbaroDigital\Defensive\V1\Requirements\RequireValidAssurances
 [x] Can instantiate
 [x] is ListRequirement
 [x] Can use as object
 [x] Can call statically
 [x] Must provide list of assurances
 [x] List of assurances can contain only assurances
 [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

• Implements ListRequirement instead of Requirement

  We feel this is a more accurate description of what this function class does.

See Also

• Assurance interface