<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.sqlite-escape-string" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>sqlite_escape_string</refname>
  <refpurpose>Escapes a string for use as a query parameter</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>sqlite_escape_string</methodname>
   <methodparam><type>string</type><parameter>item</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>sqlite_escape_string</function> will correctly quote the string
   specified by <parameter>item</parameter>
   for use in an SQLite SQL statement.  This includes doubling up
   single-quote characters (<literal>'</literal>) and checking for
   binary-unsafe characters in the query string.
  </para>
  <para>
   Although the encoding makes it safe to insert the data, it will render
   simple text comparisons and <literal>LIKE</literal> clauses in your
   queries unusable for the columns that contain the binary data.  In
   practice, this shouldn't be a problem, as your schema should be such that
   you don't use such things on binary columns (in fact, it might be better to
   store binary data using other means, such as in files).
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>item</parameter></term>
     <listitem>
      <para>
       The <type>string</type> being quoted.
      </para>
      <para>
       If the <parameter>item</parameter> contains a <literal>NUL</literal>
       character, or if it begins with a character whose ordinal value is
       <literal>0x01</literal>, PHP will apply a binary encoding scheme so that
       you can safely store and retrieve binary data.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an escaped <type>string</type> for use in an SQLite SQL statement.
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    Do not use this function to encode the return values from UDF's created
    using <function>sqlite_create_function</function> or
    <function>sqlite_create_aggregate</function> - use
    <function>sqlite_udf_encode_binary</function> instead.
   </simpara>
  </note>
  <warning>
   <simpara>
    <function>addslashes</function> should <emphasis>NOT</emphasis> be used to
    quote your strings for SQLite queries; it will lead to strange results
    when retrieving your data.
   </simpara>
  </warning>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>sqlite_udf_encode_binary</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
 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
 -->