RUNKIT_SANDBOX(3)							 1							 RUNKIT_SANDBOX(3)

Runkit_Sandbox - Runkit Sandbox Class -- PHP Virtual Machine

	Instantiating  the  Runkit_Sandbox  class  creates a new thread with its own scope and program stack. Using a set of options passed to the
       constructor, this environment may be restricted to a subset of what the primary interpreter can do and provide a safer environment for exe-
       cuting user supplied code.

       Note

	      Sandbox  support	(required for runkit_lint(3), runkit_lint_file(3), and the Runkit_Sandbox class) is only available as of PHP 5.1.0
	      or specially patched versions of PHP 5.0, and requires that thread safety be enabled. See the README file  included  in  the  runkit
	      package for more information.

SYNOPSIS

       void Runkit_Sandbox::__construct ([array  $options])

DESCRIPTION

CONSTRUCTOR

       $options is an associative array containing any combination of the special ini options listed below.

	      o $safe_mode
		-  If  the  outer script which is instantiating the Runkit_Sandbox class is configured with safe_mode = off, then safe_mode may be
		turned on for the sandbox environment. This setting can not be used to disable safe_mode when it's already enabled  in	the  outer
		script.

	      o $safe_mode_gid
		-  If  the  outer script which is instantiating the Runkit_Sandbox class is configured with safe_mode_gid = on, then safe_mode_gid
		may be turned off for the sandbox environment. This setting can not be used to enable safe_mode_gid when it's already disabled	in
		the outer script.

	      o $safe_mode_include_dir
		-  If  the  outer  script  which  is instantiating the Runkit_Sandbox class is configured with a safe_mode_include_dir, then a new
		safe_mode_include_dir may be set for sandbox environments below the currently defined value.  safe_mode_include_dir  may  also	be
		cleared to indicate that the bypass feature is disabled. If safe_mode_include_dir was blank in the outer script, but safe_mode was
		not enabled, then any arbitrary safe_mode_include_dir may be set while turning safe_mode on.

	      o $open_basedir
		-$open_basedir may be set to any path below the current setting of open_basedir. If open_basedir is  not  set  within  the  global
		scope, then it is assumed to be the root directory and may be set to any location.

	      o $allow_url_fopen
		-  Like  $safe_mode, this setting can only be made more restrictive, in this case by setting it to FALSE when it is previously set
		to TRUE

	      o $disable_functions
		- Comma separated list of functions to disable within the sandbox sub-interpreter. This list need not contain  the  names  of  the
		currently disabled functions, they will remain disabled whether listed here or not.

	      o $disable_classes
		-  Comma separated list of classes to disable within the sandbox sub-interpreter. This list need not contain the names of the cur-
		rently disabled classes, they will remain disabled whether listed here or not.

	      o $runkit.superglobal
		- Comma separated list of variables to be treated as superglobals within the sandbox sub-interpreter. These variables will be used
		in addition to any variables defined internally or through the global runkit.superglobal setting.

	      o $runkit.internal_override
		- Ini option runkit.internal_override may be disabled (but not re-enabled) within sandboxes.

       Example #1

	      Instantiating a restricted sandbox

	      <?php
	      $options = array(
		'safe_mode'=>true,
		'open_basedir'=>'/var/www/users/jdoe/',
		'allow_url_fopen'=>'false',
		'disable_functions'=>'exec,shell_exec,passthru,system',
		'disable_classes'=>'myAppClass');
	      $sandbox = new Runkit_Sandbox($options);
	      /* Non-protected ini settings may set normally */
	      $sandbox->ini_set('html_errors',true);
	      ?>

ACCESSING VARIABLES

	All  variables	in the global scope of the sandbox environment are accessible as properties of the sandbox object. The first thing to note
       is that because of the way memory between these two threads is managed, object and  resource  variables	can  not  currently  be  exchanged
       between	interpreters.  Additionally,  all  arrays are deep copied and any references will be lost. This also means that references between
       interpreters are not possible.

       Example #2

	      Working with variables in a sandbox

	      <?php
	      $sandbox = new Runkit_Sandbox();

	      $sandbox->foo = 'bar';
	      $sandbox->eval('echo "$foo
"; $bar = $foo . "baz";');
	      echo "{$sandbox->bar}
";
	      if (isset($sandbox->foo)) unset($sandbox->foo);
	      $sandbox->eval('var_dump(isset($foo));');
	      ?>

       The above example will output:

       bar
       barbaz
       bool(false)

CALLING PHP FUNCTIONS

	Any function defined within the sandbox may be called as a method on the sandbox object. This also includes a few pseudo-function language
       constructs: eval(3), include(3), include_once(3), require(3), require_once(3), echo(3), print(3), die(3), and exit(3).

       Example #3

	      Calling sandbox functions

	      <?php
	      $sandbox = new Runkit_Sandbox();

	      echo $sandbox->str_replace('a','f','abc');
	      ?>

       The above example will output:

       fbc

	When  passing  arguments to a sandbox function, the arguments are taken from the outer instance of PHP. If you wish to pass arguments from
       the sandbox's scope, be sure to access them as properties of the sandbox object as illustrated above.

       Example #4

	      Passing arguments to sandbox functions

	      <?php
	      $sandbox = new Runkit_Sandbox();

	      $foo = 'bar';
	      $sandbox->foo = 'baz';
	      echo $sandbox->str_replace('a',$foo,'a');
	      echo $sandbox->str_replace('a',$sandbox->foo,'a');
	      ?>

       The above example will output:

       bar
       baz

CHANGING SANDBOX SETTINGS

	As of runkit version 0.5, certain Sandbox settings may be modified on the fly using ArrayAccess syntax. Some settings, such as $active are
       read-only  and  meant  to  provide status information. Other settings, such as $output_handler may be set and read much like a normal array
       offset. Future settings may be write-only, however no such settings currently exist.

       Sandbox Settings / Status Indicators

PHP Documentation Group 													 RUNKIT_SANDBOX(3)