<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Runkit_Sandbox</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REL="HOME" TITLE="Manual do PHP" HREF="index.html"><LINK REL="UP" TITLE="runkit Functions" HREF="ref.runkit.html"><LINK REL="PREVIOUS" TITLE="runkit Functions" HREF="ref.runkit.html"><LINK REL="NEXT" TITLE="Runkit_Sandbox_Parent" HREF="runkit.sandbox-parent.html"><META HTTP-EQUIV="Content-type" CONTENT="text/html; charset=UTF-8"></HEAD ><BODY CLASS="refentry" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >Manual do PHP</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="ref.runkit.html" ACCESSKEY="P" >Anterior</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="runkit.sandbox-parent.html" ACCESSKEY="N" >Próxima</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="runkit.sandbox" ></A >Runkit_Sandbox</H1 ><DIV CLASS="refnamediv" ><A NAME="AEN193838" ></A ><P > (no version information, might be only in CVS)</P >Runkit_Sandbox -- Runkit Sandbox Class -- PHP Virtual Machine </DIV ><DIV CLASS="refsect1" ><A NAME="AEN193841" ></A ><H2 >Descrição</H2 ><P > Instantiating the <B CLASS="classname" >Runkit_Sandbox</B > 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. </P ><DIV CLASS="note" ><BLOCKQUOTE CLASS="note" ><P ><B >Nota: </B >Suporte para Sandbox (necessário para <A HREF="function.runkit-lint.html" ><B CLASS="function" >runkit_lint()</B ></A >, <A HREF="function.runkit-lint-file.html" ><B CLASS="function" >runkit_lint_file()</B ></A >, e a classe Runkit_Sandbox) esta disponível apenas com o PHP 5.1 com versões do PHP 5.0 com patch especial e precisam que seja uma versão segura para thread. Veja o arquivo README incluído no pacote runkit para maiores informações. </P ></BLOCKQUOTE ></DIV ></DIV ><DIV CLASS="refsect1" ><A NAME="AEN193849" ></A ><H2 >Constructor</H2 >void <B CLASS="methodname" >Runkit_Sandbox::__construct</B > ( [array options] )<BR ></BR ><P > <CODE CLASS="parameter" >options</CODE > is an associative array containing any combination of the special ini options listed below. </P ><P > <P ></P ><DIV CLASS="variablelist" ><DL ><DT ><CODE CLASS="parameter" >safe_mode</CODE ></DT ><DD ><P > If the outer script which is instantiating the <B CLASS="classname" >Runkit_Sandbox</B > class is configured with <TT CLASS="literal" >safe_mode = off</TT >, then safe_mode may be turned on for the sandbox environment. This setting can not be used to disable <TT CLASS="literal" >safe_mode</TT > when it's already enabled in the outer script. </P ></DD ><DT ><CODE CLASS="parameter" >safe_mode_gid</CODE ></DT ><DD ><P > If the outer script which is instantiating the <B CLASS="classname" >Runkit_Sandbox</B > class is configured with <TT CLASS="literal" >safe_mode_gid = on</TT >, then safe_mode_gid may be turned off for the sandbox environment. This setting can not be used to enable <TT CLASS="literal" >safe_mode_gid</TT > when it's already disabled in the outer script. </P ></DD ><DT ><CODE CLASS="parameter" >safe_mode_include_dir</CODE ></DT ><DD ><P > If the outer script which is instantiating the <B CLASS="classname" >Runkit_Sandbox</B > class is configured with a <TT CLASS="literal" >safe_mode_include_dir</TT >, then a new safe_mode_include_dir may be set for sandbox environments below the currently defined value. safe_mode_include_dir may also be cleared to indicate that the bypass feature is disabled. If safe_mode_include_dir was blank in the outer script, but safe_mode was not enabled, then any arbitrary safe_mode_include_dir may be set while turning safe_mode on. </P ></DD ><DT ><CODE CLASS="parameter" >open_basedir</CODE ></DT ><DD ><P > <CODE CLASS="parameter" >open_basedir</CODE > may be set to any path below the current setting of <TT CLASS="literal" >open_basedir</TT >. If <TT CLASS="literal" >open_basedir</TT > is not set within the global scope, then it is assumed to be the root directory and may be set to any location. </P ></DD ><DT ><CODE CLASS="parameter" >allow_url_fopen</CODE ></DT ><DD ><P > Like <CODE CLASS="parameter" >safe_mode</CODE >, this setting can only be made more restrictive, in this case by setting it to <TT CLASS="constant" ><B >FALSE</B ></TT > when it is previously set to <TT CLASS="constant" ><B >TRUE</B ></TT > </P ></DD ><DT ><CODE CLASS="parameter" >disable_functions</CODE ></DT ><DD ><P > Comma 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. </P ></DD ><DT ><CODE CLASS="parameter" >disable_classes</CODE ></DT ><DD ><P > Comma 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. </P ></DD ><DT ><CODE CLASS="parameter" >runkit.superglobal</CODE ></DT ><DD ><P > Comma separated list of variables to be treated as superglobals within the sandbox sub-interpreter. These variables will be used in addition to any variables defined internally or through the global runkit.superglobal setting. </P ></DD ><DT ><CODE CLASS="parameter" >runkit.internal_override</CODE ></DT ><DD ><P > Ini option <TT CLASS="literal" >runkit.internal_override</TT > may be disabled (but not re-enabled) within sandboxes. </P ></DD ></DL ></DIV > </P ><TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN193921" ></A ><P ><B >Exemplo 1. Instantiating a restricted sandbox</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> <font color="#0000BB"><?php<br />$options </font><font color="#007700">= array(<br /> </font><font color="#DD0000">'safe_mode'</font><font color="#007700">=></font><font color="#0000BB">true</font><font color="#007700">,<br /> </font><font color="#DD0000">'open_basedir'</font><font color="#007700">=></font><font color="#DD0000">'/var/www/users/jdoe/'</font><font color="#007700">,<br /> </font><font color="#DD0000">'allow_url_fopen'</font><font color="#007700">=></font><font color="#DD0000">'false'</font><font color="#007700">,<br /> </font><font color="#DD0000">'disable_functions'</font><font color="#007700">=></font><font color="#DD0000">'exec,shell_exec,passthru,system'</font><font color="#007700">,<br /> </font><font color="#DD0000">'disable_classes'</font><font color="#007700">=></font><font color="#DD0000">'myAppClass'</font><font color="#007700">);<br /></font><font color="#0000BB">$sandbox </font><font color="#007700">= new </font><font color="#0000BB">Runkit_Sandbox</font><font color="#007700">(</font><font color="#0000BB">$options</font><font color="#007700">);<br /></font><font color="#FF8000">/* Non-protected ini settings may set normally */<br /></font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">ini_set</font><font color="#007700">(</font><font color="#DD0000">'html_errors'</font><font color="#007700">,</font><font color="#0000BB">true</font><font color="#007700">);<br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ></DIV ><DIV CLASS="refsect1" ><A NAME="AEN193924" ></A ><H2 >Accessing Variables</H2 ><P > 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. </P ><TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN193927" ></A ><P ><B >Exemplo 2. Working with variables in a sandbox</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> <font color="#0000BB"><?php<br />$sandbox </font><font color="#007700">= new </font><font color="#0000BB">Runkit_Sandbox</font><font color="#007700">();<br /><br /></font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">foo </font><font color="#007700">= </font><font color="#DD0000">'bar'</font><font color="#007700">;<br /></font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">eval</font><font color="#007700">(</font><font color="#DD0000">'echo "$foo\n"; $bar = $foo . "baz";'</font><font color="#007700">);<br />echo </font><font color="#DD0000">"</font><font color="#007700">{</font><font color="#DD0000">$sandbox</font><font color="#007700">-></font><font color="#DD0000">bar</font><font color="#007700">}\n</font><font color="#DD0000">"</font><font color="#007700">;<br />if (isset(</font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">foo</font><font color="#007700">)) unset(</font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">foo</font><font color="#007700">);<br /></font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">eval</font><font color="#007700">(</font><font color="#DD0000">'var_dump(isset($foo));'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ><P >O exemplo acima irá imprimir:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="screen" >bar barbaz bool(false)</PRE ></TD ></TR ></TABLE ></DIV ><DIV CLASS="refsect1" ><A NAME="AEN193932" ></A ><H2 >Calling PHP Functions</H2 ><P > Any function defined within the sandbox may be called as a method on the sandbox object. This also includes a few pseudo-function language constructs: <A HREF="function.eval.html" ><B CLASS="function" >eval()</B ></A >, <A HREF="function.include.html" ><B CLASS="function" >include()</B ></A >, <A HREF="function.include-once.html" ><B CLASS="function" >include_once()</B ></A >, <A HREF="function.require.html" ><B CLASS="function" >require()</B ></A >, <A HREF="function.require-once.html" ><B CLASS="function" >require_once()</B ></A >, <A HREF="function.echo.html" ><B CLASS="function" >echo()</B ></A >, <A HREF="function.print.html" ><B CLASS="function" >print()</B ></A >, <A HREF="function.die.html" ><B CLASS="function" >die()</B ></A >, and <A HREF="function.exit.html" ><B CLASS="function" >exit()</B ></A >. </P ><TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN193944" ></A ><P ><B >Exemplo 3. Calling sandbox functions</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> <font color="#0000BB"><?php<br />$sandbox </font><font color="#007700">= new </font><font color="#0000BB">Runkit_Sandbox</font><font color="#007700">();<br /><br />echo </font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">str_replace</font><font color="#007700">(</font><font color="#DD0000">'a'</font><font color="#007700">,</font><font color="#DD0000">'f'</font><font color="#007700">,</font><font color="#DD0000">'abc'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ><P >O exemplo acima irá imprimir:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="screen" >fbc</PRE ></TD ></TR ></TABLE ><P > 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. </P ><TABLE WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" CLASS="EXAMPLE" ><TR ><TD ><DIV CLASS="example" ><A NAME="AEN193950" ></A ><P ><B >Exemplo 4. Passing arguments to sandbox functions</B ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><code><font color="#000000"> <font color="#0000BB"><?php<br />$sandbox </font><font color="#007700">= new </font><font color="#0000BB">Runkit_Sandbox</font><font color="#007700">();<br /><br /></font><font color="#0000BB">$foo </font><font color="#007700">= </font><font color="#DD0000">'bar'</font><font color="#007700">;<br /></font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">foo </font><font color="#007700">= </font><font color="#DD0000">'baz'</font><font color="#007700">;<br />echo </font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">str_replace</font><font color="#007700">(</font><font color="#DD0000">'a'</font><font color="#007700">,</font><font color="#0000BB">$foo</font><font color="#007700">,</font><font color="#DD0000">'a'</font><font color="#007700">);<br />echo </font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">str_replace</font><font color="#007700">(</font><font color="#DD0000">'a'</font><font color="#007700">,</font><font color="#0000BB">$sandbox</font><font color="#007700">-></font><font color="#0000BB">foo</font><font color="#007700">,</font><font color="#DD0000">'a'</font><font color="#007700">);<br /></font><font color="#0000BB">?></font> </font> </code></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ><P >O exemplo acima irá imprimir:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" CELLPADDING="5" ><TR ><TD ><PRE CLASS="screen" >bar baz</PRE ></TD ></TR ></TABLE ></DIV ><DIV CLASS="refsect1" ><A NAME="AEN193955" ></A ><H2 >Changing Sandbox Settings</H2 ><P > As of runkit version 0.5, certain Sandbox settings may be modified on the fly using ArrayAccess syntax. Some settings, such as <CODE CLASS="parameter" >active</CODE > are read-only and meant to provide status information. Other settings, such as <CODE CLASS="parameter" >output_handler</CODE > may be set and read much like a normal array offset. Future settings may be write-only, however no such settings currently exist. </P ><P > <DIV CLASS="table" ><A NAME="AEN193961" ></A ><P ><B >Tabela 1. Sandbox Settings / Status Indicators</B ></P ><TABLE BORDER="1" CLASS="CALSTABLE" ><COL><COL><COL><COL><THEAD ><TR ><TH >Setting</TH ><TH >Type</TH ><TH >Purpose</TH ><TH >Default</TH ></TR ></THEAD ><TBODY ><TR ><TD ><TT CLASS="literal" >active</TT ></TD ><TD >Boolean (Read Only)</TD ><TD > <TT CLASS="constant" ><B >TRUE</B ></TT > if the Sandbox is still in a usable state, <TT CLASS="constant" ><B >FALSE</B ></TT > if the request is in bailout due to a call to die(), exit(), or because of a fatal error condition. </TD ><TD ><TT CLASS="constant" ><B >TRUE</B ></TT > (Initial)</TD ></TR ><TR ><TD ><TT CLASS="literal" >output_handler</TT ></TD ><TD >Callback</TD ><TD > When set to a valid callback, all output generated by the Sandbox instance will be processed through the named function. Sandbox output handlers follow the same calling conventions as the system-wide output handler. </TD ><TD >None</TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_access</TT ></TD ><TD >Boolean</TD ><TD > May the sandbox use instances of the <B CLASS="classname" >Runkit_Sandbox_Parent</B > class? Must be enabled for other <B CLASS="classname" >Runkit_Sandbox_Parent</B > related settings to work. </TD ><TD ><TT CLASS="constant" ><B >FALSE</B ></TT ></TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_read</TT ></TD ><TD >Boolean</TD ><TD > May the sandbox read variables in its parent's context? </TD ><TD ><TT CLASS="constant" ><B >FALSE</B ></TT ></TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_write</TT ></TD ><TD >Boolean</TD ><TD > May the sandbox modify variables in its parent's context? </TD ><TD ><TT CLASS="constant" ><B >FALSE</B ></TT ></TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_eval</TT ></TD ><TD >Boolean</TD ><TD > May the sandbox evaluate arbitrary code in its parent's context? <SPAN CLASS="emphasis" ><I CLASS="emphasis" >DANGEROUS</I ></SPAN > </TD ><TD ><TT CLASS="constant" ><B >FALSE</B ></TT ></TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_include</TT ></TD ><TD >Boolean</TD ><TD > May the sandbox include php code files in its parent's context? <SPAN CLASS="emphasis" ><I CLASS="emphasis" >DANGEROUS</I ></SPAN > </TD ><TD ><TT CLASS="constant" ><B >FALSE</B ></TT ></TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_echo</TT ></TD ><TD >Boolean</TD ><TD > May the sandbox echo data in its parent's context effectively bypassing its own output_handler? </TD ><TD ><TT CLASS="constant" ><B >FALSE</B ></TT ></TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_call</TT ></TD ><TD >Boolean</TD ><TD > May the sandbox call functions in its parent's context? </TD ><TD ><TT CLASS="constant" ><B >FALSE</B ></TT ></TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_die</TT ></TD ><TD >Boolean</TD ><TD > May the sandbox kill its own parent? (And thus itself) </TD ><TD ><TT CLASS="constant" ><B >FALSE</B ></TT ></TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_scope</TT ></TD ><TD >Integer</TD ><TD > 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... </TD ><TD ><TT CLASS="literal" >0</TT > (Global)</TD ></TR ><TR ><TD ><TT CLASS="literal" >parent_scope</TT ></TD ><TD >String</TD ><TD > When <TT CLASS="literal" >parent_scope</TT > is set to a string value, it refers to a named array variable in the global scope. If the named variable does not exist at the time of access it will be created as an empty array. If the variable exists but it not an array, a dummy array will be created containing a reference to the named global variable. </TD ><TD > </TD ></TR ></TBODY ></TABLE ></DIV > </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="ref.runkit.html" ACCESSKEY="P" >Anterior</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Principal</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="runkit.sandbox-parent.html" ACCESSKEY="N" >Próxima</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >runkit Functions</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="ref.runkit.html" ACCESSKEY="U" >Acima</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Runkit_Sandbox_Parent</TD ></TR ></TABLE ></DIV ></BODY ></HTML >