A simple workflow behavior for Yii ActiveRecord
 All Data Structures Files Functions Variables Pages
SWActiveRecordBehavior Class Reference
Inheritance diagram for SWActiveRecordBehavior:

Public Member Functions

 swGetWorkflowSource ()
 
 swGetStatus ()
 
 swIsEventEnabled ()
 
 swIsStatus ($status)
 
 swStatusEquals ($status=null)
 
 swHasStatus ()
 
 swGetWorkflowId ()
 
 attach ($owner)
 
 swGetDefaultWorkflowId ()
 
 swInsertToWorkflow ($workflowId=null)
 
 swRemoveFromWorkflow ()
 
 swGetNextStatus ()
 
 swGetAllStatus ()
 
 swIsNextStatus ($nextStatus)
 
 swCreateNode ($str)
 
 swIsFinalStatus ($status=null)
 
 swIsInitialStatus ($status=null)
 
 swValidate ($attribute, $value)
 
 swNextStatus ($nextStatus, $params=null)
 
 swSetStatus ($nextStatus, $params=null)
 
 events ()
 
 beforeSave ($event)
 
 afterSave ($event)
 
 afterFind ($event)
 
 enterWorkflow ($event)
 
 onEnterWorkflow ($event)
 
 leaveWorkflow ($event)
 
 onLeaveWorkflow ($event)
 
 beforeTransition ($event)
 
 onBeforeTransition ($event)
 
 processTransition ($event)
 
 onProcessTransition ($event)
 
 afterTransition ($event)
 
 onAfterTransition ($event)
 
 finalStatus ($event)
 
 onFinalStatus ($event)
 

Data Fields

 $statusAttribute = 'status'
 
 $defaultWorkflow =null
 
 $autoInsert =true
 
 $workflowSourceComponent ='swSource'
 
 $enableEvent =true
 
 $transitionBeforeSave =true
 
const SW_LOG_CATEGORY ='application.simpleWorkflow'
 
const SW_I8N_CATEGORY ='simpleworkflow'
 

Protected Member Functions

 canFireEvent ($owner, $className)
 

Protected Attributes

 $eventClassName ='SWActiveRecord'
 

Detailed Description

This class implements all the logic for the simpleWorkflow extension. Following attributes can be initialized when this behavior is attached to the owner component :

  • statusAttribute (string) : This is the column name where status is stored
    If this attribute doesn't exist for a model, the Workflow behavior is automatically disabled and a warning is logged.
    In the database, this attribute must be defined as a VARCHAR() whose length should be large enough to contains a complete status name with format workflowId/nodeId.
    example :
    task/pending
    postWorkflow/to_review
    
    Default : 'status'
  • defaultWorkflow (string) : workflow name that should be used by default for the owner model
    If this parameter is not set, then it is automatically created based on the name of the owner model, prefixed with 'workflowNamePrefix' defined by the workflow source component. By default this value is set to 'sw' and so, for example 'Model1' is associated by default with workflow 'swModel1'.
    Default : SWWorkflowSource->workflowNamePrefix . ModelName
  • autoInsert (boolean) :
    If TRUE, the model is automatically inserted in the workflow (if not already done) when it is saved. If FALSE, it is developer responsability to insert the model in the workflow.
    Default : true
  • workflowSourceComponent (string) :
    Name of the workflow source component to use with this behavior.
    By ddefault this parameter is set to swSource (see SWPhpWorkflowSource)
  • enableEvent (boolean) :
    If TRUE, this behavior will fire SWEvents. Note that even if it is true, this doesn't garantee that SW events will be fired as another condition is that the owner component provides SWEvent handlers.
    Default : true
  • transitionBeforeSave (boolean) :
    If TRUE, SWEvents are fired and possible transitions tasks are executed before the owner model is actually saved. If FALSE, events and task transitions are processed after save.
    It has no effect if the transition is done programatically by a call to swNextStatus(), but only if it is done when the owner model is saved.
    Default : true

Member Function Documentation

afterFind (   $event)

Responds to CActiveRecord::onAfterFind event. This method is called when a CActiveRecord instance is created from DB access (model read from DB). At this time, the worklow behavior must be initialized.

Parameters
CEventevent parameter
afterSave (   $event)

When option transitionBeforeSave is false, if a task is associated with the transition that was performed, it is executed now, that it after the activeRecord owner component has been saved. The onAfterTransition is also raised.

Parameters
SWEvent$event
afterTransition (   $event)

Default implementation for the onAfterTransition event.
This method is dedicated to be overloaded by custom event handler.

Parameters
SWEventthe event parameter
attach (   $owner)

Overloads parent attach method so at the time the behavior is about to be attached to the owner component, the behavior is initialized.
During the initialisation, following actions are performed:

  • The status attribute exists
  • Check whether or not, workflow events should be enabled, by testing if the owner component class inherits from the 'SWComponent' or 'SWActiveRecord' class.
See Also
base/CBehavior::attach()
beforeSave (   $event)

Depending on the value of the owner status attribute, and the current status, this method performs an actual transition.

Parameters
Event$event
Returns
boolean
beforeTransition (   $event)

