Class Operation

An operation.

ICanBoogie\Routing\Controller

┗ ICanBoogie\Operation

Abstract
Namespace: ICanBoogie
Located at Operation.php

Methods summary


				
				 public static
				
				

				encode( string $pattern, array $params = [] )
				

				: string

Encodes a RESTful operation.


				
				 protected 
				
				

				get_controls( void )
				

				: array

Returns the controls to pass.


				
				 protected 
				
				

				lazy_get_record( void )
				

				: ActiveRecord

Getter for the $record property.


				
				 protected 
				
				

				get_response( void )
				

				: ICanBoogie\Operation\Response

Returns the operation response.


				
				 protected 
				
				

				lazy_get_form( void )
				

				: object|null

Getter for the ICanBoogie\Operation::$form property.

The operation object fires a ICanBoogie\Operation\GetFormEvent event to retrieve the form. One can listen to the event to provide the form associated with the operation.

One can override this method to provide the form using another method. Or simply define the ICanBoogie\Operation::$form property to circumvent the getter.

Returns

object|null


				
				 protected 
				
				

				get_is_forwarded( void )
				

				: boolean

Returns true if the operation is forwarded.

An operation is considered forwarded if the destination module and the operation name are defined in the request parameters. This is usually the case for forms which are posted on their URI but forwarded to a specified destination module.

Returns

boolean


				
				 protected 
				
				

				action( ICanBoogie\HTTP\Request $request )
				

				: ICanBoogie\Operation\Response

Handles the operation and returns a response.

The $record and ICanBoogie\Operation::$form properties are unset in order for their getters to be called on the next access, while keeping their scope.

The response object

The operation result is saved in a response object, which may contain meta data describing or accompanying the result. For example, the ICanBoogie\Operation class returns success and error messages in the $message and $errors properties.

Depending on the Accept header of the request, the response object can be formatted as JSON or XML. If the Accept header is "application/json" the response is formatted as JSON. If the Accept header is "application/xml" the response is formatted as XML. If the Accept header is not of a supported type, only the result is printed, as a string.

For API requests, the output format can also be defined by appending the corresponding extension to the request path:

/api/nodes/12/online.json

The response location

The Location header is used to ask the browser to load a different web page. This is often used to redirect the user when an operation has been performed e.g. creating/deleting a resource. The location property of the response is used to set that header. This is not a desirable behavior for XHR because although we might want to redirect the user, we still need to get the result of our request first. That is why when the location property is set, and the request is an XHR, the location is set to the redirect_to field and the location property is set to null to disable browser redirection.

Control, validation and processing

Before the operation is actually processed with the ICanBoogie\Operation::process() method, it is controlled and validated using the ICanBoogie\Operation::control() and ICanBoogie\Operation::validate() methods. If the control or validation fail the operation is not processed.

The controls passed to the ICanBoogie\Operation::control() method are obtained through the $controls property or the ICanBoogie\Operation::get_controls() getter if the property is not accessible.

Events

The failure event is fired when the control or validation of the operation failed. The type property of the event is "control" or "validation" depending on which method failed. Note that the event won't be fired if an exception is thrown.

The process:before event is fired with the operation as sender before the operation is processed using the ICanBoogie\Operation::process() method.

The process event is fired with the operation as sender after the operation has been processed if its result is not null.

Failed operation

If the result of the operation is null, the operation is considered as failed, in which case the status code of the response is changed to 404 and the ICanBoogie\Operation\ProcessEvent is not fired.

Note that exceptions are not caught by the method.

Parameters

$request: The request triggering the operation.

Returns

ICanBoogie\Operation\Response
The response of the operation.

Throws

ICanBoogie\Operation\Failure

when the response has a client or server error, or the ICanBoogie\Operation\FormHasExpired exception was raised.


				
				 public 
				
				

				format( string $format, array $args = [], array $options = [] )
				

				: ICanBoogie\I18n\FormattedString

Format a string.


				
				 protected 
				
				

				reset( void )

Resets the operation state.


				
				 protected 
				
				

				control( array $controls )
				

				: boolean

Controls the operation.

A number of controls may be passed before an operation is validated and processed. Controls are defined as an array where the key is the control identifier, and the value defines whether the control is enabled. Controls are enabled by setting their value to true:

[
    self::CONTROL_AUTHENTICATION => true,
    self::CONTROL_RECORD => true,
    self::CONTROL_FORM => false
];

Instead of a boolean, the "permission" control is enabled by a permission string or a permission level.

[
    self::CONTROL_PERMISSION => Module::PERMISSION_MAINTAIN
];

The $controls property is used to get the controls or its magic getter ICanBoogie\Operation::get_controls() if the property is not accessible.

Controls are passed in the following order:

CONTROL_SESSION_TOKEN

Controls that '_session_token' is defined in $_POST and matches the current session's token. The ICanBoogie\Operation::control_session_token() method is invoked for this control. An exception with code 401 is thrown when the control fails.

