add pg_escape_literal() and pg_escape_identifier()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@319799 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Yasuo Ohgaki 2011-11-25 04:25:08 +00:00
parent 6ee44cfc78
commit d74d18bfd2
3 changed files with 315 additions and 7 deletions

View file

@ -0,0 +1,152 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.61 -->
<refentry xml:id='function.pg-escape-identifier' xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>pg_escape_identifier</refname>
<refpurpose>
Escape a identifier for insertion into a text field
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>pg_escape_identifier</methodname>
<methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
<function>pg_escape_identifier</function> escapes a identifier
(e.g. table, field names) for quering the database. It returns an
escaped identifier string for PostgreSQL
server. <function>pg_escape_identifier</function> adds double
quotes before and after data. Users should not add double
quotes. Use of this function is recommended for identifier
parameters in query. For SQL literals (i.e. parameters except
bytea), <function>pg_escape_literal</function>
or <function>pg_escape_string</function> muse be used. For bytea
type fields, <function>pg_escape_bytea</function> must be used
instead.
</para>
<note>
<para>
This function has internal escape code and can also be used with
PostgreSQL 8.4 or less.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
<listitem>
<para>
PostgreSQL database connection resource. When
<parameter>connection</parameter> is not present, the default connection
is used. The default connection is the last connection made by
<function>pg_connect</function> or <function>pg_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
A <type>string</type> containing text to be escaped.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
A <type>string</type> containing the escaped data.
</para>
</refsect1>
<!--
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.5.0</entry>
<entry>added function</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
-->
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>pg_escape_identifier</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// Connect to the database
$dbconn = pg_connect('dbname=foo');
// Escape the table name data
$escaped = pg_escape_identifier($table_name);
// Select rows from $table_name
pg_query("SELECT * FROM {$escaped};");
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>pg_escape_literal</function></member>
<member><function>pg_escape_bytea</function></member>
<member><function>pg_escape_string</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:"~/.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
-->

View file

@ -0,0 +1,153 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.61 -->
<refentry xml:id='function.pg-escape-literal' xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>pg_escape_literal</refname>
<refpurpose>
Escape a literal for insertion into a text field
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>pg_escape_literal</methodname>
<methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
<function>pg_escape_literal</function> escapes a literal for
querying the PostgreSQL database. It returns an escaped literal in
the PostgreSQL format. <function>pg_escape_literal</function> adds
quotes before and after data. Users should not add quotes. Use of
this function is recommended instead
of <function>pg_escape_string</function>. If the type of the
column is bytea, <function>pg_escape_bytea</function> must be used
instead. For escaping identifiers (e.g. table, field
names), <function>pg_escape_identifier</function> must be used.
</para>
<note>
<para>
This function has internal escape code and can also be used with
PostgreSQL 8.4 or less.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
<listitem>
<para>
PostgreSQL database connection resource. When
<parameter>connection</parameter> is not present, the default connection
is used. The default connection is the last connection made by
<function>pg_connect</function> or <function>pg_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
A <type>string</type> containing text to be escaped.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
A <type>string</type> containing the escaped data.
</para>
</refsect1>
<!--
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.5.0</entry>
<entry>added function</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
-->
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>pg_escape_literal</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// Connect to the database
$dbconn = pg_connect('dbname=foo');
// Read in a text file (containing apostrophes and backslashes)
$data = file_get_contents('letter.txt');
// Escape the text data
$escaped = pg_escape_literal($data);
// Insert it into the database. Note that no quotes around {$escaped}
pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', {$escaped})");
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>pg_escape_identifier</function></member>
<member><function>pg_escape_bytea</function></member>
<member><function>pg_escape_string</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:"~/.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
-->

View file

@ -5,7 +5,7 @@
<refnamediv>
<refname>pg_escape_string</refname>
<refpurpose>
Escape a string for insertion into a text field
Escape a string for query
</refpurpose>
</refnamediv>
@ -17,12 +17,15 @@
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
<function>pg_escape_string</function> escapes a string for
insertion into the database. It returns an escaped string in the
PostgreSQL format. Use of this function is recommended instead of
<function>addslashes</function>. If the type of the column
is bytea, <function>pg_escape_bytea</function> must be used
instead.
<function>pg_escape_string</function> escapes a string for querying
the database. It returns an escaped string in the PostgreSQL
format without quotes. <function>pg_escape_literal</function> is
more preffered way to escape SQL parameters for PostgreSQL.
<function>addslashes</function> must not be used with PostgreSQL.
If the type of the column is
bytea, <function>pg_escape_bytea</function> must be used
instead. <function>pg_escape_identifier</function> must be used to
escape identifiers (e.g. table names, field names)
</para>
<note>
<para>