V8Js 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.

1. 1. 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.

1. 1. 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](DreamFactory/Troubleshooting).
• 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 ([Event Scripting](Events)) or from the API service call ([Custom Scripting Service](Services)). For details on this object, see [here](/DreamFactory/Features/Scripting).
• `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.

1. 1. 1. Platform Properties

The `platform` object has the following properties:

| Field | Type | Description | |-------|------|-------------| | `platform.api` | object | An object that allows access to the DSP's REST API | | `platform.config` | object | The current configuration of the DSP | | `platform.session` | object | The current session information |

More information about `platform.api` is available on the API-Access-via-Scripts page.

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

1. 1. 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.
}

if (event.request.api_version !== "2.0") {
    var old = {"test": "value"};
    return old;
}

return event.request;

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.