Updated README for GitHub.

README.md

@@ -1,30 +1,29 @@
 V8Js
 ====
 
-This is a PHP extension for Google's V8 Javascript engine 
+This is a PHP extension for Google's V8 Javascript engine.
+
+The extension allows you 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.
 
 
 Minimum requirements
 --------------------
 
-- V8 JavaScript Engine library version 2.5.8 <http://code.google.com/p/v8/> (trunk)
+- V8 Javascript Engine library (libv8) version 3.2.4 or above <http://code.google.com/p/v8/> (trunk)
 
-	V8 is Google's open source JavaScript engine.
+	V8 is Google's open source Javascript engine.
 	V8 is written in C++ and is used in Google Chrome, the open source browser from Google.
-	V8 implements ECMAScript as specified in ECMA-262, 5th edition, and runs on Windows (XP or newer), 
+	V8 implements ECMAScript as specified in ECMA-262, 5th edition.
-	Mac OS X (10.5 or newer), and Linux systems that use IA-32, x64, or ARM processors.
+    This extension makes use of V8 isolates to ensure separation between multiple V8Js instances, hence the need for 3.2.4 or above.
-	V8 can run standalone, or can be embedded into any C++ application.
-	You can find more information here:
-	<http://code.google.com/p/v8/>
 
-- PHP 5.3.3+ (non-ZTS build preferred)
+- PHP 5.3.3+
-  Note: V8 engine is not natively thread safe and this extension
+
-  has not been designed to work around it either yet and might or
+  This embedded implementation of the V8 engine uses thread locking so it should work with ZTS enabled.
-  might not work properly with ZTS enabled PHP. :)
+  However, this has not been tested yet.
 
 
-API
+PHP API
-===
+=======
 
     class V8Js
     {
@@ -37,23 +36,28 @@ API
         /* Methods */
 
         // Initializes and starts V8 engine and Returns new V8Js object with it's own V8 context.
-        public __construct ( [string object_name = "PHP" [, array variables = NULL [, array extensions = NULL [, bool report_uncaught_exceptions = TRUE]]] )
+        public __construct ( [ string $object_name = "PHP" [, array $variables = NULL [, array $extensions = NULL [, bool $report_uncaught_exceptions = TRUE ] ] ] )
+
+        // Provide a function or method to be used to load required modules. This can be any valid PHP callable.
+        // The loader function will receive the normalised module path and should return Javascript code to be executed.
+        public setModuleLoader ( callable $loader )
 
         // Compiles and executes script in object's context with optional identifier string.
-        public mixed V8Js::executeString( string script [, string identifier [, int flags = V8Js::FLAG_NONE]])
+        // A time limit (milliseconds) and/or memory limit (bytes) can be provided to restrict execution. These options will throw a V8JsTimeLimitException or V8JsMemoryLimitException.
+        public mixed V8Js::executeString( string $script [, string $identifier [, int $flags = V8Js::FLAG_NONE [, int $time_limit = 0 [, int $memory_limit = 0]]]])
 
         // Returns uncaught pending exception or null if there is no pending exception.
-        public V8JsScriptException V8Js::getPendingException( void )
+        public V8JsScriptException V8Js::getPendingException( )
 
         /** Static methods **/
 
         // Registers persistent context independent global Javascript extension.
         // NOTE! These extensions exist until PHP is shutdown and they need to be registered before V8 is initialized. 
         // For best performance V8 is initialized only once per process thus this call has to be done before any V8Js objects are created!
-        public static bool V8Js::registerExtension(string ext_name, string script [, array deps [, bool auto_enable = FALSE]])
+        public static bool V8Js::registerExtension( string $extension_name, string $code [, array $dependenciess [, bool $auto_enable = FALSE ] ] )
 
         // Returns extensions successfully registered with V8Js::registerExtension().
-        public static array V8Js::getExtensions( void )
+        public static array V8Js::getExtensions( )
     }
 
     final class V8JsScriptException extends Exception
@@ -65,10 +69,33 @@ API
         protected string JsTrace = NULL;
         
         /* Methods */
-        final public string getJsFileName( void )
+        final public string getJsFileName( )
-        final public int getJsLineNumber( void )
+        final public int getJsLineNumber( )
-        final public string getJsSourceLine( void )
+        final public string getJsSourceLine( )
-        final public string getJsTrace( void )
+        final public string getJsTrace( )
     }
-    
+
+    final class V8JsTimeLimitException extends Exception
+    {
+    }
+
+    final class V8JsMemoryLimitException extends Exception
+    {
+    }
+
+Javascript API
+==============
+
+    // Print a string.
+    print(string);
+
+    // Dump the contents of a variable.
+    var_dump(value);
+
+    // Terminate Javascript execution immediately.
+    exit();
+
+    // CommonJS Module support to require external code.
+    // This makes use of the PHP module loader provided via V8Js::setModuleLoader (see PHP API above).
+    require("path/to/module");