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);
}
}
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.
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.
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 theasync
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);
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.