PHP Class izzum\statemachine\persistence\Adapter

In essence subclasses will be data access objects (https://en.wikipedia.org/wiki/Data_access_object) This class serves as a base class for access to different type of persistence layers we might want to use to store the states for stateful entities. for example: relational (postgres/mysql) databases, nosql databases, php sessions, files, memory, mongodb, redis etc.. It also acts as a central place to store logic related to this persistance layer, which might be useful when you want to get statistics from the persistence layer and make it available to your application code. all data access logic should be centralized in a subclass of adapter logic such as: - history of all transitions (when did an entity for a statemachine transition?) - the retrieval of the definition of transitions - the retrieval of data (like state, rules and commands) to be able to check/execute them via a form (with input of machine and entity_id). see the persistence/Tooling interface. A specific type of persistence adapter can be coupled (via the AbstractFactory) to a specific implementation of a statemachine. This abstract Adapter class has no side effects (like database/file/session/memory writes etc). Subclasses will probably have side effects. Adapter is a base class that defines the algorithm outline for reading and writing a state. It implements hooks to allow subclasses to alter the base implementation. This class is a helper class for Context. Context delegates reading and writing states to this class and it's subclasses.
See link: https://en.wikipedia.org/wiki/Data_access_object
Author: Rolf Vreijdenberger
Show file Open project: rolfvreijdenberger/izzum-statemachine Class Usage Examples

Public Methods

Method Description
__toString ( )
add ( Identifier $identifier, string $state, string $message = null ) : boolean Adds state information to the persistence layer so it can be manipulated by the statemachine package.
getEntityIds ( string $machine, string $state = null ) : string[] Get all the entity id's for a specific statemachine that have been persisted All entity id's in all states are returned unless a specific state is given via the optional parameter.
getState ( Identifier $identifier ) : string Get the current state for an Identifier (machine/id)
isPersisted ( Identifier $identifier ) : boolean is the state information already persisted?
processGetState ( Identifier $identifier ) : string A hook to be able to process the getting of the current state.
processSetState ( Identifier $identifier, string $state, $message = null ) : boolean A template method to be able to process the setting of the current state.
setFailedTransition ( Identifier $identifier, Transition $transition, Exception $e ) A template method that Stores a failed transition in the storage facility for historical/analytical purposes.
setState ( Identifier $identifier, string $state, string $message = null ) : boolan Sets the new state for an Identifier in the storage facility.
toString ( )

Protected Methods

Method Description
addHistory ( Identifier $identifier, string $state, mixed $message = null, boolean $is_exception = false ) Adds a history record for a transition
insertState ( Identifier $identifier, string $state, $message = null ) insert state for Identifier into persistance layer.
updateState ( Identifier $identifier, string $state, $message = null ) update state for statemachine/entity into persistance layer

Method Details

__toString() public method

public __toString ( )

add() public method

It adds a record to the underlying implementation about when the stateful object was first generated/manipulated. This method can safely be called multiple times. It will only add data when there is no state information already present. This template method creates a record in the underlying persistence layer where it's initial state is set. It can then be manipulated via other methods via this Adapter or via the statemachine itself eg: via 'getEntityIds' etc.
public add ( Identifier $identifier, string $state, string $message = null ) : boolean
$identifier izzum\statemachine\Identifier
$state string the initial state to set, which should be known to the client of the statemachine the first time a machine is created. this can also be retrieved via a loaded statemachine: $machine->getInitialState()->getName()
$message string optional message. this can be used by the persistence adapter to be part of the transition history to provide extra information about the transition.
return boolean true if it was added, false if it was already there.

addHistory() protected method

Adds a history record for a transition
protected addHistory ( Identifier $identifier, string $state, mixed $message = null, boolean $is_exception = false )
$identifier izzum\statemachine\Identifier
$state string
$message mixed string or array/object with relevant fields. an optional message (which might be exception data or not).
$is_exception boolean an optional value, specifying if there was something exceptional or not. this can be used to signify an exception for storage in the backend so we can analyze the history for regular transitions and failed transitions

getEntityIds() abstract public method

This method will be highly useful when you want to select a batch of entities to feed to the statemachine, for example in a cron job or a message queue.
abstract public getEntityIds ( string $machine, string $state = null ) : string[]
$machine string the name of the machine
$state string optional: if provided, only those entities in the specific state
return string[] an array of entity_id's

getState() public method

A template method.
public getState ( Identifier $identifier ) : string
$identifier izzum\statemachine\Identifier
return string the state

insertState() protected method

insert state for Identifier into persistance layer.
protected insertState ( Identifier $identifier, string $state, $message = null )
$identifier izzum\statemachine\Identifier
$state string

isPersisted() abstract public method

is the state information already persisted?
abstract public isPersisted ( Identifier $identifier ) : boolean
$identifier izzum\statemachine\Identifier
return boolean

processGetState() abstract public method

Implement this method for specifying how you want to get a state from a storage facility. this method is public to be able to call it via the ReaderWriterDelegator
abstract public processGetState ( Identifier $identifier ) : string
$identifier izzum\statemachine\Identifier
return string the current state of the entity represented in the context

processSetState() public method

saves an object to a storage facility (either insert or update). Implement this method for specifying how you want to set a state in the storage facility. A storage facility could store a timestamp and the state the transition was made to, for extra statistical information. this method is public to be able to call it via the ReaderWriterDelegator
public processSetState ( Identifier $identifier, string $state, $message = null ) : boolean
$identifier izzum\statemachine\Identifier
$state string
return boolean true if just added to storage, false if stored before

setFailedTransition() public method

A template method that Stores a failed transition in the storage facility for historical/analytical purposes.
public setFailedTransition ( Identifier $identifier, Transition $transition, Exception $e )
$identifier izzum\statemachine\Identifier
$transition izzum\statemachine\Transition
$e Exception

setState() public method

Will only be called by the statemachine. A template method.
public setState ( Identifier $identifier, string $state, string $message = null ) : boolan
$identifier izzum\statemachine\Identifier (old state can be retrieved via the identifier and this class)
$state string this is the new state
$message string optional message. this can be used by the persistence adapter to be part of the transition history to provide extra information about the transition.
return boolan false if already stored before, true if just added

toString() public method

public toString ( )

updateState() protected method

update state for statemachine/entity into persistance layer
protected updateState ( Identifier $identifier, string $state, $message = null )
$identifier izzum\statemachine\Identifier
$state string