Controller

Plugins can interact with libkinetic through "controller" classes.

A controller class is a PHP class that implements an API interface from libkinetic. It can be specified in the kinetic file.

Constructor

The controller class may have no constructor. If it has a constructor, its signature can have these options:

public function __construct();
public function __construct(array $args);
public function __construct(MainClass $plugin);
public function __construct(MainClass $plugin, array $args);
public function __construct(KineticManager $manager);
public function __construct(KineticManager $manager, array $args);

where MainClass $plugin will be the plugin main class instance, and KineticManager $manager will be the KineticManager that handles the libkinetic logic of the plugin. The additional $args is an array of options that will be explained in the FQN section below.

The parameter names can be anything syntactically valid. The parameter type hints must be explicitly declared, with the following rules:

• for args, the parameter type must be array
• for KineticManager, the parameter type must reference to the class SOFe\Libkinetic\KineticManager
• for MainClass, the parameter type can be any class or interface extended/implemented by your plugin's main class.

Only the first two parameters will be checked by libkinetic. Developers may include extra optional parameters or mark the first two parameters as optional.

A controller class is instantiated once for each occurrence in the kinetic file. However, it is not recommended that plugins store their data in controller class properties. Instead,

• temporary flow-specific plugin data should be stored through the UserContext
• temporary session-specific or global plugin data should be stored in a less volatile object, e.g. the plugin main class (controller classes are considered volatile)
• persistent plugin data should be stored through a database managed by the plugin and cached in a less volatile object

A controller class is considered "volatile" (nothing to do with "volatile" in multithreading) because it is instantiated by libkinetic, and the same object may be instantiated multiple times if used in multiple places, making it very confusing to keep track of what is happening.

FQN

FQN is the abbreviation of "fully-qualified name" of PHP classes. In the kinetic file, certain attributes like onStart, provider, predicate etc. can accept FQNs to reference a controller.

There are special formats for the FQN:

• If an FQN starts with a $, the whole FQN (including the args part) will be passed into the KineticAdapter interface to get resolved into a controller object.
• If an FQN starts with a \, it will be used as the class name directly.
• If an FQN starts with a !, it will be prepended with the libkinetic namespace. The libkinetic source namespace SOFe\libkinetic\ must not be referenced in the kinetic file directly, because libkinetic will be shaded in production, while the kinetic file won't be shaded by the virion compiler.
• Otherwise, it will be prepended with the namespace declared in the root element.

The FQN can be followed by a semicolon ;, then a string-string map of options for the controller in the format key=value delimited by semicolonss. This map of options is the array $args in the controller constructor. These options should be very minimal, so libkinetic will not add escape logic for ; and = in the keys or ; in the values. If you really need to use = or ;, consider designing your own format of escaping characters. Nevertheless, the options are supposed to be very minimal and should not contain such special characters.