\org_openpsa_user_viewer

Request class for user management

It provides an automatic mechanism for URL processing and validation, minimizing the required work to get a new component running.

Request switch configuration

The class uses an array which aids in URL-to-function mapping. Handlers are distinguished by the "URL-space" they handle. For each handler three functions are needed, one for the request handle decision ("Can Handle Phase"), one for the request handling ("Handle Phase") and one for output ("Output Phase"). These handlers refer to another class which gets instantiated if necessary.

All request handlers are contained in a single array, whose keys identify the various switch configurations. These identifiers are only for informational purposes (they appear in the debug log), so you could just resort to automatic array index numbering using the [] operator.

Each request handler definition in the switch must contain these key/value pairs:

  • mixed fixed_args: This is either a string or an array and defines the fixed arguments that have to be present at the beginning of the URL to be handled. A string denotes a single argument, an array is used if more than one fixed argument is needed. If you do not have any fixed arguments, set this parameter to null, which is the default.

  • int variable_args: Usually, there are a number of variables in the URL, like article IDs, or article names. This can be 0, indicating that no variable arguments are required, which is the default. For an unlimited number of variable_args set it to -1.

  • mixed handler: This is a definition of what method should be invoked to handle the request using the callable array syntax. The first array member must contain the name of an existing class. This value has no default and must be set. The actual methods called will have either an handler or show prefix.

Example:

$this->_request_switch[] = [ 'fixed_args' => ['registrations', 'view'], 'variable_args' => 1, 'handler' => ['net_nemein_registrations_regadmin', 'view'] ];

This definition is usually located in either in the routes.inc file (preferred) or the _on_initialize event handler.

The handlers are processed in the order which they have been added to the array. This has several implications:

First, if you have two handlers with similar signatures, the latter might be hidden by the former, for example the handler 'view' with two variable arguments includes the urls that could match 'view', 'registration' with a single variable argument if processed in this order. In these cases you have to add the most specific handlers first.

Second, for performance reasons, you should try to add the handler which will be accessed most of the time first (unless it conflicts with the first rule above), as this will speed up average request processing.

It is recommended that you add string-based identifiers to your handlers. This makes debugging of URL parsing much easier, as MidCOM logs which request handlers are checked in debug mode. The above example could use something like $this->_request_switch['registrations-view'] to do so. Just never prefix one of your handlers with one underscores, this namespace is reserved for MidCOM usage.

Callback method signatures

