/** * 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; }