cvs: phpdoc /en/reference/runkit reference.xml sandbox.xml

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 -->