CONTROL_AUTHENTICATION

Controls the authentication of the user. The ICanBoogie\Operation::control_authentication() method is invoked for this control. An exception with the code 401 is thrown when the control fails.

CONTROL_PERMISSION

Controls the permission of the guest or user. The ICanBoogie\Operation::control_permission() method is invoked for this control. An exception with code 401 is thrown when the control fails.

CONTROL_RECORD

Controls the existence of the record specified by the operation's key. The ICanBoogie\Operation::control_record() method is invoked for this control. The value returned by the method is set in the operation object under the record property. The callback method must throw an exception if the record could not be loaded or the control of this record failed.

The record property, or the ICanBoogie\Operation::lazy_get_record() getter, is used to get the record.

CONTROL_OWNERSHIP

Controls the ownership of the user over the record loaded during the CONTROL_RECORD step. The ICanBoogie\Operation::control_ownership() method is invoked for the control. An exception with code 401 is thrown if the control fails.

CONTROL_FORM

Controls the form associated with the operation by checking its existence and validity. The ICanBoogie\Operation::control_form() method is invoked for this control. Failing the control does not throw an exception, but a message is logged to the debug log.

Parameters

$controls: The controls to pass for the operation to be processed.

Returns

boolean
true if all the controls pass, false otherwise.

Throws

Exception
Depends on the control.


				
				 protected 
				
				

				control_method( string $method )
				

				: boolean

Controls the request method.


				
				 protected 
				
				

				control_session_token( void )
				

				: boolean

Controls the session token.


				
				 protected 
				
				

				control_authentication( void )

Controls the authentication of the user.


				
				 protected 
				
				

				control_permission( mixed $permission )
				

				: boolean

Controls the permission of the user for the operation.

Parameters

$permission: The required permission.

Returns

boolean
true if the user has the specified permission, false otherwise.

Todo-20150816:

should be a prototype method


				
				 protected 
				
				

				control_ownership( void )
				

				: boolean

Controls the ownership of the user over the operation target record.


				
				 protected 
				
				

				control_record( void )
				

				: ActiveRecord|null

Checks if the operation target record exists.


				
				 protected 
				
				

				control_form( void )
				

				: boolean

Control the operation's form.

The form is retrieved from the ICanBoogie\Operation::$form property, which invokes the ICanBoogie\Operation::lazy_get_form() getter if the property is not accessible.

Returns

boolean
true if the form exists and validates, false otherwise.


				
				abstract protected 
				
				

				validate( ICanBoogie\ErrorCollection $errors )
				

				: ErrorCollection|boolean

Validates the operation before processing.


				
				abstract protected 
				
				

				process( void )
				

				: mixed

Processes the operation.

Magic methods summary


				
				 public 
				
				

				__invoke( ICanBoogie\HTTP\Request $request )
				

				: ICanBoogie\Operation\Response

Constants summary


				
DESTINATION				

                : string

Defines the destination of a forwarded operation.

'_operation_destination'


				
NAME				

                : string

Defines the operation name of a forwarded operation.

'_operation_name'


				
KEY				

                : string

Defines the key of the resource targeted by the operation.

'_operation_key'


				
SESSION_TOKEN				

                : string

Defines the session token to be matched.

'_session_token'


				
RESTFUL_BASE				

                : string

'/api/'


				
RESTFUL_BASE_LENGTH				

                : integer


				
CONTROL_METHOD				

                : integer


				
CONTROL_SESSION_TOKEN				

                : integer


				
CONTROL_AUTHENTICATION				

                : integer


				
CONTROL_PERMISSION				

                : integer


				
CONTROL_RECORD				

                : integer


				
CONTROL_OWNERSHIP				

                : integer


				
CONTROL_FORM				

                : integer

Properties summary


				
				public  
				

				
$key


				
				public  
				

				
$response				

				: ICanBoogie\Operation\Response


				
				protected  
				

				
$form				

				: object

The form object of the operation.


				
				protected  
				

				
$format				

				: string

Output format of the operation response.

Magic properties


				
				public  
				

				
$record				

				: ActiveRecord

The target active record object of the operation.


				
				public  
				

				
$module				

				: Module


				
				public  read-only
				

				
$app				

				: Application


				
				public  read-only
				

				
$request				

				: ICanBoogie\HTTP\Request

The request.


				
				public  read-only
				

				
$controls				

				: array

The controls to apply to the operation before it is processed.


				
				public  read-only
				

				
$is_forwarded				

				: boolean

true if the operation is forwarded, false otherwise.

Class Operation

Methods summary

Deprecated

Parameters

Returns

Returns

Returns

Returns

Returns

Returns

The response object

The response location

Control, validation and processing

Events

Failed operation

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Returns

Todo-20150816:

Parameters

Returns

Todo-20150816:

Returns

Todo-20150816:

Returns

Returns

Parameters

Returns

Returns

Magic methods summary

Parameters

Returns

Constants summary

Properties summary

Magic properties