Class Operation

An operation.

ICanBoogie\Object implements ICanBoogie\ToArrayRecursive uses ICanBoogie\ToArrayRecursiveTrait, ICanBoogie\PrototypeTrait

ICanBoogie\Operation

Direct known subclasses

Indirect known subclasses

Abstract
Namespace: ICanBoogie
Located at vendor/icanboogie/operation/lib/operation.php

Methods summary

`public static ICanBoogie\Operation`	# `from( array $properties = null, array $construct_args = array(), string\|null $class_name = null )` Creates a `ICanBoogie\Operation` instance from the specified parameters. Creates a `ICanBoogie\Operation` instance from the specified parameters. Parameters `$properties` `array` $properties Properties to be set before the constructor is invoked. `$construct_args` `array` $construct_args Arguments passed to the constructor. `$class_name` `string\|null` $class_name The name of the instance class. If empty the name of the called class is used. Returns `ICanBoogie\Operation` Overrides `ICanBoogie\Object::from`
`protected static ICanBoogie\Operation\|null`	# `from_request( ICanBoogie\HTTP\Request $request )` Creates an operation instance from a request. 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 optionaly `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` aparameters 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` `string` $uri The request URI. 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.
`protected static ICanBoogie\Operation\|null`	# `from_route( ICanBoogie\HTTP\Request $request, string $path )` Tries to create an `ICanBoogie\Operation` instance from a route. Tries to create an `ICanBoogie\Operation` instance from a route. Parameters `$request` `ICanBoogie\HTTP\Request` $request `$path` `string` $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 ICanBoogie\Operation`	# `from_module_request( ICanBoogie\HTTP\Request $request, unknown $module_id, unknown $operation_name )` Creates an `ICanBoogie\Operation` instance from a module request. Creates an `ICanBoogie\Operation` instance from a module request. Parameters `$request` `ICanBoogie\HTTP\Request` $request `$module_id` `unknown` $module_id `$operation_name` `unknown` $operation_name Returns `ICanBoogie\Operation` Throws `ICanBoogie\HTTP\HTTPError` if the operation is not supported by the module.
`public static string`	# `encode( string $pattern, array $params = array() )` Encodes a RESTful operation. Encodes a RESTful operation. Parameters `$pattern` `string` $pattern `$params` `array` $params Returns `string` The operation encoded as a RESTful relative URL.
`public static string`	# `format_class_name( string $namespace, string $operation_name )` Formats the specified namespace and operation name into an operation class. Formats the specified namespace and operation name into an operation class. Parameters `$namespace` `string` $namespace `$operation_name` `string` $operation_name Returns `string`
`protected`	# `get_request( )`
`protected array`	# `get_controls( )` Returns the controls to pass. Returns the controls to pass. Returns `array` All the controls set to false.
`protected ICanBoogie\ActiveRecord`	# `lazy_get_record( )` Getter for the $record property. Getter for the $record property. Returns `ICanBoogie\ActiveRecord`
`protected ICanBoogie\Operation\Response`	# `get_response( )` Returns the operation response. Returns the operation response. Returns `ICanBoogie\Operation\Response`
`protected object\|null`	# `lazy_get_form( )` Getter for the `ICanBoogie\Operation::$form` property. 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 array`	# `lazy_get_properties( )` Getter for the `ICanBoogie\Operation::$properties` property. Getter for the `ICanBoogie\Operation::$properties` property. The getter should only be called during the `ICanBoogie\Operation::process()` method. Returns `array`
`protected`	# `get_module( )`
`protected boolean`	# `get_is_forwarded( )` Returns `true` if the operation is forwarded. 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. Constructor. The $controls property is unset in order for its getters to be called on the next access, while keeping its scope. Parameters `$request` `ICanBoogie\HTTP\Request` $request @todo: should be a Request, but is sometimes a module.
`public ICanBoogie\Operation\Response`	# `__invoke( ICanBoogie\HTTP\Request $request )` Handles the operation and prints or returns its result. 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` `ICanBoogie\HTTP\Request` $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.
`protected`	# `reset( )` Resets the operation state. Resets the operation state. A same operation object can be used multiple time to perform an operation with different parameters, this method is invoked to reset the operation state before it is controled, validated and processed.
`protected boolean`	# `control( array $controls )` Controls the operation. 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: array ( 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. array ( 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: 1. 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. 2. 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. 3. 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. 4. 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. 5. 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. 6. 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` `array` $controls The controls to pass for the operation to be processed. Returns `boolean` true if all the controls pass, false otherwise. Throws `ICanBoogie\HTTP\HTTPError` Depends on the control.
`protected boolean`	# `control_method( string $method )` Controls the request method. Controls the request method. If the method is ICanBoogie\Request::METHOD_ANY it always matches. Parameters `$method` `string` $method Returns `boolean` `true` if the method matches, `false` otherwise.
`protected boolean`	# `control_session_token( )` Controls the session token. Controls the session token. Returns `boolean` true if the token is defined and correspond to the session token, false otherwise.
`protected`	# `control_authentication( )` Controls the authentication of the user. Controls the authentication of the user.
`protected boolean`	# `control_permission( mixed $permission )` Controls the permission of the user for the operation. Controls the permission of the user for the operation. Parameters `$permission` `mixed` $permission The required permission. Returns `boolean` true if the user has the specified permission, false otherwise.
`protected boolean`	# `control_ownership( )` Controls the ownership of the user over the operation target record. Controls the ownership of the user over the operation target record. Returns `boolean` true if the user as ownership of the record or there is no record, false otherwise.
`protected ICanBoogie\ActiveRecord\|null`	# `control_record( )` Checks if the operation target record exists. Checks if the operation target record exists. The method simply returns the $record property, which calls the `ICanBoogie\Operation::lazy_get_record()` getter if the property is not accessible. Returns `ICanBoogie\ActiveRecord\|null`
`protected boolean`	# `control_form( )` Control the operation's form. 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 boolean`	# `validate( ICanBoogie\Errors $errors )` Validates the operation before processing. Validates the operation before processing. The method is abstract and therefore must be implemented by subclasses. Returns `boolean` true if the operation is valid, false otherwise. Throws `Exception` If something horribly wrong happens.
`abstract protected mixed`	# `process( )` Processes the operation. Processes the operation. The method is abstract and therefore must be implemented by subclasses. Returns `mixed` Depends on the implementation.