Default implementation for the onBeforeTransition event.
This method is dedicated to be overloaded by custom event handler.

Parameters
SWEventthe event parameter
canFireEvent (   $owner,
  $className 
)
protected

Checks that the owner component is able to handle workflow events that could be fired by this behavior

Parameters
CComponent$ownerthe owner component attaching this behavior
string$className
Returns
bool TRUE if workflow events are fired, FALSE if not.
enterWorkflow (   $event)

Default implementation for the onEnterWorkflow event.
This method is dedicated to be overloaded by custom event handler.

Parameters
SWEventthe event parameter
string name of the class the owner should inherit from in order for SW events ( )

Attach event handlers. The behavior registers its own mandatory event handlers in case the owner model is a CActiveRecord instance.

  • onBeforeSave : perform status validation and update if needed. If configured, a task is also executed
  • onAfterSave : if configured a task is executed
  • onAfterFind : initialize internal status value

Additionnally, the behavior will fire custom events on various steps of the owner model life-cycle within its workflow :

  • onEnterWorkflow : the owner model is inserted in a workflow. Its status is now the initial status of the workflow
  • onFinalStatus : the owner model is in a status with no out going edge.
  • onLeaveWorkflow : the owner model status is set to NULL. This is possible only if the model is in a final status
  • onBeforeTransition : the owner model is about to change status
  • onProcessTransition : the owner model is changing status
  • onAfterTransition : the owner model has changed status
See Also
base/CBehavior::events()

to be enabled.

finalStatus (   $event)

Default implementation for the onFinalStatus event.
This method is dedicated to be overloaded by custom event handler.

Parameters
SWEventthe event parameter
leaveWorkflow (   $event)

Default implementation for the onEnterWorkflow event.
This method is dedicated to be overloaded by custom event handler.

Parameters
SWEventthe event parameter
onAfterTransition (   $event)

This event is raised after the onProcessTransition is fired. It is the last event fired during a non-final transition.
Again, in the case of an AR being saved, this event may be fired before or after the record is actually save, depending on the 'transitionBeforeSave' initialization parameters.

Parameters
SWEventthe event parameter
onBeforeTransition (   $event)

This event is raised before a workflow transition is applied to the owner instance.

Parameters
SWEventthe event parameter
onEnterWorkflow (   $event)

This event is raised after the record instance is inserted into a workflow. This may occur at construction time (new) if the behavior is initialized with autoInsert set to TRUE and in this case, the 'onEnterWorkflow' event is always fired. Consequently, when a model instance is created from database (find), the onEnterWorkflow is fired even if the record has already be inserted in a workflow (e.g contains a valid status).

Parameters
SWEventthe event parameter
onFinalStatus (   $event)

This event is raised at the end of a transition, when the destination status is a final status (i.e the owner model has reached a status from where it will not be able to move).

Parameters
SWEventthe event parameter
onLeaveWorkflow (   $event)

This event is raised after the record instance is removed from a workflow. This occures when the owner status attribut is set to NULL, for instance by calling $c->swNextStatus()

Parameters
SWEventthe event parameter
onProcessTransition (   $event)

This event is raised when a workflow transition is in progress. In such case, the user may define a handler for this event in order to run specific process.
Depending on the 'transitionBeforeSave' initialization parameters, this event could be fired before or after the owner model is actually saved to the database. Of course this only applies when status change is initiated when saving the record. A call to swNextStatus() is not affected by the 'transitionBeforeSave' option.

Parameters
SWEventthe event parameter
processTransition (   $event)

Default implementation for the onProcessTransition event.
This method is dedicated to be overloaded by custom event handler.

Parameters
SWEventthe event parameter
swCreateNode (   $str)

Creates a new node from the string passed as argument. If $str doesn't contain a workflow Id, this method uses the workflowId associated with the owner model. The node created here doesn't have to exist within a workflow. This method is mainly used by the SWValidator

Parameters
string$strstring status name
Returns
SWNode the node
swGetAllStatus ( )

Returns all statuses belonging to the workflow the owner component is inserted in or is related to. If the owner component is not inserted in a workflow or related to no workflow, an empty array is returned.

Returns
array list of SWNode objects.
swGetDefaultWorkflowId ( )

Finds out what should be the default workflow to use with the owner model. To find out what is the default workflow, this method perform following tests :

  • behavior initialization parameter defaultWorkflow
  • owner component method workflow : if the owner component is able to provide the complete workflow, this method will invoke SWWorkflowSource.addWorkflow
  • created based on the configured prefix followed by the model class name. The default workflow prefix is 'sw' so if the owner model is MyModel, the default workflow id will be swMyModel (case sensitive)
Returns
string workflow id to use with the owner component or NULL if no workflow was found
swGetNextStatus ( )

This method returns a list of nodes that can be actually reached at the time the method is called. To be reachable, a transition must exist between the current status and the next status, AND if a constraint is defined, it must be evaluated to true.

Returns
array SWNode object array for all nodes thats can be reached from the current node.
swGetStatus ( )

If the owner component is inserted into a workflow, this method returns the SWNode object that represent this status, otherwise NULL is returned.

