api.md

API usage

Options

The entry point of Rialto accepts multiple options, here are some descriptions with the default values:

[
    // Node's executable path
    'executable_path' => 'node',

    // How much time (in seconds) the process can stay inactive before being killed (set to null to disable)
    'idle_timeout' => 60,

    // How much time (in seconds) an instruction can take to return a value (set to null to disable)
    'read_timeout' => 30,

    // How much time (in seconds) the process can take to shutdown properly before being killed
    'stop_timeout' => 3,

    // A logger instance for debugging (must implement \Psr\Log\LoggerInterface)
    'logger' => null,

    // Logs the output of console methods (console.log, console.debug, console.table, etc...) to the PHP logger
    'log_node_console' => false,

    // Enables debugging mode:
    //   - adds the --inspect flag to Node's command
    //   - appends stack traces to Node exception messages
    'debug' => false,
]

You can define an option in your entry point using the third parameter of the parent constructor:

class MyEntryPoint extends AbstractEntryPoint
{
    public function __construct()
    {
        // ...

        $myOptions = [
            'idle_timeout' => 300, // 5 minutes
        ];

        parent::__construct($connectionDelegate, $processDelegate, $myOptions);
    }
}

Accepting user options

If you want your users to define some of Rialto's options, you can use the fourth parameter:

class MyEntryPoint extends AbstractEntryPoint
{
    public function __construct(array $userOptions = [])
    {
        // ...

        parent::__construct($connectionDelegate, $processDelegate, $myOptions, $userOptions);
    }
}

User options will override your own defaults. To prevent a user to define some specific options, use the $forbiddenOptions property:

class MyEntryPoint extends AbstractEntryPoint
{
    protected $forbiddenOptions = ['idle_timeout', 'stop_timeout'];

    public function __construct(array $userOptions = [])
    {
        // ...

        parent::__construct($connectionDelegate, $processDelegate, $myOptions, $userOptions);
    }
}

By default, users are forbidden to define the stop_timeout option.

Note: You should authorize your users to define, at least, the executable_path, logger and debug options.

Node errors

If an error (or an unhandled rejection) occurs in Node, a Node\FatalException will be thrown and the process closed, you will have to create a new instance of your entry point.

To avoid that, you can ask Node to catch these errors by prepending your instruction with ->tryCatch:

use Nesk\Rialto\Exceptions\Node;

try {
    $someResource->tryCatch->inexistantMethod();
} catch (Node\Exception $exception) {
    // Handle the exception...
}

Instead, a Node\Exception will be thrown, the Node process will stay alive and usable.

JavaScript functions

With Rialto you can create JavaScript functions and pass them to the Node process, this can be useful to map some values or any other actions based on callbacks.

To create them, you need to use the Nesk\Rialto\Data\JsFunction class and call one or multiple methods in this list:

• parameters(array): Sets parameters for your function, each string in the array is a parameter. You can define a default value for a parameter by using the parameter name as a key and its default value as the item value (e.g. ->parameters(['firstParam', 'secondParam' => 'Default string value'])).

• body(string): Sets the body of your function, just write your JS code in a PHP string (e.g. ->body("return 'Hello world!'")).

• scope(array): Defines scope variables for your function. Say you have $hello = 'Hello world!' in your PHP and you want to use it in your JS code, you can write ->scope(['myVar' => $hello]) and you will be able to use it in your body ->body("console.log(myVar)").
  Note: Scope variables must be JSON serializable values or resources created by Rialto.

• async(?bool): Makes your JS function async. Optionally, you can provide a boolean: true will make the function async, false will remove the async state.
  Note: Like in the ECMAScript specification, JS functions aren't async by default.

To create a new JS function, use JsFunction::createWith__METHOD_NAME__ with the method name you want (in the list just above):

JsFunction::createWithParameters(['a', 'b'])
    ->body('return a + b;');

Here we used createWithParameters to start the creation, but we could have used createWithBody, createWithScope, etc…

⚙️ Some examples showing how to use these methods

• A function with a body:

$jsFunction = JsFunction::createWithBody("return process.uptime()");

$someResource->someMethodWithCallback($jsFunction);

• A function with parameters and a body:

$jsFunction = JsFunction::createWithParameters(['str', 'str2' => 'Default value!'])
    ->body("return 'This is my string: ' + str");

$someResource->someMethodWithCallback($jsFunction);

• A function with parameters, a body, scoped values, and async flag:

$functionScope = ['stringtoPrepend' => 'This is another string: '];

$jsFunction = JsFunction::createWithAsync()
    ->parameters(['str'])
    ->body("return stringToPrepend + str")
    ->scope($functionScope);

$someResource->someMethodWithCallback($jsFunction);

⚠️ Deprecated examples of the JsFunction::create() method

• A function with a body:

$jsFunction = JsFunction::create("
    return process.uptime();
");

$someResource->someMethodWithCallback($jsFunction);

• A function with parameters:

$jsFunction = JsFunction::create(['str', 'str2' => 'Default value!'], "
    return 'This is my string: ' + str;
");

$someResource->someMethodWithCallback($jsFunction);

• A function with parameters, a body, and scoped values:

$functionScope = ['stringtoPrepend' => 'This is another string: '];

$jsFunction = JsFunction::create(['str'], "
    return stringToPrepend + str;
", $functionScope);

$someResource->someMethodWithCallback($jsFunction);

Destruction

If you're worried about the destruction of the Node process, here's two things you need to know:

• Once the entry point and all the resources (like the BasicResource class) are unset, the Node process is automatically terminated.
• If, for any reason, the Node process doesn't terminate, it will kill itself once the idle_timeout is exceeded.