php-doc-en/security/magicquotes.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
  <chapter xml:id="security.magicquotes" xmlns="http://docbook.org/ns/docbook">
   <title>Magic Quotes</title>
   &warn.deprecated.feature-5-3-0.removed-6-0-0;
   <para>
    Magic Quotes is a process that automagically escapes incoming data to the 
    PHP script. It's preferred to code with magic quotes off and to instead
    escape the data at runtime, as needed.
   </para>

   <sect1 xml:id="security.magicquotes.what">
    <title>What are Magic Quotes</title>
    <para>
     When on, all <literal>'</literal> (single-quote), <literal>"</literal> 
     (double quote), <literal>\</literal> (backslash) and <literal>NULL</literal> 
     characters are escaped with a backslash automatically.  This is identical
     to what <function>addslashes</function> does.
    </para>
    <para>
     There are three magic quote directives:
    </para>
    <itemizedlist>
     <listitem>
      <simpara>
       <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>
      </simpara>
      <simpara>
       Affects HTTP Request data (GET, POST, and COOKIE). Cannot be set at 
       runtime, and defaults to <emphasis>on</emphasis> in PHP.
      </simpara>
      <simpara>
       See also <function>get_magic_quotes_gpc</function>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <link linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
      </simpara>
      <simpara>
       If enabled, most functions that return data from an external source, 
       including databases and text files, will have quotes escaped with a 
       backslash. Can be set at runtime, and defaults to <emphasis>off</emphasis>
       in PHP.
      </simpara>
      <simpara>
       See also <function>set_magic_quotes_runtime</function> and
       <function>get_magic_quotes_runtime</function>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <link linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link>
      </simpara>
      <simpara>
       If enabled, a single-quote is escaped with a single-quote instead of a 
       backslash.  If on, it completely overrides 
       <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>. Having 
       both directives enabled means only single quotes are escaped as 
       <literal>''</literal>. Double quotes, backslashes and NULL's will 
       remain untouched and unescaped.
      </simpara>
      <simpara>
       See also <function>ini_get</function> for retrieving its value.
      </simpara>
     </listitem>
    </itemizedlist>
   </sect1>

   <sect1 xml:id="security.magicquotes.why">
    <title>Why did we use Magic Quotes</title>
    &warn.deprecated.feature-5-3-0.removed-6-0-0;
    <itemizedlist>
     <listitem>
      <simpara>
       There is no reason to use magic quotes because they are no longer
       a supported part of PHP. However, they did exist and did help a
       few beginners blissfully and unknowingly write better (more secure)
       code. But, when dealing with code that relies upon this behavior
       it's better to update the code instead of turning magic quotes on.
      </simpara>
      <simpara>
       So why did this feature exist? Simple, to help prevent
       <link linkend="security.database.sql-injection">SQL Injection</link>.
       Today developers are better aware of security and end up using
       database specific escaping mechanisms and/or prepared statements
       instead of relying upon features like magical quotes.
      </simpara>
     </listitem>
    </itemizedlist>
   </sect1>

   <sect1 xml:id="security.magicquotes.whynot">
    <title>Why not to use Magic Quotes</title>
    &warn.deprecated.feature-5-3-0.removed-6-0-0;
    <itemizedlist>
     <listitem>
      <simpara>
       Portability
      </simpara>
      <simpara>
       Assuming it to be on, or off, affects portability. Use
       <function>get_magic_quotes_gpc</function> to check for this, and code
       accordingly.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Performance
      </simpara>
      <simpara>
       Because not every piece of escaped data is inserted into a 
       database, there is a performance loss for escaping all this data. 
       Simply calling on the escaping functions (like 
       <function>addslashes</function>) at runtime is more efficient.
      </simpara>
      <simpara>
       Although <filename>php.ini-development</filename> enables these directives  
       by default, <filename>php.ini-production</filename> disables it.
       This recommendation is mainly due to performance reasons.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Inconvenience
      </simpara>
      <simpara>
       Because not all data needs escaping, it's often annoying to see escaped
       data where it shouldn't be. For example, emailing from a form, and
       seeing a bunch of \' within the email. To fix, this may require 
       excessive use of <function>stripslashes</function>.
      </simpara>
     </listitem>
    </itemizedlist>
   </sect1>

   <sect1 xml:id="security.magicquotes.disabling">
    <title>Disabling Magic Quotes</title>
    &warn.deprecated.feature-5-3-0.removed-6-0-0;
    <para>
     The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>
     directive may only be disabled at the system level, and not at
     runtime. In otherwords, use of <function>ini_set</function> is not
     an option.
    </para>
    <para>
     <example>
      <title>Disabling magic quotes server side</title>
      <para>
       An example that sets the value of these directives to 
       <literal>Off</literal> in &php.ini;.  For additional details, read the 
       manual section titled <link linkend="configuration.changes">How to 
       change configuration settings</link>.
      </para>
      <screen>
<![CDATA[
; Magic quotes
;

; Magic quotes for incoming GET/POST/Cookie data.
magic_quotes_gpc = Off

; Magic quotes for runtime-generated data, e.g. data from SQL, from exec(), etc.
magic_quotes_runtime = Off

; Use Sybase-style magic quotes (escape ' with '' instead of \').
magic_quotes_sybase = Off
]]>
      </screen>
      <para>
       If access to the server configuration is unavailable, use of
       <filename>.htaccess</filename> is also an option.  For example:
      </para>
      <screen>
<![CDATA[
php_flag magic_quotes_gpc Off
]]>
      </screen>
     </example>
    </para>
    <para>
     In the interest of writing portable code (code that works in any 
     environment), like if setting at the server level is not possible,
     here's an example to disable <link linkend="ini.magic-quotes-gpc">
     magic_quotes_gpc</link> at runtime. This method is inefficient so 
     it's preferred to instead set the appropriate directives elsewhere.
    </para>
    <para>
     <example>
      <title>Disabling magic quotes at runtime</title>
      <programlisting role="php">
<![CDATA[
<?php
if (get_magic_quotes_gpc()) {
    function stripslashes_deep($value)
    {
        $value = is_array($value) ?
                    array_map('stripslashes_deep', $value) :
                    stripslashes($value);

        return $value;
    }

    $_POST = array_map('stripslashes_deep', $_POST);
    $_GET = array_map('stripslashes_deep', $_GET);
    $_COOKIE = array_map('stripslashes_deep', $_COOKIE);
    $_REQUEST = array_map('stripslashes_deep', $_REQUEST);
}
?>
]]>
      </programlisting>
     </example>
    </para>
   </sect1>

  </chapter>

<!-- 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:"~/.phpdoc/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
-->