Class Operation

An operation.

ICanBoogie\Object

┗ ICanBoogie\Operation

Direct known subclasses

ICanBoogie\Operation\PingOperation

Abstract
Namespace: ICanBoogie
Located at Operation.php

Methods summary


				
				 public static
				
				

				from(  $properties = null, array $construct_args = [],  $class_name = null )
				

				: ICanBoogie\Operation

Creates a ICanBoogie\Operation instance from the specified parameters.


				
				 protected static
				
				

				from_request( ICanBoogie\HTTP\Request $request )
				

				: ICanBoogie\Operation|null

Creates an operation instance from a request.

An operation can be defined as a route, in which case the path of the request starts with "/api/". An operation can also be defined using the request parameters, in which case the ICanBoogie\Operation::DESTINATION, ICanBoogie\Operation::NAME and optionally ICanBoogie\Operation::KEY parameters are defined within the request parameters.

When the operation is defined as a route, the method searches for a matching route.

If a matching route is found, the captured parameters of the matching route are merged with the request parameters and the method tries to create an Operation instance using the route.

If no matching route could be found, the method tries to extract the ICanBoogie\Operation::DESTINATION, ICanBoogie\Operation::NAME and optional ICanBoogie\Operation::KEY parameters from the route using the /api/:destination(/:key)/:name pattern. If the route matches this pattern, captured parameters are merged with the request parameters and the operation decoding continues as if the operation was defined using parameters instead of the REST API.

Finally, the method searches for the ICanBoogie\Operation::DESTINATION, ICanBoogie\Operation::NAME and optional ICanBoogie\Operation::KEY parameters within the request parameters to create the Operation instance.

If no operation was found in the request, the method returns null.

Instancing using the matching route

The matching route must define either the class of the operation instance (by defining the class key) or a callback that would create the operation instance (by defining the callback key).

If the route defines the instance class, it is used to create the instance. Otherwise, the callback is used to create the instance.

Instancing using the request parameters

The operation destination (specified by the ICanBoogie\Operation::DESTINATION parameter) is the id of the destination module. The class and the operation name (specified by the ICanBoogie\Operation::NAME parameter) are used to search for the corresponding operation class to create the instance:

ICanBoogie\<normalized_module_id>\<normalized_operation_name>Operation

The inheritance of the module class is used the find a suitable class. For example, these are the classes tried for the "articles" module and the "save" operation:

ICanBoogie\Modules\Articles\SaveOperation
ICanBoogie\Modules\Contents\SaveOperation
ICanBoogie\Modules\Nodes\SaveOperation

An instance of the found class is created with the request arguments and returned. If the class could not be found to create the operation instance, an exception is raised.

Parameters

$request: The request parameters.

Returns

ICanBoogie\Operation|null
The decoded operation or null if no operation was found.

Throws

BadMethodCallException

when the destination module or the operation name is not defined for a module operation.

ICanBoogie\HTTP\NotFound
if the operation is not found.


				
				 protected static
				
				

				from_route( ICanBoogie\HTTP\Request $request, string $path )
				

				: ICanBoogie\Operation|null

Tries to create an ICanBoogie\Operation instance from a route.

Parameters

$request
$path: An API path.

Returns

ICanBoogie\Operation|null

Throws

Exception
If the route controller fails to produce an ICanBoogie\Operation instance.
InvalidArgumentException

If the route's controller cannot be determined from the route definition.


				
				 protected static
				
				

				from_module_request( ICanBoogie\HTTP\Request $request, string $module_id, string $operation_name )
				

				: ICanBoogie\Operation

Creates an ICanBoogie\Operation instance from a module request.

Parameters

$request
$module_id
$operation_name

Returns

ICanBoogie\Operation

Throws

Exception
if the operation is not supported by the module.


				
				 public static
				
				

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

				: string

Encodes a RESTful operation.


				
				 public static
				
				

				format_class_name( string $namespace, string $operation_name )
				

				: string

Formats the specified namespace and operation name into an operation class.


				
				 protected 
				
				

				get_request( void )


				
				 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 
				
				

				lazy_get_properties( void )
				

				: array

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


				
				 protected 
				
				

				get_module( void )


				
				 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


				
				 public 
				
				

				__construct( ICanBoogie\HTTP\Request $request = null )

Constructor.


				
				 public 
				
				

				__invoke( ICanBoogie\HTTP\Request $request )
				

				: ICanBoogie\Operation\Response

Handles the operation and prints or returns its result.

The $record, ICanBoogie\Operation::$form and ICanBoogie\Operation::$properties 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/system.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.


				
				 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\Errors $errors )
				

				: boolean

Validates the operation before processing.


				
				abstract protected 
				
				

				process( void )
				

				: mixed

Processes the operation.

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  
				

				
$destination


				
				protected  
				

				
$request				

				: ICanBoogie\HTTP\Request

The request triggering the operation.


				
				public  
				

				
$response				

				: ICanBoogie\Operation\Response


				
				public  
				

				
$method				

				: string


				
				protected  
				

				
$form				

				: object

The form object of the operation.


				
				protected  
				

				
$properties				

				: array

The properties for the operation.


				
				protected  
				

				
$format				

				: string

Output format of the operation response.


				
				protected  
				

				
$module				

				: Module

Target module for the operation.

Magic properties


				
				public  
				

				
$record				

				: ActiveRecord

The target active record object of the operation.


				
				public  read-only
				

				
$app				

				: Core


				
				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

Direct known subclasses

Methods summary

Returns

Inheritdoc

Instancing using the matching route

Instancing using the request parameters

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Returns

Returns

Returns

Parameters

The response object

The response location

Control, validation and processing

Events

Failed operation

Parameters

Returns

Throws

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Returns

Parameters

Returns

Returns

Returns

Returns

Parameters

Returns

Returns

Constants summary

Properties summary

Magic properties