/**
* Triggers the given event.
*
* @param string $eventName
* @param boolean $transitionToHistoryMarker
* @return Stagehand_FSM_State
* @throws PIECE_FLOW_ERROR_INVALID_OPERATION
* @throws PIECE_FLOW_ERROR_CANNOT_INVOKE
*/
function &triggerEvent($eventName, $transitionToHistoryMarker = false)
{
if (!$this->_started()) {
Piece_Flow_Error::push(PIECE_FLOW_ERROR_INVALID_OPERATION, __FUNCTION__ . ' method must be called after starting flows.');
$return = null;
return $return;
}
if ($eventName == PIECE_FLOW_PROTECTED_EVENT || $this->_fsm->isProtectedEvent($eventName)) {
trigger_error("The event [ {$eventName} ] cannot be called directly. The current state [ " . $this->getCurrentStateName() . ' ] will only be updated.', E_USER_WARNING);
$eventName = PIECE_FLOW_PROTECTED_EVENT;
}
$this->_lastEventIsValid = $this->_fsm->hasEvent($eventName);
Stagehand_FSM_Error::disableCallback();
$state =& $this->_fsm->triggerEvent($eventName, $transitionToHistoryMarker);
Stagehand_FSM_Error::enableCallback();
if (Stagehand_FSM_Error::hasErrors()) {
Piece_Flow_Error::push(PIECE_FLOW_ERROR_CANNOT_INVOKE, 'Failed to invoke Stagehand_FSM::triggerEvent() for any reasons.', 'exception', array(), Stagehand_FSM_Error::pop());
$return = null;
return $return;
}
if (!is_null($this->_lastState) && $state->getName() == $this->_lastState) {
Stagehand_FSM_Error::disableCallback();
$state =& $this->_fsm->triggerEvent(STAGEHAND_FSM_EVENT_END);
Stagehand_FSM_Error::enableCallback();
if (Stagehand_FSM_Error::hasErrors()) {
Piece_Flow_Error::push(PIECE_FLOW_ERROR_CANNOT_INVOKE, 'Failed to invoke Stagehand_FSM::triggerEvent() for any reasons.', 'exception', array(), Stagehand_FSM_Error::pop());
$return = null;
return $return;
}
}
return $state;
}
