diff --git a/reference/runkit/reference.xml b/reference/runkit/reference.xml
index 8b6ea01eb7..3ef971370a 100644
--- a/reference/runkit/reference.xml
+++ b/reference/runkit/reference.xml
@@ -1,5 +1,5 @@
-
+
@@ -59,6 +59,7 @@
&reference.runkit.sandbox;
+ &reference.runkit.sandbox-parent;
&reference.runkit.functions;
diff --git a/reference/runkit/sandbox-parent.xml b/reference/runkit/sandbox-parent.xml
new file mode 100644
index 0000000000..8d9e8f7390
--- /dev/null
+++ b/reference/runkit/sandbox-parent.xml
@@ -0,0 +1,178 @@
+
+
+
+
+
+ Runkit_Sandbox_Parent
+
+ Runkit Anti-Sandbox Class
+
+
+
+ &reftitle.description;
+
+
+ voidRunkit_Sandbox_Parent::__construct
+
+
+
+
+ Instantiating the Runkit_Sandbox_Parent
+ class from within a sandbox environment created from the
+ Runkit_Sandbox class provides some
+ (controlled) means for a sandbox child to access its parent.
+
+
+ ¬e.runkit.sandbox;
+
+
+ In order for any of the Runkit_Sandbox_Parent
+ features to function. Support must be enabled on a per-sandbox basis
+ by enabling the parent_access flag from the parent's
+ context.
+
+
+
+ Working with variables in a sandbox
+
+
+
+
+
+
+
+
+ Accessing the Parent's Variables
+
+ Just as with sandbox variable access, a sandbox parent's
+ variables may be read from and written to as properties of
+ the Runkit_Sandbox_Parent class.
+ Read access to parental variables may be enabled with
+ the parent_read setting (in addition
+ to the base parent_access setting.
+ Write access, in turn, is enabled through the
+ parent_write setting.
+
+
+
+ Unlike sandbox child variable access, the variable scope
+ is not limited to globals only. By setting the
+ parent_scope setting to an appropriate
+ integer value, other scopes in the active call stack may
+ be inspected instead. A value of 0 (Default) will direct
+ variable access at the global scope. 1 will point variable
+ access at whatever variable scope was active at the time the
+ current block of sandbox code was executed. Higher values
+ progress back through the functions that called the functions
+ that led to the sandbox executing code that tried to access
+ its own parent's variables.
+
+
+
+ Accessing parental variables
+
+eval('$PARENT = new Runkit_Sandbox_Parent;');
+
+$php['parent_scope'] = 0;
+one();
+
+$php['parent_scope'] = 1;
+one();
+
+$php['parent_scope'] = 2;
+one();
+
+$php['parent_scope'] = 3;
+one();
+
+$php['parent_scope'] = 4;
+one();
+
+$php['parent_scope'] = 5;
+one();
+
+function one() {
+ $test = "one()";
+ two();
+}
+
+function two() {
+ $test = "two()";
+ three();
+}
+
+function three() {
+ $test = "three()";
+ $GLOBALS['php']->eval('var_dump($PARENT->test);');
+}
+?>
+]]>
+
+
+ &example.outputs;
+
+
+
+
+
+
+ Calling the Parent's Functions
+
+ Just as with sandbox access, a sandbox may access its parents
+ functions providing that the proper settings have been enabled.
+ Enabling parent_call will allow the sandbox
+ to call all functions available to the parent scope. Language
+ constructs are each controlled by their own setting:
+ print and echo are
+ enabled with parent_echo.
+ die and exit are
+ enabled with parent_die.
+ eval is enabled with parent_eval
+ while include, include_once,
+ require, and require_once
+ are enabled through parent_include.
+
+
+
+
+
+
+
diff --git a/reference/runkit/sandbox.xml b/reference/runkit/sandbox.xml
index f1e00b8ab8..9fad4c3269 100644
--- a/reference/runkit/sandbox.xml
+++ b/reference/runkit/sandbox.xml
@@ -1,5 +1,5 @@
-
+
@@ -277,28 +277,30 @@ baz
Sandbox Settings / Status Indicators
-
+
Setting
- Visibility
+ Type
Purpose
+ Default
active
- Read Only
+ Boolean (Read Only)
&true; if the Sandbox is still in a usable state,
&false; if the request is in bailout due to a
call to die(), exit(), or because of a fatal
error condition.
+ &true; (Initial)
output_handler
- Read/Write
+ Callback
When set to a valid callback, all output generated
by the Sandbox instance will be processed through
@@ -306,6 +308,90 @@ baz
Sandbox output handlers follow the same calling
conventions as the system-wide output handler.
+ None
+
+
+ parent_access
+ Boolean
+
+ May the sandbox use instances of the
+ Runkit_Sandbox_Parent class?
+ Must be enabled for other
+ Runkit_Sandbox_Parent
+ related settings to work.
+
+ &false;
+
+
+ parent_read
+ Boolean
+
+ May the sandbox read variables in its parent's context?
+
+ &false;
+
+
+ parent_write
+ Boolean
+
+ May the sandbox modify variables in its parent's context?
+
+ &false;
+
+
+ parent_eval
+ Boolean
+
+ May the sandbox evaluate arbitrary code in its
+ parent's context? DANGEROUS
+
+ &false;
+
+
+ parent_include
+ Boolean
+
+ May the sandbox include php code files in its
+ parent's context? DANGEROUS
+
+ &false;
+
+
+ parent_echo
+ Boolean
+
+ May the sandbox echo data in its parent's context
+ effectively bypassing its own output_handler?
+
+ &false;
+
+
+ parent_call
+ Boolean
+
+ May the sandbox call functions in its
+ parent's context?
+
+ &false;
+
+
+ parent_die
+ Boolean
+
+ May the sandbox kill its own parent? (And thus itself)
+
+ &false;
+
+
+ parent_scope
+ Integer
+
+ What scope will parental property access look at?
+ 0 == Global scope, 1 == Calling scope,
+ 2 == Scope preceeding calling scope,
+ 3 == The scope before that, etc..., etc...
+
+ 0 (Global)