V8Js

From DreamFactory
Jump to: navigation, search
Line 1: Line 1:
V8 Javascript Scripting
+
V8Js is a popular PHP extension that uses Google's V8 engine to execute Javascript code in a secure sandbox from within PHP. The executed code can be restricted using a time limit and/or memory limit. This provides the possibility to execute untrusted code with confidence. '''Note:''' While the scripts are written in Javascript, not all functionality available in browser-based Javascript is available in V8Js, particular things related to the DOM, window, or console. Go [https://github.com/phpv8/v8js here] for more information.
 
+
V8Js is a popular PHP extension that uses Google's V8 engine to execute Javascript code in a secure sandbox from PHP. The executed code can be restricted using a time limit and/or memory limit. This provides the possibility to execute untrusted code with confidence. '''Note:''' While the scripts are written in Javascript, not all functionality available in browser-based Javascript is available in V8Js, particular things related to the DOM, window, or console. Go [https://github.com/phpv8/v8js here] for more information.
+
  
 
== Requirements ==
 
== Requirements ==
  
V8Js is a PHP extension that currently is not part of the PHP standard distribution. It is however included in all of our Bitnami installs, including the IaaS and PaaS environments. If you are installing DreamFactory by other means, methods for compiling the extension can be found [https://github.com/phpv8/v8js here] in the individual README files.
+
V8Js is a PHP extension that currently is not part of the PHP standard distribution. It is however included in all of our Bitnami installs, including the IaaS and PaaS environments. If you are installing DreamFactory by other means, methods for compiling the extension can be found [[DreamFactory/Installation/Modules/v8js|here]] or more externally [https://github.com/phpv8/v8js here] in the individual README files.
  
== Functions and Objects Available ==
+
== Additional Functions Available ==
  
In addition to standard Javascript functions, the following functions are also available for use in V8Js.
+
In addition to standard Javascript functions, the following functions are also available for use in V8Js scripts.
  
 
* print("some string") - Useful in debugging or logging from a script, the output of the call is written to the DreamFactory [[DreamFactory/Troubleshooting|log]].
 
* print("some string") - Useful in debugging or logging from a script, the output of the call is written to the DreamFactory [[DreamFactory/Troubleshooting|log]].
Line 17: Line 15:
 
* exit() - This function halts the script, and currently blows up the PHP execution as well, so don't use it! Use throw('error string'); instead;
 
* exit() - This function halts the script, and currently blows up the PHP execution as well, so don't use it! Use throw('error string'); instead;
  
DreamFactory passes in two additional objects for use in the scripts.
+
== Accessing Resources ==
* `event` - This object contains the structured data about the event triggered ([[DreamFactory/Features/Scripting/Event Scripting|Events]]) or from the API service call ([[DreamFactory/Features/Scripting/Custom Scripting Service|Services]]). For details on this object, see [[DreamFactory/Features/Scripting|here]].
+
* `platform` - This object may be used to access the REST API of your DSP via **inline** calls. This make service requests directly without requiring an HTTP call. For details on this object, see [[DreamFactory/Features/Scripting|here]]. The `platform` object is only available in V8Js scripts currently.
+
  
== Including Other Scripts ==
+
DreamFactory passes in two [[DreamFactory/Features/Scripting Resources Available To A Script|additional objects]] for use in the scripts.
 +
In V8Js, these resources are represented as javascript objects and can be accessed as normal. See the examples below.
  
The script 'test.js' is located in the storage/scripting/ directory on my instance and simple defines an array, i.e. "exports.a = ['one', 'two','three'];
+
Using the '''event''' resource...
 +
<source lang="javascript">
 +
result = platform.api.post("http://example.com/my_api", {"name":"test"}, options);
 +
</source>
  
<pre>
+
Using the '''platform''' resource...
test = require('test.js');
+
<source lang="javascript">
var_dump(test.a);
+
</pre>
+
 
+
== Stopping Execution ==
+
 
+
Execution of a script is stopped prematurely by two means, throwing an exception, or returning a value.
+
 
+
<pre>
+
 
// Stop execution if verbs other than GET are used in Custom Scripting Service
 
// Stop execution if verbs other than GET are used in Custom Scripting Service
 
if (event.request.method !== "GET") {
 
if (event.request.method !== "GET") {
Line 49: Line 41:
 
// defaults to 200 status code
 
// defaults to 200 status code
 
event.response.content = {"test": "value"};
 
event.response.content = {"test": "value"};
</pre>
+
</source>
  
Event scripts can halt propagation to future listeners as well. Setting the '''event.stop_propagation''' property to '''true''' will halt propagation of the event immediately upon return from the script.
+
 
 +
== Including Other Scripts ==
 +
 
 +
The script 'test.js' is located in the storage/scripting/ directory on my instance and simple defines an array, i.e. "exports.a = ['one', 'two','three'];
 +
 
 +
<source lang="javascript">
 +
test = require('test.js');
 +
var_dump(test.a);
 +
</source>

Revision as of 15:18, 23 February 2016

V8Js is a popular PHP extension that uses Google's V8 engine to execute Javascript code in a secure sandbox from within PHP. The executed code can be restricted using a time limit and/or memory limit. This provides the possibility to execute untrusted code with confidence. Note: While the scripts are written in Javascript, not all functionality available in browser-based Javascript is available in V8Js, particular things related to the DOM, window, or console. Go here for more information.

Requirements

V8Js is a PHP extension that currently is not part of the PHP standard distribution. It is however included in all of our Bitnami installs, including the IaaS and PaaS environments. If you are installing DreamFactory by other means, methods for compiling the extension can be found here or more externally here in the individual README files.

Additional Functions Available

In addition to standard Javascript functions, the following functions are also available for use in V8Js scripts.

  • print("some string") - Useful in debugging or logging from a script, the output of the call is written to the DreamFactory log.
  • var_dump(object) - Another debugging or logging function, this dumps the content of the object into the DreamFactory log as well.
  • sleep(seconds) - Pauses execution for the number of seconds passed in. Take care, as V8Js executes in a limited time, delaying processing obviously delays API handling.
  • require('script_name.js') - As in Javascript, this allows you to pull in others scripts. Scripts can currently be pulled from the <install directory>/storage/scripting/ simply by using the name of the script, i.e. 'test.js'.
  • exit() - This function halts the script, and currently blows up the PHP execution as well, so don't use it! Use throw('error string'); instead;

Accessing Resources

DreamFactory passes in two additional objects for use in the scripts. In V8Js, these resources are represented as javascript objects and can be accessed as normal. See the examples below.

Using the event resource...

result = platform.api.post("http://example.com/my_api", {"name":"test"}, options);

Using the platform resource...

// Stop execution if verbs other than GET are used in Custom Scripting Service
if (event.request.method !== "GET") {
    throw "Only HTTP GET is allowed on this endpoint."; // will result in a 500 back to client with the given message.
}
 
// Stop execution and return a specific status code
if (event.resource !== "test") {
    event.response.status_code = 400;
    event.response.content = {"error": "Invalid resource requested."};
    return;
}
 
// defaults to 200 status code
event.response.content = {"test": "value"};


Including Other Scripts

The script 'test.js' is located in the storage/scripting/ directory on my instance and simple defines an array, i.e. "exports.a = ['one', 'two','three'];

test = require('test.js');
var_dump(test.a);