V8Js

From DreamFactory
Jump to: navigation, search
Line 1: Line 1:
 
V8 Javascript Scripting
 
V8 Javascript Scripting
  
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 [here](https://github.com/phpv8/v8js) 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 [here](https://github.com/phpv8/v8js) 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 [https://github.com/phpv8/v8js here] in the individual README files.
  
 
== Functions and Objects Available ==
 
== Functions and Objects Available ==
Line 11: Line 11:
 
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.
  
* print("some string") - Useful in debugging or logging from a script, the output of the call is written to the DreamFactory [log](DreamFactory/Troubleshooting).
+
* print("some string") - Useful in debugging or logging from a script, the output of the call is written to the DreamFactory [[DreamFactory/Troubleshooting|log]].
 
* var_dump(object) - Another debugging or logging function, this dumps the content of the object into the DreamFactory log as well.
 
* 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.
 
* 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.
Line 18: Line 18:
  
 
DreamFactory passes in two additional objects for use in the scripts.  
 
DreamFactory passes in two additional objects for use in the scripts.  
* `event` - This object contains the structured data about the event triggered ([Event Scripting](Events)) or from the API service call ([Custom Scripting Service](Services)). For details on this object, see [here](/DreamFactory/Features/Scripting).  
+
* `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 [here](/DreamFactory/Features/Scripting). The `platform` object is only available in V8Js scripts currently.
+
* `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 ==
 
== Including Other Scripts ==
Line 40: Line 40:
 
}
 
}
  
if (event.request.api_version !== "2.0") {
+
// Stop execution and return a specific status code
     var old = {"test": "value"};
+
if (event.resource !== "test") {
     return old;
+
     event.response.status_code = 400;
 +
    event.response.content = {"error": "Invalid resource requested."};
 +
     return;
 
}
 
}
  
return event.request;
+
// defaults to 200 status code
 +
event.response.content = {"test": "value"};
 
</pre>
 
</pre>
  
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.
+
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.

Revision as of 02:15, 5 February 2016

V8 Javascript Scripting

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 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 in the individual README files.

Functions and Objects Available

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

  • 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;

DreamFactory passes in two additional objects for use in the scripts.

  • `event` - This object contains the structured data about the event triggered (Events) or from the API service call (Services). For details on this object, see 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 here. The `platform` object is only available in V8Js scripts currently.

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);

Stopping Execution

Execution of a script is stopped prematurely by two means, throwing an exception, or returning a value.

// 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"};

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.