Magic methods summary

Constants summary

`string`	`DESTINATION`	`'_operation_destination'`	# Defines the destination of a forwarded operation. Defines the destination of a forwarded operation.
`string`	`NAME`	`'_operation_name'`	# Defines the operation name of a forwarded operation. Defines the operation name of a forwarded operation.
`string`	`KEY`	`'_operation_key'`	# Defines the key of the resource targeted by the operation. Defines the key of the resource targeted by the operation.
`string`	`SESSION_TOKEN`	`'_session_token'`	# Defines the session token to be matched. Defines the session token to be matched.
`string`	`RESTFUL_BASE`	`'/api/'`	#
`integer`	`RESTFUL_BASE_LENGTH`	`5`	#
`integer`	`CONTROL_METHOD`	`101`	#
`integer`	`CONTROL_SESSION_TOKEN`	`102`	#
`integer`	`CONTROL_AUTHENTICATION`	`103`	#
`integer`	`CONTROL_PERMISSION`	`104`	#
`integer`	`CONTROL_RECORD`	`105`	#
`integer`	`CONTROL_OWNERSHIP`	`106`	#
`integer`	`CONTROL_FORM`	`107`	#

Properties summary

`public mixed`	`$key`	#
`public mixed`	`$destination`	#
`protected ICanBoogie\HTTP\Request`	`$request`	# The request triggering the operation. The request triggering the operation.
`public mixed`	`$response`	#
`public mixed`	`$method`	#
`protected object`	`$form`	# The form object of the operation. The form object of the operation.
`protected array`	`$properties`	# The properties for the operation. The properties for the operation.
`protected string`	`$format`	# Output format of the operation response. Output format of the operation response.
`protected ICanBoogie\Module`	`$module`	# Target module for the operation. Target module for the operation. The property is set by the constructor.

Magic properties

`public ICanBoogie\ActiveRecord`	`$record`	# The target active record object of the operation. The target active record object of the operation.
`public read-only ICanBoogie\HTTP\Request`	`$request`	# The request. The request.
`public read-only boolean`	`$is_forwarded`	# `true` if the operation is forwarded. See `ICanBoogie\Operation::get_is_forwarded()`. `true` if the operation is forwarded. See `ICanBoogie\Operation::get_is_forwarded()`.

Magic properties inherited from ICanBoogie\Object

$prototype

Namespaces

Classes

Interfaces

Traits

Exceptions

Constants

Functions

Class Operation

Direct known subclasses

Indirect known subclasses

Methods summary

Parameters

Returns

Overrides

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

Throws

Parameters

Returns

Returns

Parameters

Returns

Returns

Returns

Returns

Returns

Throws

Returns

Methods inherited from ICanBoogie\Object

Methods inherited from ICanBoogie\ToArrayRecursive

Methods used from ICanBoogie\ToArrayRecursiveTrait

Methods used from ICanBoogie\PrototypeTrait

Magic methods summary

Constants summary

Properties summary

Magic properties

Magic properties inherited from ICanBoogie\Object