From 0d66a6cf2c0cad946dd8b766ac6ea09b96989114 Mon Sep 17 00:00:00 2001
From: Nikita Popov <nikic@php.net>
Date: Sat, 24 Dec 2011 23:05:58 +0000
Subject: [PATCH] Slightly cleanup eval() docs and add a Caution at the top
 encouraging to avoid eval().

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321375 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/misc/functions/eval.xml | 52 ++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 19 deletions(-)

diff --git a/reference/misc/functions/eval.xml b/reference/misc/functions/eval.xml
index 6194230f4a..b66c60478e 100644
--- a/reference/misc/functions/eval.xml
+++ b/reference/misc/functions/eval.xml
@@ -10,23 +10,20 @@
   &reftitle.description;
   <methodsynopsis>
    <type>mixed</type><methodname>eval</methodname>
-   <methodparam><type>string</type><parameter>code_str</parameter></methodparam>
+   <methodparam><type>string</type><parameter>code</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Evaluates the string given in <parameter>code_str</parameter> as PHP code.
-  </para>
-  <para>
-   There are some factors to keep in mind when using
-   <function>eval</function>. Remember that the string passed must be valid
-   PHP code, including things like terminating statements with a semicolon so
-   the parser doesn't die on the line after the <function>eval</function>,
-   and properly escaping things in <parameter>code_str</parameter>. To mix
-   HTML output and PHP code you can use a closing PHP tag to leave PHP mode.
-  </para>
-  <para>
-   Also remember that variables given values under <function>eval</function>
-   will retain these values in the main script afterwards.
+   Evaluates the given <parameter>code</parameter> as PHP.
   </para>
+  <caution>
+   <para>
+    The <function>eval</function> language construct is <emphasis>very dangerous</emphasis>
+    because it allows execution of arbitrary PHP code. <emphasis>Its use thus is
+    discouraged.</emphasis> If you have carefully verified that there is no other option
+    than to use this construct, pay special attention <emphasis>not to pass any user
+    provided data</emphasis> into it without properly validating it beforehand.
+   </para>
+  </caution>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -34,16 +31,33 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>code_str</parameter></term>
+     <term><parameter>code</parameter></term>
      <listitem>
       <para>
-       The code string to be evaluated.
-       <parameter>code_str</parameter> does not have to contain <link
-       linkend="language.basic-syntax.phpmode">PHP Opening tags</link>.
+       Valid PHP code to be evaluated.
+      </para>
+      <para>
+       The code mustn't be wrapped in opening and closing
+       <link linkend="language.basic-syntax.phpmode">PHP tags</link>, i.e.
+       <literal>'echo "Hi!";'</literal> must be passed instead of
+       <literal>'&lt;? echo "Hi!"; &gt;'</literal>. It is still possible to leave and
+       reenter PHP mode though using the appropriate PHP tags, e.g.
+       <literal>'echo "In PHP mode!"; ?&gt;In HTML mode!&lt;? echo "Back in PHP mode!";'</literal>.
+      </para>
+      <para>
+       Apart from that the passed code must be valid PHP. This includes that all statements
+       must be properly terminated using a semicolon.
+       <literal>'echo "Hi!"'</literal> for example will cause a parse error, whereas
+       <literal>'echo "Hi!";'</literal> will work.
       </para>
       <para>
        A <literal>return</literal> statement will immediately terminate the
-       evaluation of the string . 
+       evaluation of the code. 
+      </para>
+      <para>
+       The code will be executed in the scope of the code calling <function>eval</function>. Thus any
+       variables defined or changed in the <function>eval</function> call will remain visible after
+       it terminates.
       </para>
      </listitem>
     </varlistentry>