From 50b2dea45f296af01ebba3ae34d4d40c795358c9 Mon Sep 17 00:00:00 2001
From: Nuno Lopes <nlopess@php.net>
Date: Sat, 12 Aug 2006 18:00:17 +0000
Subject: [PATCH] document the 2nd parameter of parse_url() and add its
 constants

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@218045 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/url/constants.xml           | 121 ++++++++++++++++++++++++++
 reference/url/functions/parse-url.xml |  51 ++++++++++-
 reference/url/reference.xml           |   7 +-
 3 files changed, 172 insertions(+), 7 deletions(-)
 create mode 100644 reference/url/constants.xml

diff --git a/reference/url/constants.xml b/reference/url/constants.xml
new file mode 100644
index 0000000000..5e87ec6f29
--- /dev/null
+++ b/reference/url/constants.xml
@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+<section id="url.constants">
+ &reftitle.constants;
+ &extension.constants;
+ <para>
+  The following constants are meant to be used with
+  <function>parse_url</function> and are available since PHP 5.1.2.
+ </para>
+ <variablelist>
+  <varlistentry>
+   <term>
+    <constant>PHP_URL_SCHEME</constant>
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+     
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <constant>PHP_URL_HOST</constant>
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+     
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <constant>PHP_URL_PORT</constant>
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+     
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <constant>PHP_URL_USER</constant>
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+     
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <constant>PHP_URL_PASS</constant>
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+     
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <constant>PHP_URL_PATH</constant>
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+     
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <constant>PHP_URL_QUERY</constant>
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+     
+    </simpara>
+   </listitem>
+  </varlistentry>
+  <varlistentry>
+   <term>
+    <constant>PHP_URL_FRAGMENT</constant>
+    (<type>integer</type>)
+   </term>
+   <listitem>
+    <simpara>
+     
+    </simpara>
+   </listitem>
+  </varlistentry>
+ </variablelist>
+</section>
+
+<!-- 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
+-->
diff --git a/reference/url/functions/parse-url.xml b/reference/url/functions/parse-url.xml
index fb6d069756..53c854624a 100644
--- a/reference/url/functions/parse-url.xml
+++ b/reference/url/functions/parse-url.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
 <!-- splitted from ./en/functions/url.xml, last change in rev 1.2 -->
 <refentry id="function.parse-url">
  <refnamediv>
@@ -9,8 +9,9 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>array</type><methodname>parse_url</methodname>
+   <type>mixed</type><methodname>parse_url</methodname>
    <methodparam><type>string</type><parameter>url</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>component</parameter></methodparam>
   </methodsynopsis>
   <para>
    This function parses a URL and returns an associative array containing any
@@ -37,6 +38,22 @@
      </listitem>
     </varlistentry>
    </variablelist>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>component</parameter></term>
+     <listitem>
+      <para>
+       Specify one of <constant>PHP_URL_SCHEME</constant>,
+       <constant>PHP_URL_HOST</constant>, <constant>PHP_URL_PORT</constant>,
+       <constant>PHP_URL_USER</constant>, <constant>PHP_URL_PASS</constant>,
+       <constant>PHP_URL_PATH</constant>, <constant>PHP_URL_QUERY</constant>
+       or <constant>PHP_URL_FRAGMENT</constant> to retrieve just a specific
+       URL component as a <type>string</type>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+
   </para>
  </refsect1>
 
@@ -89,6 +106,32 @@
     </listitem>
    </itemizedlist>
   </para>
+  <para>
+   If the <parameter>component</parameter> parameter is specified a
+   <type>string</type> is returned instead of an <type>array</type>.
+  </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.1.2</entry>
+       <entry>Added the <parameter>component</parameter> parameter</entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
  </refsect1>
 
  <refsect1 role="examples">
@@ -102,6 +145,8 @@
 $url = 'http://username:password@hostname/path?arg=value#anchor';
 
 print_r(parse_url($url));
+
+echo parse_url($url, PHP_URL_PATH);
 ?>
 ]]>
     </programlisting>
@@ -118,6 +163,7 @@ Array
     [query] => arg=value
     [fragment] => anchor
 )
+/path
 ]]>
     </screen>
    </example>
@@ -146,6 +192,7 @@ Array
    <simplelist>
     <member><function>pathinfo</function></member>
     <member><function>parse_str</function></member>
+    <member><function>http_build_query</function></member>
     <member><function>dirname</function></member>
     <member><function>basename</function></member>
    </simplelist>
diff --git a/reference/url/reference.xml b/reference/url/reference.xml
index a3764457b4..96d9836d6f 100644
--- a/reference/url/reference.xml
+++ b/reference/url/reference.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- Purpose: basic.other -->
 <!-- Membership: core -->
 
@@ -35,10 +35,7 @@
     &no.resource;
    </section>
 
-   <section id="url.constants">
-    &reftitle.constants;
-    &no.constants;
-   </section>
+   &reference.url.constants;
 
   </partintro>