pollita Mon May 2 16:48:29 2005 EDT
Added files:
/phpdoc/en/reference/runkit sandbox.xml
Modified files:
/phpdoc/en/reference/runkit reference.xml
Log:
Document the Runkit_Sandbox class
http://cvs.php.net/diff.php/phpdoc/en/reference/runkit/reference.xml?r1=1.2&r2=1.3&ty=u
Index: phpdoc/en/reference/runkit/reference.xml
diff -u phpdoc/en/reference/runkit/reference.xml:1.2
phpdoc/en/reference/runkit/reference.xml:1.3
--- phpdoc/en/reference/runkit/reference.xml:1.2 Sun May 1 05:08:13 2005
+++ phpdoc/en/reference/runkit/reference.xml Mon May 2 16:48:28 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc.
-->
<reference id="ref.runkit">
<title>runkit Functions</title>
@@ -83,6 +83,9 @@
</section>
</partintro>
+
+ &reference.runkit.sandbox;
+
&reference.runkit.functions;
</reference>
http://cvs.php.net/co.php/phpdoc/en/reference/runkit/sandbox.xml?r=1.1&p=1
Index: phpdoc/en/reference/runkit/sandbox.xml
+++ phpdoc/en/reference/runkit/sandbox.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">
<refnamediv>
<refname>Runkit_Sandbox</refname>
<refpurpose>
Runkit Sandbox Class -- PHP Virtual Machine
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>
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 executing user supplied code.
</para>
</refsect1>
<refsect1 role="constructor">
<title>Constructor</title>
<methodsynopsis>
<type>void</type><methodname>Runkit_Sandbox::__construct</methodname>
<methodparam
choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
<parameter>option</parameter> is an associative array containing
any combination of the special ini options listed below.
</para>
<para>
<variablelist>
<varlistentry>
<term><parameter>safe_mode</parameter></term>
<listitem>
<para>
If the outer script which is instantiating the Runkit_Sandbox class
is configured with <literal>safe_mode = off</literal>, 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>open_basedir</parameter></term>
<listitem>
<para>
<parameter>open_basedir</parameter> 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>allow_url_fopen</parameter></term>
<listitem>
<para>
Like <parameter>safe_mode</parameter>, this setting can only be made
more restrictive,
in this case by setting it to &false; when it is previously set to &true;
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>disable_functions</parameter></term>
<listitem>
<para>
Coma 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>disable_classes</parameter></term>
<listitem>
<para>
Coma separated list of classes to disable within the sandbox
sub-interpreter.
This list need not contain the names of the currently disabled classes,
they will remain disabled whether listed here or not.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<example>
<title>Instantiating a restricted sandbox</title>
<programlisting role="php">
<![CDATA[
<?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);
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="variables">
<title>Accessing Variables</title>
<para>
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.
</para>
<example>
<title>Working with variables in a sandbox</title>
<programlisting role="php">
<![CDATA[
<?php
$sandbox = new Runkit_Sandbox();
$sandbox->foo = 'bar';
$sandbox->eval('echo "$foo\n"; $bar = $foo . "baz";');
echo "{$sandbox->bar}\n";
if (isset($sandbox->foo)) unset($sandbox->foo);
$sandbox->eval('var_dump(isset($foo));');
]]>
</programlisting>
</example>
<screen>
<![CDATA[
bar
barbaz
bool(false)
]]>
</screen>
</refsect1>
<refsect1 role="variables">
<title>Accessing Variables</title>
<para>
Any function defined within the sandbox may be called as
a method on the sandbox object. This also includes a few
psuedo-function language constructs: <function>eval</function>,
<function>include</function>, <function>include_once</function>,
<function>require</function>, and <function>require_once</function>.
Most notably abset are the language constructs: <function>echo</function>,
<function>print</function>, <function>die</function>, and
<function>exit</function>.
These functions are excluded out of simplicity and to avoid confusion
as they would mostly likely be used incorrectly.
</para>
<example>
<title>Calling sandbox functions</title>
<programlisting role="php">
<![CDATA[
<?php
$sandbox = new Runkit_Sandbox();
$sandbox->str_replace('a','f','abc');
]]>
</programlisting>
</example>
<screen>
<![CDATA[
fbc
]]>
</screen>
<para>
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.
</para>
<example>
<title>Passing arguments to sandbox functions</title>
<programlisting role="php">
<![CDATA[
<?php
$sandbox = new Runkit_Sandbox();
$foo = 'bar';
$sandbox->foo = 'baz';
$sandbox->str_replace('a',$foo,'a');
$sandbox->str_replace('a',$sandbox->foo,'a');
]]>
</programlisting>
</example>
<screen>
<![CDATA[
bar
baz
]]>
</screen>
</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
-->
