FlupdoCrudMachine Class Reference

Description

Simple state machine for typical CRUD entities accessed via Flupdo.

Configuration Schema

The state machine is configured using JSON object passed to the constructor (the $config parameter). The object must match the following JSON schema (JSON format):

• Smalldb Flupdo CRUD State Machine [object]
  • _: [AbstractMachine] [string] Token to stop PHP from interpreting the rest of the file. Ignored by Smalldb.
    Pattern: ^<\?php printf\('_%c%c}%c',34,10,10\);__halt_compiler\(\);\?>$
  • access_policies: [AbstractMachine] [object] Access policies
    • *: [AbstractMachine] [object] Access policy
      • arrow_tail: [AbstractMachine] [string] Shape of arrow tail in the state diagram. Visual effect only. See http://www.graphviz.org/content/arrow-shapes.
        Pattern: ^((|l|r|o|ol|or)box|(|l|r)crow|(l|r|o|ol|or)diamond|(|o)dot|(|l|r|o|ol|or)inv|none|(|l|r|o|ol|or)normal|(|l|r)tee|(|l|e)vee|(|l|r|i|li|ri)curve){1,4}$
      • owner_property: [FlupdoMachine] [string] State machine property (scalar ID) which defines owner of this state machine instance. Used by 'owner' policy type.
      • required_role: [FlupdoMachine] [string] Required user role. Used by 'role' policy type.
      • required_value: [FlupdoMachine] [string] Value required to be equal to the value of 'sql_select'. If not set, the 'sql_select' is check to not be null.
      • session_state: [FlupdoMachine] [string] Required state of the session machine (IAuth). Used by 'owner' policy type. If not set, the session state is not checked.
      • sql_select: [FlupdoMachine] [string] SQL expression to retrieve the checked value from the database. It will be mixed into the SQL select or where clause when reading state machine properties. Used by 'condition' and 'user_relation' policy types. The policy allows access when this expression is not null or when equal to 'required_role' (if set). When used with 'user_relation' policy type, it accepts one parameter (positional placeholder '?') which provides user's ID.
      • type: [FlupdoMachine] [string] [required] Type of the policy (algorithm).
        Enum: [ "anyone", "nobody", "anonymous", "user", "owner", "role", "condition", "user_relation" ]
  • actions: [AbstractMachine] [object] State machine actions (groups of transitions of the same name).
    • *: [AbstractMachine] [object] State machine action.
      • access_policy: [AbstractMachine] [string] Name of required access policy, see access_policies.
      • args: [AbstractMachine] [array] Additional arguments prefixed to transition arguments when calling the method.
      • color: [AbstractMachine] [string] Color of the arrow in the state diagram.
        Pattern: ^#[0-9A-Fa-f]{6}$
      • method: [AbstractMachine] [string] Name of PHP method which implements the transition.
        Pattern: ^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$
      • post_transition_methods: [AbstractMachine] [array] Methods to call after the transition is invoked.
        • *: [AbstractMachine] [string]
          Pattern: ^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$
      • pre_check_methods: [AbstractMachine] [array] Methods to call before the transition is invoked. All of these methods must not return false otherwise the transition is aborted.
        • *: [AbstractMachine] [string]
          Pattern: ^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$
      • returns: [AbstractMachine] [string, null] Semantics of return value of the method.
      • transitions: [AbstractMachine] [object] Transitions of the action
        • *: [AbstractMachine] [object] Starting state of the transition.
          • targets: [AbstractMachine] [array] List of possible target states of the transition starting from this state.
            • *: [AbstractMachine] [string]

          • *: [AbstractMachine] [object] All properties are merged with action's properties; transition's properties have precedence.
      • weight: [AbstractMachine] [number] Weight of the arrow in the state diagram (heavier arrows are rendered shorter).
  • auth_resource: [FlupdoMachine] [string] [required] Context property containing the authenticator (IAuth)
    Default: "auth"
  • class: [JsonDirBackend] [string] [required] Interpreted by JsonDirBackend. PHP class name of transitions implementation.
    Pattern: ^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*(\\[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)*$
  • default_access_policy: [AbstractMachine] [string, null] Default access policy (used unless given action specifies another policy). See 'access_policies'.
  • flupdo_resource: [FlupdoMachine] [string] Context property containing the Flupdo instance connected to database.
    Default: "database"
  • generate_random_id: [null, bool] Generate random ID if not specified.
  • include: [JsonDirBackend] [array] Interpreted by JsonDirBackend only. List of files to include and merge with this JSON file.
    • *: [JsonDirBackend] [string, object] File name of the file to include or object containing the filename and additional options.
      • file: [JsonDirBackend] [string] File name of the file to include.

      • *: [JsonDirBackend] Options passed to dedicated reader.
  • io_name: [string] Name of inputs and outputs used for generated cascade blocks.
    Default: "item"
  • listing_access_policy: [AbstractMachine] [string, null] Access policy when listing state machine instances (user may be able to read any state machine state, but may not be able to enumerate them). See 'access_policies'.
  • nested_sets: [null, object] Implementation of a tree structure using nested sets.
    • enabled: [bool] Enable nested sets updates
      Default: false
    • order_by: [string] Column name used to order the tree nodes.
    • table_columns: [object] Columns used for storing nested sets numbering.
      • depth: [string] Column name of the depth in the tree (updated by FlupdoCrudMachine).
        Default: "tree_depth"
      • id: [string] Column name of the primary key
        Default: "id"
      • left: [string] Column name of the left number (updated by FlupdoCrudMachine).
        Default: "tree_left"
      • parent_id: [string] Column name of the reference to parent in the tree (foreign key to id column).
        Default: "parent_id"
      • right: [string] Column name of the right number (updated by FlupdoCrudMachine).
        Default: "tree_right"
  • no_default_machine: [bool] Disable initialization with a default state machine diagram. Useful when custom state diagram is provided.
  • owner_create_transition: [null, string] Name of the owner state machine's transition which must be allowed to create a new instance of this state machine.
  • owner_relation: [null, string] Relation to owner state machine of this state machine.
  • parent_url: [FlupdoMachine] [string, null] Format string to generate URL of machine which is parent of this machine (for post-delete redirect)
  • post_action_url: [FlupdoMachine] [string, null] Format string to generate URL where to redirect after action is invoked.
  • properties: [FlupdoMachine] [object] State machine properties. If not defined (or empty object), the properties are automatically detected from the database columns (including is_pk).
    • *: [AbstractMachine] [object] State machine property definition
      • column_encoding: [FlupdoMachine] [null, string] Data are encoded before storing in the database and decoded after loading from the database using this encoding. This allows storing complex data in a single text/blob column (as long as the database does not need to understand this column).
        Enum: [ null, "json" ]
      • components: [FlupdoMachine] [null, object] Property is composed from these database columns. Data are loaded into a key-value map (array); the components are the keys, the database columns are the values.
        • *: [FlupdoMachine] [string] Name of the database column.
      • is_pk: [FlupdoMachine] [bool] Flag whether the property is a primary key. Compound primary keys must have properties defined in correct order.
        Default: false
      • label: [FlupdoMachine] [string] Name of the property (human readable).
      • type: [FlupdoMachine] [string] Type of the property (not interpreted by the state machine; autodetection uses column types provided by the database).
  • read_access_policy: [AbstractMachine] [string, null] Access policy when reading state machine state and properties. See 'access_policies'.
  • sphinx_resource: [FlupdoMachine] [null, string] Context property containing the Flupdo resource connected to a Sphinx search engine.
  • state_diagram_extras: [AbstractMachine] [array] List of additional fragments of state diagram.
    • *: [AbstractMachine] [string] Dot source code to be added just before the end of the state diagram..
  • state_groups: [AbstractMachine] [object] Groups of states in the state machine diagram. Visual effect only.
    • *: [AbstractMachine] [object] Group of states in the state machine diagram.
      • color: [AbstractMachine] [string] Color of the group (border and label).
        Pattern: ^#[0-9A-Fa-f]{6}$
      • label: [AbstractMachine] [string] [required] Label of the group.
      • state_groups: [AbstractMachine] [object] Recursively nested state groups (same as parent state_groups).

      • *: [not allowed]
  • state_select: [FlupdoMachine] [string] SQL expression to calculate current state (required unless the getStateSelect method is overriden).
  • states: [AbstractMachine] [object] State machine states
    • *: [AbstractMachine] [object] State of the state machine
      • color: [AbstractMachine] [string] Color of the state in the state diagram (fillcolor). Visual effect only.
        Pattern: ^#[0-9A-Fa-f]{6}$
      • group: [AbstractMachine] [string] Name of a group (subgraph) in the state diagram to which the state belongs. Visual effect only. See state_groups.
  • table: [FlupdoMachine] [string] [required] Name of the SQL table where state machines of this type are stored.
  • table_alias: [FlupdoMachine] [null, string]
  • time_created_table_column: [null, string] Column to store time of creation.
  • time_modified_table_column: [null, string] Column to store time of last modification (or creation if not yet modified)
  • url: [FlupdoMachine] [string, null] Format string to generate machine URL
  • user_id_table_column: [null, string] Table column containing user (owner) ID.

Inheritance diagram for FlupdoCrudMachine

Protected Member Functions
	initializeMachine ($config)
	Define state machine used by all instances of this type. More...
	setupDefaultMachine ($config)
	Setup basic CRUD machine. More...
	create (Reference $ref, $properties)
	Create. More...
	edit (Reference $ref, $properties)
	Edit. More...
	delete (Reference $ref)
	Delete. More...
	recalculateTree ()
	Recalculate nested-sets tree indices. More...
Protected Member Functions inherited from FlupdoMachine
	initializeMachine ($config)
	Define state machine used by all instances of this type. More...
	scanTableColumns ()
	Scan table in database and populate properties. More...
	checkAccessPolicy ($access_policy_name, Reference $ref)
	Returns true if user has required access_policy. More...
	queryAddAccessPolicyCondition ($access_policy_name, $query)
	Adds conditions to enforce read access_policy to query object. More...
	queryAddFrom ($query)
	Add FROM clause. More...
	queryGetThisTable ($query)
	Get table name with alias. More...
	queryAddStateSelect ($query)
	Add state column into select clause of the $query. More...
	queryAddPropertiesSelect ($query)
	Add properties to select. More...
	queryAddPrimaryKeyWhere ($query, $id, $clause= 'where')
	Add primary key condition to where clause. More...
Protected Member Functions inherited from AbstractMachine
	initializeMachine ($config)
	Define state machine used by all instances of this type. More...
	setupDefaultMachine ($config)
	Setup default machine when initializeMachine is finished. More...
	initializeMachineConfig ($config, $keys)
	Merge $config into state machine member variables. More...
	checkAccessPolicy ($access_policy, Reference $ref)
	Returns true if user has required access_policy to invoke a transition, which requires given access_policy. More...
	calculateViewValue ($id, $view, &$properties_cache=null, &$view_cache=null, &$persistent_view_cache=null)
	Calculate value of a view. More...
	getContext ($resource_name=null)
	Get context object (whatever it is). More...
	urlFormat ($id, $url_fmt, $properties_cache)
	Create URL using properties and given format. More...
	resolveMachineReference ($reference_name, $properties_cache)
	Helper function to resolve reference to another machine. More...
	onStateChanged (Reference $ref, $old_state, $transition_name, $new_state)
	Called when state is changed, when transition invocation is completed. More...
	exportDotRenderExtras ($debug_opts)
	Render extra diagram features. More...
	exportJsonAddExtras ($debug_opts, $machine_graph)
	Add extra diagram features into the diagram. More...

Protected Attributes
	$owner_relation = null
	Relation defining shich machine owns this machine. More...
	$owner_create_transition = null
	Transition of owner to check when creating this machine. More...
	$nested_sets_table_columns
	Nested-sets configuration. More...
	$nested_sets_enabled = false
	Enable nested-sets tree? More...
	$nested_sets_order_by = 'id'
	Order by this column. More...
	$generate_random_id = null
	Generate random id? More...
	$time_created_table_column = null
	Set this column to CURRENT_TIMESTAMP on create transition. More...
	$time_modified_table_column = null
	Set this column to CURRENT_TIMESTAMP on edit transition. If MySQL is in use, it is better to use CURRENT_TIMESTAMP column feature. More...
Protected Attributes inherited from FlupdoMachine
	$flupdo
	Database connection. More...
	$sphinx
	Sphinx indexer connection. More...
	$auth
	Authenticator (gets user id and role) More...
	$table
	Name of SQL table, where machine properties are stored. More...
	$table_alias = null
	Alias of the $table. More...
	$pk_columns = null
	List of columns which are used as primary key. More...
	$json_columns = array()
	List of columns which are serialized as JSON in database. More...
	$composed_properties = array()
	List of properties, which are composed of multiple columns. More...
	$user_id_table_column = null
	Column containing entity owner. More...
	$user_id_auth_method = null
	Auth object method name to retrieve current user ID. More...
	$load_state_with_properties = true
	True if state should not be loaded with properties. More...
	$filters = null
	Filters defined in configuration. More...
	$default_filters = null
	Default filters for listing. More...
	$additional_filters_data = null
	Additional filters data definition for listing. More...
	$state_select = null
	Select expression for selecting machine state. More...
Protected Attributes inherited from AbstractMachine
	$backend
	Backend, where all machines are stored. More...
	$machine_type
	Identification within $backend. More...
	$state_diagram_extras = []
	List of additional diagram parts in Dot language provided by backend (and its readers). More...
	$state_diagram_extras_json = []
	$errors = []
	List of errors in state machine definition. More...
	$url_fmt
	URL format string where machine is located, usualy only the path part, e.g. More...
	$parent_url_fmt
	URL format string where parent of this machine is located, usualy only the path part, e.g. More...
	$post_action_url_fmt
	URL format string for redirect-after-post. More...
	$states
	Descriptions of all known states – key is state id, value is * description. More...
	$state_groups
	State groups. More...
	$actions
	Description of all known actions – key is action name. More...
	$default_access_policy = null
	Default access policy. More...
	$read_access_policy = null
	Read access policy. More...
	$listing_access_policy = null
	Listing access policy. More...
	$access_policies
	Access policies. More...
	$properties
	Description of machine properties – key is property name. More...
	$views
	Description of machine views – key is view name. More...
	$references
	Description of machine references. More...

Additional Inherited Members
Public Member Functions inherited from FlupdoMachine
	invokeTransition (Reference $ref, $transition_name, $args, &$returns, callable $new_id_callback=null)
	Invoke state machine transition. More...
	createListing ($filters, $filtering_flags=0)
	Create generic listing on this machine type. More...
	createQueryBuilder ()
	Create query builder. More...
	getState ($id)
	Get current state of state machine. More...
	getProperties ($id, &$state_cache=null)
	Get all properties of state machine, including it's state. More...
	encodeProperties ($properties)
	Encode properties to database representation. More...
	decodeProperties ($properties)
	Decode properties from database representation. More...
	describeId ()
	Reflection: Describe ID (primary key). More...
Public Member Functions inherited from AbstractMachine
	__construct (AbstractBackend $backend, $type, $config)
	Constructor. More...
	setDebugLogger (IDebugLogger $debug_logger)
	Set debug logger. More...
	getDebugLogger ()
	Get debug logger. More...
	getErrors ()
	Get errors found while loading the machine definition. More...
	getState ($id)
	Get current state of state machine. More...
	getProperties ($id, &$state_cache=null)
	Get properties of state machine, including it's state. More...
	getView ($id, $view, &$properties_cache=null, &$view_cache=null, &$persistent_view_cache=null)
	Get properties in given view. More...
	isTransitionAllowed (Reference $ref, $transition_name, $state=null, &$access_policy=null)
	Returns true if transition can be invoked right now. More...
	getAvailableTransitions (Reference $ref, $state=null)
	Get list of all available actions for state machine instance identified by $id. More...
	invokeTransition (Reference $ref, $transition_name, $args, &$returns, callable $new_id_callback=null)
	Invoke state machine transition. More...
	getMachineType ()
	Get type of this machine. More...
	getBackend ()
	Get backend which owns this machine. More...
	ref ($id)
	Helper to create Reference to this machine. More...
	nullRef ()
	Helper to create null Reference to this machine. More...
	hotRef ($properties)
	Create pre-heated reference using properties loaded from elsewhere. More...
	performSelfCheck ()
	Perform self-check. More...
	describeId ()
	Reflection: Describe ID (primary key). More...
	getUrlFormat ()
	Get URL format. More...
	getParentUrlFormat ()
	Get prent URL format. More...
	getPostActionUrlFormat ()
	Get URL for redirect-after-post. More...
	getMachineImplementationMTime ()
	Get mtime of machine implementation. More...
	getAllMachineStates ($having_section=null)
	Reflection: Get all states. More...
	describeMachineState ($state, $field=null)
	Reflection: Describe given machine state. More...
	describeAllMachineStates ($having_section=null)
	Reflection: Describe all states. More...
	getAllMachineActions ($having_section=null)
	Reflection: Get all actions (transitions) More...
	describeMachineAction ($action, $field=null)
	Reflection: Describe given machine action (transition) More...
	describeAllMachineActions ($having_section=null)
	Reflection: Describe all actions (transitions) More...
	getAllMachineProperties ($having_section=null)
	Reflection: Get all properties. More...
	describeMachineProperty ($property, $field=null)
	Reflection: Describe given property. More...
	describeAllMachineProperties ($having_section=null)
	Reflection: Describe all properties. More...
	getAllMachineViews ($having_section=null)
	Reflection: Get all views. More...
	describeMachineView ($view, $field=null)
	Reflection: Describe given view. More...
	describeAllMachineViews ($having_section=null)
	Reflection: Describe all views. More...
	getAllMachineReferences ($having_section=null)
	Reflection: Get all references. More...
	describeMachineReference ($reference, $field=null)
	Reflection: Describe given reference. More...
	describeAllMachineReferences ($having_section=null)
	Reflection: Describe all references. More...
	exportJson ($debug_opts=false)
	Export state machine as JSON siutable for Grafovatko. More...
	exportDot ($debug_opts=false)
	Export state machine to Graphviz source code. More...
Static Public Member Functions inherited from AbstractMachine
static	exportDotIdentifier ($str, $prefix= 's_')
	Convert state machine state name or group name to a safe dot identifier. More...
Public Attributes inherited from AbstractMachine
const	RETURNS_VALUE = null
	Return value of invoked transition is just some value. More...
const	RETURNS_NEW_ID = 'new_id'
	Return value of invoked transition is new ID of the state machine. More...

Member Function Documentation

initializeMachine (   $config )

protected

Define state machine used by all instances of this type.

setupDefaultMachine (   $config )

protected

Setup basic CRUD machine.

Deprecated:

create ( Reference  $ref,   $properties  )

protected

Create.

$ref may be nullRef, then auto increment is used.

edit ( Reference  $ref,   $properties  )

protected

Edit.

delete ( Reference  $ref )

protected

Delete.

recalculateTree ( )

protected

Recalculate nested-sets tree indices.

To use this feature a parent, left, right and depth columns must be specified.

Composed primary keys are not supported yet.

Three extra columns are required: tree_left, tree_right, tree_depth (ints, all nullable). This function will update them according to id and parent_id columns.

Member Data Documentation

$owner_relation = null

protected

Relation defining shich machine owns this machine.

$owner_create_transition = null

protected

Transition of owner to check when creating this machine.

$nested_sets_table_columns

protected

Initial value:

= array(
                'id' => 'id',
                'parent_id' => 'parent_id',
                'left' => 'tree_left',
                'right' => 'tree_right',
                'depth' => 'tree_depth',
        )

Nested-sets configuration.

$nested_sets_enabled = false

protected

Enable nested-sets tree?

$nested_sets_order_by = 'id'

protected

Order by this column.

$generate_random_id = null

protected

Generate random id?

$time_created_table_column = null

protected

Set this column to CURRENT_TIMESTAMP on create transition.

$time_modified_table_column = null

protected

Set this column to CURRENT_TIMESTAMP on edit transition. If MySQL is in use, it is better to use CURRENT_TIMESTAMP column feature.