sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document the Runkit_Sandbox class

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@185668 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Sara Golemon 2005-05-02 20:48:28 +00:00
parent f3e1ba99bb
commit fca16aa677
2 changed files with 230 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
reference/runkit/reference.xml
View file

@ -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 @@ show_values();
</section>
</partintro>
&reference.runkit.sandbox;
&reference.runkit.functions;
</reference>

226
reference/runkit/sandbox.xml Normal file
View file

@ -0,0 +1,226 @@
<?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
-->