pollita Thu Sep 29 20:47:19 2005 EDT
Added files:
/phpdoc/en/reference/runkit sandbox-parent.xml
Modified files:
/phpdoc/en/reference/runkit reference.xml sandbox.xml
Log:
Document Runkit_Sandbox_Parent
http://cvs.php.net/diff.php/phpdoc/en/reference/runkit/reference.xml?r1=1.8&r2=1.9&ty=u
Index: phpdoc/en/reference/runkit/reference.xml
diff -u phpdoc/en/reference/runkit/reference.xml:1.8
phpdoc/en/reference/runkit/reference.xml:1.9
--- phpdoc/en/reference/runkit/reference.xml:1.8 Tue Sep 27 04:52:35 2005
+++ phpdoc/en/reference/runkit/reference.xml Thu Sep 29 20:47:18 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
<!-- Purpose: basic.php -->
<!-- Membership: pecl -->
@@ -59,6 +59,7 @@
</partintro>
&reference.runkit.sandbox;
+ &reference.runkit.sandbox-parent;
&reference.runkit.functions;
</reference>
http://cvs.php.net/diff.php/phpdoc/en/reference/runkit/sandbox.xml?r1=1.14&r2=1.15&ty=u
Index: phpdoc/en/reference/runkit/sandbox.xml
diff -u phpdoc/en/reference/runkit/sandbox.xml:1.14
phpdoc/en/reference/runkit/sandbox.xml:1.15
--- phpdoc/en/reference/runkit/sandbox.xml:1.14 Tue Sep 27 04:52:26 2005
+++ phpdoc/en/reference/runkit/sandbox.xml Thu Sep 29 20:47:18 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.14 $ -->
+<!-- $Revision: 1.15 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc.
-->
<refentry id="runkit.sandbox">
<refnamediv>
@@ -277,28 +277,30 @@
<para>
<table>
<title>Sandbox Settings / Status Indicators</title>
- <tgroup cols="3">
+ <tgroup cols="4">
<thead>
<row>
<entry>Setting</entry>
- <entry>Visibility</entry>
+ <entry>Type</entry>
<entry>Purpose</entry>
+ <entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>active</literal></entry>
- <entry><constant>Read Only</constant></entry>
+ <entry><type>Boolean</type> (Read Only)</entry>
<entry>
&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.
</entry>
+ <entry>&true; (Initial)</entry>
</row>
<row>
<entry><literal>output_handler</literal></entry>
- <entry><constant>Read/Write</constant></entry>
+ <entry><type>Callback</type></entry>
<entry>
When set to a valid callback, all output generated
by the Sandbox instance will be processed through
@@ -306,6 +308,90 @@
Sandbox output handlers follow the same calling
conventions as the system-wide output handler.
</entry>
+ <entry>None</entry>
+ </row>
+ <row>
+ <entry><literal>parent_access</literal></entry>
+ <entry><type>Boolean</type></entry>
+ <entry>
+ May the sandbox use instances of the
+ <classname>Runkit_Sandbox_Parent</classname> class?
+ Must be enabled for other
+ <classname>Runkit_Sandbox_Parent</classname>
+ related settings to work.
+ </entry>
+ <entry>&false;</entry>
+ </row>
+ <row>
+ <entry><literal>parent_read</literal></entry>
+ <entry><type>Boolean</type></entry>
+ <entry>
+ May the sandbox read variables in its parent's context?
+ </entry>
+ <entry>&false;</entry>
+ </row>
+ <row>
+ <entry><literal>parent_write</literal></entry>
+ <entry><type>Boolean</type></entry>
+ <entry>
+ May the sandbox modify variables in its parent's context?
+ </entry>
+ <entry>&false;</entry>
+ </row>
+ <row>
+ <entry><literal>parent_eval</literal></entry>
+ <entry><type>Boolean</type></entry>
+ <entry>
+ May the sandbox evaluate arbitrary code in its
+ parent's context? <emphasis>DANGEROUS</emphasis>
+ </entry>
+ <entry>&false;</entry>
+ </row>
+ <row>
+ <entry><literal>parent_include</literal></entry>
+ <entry><type>Boolean</type></entry>
+ <entry>
+ May the sandbox include php code files in its
+ parent's context? <emphasis>DANGEROUS</emphasis>
+ </entry>
+ <entry>&false;</entry>
+ </row>
+ <row>
+ <entry><literal>parent_echo</literal></entry>
+ <entry><type>Boolean</type></entry>
+ <entry>
+ May the sandbox echo data in its parent's context
+ effectively bypassing its own output_handler?
+ </entry>
+ <entry>&false;</entry>
+ </row>
+ <row>
+ <entry><literal>parent_call</literal></entry>
+ <entry><type>Boolean</type></entry>
+ <entry>
+ May the sandbox call functions in its
+ parent's context?
+ </entry>
+ <entry>&false;</entry>
+ </row>
+ <row>
+ <entry><literal>parent_die</literal></entry>
+ <entry><type>Boolean</type></entry>
+ <entry>
+ May the sandbox kill its own parent? (And thus itself)
+ </entry>
+ <entry>&false;</entry>
+ </row>
+ <row>
+ <entry><literal>parent_scope</literal></entry>
+ <entry><type>Integer</type></entry>
+ <entry>
+ 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...
+ </entry>
+ <entry><literal>0</literal> (Global)</entry>
</row>
</tbody>
</tgroup>
http://cvs.php.net/co.php/phpdoc/en/reference/runkit/sandbox-parent.xml?r=1.1&p=1
Index: phpdoc/en/reference/runkit/sandbox-parent.xml
+++ phpdoc/en/reference/runkit/sandbox-parent.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="runkit.sandbox-parent">
<refnamediv>
<refname>Runkit_Sandbox_Parent</refname>
<refpurpose>
Runkit Anti-Sandbox Class
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>Runkit_Sandbox_Parent::__construct</methodname>
<void/>
</methodsynopsis>
<para>
Instantiating the <classname>Runkit_Sandbox_Parent</classname>
class from within a sandbox environment created from the
<classname>Runkit_Sandbox</classname> class provides some
(controlled) means for a sandbox child to access its parent.
</para>
¬e.runkit.sandbox;
<para>
In order for any of the <classname>Runkit_Sandbox_Parent</classname>
features to function. Support must be enabled on a per-sandbox basis
by enabling the <literal>parent_access</literal> flag from the parent's
context.
</para>
<example>
<title>Working with variables in a sandbox</title>
<programlisting role="php">
<![CDATA[
<?php
$sandbox = new Runkit_Sandbox();
$sandbox['parent_access'] = true;
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="variables">
<title>Accessing the Parent's Variables</title>
<para>
Just as with sandbox variable access, a sandbox parent's
variables may be read from and written to as properties of
the <classname>Runkit_Sandbox_Parent</classname> class.
Read access to parental variables may be enabled with
the <literal>parent_read</literal> setting (in addition
to the base <literal>parent_access</literal> setting.
Write access, in turn, is enabled through the
<literal>parent_write</literal> setting.
</para>
<para>
Unlike sandbox child variable access, the variable scope
is not limited to globals only. By setting the
<literal>parent_scope</literal> 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.
</para>
<example>
<title>Accessing parental variables</title>
<programlisting role="php">
<![CDATA[
<?php
$php = new Runkit_Sandbox();
$php['parent_access'] = true;
$php['parent_read'] = true;
$test = "Global";
$php->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);');
}
?>
]]>
</programlisting>
</example>
&example.outputs;
<screen>
<![CDATA[
string(6) "Global"
string(7) "three()"
string(5) "two()"
string(5) "one()"
string(6) "Global"
string(6) "Global"
]]>
</screen>
</refsect1>
<refsect1 role="functions">
<title>Calling the Parent's Functions</title>
<para>
Just as with sandbox access, a sandbox may access its parents
functions providing that the proper settings have been enabled.
Enabling <literal>parent_call</literal> will allow the sandbox
to call all functions available to the parent scope. Language
constructs are each controlled by their own setting:
<function>print</function> and <function>echo</function> are
enabled with <literal>parent_echo</literal>.
<function>die</function> and <function>exit</function> are
enabled with <literal>parent_die</literal>.
<function>eval</function> is enabled with <literal>parent_eval</literal>
while <function>include</function>, <function>include_once</function>,
<function>require</function>, and <function>require_once</function>
are enabled through <literal>parent_include</literal>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
