From e2ea803dbd17989fd698add2ec7c6088557e4cd3 Mon Sep 17 00:00:00 2001
From: Sara Golemon <pollita@php.net>
Date: Wed, 10 Sep 2003 15:35:59 +0000
Subject: [PATCH] Initial Revision

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@140019 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/url/functions/http-build-query.xml | 153 +++++++++++++++++++
 1 file changed, 153 insertions(+)
 create mode 100644 reference/url/functions/http-build-query.xml

diff --git a/reference/url/functions/http-build-query.xml b/reference/url/functions/http-build-query.xml
new file mode 100644
index 0000000000..d9e51b42db
--- /dev/null
+++ b/reference/url/functions/http-build-query.xml
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.0 -->
+  <refentry id="function.http-build-query">
+   <refnamediv>
+    <refname>http_build_query</refname>
+    <refpurpose>Generate url-encoded query string</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <methodsynopsis>
+     <type>string</type><methodname>http_build_query</methodname>
+     <methodparam><type>array</type><parameter>formdata</parameter></methodparam>
+     <methodparam choice="opt"><type>string</type><parameter>numeric_prefix</parameter></methodparam>
+    </methodsynopsis>
+    
+    <simpara>
+     Generates a url-encoded query string from the associative (or indexed) array provided.
+     <parameter>formdata</parameter> may be an array or object containing properties.
+     A <parameter>formdata</parameter> array may be a simple one-dimensional structure,
+     or an array of arrays (who in turn may contain other arrays).  If numeric indices
+     are used in the base array and a <parameter>numeric_prefix</parameter> is provided,
+     it will be prepended to the numeric index for elements in the base array only.
+     This is to allow for legal variable names when the data is decoded by <literal>PHP</literal>
+     or another CGI application later on.
+    </simpara>
+    
+    <example>
+     <title>Simple usage of <function>http_build_query</function></title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$data = array('foo'=>'bar',
+              'baz'=>'boom',
+              'cow'=>'milk',
+              'php'=>'hypertext processor');
+              
+echo http_build_query($data);
+/* Outputs:
+      foo=bar&baz=boom&cow=milk&php=hypertext+processor
+ */
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <example>
+     <title><function>http_build_query</function> with numerically index elements.</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$data = array('foo', 'bar', 'baz', 'boom', 'cow' => 'milk', 'php' =>'hypertext processor');
+              
+echo http_build_query($data);
+/* Outputs:
+      0=foo&1=bar&2=baz&3=boom&cow=milk&php=hypertext+processor
+ */
+ 
+echo http_build_query($data, 'myvar_');
+/* Outputs:
+      myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_3=boom&cow=milk&php=hypertext+processor
+ */
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <example>
+     <title><function>http_build_query</function> with complex arrays</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$data = array('user'=>array('name'=>'Bob Smith',
+                            'age'=>47,
+                            'sex'=>'M',
+                            'dob'=>'5/12/1956'),
+              'pastimes'=>array('golf', 'opera', 'poker', 'rap'),
+              'children'=>array('bobby'=>array('age'=>12,
+                                               'sex'=>'M'),
+                                'sally'=>array('age'=>8,
+                                               'sex'=>'F')),
+              'CEO');
+                                               
+echo http_build_query($data, 'flags_');
+/* Outputs: (word wrapped for readability)
+      user[name]=Bob+Smith&user[age]=47&user[sex]=M&user[dob]=5%1F12%1F1956&
+      pastimes[0]=golf&pastimes[1]=opera&pastimes[2]=poker&pastimes[3]=rap&
+      children[bobby][age]=12&children[bobby][sex]=M&children[sally][age]=8&
+      children[sally][sex]=F&flags_0=CEO
+
+   Note: Only the numericly indexed element in the base array "CEO"
+         received a prefix.  The other numeric indices, found under
+         pastimes, do not require a string prefix to be legal variable names.
+ */
+?>
+]]>
+     </programlisting>
+    </example>
+    
+    <example>
+     <title>Using <function>http_build_query</function> with an object</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+class myClass {
+  var $foo;
+  var $baz;
+  
+  function myClass() {
+    $this->foo = 'bar';
+    $this->baz = 'boom';
+  }
+}
+
+$data = new myClass();
+
+echo http_build_query($data);
+/* Outputs:
+      foo=bar&baz=boom
+ */
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See also:
+     <function>urlencode</function>, and
+     <function>array_walk</function>
+    </simpara>
+   </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
+-->
+