Dispatches in the Chain system are primarily data carriers. Any information that should be carried along a chain to its nodes should be stored within the dispatch. During traversal, nodes can read from the dispatch and write to it for later nodes to see, or for the end result.
Dispatches by default have three 'states' that can be queried. Each defaults to false
and
must be set by any dispatch during initialization. The states are as follows:
When a dispatch is marked as consumable, it tells the ChainHelper to stop traversing the chain if the dispatched is marked as 'consumed' by a node. This can be helpful for building chains that resemble the chain-of-responsibility pattern.
All nodes are given the ability to store results in dispatches, and the dispatch's stateful setting will determine if only one result is allowed or multiple are kept. If multiple are set, they are returned as an array. A single result is returned if only one result is stored, and null is returned if there are no stored results.
In order for the ChainHelper to traverse a chain it must have both nodes and a valid dispatch. This gives developers the ability to enforce custom restrictions on data validity at initialization in order to stop chain traversal.
All dispatches must implement the DispatchBase
abstract class. This provides some minimum
functionality and requires developers to implement an initialize()
method. The following are
the properties and methods defined in DispatchBase
:
protected boolean $_isConsumable Whether or not the dispatch is 'consumable' protected boolean $_isStateful Whether or not the dispatch should retain multiple results protected boolean $_isConsumed Whether or not the dispatch has been consumed by a node protected mixed[] $_results Collection of results from processing nodes protected boolean $_isValid Whether or not the dispatch is valid for processing protected DateTimeInterface $_calledDateTime Date and time the dispatch was marked valid
public string __toString() Converts the class into a readable string public boolean consume() Marks dispatch as having been consumed public DateTimeInterface getCalledDateTime() Returns the date and time the dispatch was marked valid public mixed[]|mixed|null getResults() Returns any results stored in dispatch, single result if one, array of results if many, null if none abstract public void initialize(mixed $input) Abstract method that dispatch classes should use to handle initialization public boolean isConsumable() Returns whether or not the dispatch can be consumed public boolean isConsumed() Returns whether or not the dispatch has been consumed public boolean isStateful() Returns whether or not the dispatch will hold multiple results public boolean isValid() Returns whether or not the dispatch is valid for traversal protected DispatchBase makeConsumable() Sets a dispatch as consumable protected DispatchBase makeStateful() Sets a dispatch as stateful protected DispatchBase makeValid() Sets dispatch as valid and sets 'called' date and time in UTC offset public integer numResults() Returns the number of results stored in dispatch public DispatchBase setResult(mixed $result) Sets a result in the dispatch
For examples, see the 'Dispatch' section of the Examples page.
Continue to read about nodes, or visit the Table of Contents.