/**

  • Exec handler example, with Docblock:
  • @param mixed $handler_id The ID of the handler.
  • @param array $args The argument list.
  • @param array &$data The local request data. {@*} public function _handler_xxx ($handler_id, array $args, array &$data) {}

/**

  • Show handler example, with Docblock:
  • @param mixed $handler_id The ID of the handler.
  • @param array &$data The local request data. {@*} public function _show_xxx ($handler_id, array &$data) {}

The two callbacks match the regular processing sequence of MidCOM.

The main callback _handle_xxx is mandatory, _show_xxx is optional since the handle method can return a response directly.

As you can see, the system provides you with an easy way to keep track of the data of your request, without having dozens of members for trivial flags. This data array is automatically registered in the custom component context under the name 'request_data', making it easily available within style elements as $data

The data array can also be accessed by using the $_request_data member of this class, which is the original data storage location for the request data.

Note that the request data, for ease of use, already contains the L10n Databases of the Component and MidCOM itself located in this class. They are stored as 'l10n' and 'l10n_midcom'. Also available as 'config' is the current component configuration and 'topic' will hold the current content topic.

Automatic handler class instantiation

If you specify a class name instead of a class instance as an exec handler, MidCOM will automatically create an instance of that class type and initialize it. These so-called handler classes must be a subclass of midcom_baseclasses_components_handler.

The subclasses you create should look about this:

class my_handler extends midcom_baseclasses_components_handler { public function _on_initialize() { // Add class initialization code here, all members have been prepared } }

The two methods for each handler have the same signature as if they were in the same class.

Plugin Interface

This class includes a plugin system which can be used to flexibly enhance the functionality of the request classes by external sources. Your component does not have to worry about this, you just have to provide a way to register plugins to site authors.

Plugins always come in "packages", which are assigned to a namespace. The namespace is used to separate various plugins from each other, it is prepended before any URL. Within a plugin you can register one or more handler classes. Each of this classes can of course define more than one request handler.

A plugin class must be a descendant of midcom_baseclasses_components_handler or at least support its full interface.

As outlined above, plugins are managed in a two-level hierarchy. First, there is the plugin identifier, second the class identifier. When registering a plugin, these two are specified. The request handlers obtained by the above callback are automatically expanded to match the plugin namespace.

Example: Plugin registration

$this->register_plugin_namespace( '__ais', [ 'folder' => [ 'class' => 'midcom_admin_folder_management', 'config' => null, ], ] );

The first argument of this call identifies the plugin namespace, the second the list of classes associated with this plugin. Each class gets its own identifier. The namespace and class identifier is used to construct the final plugin URL: {$anchor_prefix}/{$namespace}/{$class_identifier}/... This gives fully unique URL namespaces to all registered plugins.

Plugin handlers always last in queue, so they won't override component handlers. Their name is prefixed with __{$namespace}-{$class_identifier} to ensure uniqueness.

Each class must have these options:

  • class: The name of the class to use
  • src: The source URL of the plugin class. This can be either a file:/... URL which is relative to MIDCOM_ROOT, snippet:/... which identifies an arbitrary snippet, or finally, component:... which will load the component specified. This is only used if the class is not yet available.
  • name: This is the clear-text name of the plugin.
  • config: This is an optional configuration argument, allows for customization. May be omitted, in which case it defaults to null.

Once a plugin has been successfully initialized, its configuration is put into the request data:

  • mixed plugin_config: The configuration passed to the plugin as outlined above.
  • string plugin_name: The name of the plugin as defined in its config

Summary

Methods
Properties
Constants
__construct()
initialize()
can_handle()
get_router()
handle()
show()
_on_initialize()
_on_handle()
_on_handled()
register_plugin_namespace()
__get()
__isset()
set_active_leaf()
add_stylesheet()
get_workflow()
$_topic
$_config
$_request_data
$_node_toolbar
$_view_toolbar
$_handler
$_component
$_i18n
$_l10n
$_l10n_midcom
$_config
No constants found
No protected methods found
$router
$_request_switch
N/A
_prepare_handler()
_load_plugin()
_register_core_plugin_namespaces()
$_plugin_namespace_config
$active_plugin
$loader
$_services
N/A

Properties

$_topic

$_topic : \midcom_db_topic

The topic for which we are handling a request.

Type

\midcom_db_topic

$_request_data

$_request_data : array

Request specific data storage area. Registered in the component context as ''.

Type

array

$_node_toolbar

$_node_toolbar : \midcom_helper_toolbar

The node toolbar for the current request context. Not available during the can_handle phase.

Type

\midcom_helper_toolbar

$_view_toolbar

$_view_toolbar : \midcom_helper_toolbar

The view toolbar for the current request context. Not available during the can_handle phase.

Type

\midcom_helper_toolbar

$_handler

$_handler : Array

The handler which has been declared to be able to handle the request. The array will contain the original index of the handler in the '_route' member for backtracking purposes. The variable argument list will be placed into 'args' for performance reasons.

Type

Array

$_component

$_component : string

The name of the component, e.g. net.nehmer.static. Should be used whenever the component's name is required instead of hardcoding it.

Type

string

$_i18n

$_i18n : \midcom_services_i18n

A handle to the i18n service.

Type

\midcom_services_i18n

$_l10n

$_l10n : \midcom_services_i18n_l10n

The components' L10n string database.

Type

\midcom_services_i18n_l10n

$_l10n_midcom

$_l10n_midcom : \midcom_services_i18n_l10n

The global MidCOM string database.

Type

\midcom_services_i18n_l10n

$_config

$_config : \midcom_helper_configuration

The current configuration.

Type

\midcom_helper_configuration

$router

$router : \Symfony\Component\Routing\Router

Type

\Symfony\Component\Routing\Router

$_request_switch

$_request_switch : array

Request execution switch configuration.

The main request switch data. You need to set this during construction, it will be post-processed afterwards during initialize to provide a unified set of data. Therefore you must not modify this switch after construction.

Type

array

$_plugin_namespace_config

$_plugin_namespace_config : array

This variable keeps track of the registered plugin namespaces. It maps namespace identifiers against plugin config lists. This is used during can_handle startup to determine whether the request has to be relayed to a plugin.

You have to use the register_plugin_namespace() member function during the _on_initialize event to register plugin namespaces.

Type

array

$active_plugin

$active_plugin : 

Type

$loader

$loader : 

Type

$_services

$_services : array

Array that holds the already instantiated services

Type

array

Methods

__construct()

__construct() 

Initialize all member variables, remember to set $_component before calling this constructor from your derived classes.

initialize()

initialize(string  $component) 

Initializes the request handler class, called by the component interface after instantiation.

Parameters

string $component

The name of the component.

can_handle()

can_handle(\Symfony\Component\HttpFoundation\Request  $request) : boolean

CAN_HANDLE Phase interface, checks against all registered handlers if a valid one can be found. You should not need to override this, instead, use the HANDLE Phase for further checks.

Parameters

\Symfony\Component\HttpFoundation\Request $request

Returns

boolean —

Indicating whether the request can be handled by the class, or not.

get_router()

get_router(string  $component = null) : \Symfony\Component\Routing\Router

Parameters

string $component

Returns

\Symfony\Component\Routing\Router

handle()

handle() : \midcom_response|null

Handle the request using the handler determined by the can_handle check.

Before doing anything, it will call the _on_handle event handler to allow for generic request preparation.

Returns

\midcom_response|null —

The response object (or null in the case of old-style handlers)

show()

show() 

Display the content, it uses the handler as determined by can_handle.

_on_initialize()

_on_initialize() 

Initialization event handler, called at the end of the initialization process

Use this function instead of the constructor for all initialization work. You can safely populate the request switch from here.

You should not do anything else then general startup work, as this callback executes before the can_handle phase. You don't know at this point whether you are even able to handle the request. Thus, anything that is specific to your request (like HTML HEAD tag adds) must not be done here. Use _on_handle instead.

_on_handle()

_on_handle(  $handler_id, array  $args) 

Component specific initialization code for the handle phase. The name of the request handler is passed as an argument to the event handler.

Note, that while you have the complete information around the request (handler id, args and request data) available, it is strongly discouraged to handle everything here. Instead, stay with the specific request handler methods as far as sensible.

Parameters

$handler_id
array $args

The argument list.

_on_handled()

_on_handled(  $handler, array  $args) 

Parameters

$handler
array $args

register_plugin_namespace()

register_plugin_namespace(string  $namespace, array  $config) 

Create a new plugin namespace and map the configuration to it.

It allows flexible, user-configurable extension of components.

Only very basic testing is done to keep runtime up, currently the system only checks to prevent duplicate namespace registrations. In such a case, midcom_error will be thrown. Any further validation won't be done before can_handle determines that a plugin is actually in use.

Parameters

string $namespace

The plugin namespace, checked against $args[0] during URL parsing.

array $config

The configuration of the plugin namespace as outlined in the class introduction

__get()

__get(  $field) 

Parameters

$field

__isset()

__isset(  $field) 

Parameters

$field

set_active_leaf()

set_active_leaf(  $leaf_id) 

Parameters

$leaf_id

add_stylesheet()

add_stylesheet(string  $url, string  $media = false) 

Convenience shortcut for adding CSS files

Parameters

string $url

The stylesheet URL

string $media

The media type(s) for the stylesheet, if any

get_workflow()

get_workflow(string  $identifier, array  $options = array()) : \midcom\workflow\dialog

Parameters

string $identifier
array $options

Returns

\midcom\workflow\dialog

_prepare_handler()

_prepare_handler(array  $request) 

Prepares the handler callback for execution.

This will create the handler class instance if required.

Parameters

array $request

Throws

\midcom_error

_load_plugin()

_load_plugin(string  $namespace, string  $name) 

Load the specified namespace/plugin combo.

Any problem to load a plugin will be logged accordingly and false will be returned. Critical errors will trigger midcom_error.

Parameters

string $namespace

The plugin namespace to use.

string $name

The plugin to load from the namespace.

_register_core_plugin_namespaces()

_register_core_plugin_namespaces() 

Register the plugin namespaces provided from MidCOM core.