waController

As a rule, controllers based on class waController are not supposed to return anything in response to received HTTP request and rather usually perform some hidden actions; e.g., update database contents, save data to files, send requests to remote resources. However, when necessary, such a controller is capable of sending any response; e.g., using echo or other similar methods.

If you need to return HTML code or a JSON string in response to an HTTP request, then it might be more convenient use a controller based on classes waViewAction, waViewActions, waViewController, waJsonController, waJsonActions.

See explanation of HTTP request routing in backend and in frontend.

Main request processing logic must be described in public method execute().

Controllers & actions

A product may have both a controller and an action class with the same combination of module_id and action_id. In this case a controller has the priority over an action for processing an HTTP request. An action in this case can be called only from within a controller when necessary.

Below is shown an example of such a controller/action couple:

• myappBackendPage.action.php
• myappBackendPage.controller.php

Methods

• appSettings

  Returns app settings values.

• configPath

  Returns path to app's configuration file.

• getApp

  Returns controller app ID.

• getAppId

  Alias for method getApp.

• getConfig

  Returns current instance of class responsible for managing system configuration.

• getPluginRoot

  Returns path to plugin source files directory, if the controller is part of an app plugin.

• getResponse

  Returns current instance of class responsible for preparing response to HTTP requests.

• getRights

  Returns information on authorized backend user's access rights.

• getStorage

  Returns current instance of class responsible for managing PHP sessions.

• getUser

  Returns current instance of class responsible for managing authorized backend users.

• getUserId

  Returns authorized backend user ID.

• logAction

  Logs information on a user action to system storage.

• preExecute

  Performs arbitrary additional actions before main controller logic.

• redirect

  Redirects a user to specified URL.

• storage

  Returns, updates, or clears values of PHP session variables.

public function appSettings ($name, $default = '')

Returns app settings values.

Parameters

• $name

  Settings field name.

• $default

  Value to be returned by default if specified settings field has no value.

Example

$app_settings = $this->appSettings();

public function configPath ($name, $custom = false)

Returns path to app's configuration file.

Parameters

• $name

  Configuration file name.

• $custom

  Flag requiring to return path to a custom configuration file from wa-config/apps/[app_id]/ directory. By default, path to app's main configuration directory wa-apps/[app_id]/lib/config/ is used.

Example

$custom_workflow_config = include $this->configPath('workflow.php', true);

public function getApp ()

Returns controller app ID.

Example

$app_id = $this->getApp();

public function getConfig ()

Returns current instance of class (waSystemConfig) responsible for managing system configuration.

Example

$current_domain = $this->getConfig()->getDomain();

public function getPluginRoot ()

Returns path to plugin source files directory, if the controller is part of an app plugin.

Example

$plugin_dir = $this->getPluginRoot();

public function getResponse ()

Returns current instance of class responsible for preparing response to HTTP requests.

Example

$this->getResponse()->redirect($url);

public function getRights ($name = null, $assoc = true)

Returns information on authorized backend user's access rights.

Parameters

• $name

  String ID of the access rights element available for the specified app. If not specified, all values of access rights for the current contact are returned. If % character is appended to the access rights element id, then the access rights values for that element are returned as an array. The array structure is defined by the value of the $assoc parameter.

• $assoc

  Flag defining the structure of the returned array:

  • true (default value): multi-fields of access rights configuration elements are included in the returned array with access rights elements' ids as array keys and 1 as their values.
  • false: array keys are incremented starting from 0, array item values containing the ids of access rights configuration elements of access rights multi-fields enabled for a user.

Example

$can_edit = $this->getRights('edit');

public function getStorage ()

Returns current instance of class responsible for managing PHP sessions.

Example

$my_session_var = $this->getStorage()->get('my_session_var');

public function getUser ()

Returns current instance of class responsible for managing authorized backend users.

Example

$user = $this->getUser();

public function getUserId ()

Returns authorized backend user ID.

Example

$user_id = $this->getUserId();

public function logAction ($action, $params = null, $subject_contact_id = null, $contact_id = null)

Logs information on a user action to system storage.

Parameters

• $action

  String action ID.

• $params

  Arbitrary array of parameters asspciated with the action.

• $subject_contact_id

  ID of contact affected by the action performed by current user.

• $contact_id

  Current user contact ID.

Example

$this->logAction(
    'page_edit',
    array(
        'id'   => 12,
        'name' => 'About us'
    ),
    null,
    $this->getUserId()
);

protected function preExecute ()

Performs arbitrary additional actions before main controller logic. This method must be implemented by the developer, if necessary.

public function redirect ($params = array(), $code = null)

Redirects a user to specified URL.

Parameters

• $params

  URL as a string or, if redirect must occur within current domain, as an associative array of GET parameters to generate a URL from.

• $code

  Server response code for the redirect. By default code 302 is used.

Example

// URL as a string
$this->redirect('https://'.$this->getConfig()->getDomain(), 301);

// URL as an array of GET parameters
$this->redirect(array(
    'module' => 'pages',
    'action' => 'edit',
    'id'     => $page_id,
));

public function storage ($name)

Returns, updates, or clears values of PHP session variables.

Parameters

• $name

  String ID of a session variable.

• $value

  If this parameter is not specified, then method returns variable value. If null is specified, then variable value is cleared. if a different value is specified, it is assigned to the variable instead of an old value.

Example

//getting variable value
$this->storage('my_var');
    
//clearing variable value
$this->storage('my_var', null);

//updating variable value
$this->storage('my_var', $new_value);