php-doc-en/reference/pdo/functions/PDO-quote.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-quote">
 <refnamediv>
  <refname>PDO::quote</refname>
  <refpurpose>
   Quotes a string for use in a query.
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>PDO::quote</methodname>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>parameter_type</parameter></methodparam>
  </methodsynopsis>

  <para>
   <function>PDO::quote</function> places quotes around the input string (if
   required) and escapes special characters within the input string, using a
   quoting style appropriate to the underlying driver.
  </para>
  <para>
   If you are using this function to build SQL statements, you are
   <emphasis>strongly</emphasis> recommended to use
   <function>PDO::prepare</function> to prepare SQL statements with bound
   parameters instead of using <function>PDO::quote</function> to interpolate
   user input into a SQL statement.  Prepared statements with bound parameters
   are not only more portable, more convenient, immune to SQL injection, but
   are often much faster to execute than interpolated queries, as both the
   server and client side can cache a compiled form of the query.
  </para>
  <para>
   Not all PDO drivers implement this method (notably PDO_ODBC).  Consider
   using prepared statements instead.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
      <listitem>
       <para>
        The string to be quoted.
       </para>
      </listitem>
     </varlistentry>
    <varlistentry>
     <term><parameter>parameter_type</parameter></term>
      <listitem>
       <para>
        Provides a data type hint for drivers that have alternate quoting styles.
        The default value is PDO::PARAM_STR.
       </para>
      </listitem>
     </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a quoted string that is theoretically safe to pass into an
   SQL statement.  Returns &false; if the driver does not support quoting in
   this way.
  </para>
 </refsect1>

 <!-- Use when EXCEPTIONS exist
 <refsect1 role="exceptions">
  &reftitle.exceptions;
  <para>
   When does this function throw exceptions?
  </para>
 </refsect1>
 -->

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Quoting a normal string</title>
    <programlisting role="php">
<![CDATA[
<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');

/* Simple string */
$string = 'Nice';
print "Unquoted string: $string\n";
print "Quoted string: " . $conn->quote($string) . "\n";
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Unquoted string: Nice
Quoted string: 'Nice'
]]>
    </screen>
   </example>
   <example>
    <title>Quoting a dangerous string</title>
    <programlisting role="php">
<![CDATA[
<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');

/* Dangerous string */
$string = 'Naughty \' string';
print "Unquoted string: $string\n";
print "Quoted string:" . $conn->quote($string) . "\n";
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Unquoted string: Naughty ' string
Quoted string: 'Naughty '' string'
]]>
    </screen>
   </example>
   <example>
    <title>Quoting a complex string</title>
    <programlisting role="php">
<![CDATA[
<?php
$conn = new PDO('sqlite:/home/lynn/music.sql3');

/* Complex string */
$string = "Co'mpl''ex \"st'\"ring";
print "Unquoted string: $string\n";
print "Quoted string: " . $conn->quote($string) . "\n";
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Unquoted string: Co'mpl''ex "st'"ring
Quoted string: 'Co''mpl''''ex "st''"ring'
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>PDO::prepare</function></member>
    <member><function>PDOStatement::execute</function></member>
   </simplelist>
  </para>
 </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
-->