Returns
SWNode the current status or NULL if no status is set
swGetWorkflowId ( )

Returns the current workflow Id the owner component is inserted in, or NULL if the owner component is not inserted into a workflow.

Parameters
stringcurrent workflow Id or NULL
swGetWorkflowSource ( )
Returns
reference to the workflow source used by this behavior
swHasStatus ( )

Test if the owner component is currently inserted in a workflow. This method is equivalent to swGetStatus()!=null.

Returns
boolean true if the owner model is in a workflow, FALSE otherwise
See Also
swGetStatus
swInsertToWorkflow (   $workflowId = null)

Insert the owner component into the workflow whose id is passed as argument. If NULL is passed as argument, the default workflow is used. If no error occurs, when this method ends, the owner component's status is the initial node of the selected workflow.

Parameters
string$workflowIdworkflow Id or NULL. If NULL the default workflow Id is used
Exceptions
SWExceptionthe owner model is already in a workflow
Returns
boolean TRUE
swIsEventEnabled ( )

Event may be enabled by configuration (when the behavior is attached to the owner component) but it can be automatically disabled if the owner component does not define handlers for all SWEvents (i.e events fired when the owner component evolves in the workflow). SWActiveRecordBehavior::attach

Returns
bool TRUE if workflow events are fire by this behavior, FALSE if not.
swIsFinalStatus (   $status = null)

Checks if the status passed as argument, or the current status (if NULL is passed) is a final status of the corresponding workflow. By definition a final status as no outgoing transition to other status.

Parameters
statusstatus to test, or null (will test current status)
Returns
boolean TRUE when the owner component is in a final status, FALSE otherwise
swIsInitialStatus (   $status = null)

Checks if the status passed as argument, or the current status (if NULL is passed) is the initial status of the corresponding workflow. An exception is raised if the owner model is not in a workflow and if $status is null.

Parameters
mixed$statusstring or SWNode instance
Returns
boolean TRUE if the owner component is in an initial status or if $status is an initial status.
Exceptions
SWException
swIsNextStatus (   $nextStatus)

Checks if the status passed as argument can be reached from the current status. This occurs when

  • a transition has been defined in the workflow between those 2 status
  • the destination status has a constraint that is evaluated to true in the context of the owner model

Note that if the owner component is not in a workflow, this method returns true if argument $nextStatus is the initial status for the workflow associated with the owner model. In other words the initial status for a given workflow is considered as the 'next' status, for all component associated to this workflow but not inserted in it. Of course, if a constraint is associated with the initial status, it must be evaluated to true.

Parameters
mixednextStatus String or SWNode object for the next status
Returns
boolean TRUE if the status passed as argument can be reached from the current status, FALSE otherwise.
swIsStatus (   $status)

Test if the owner component is currently in the status passed as argument.

Parameters
mixed$statusname or SWNode instance of the status to test
Returns
boolean TRUE if the owner component is in the status passed as argument, FALSE otherwise
swNextStatus (   $nextStatus,
  $params = null 
)

This is an alias for methode SWActiveRecordBehavior::swSetStatus() and should not be used anymore

Deprecated:
swRemoveFromWorkflow ( )

Removes the owner component from its current workflow. An exception is thrown if the owner model is not in a final status (i.e a status with no outgoing transition).

see SWActiveRecordBehavior::swIsFinalStatus()

Exceptions
SWException
swSetStatus (   $nextStatus,
  $params = null 
)

Set the owner component into the status passed as argument. If a transition could be performed, the owner status attribute is updated with the new status value in the form workflowId/nodeId. This method is responsible for firing SWEvents and executing workflow tasks if defined for the given transition.

Parameters
mixed$nextStatusstring or array. If array, it must contains a key equals to the name of the status attribute, and its value is the one of the destination node (e.g. $arr['status']). This is mainly useful when processing _POST array. If a string is provided, it must contain the fullname of the target node (e.g. workfowId/nodeId)
Returns
boolean True if the transition could be performed, FALSE otherwise
swStatusEquals (   $status = null)

Test if the current status is the same as the one passed as argument. A call to swStatusEquals(null) returns TRUE only if the owner component is not in a workflow.

Parameters
mixed$statusstring or SWNode instance.
Returns
boolean
swValidate (   $attribute,
  $value 
)

Validates the status attribute stored in the owner model. This attribute is valid if :

  • it is not empty
  • it contains a valid status name
  • this status can be reached from the current status
  • or it is equal to the current status (no status change)
Parameters
string$attributestatus attribute name (by default 'status')
mixed$valuecurrent value of the status attribute provided as a string or a SWNode object
Returns
boolean TRUE if the status attribute contains a valid value, FALSE otherwise

Field Documentation

$autoInsert =true
$defaultWorkflow =null
$enableEvent =true
$eventClassName ='SWActiveRecord'
protected
$statusAttribute = 'status'
$transitionBeforeSave =true
$workflowSourceComponent ='swSource'
const SW_I8N_CATEGORY ='simpleworkflow'
const SW_LOG_CATEGORY ='application.simpleWorkflow'

The documentation for this class was generated from the following file: