<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.27 $ -->
 <reference id="ref.url">
  <title>URL Functions</title>
  <titleabbrev>URLs</titleabbrev>

  <refentry id="function.base64-decode">
   <refnamediv>
    <refname>base64_decode</refname>
    <refpurpose>Decodes data encoded with MIME base64</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>base64_decode</methodname>
      <methodparam><type>string</type><parameter>encoded_data</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>base64_decode</function> decodes
     <parameter>encoded_data</parameter> and returns the original
     data.  The returned data may be binary.
    </para>
    <para>
     See also: <function>base64_encode</function>, RFC2045 section
     6.8.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.base64-encode">
   <refnamediv>
    <refname>base64_encode</refname>
    <refpurpose>Encodes data with MIME base64</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>base64_encode</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>base64_encode</function> returns
     <parameter>data</parameter> encoded with base64.  This encoding
     is designed to make binary data survive transport through
     transport layers that are not 8-bit clean, such as mail bodies.
    </para>
    <para>
     Base64-encoded data takes about 33% more space than the original
     data.</para>
    <para>
     See also:
     <function>base64_decode</function>,
     <function>chunk_split</function>,
     RFC2045 section 6.8.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.parse-url">
   <refnamediv>
    <refname>parse_url</refname>
    <refpurpose>Parse a URL and return its components</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>parse_url</methodname>
      <methodparam><type>string</type><parameter>url</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function returns an associative array returning any of the
     various components of the URL that are present. This includes the
    <itemizedlist>
     <listitem>
      <simpara>
       <structfield>scheme</structfield> - e.g. http://
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <structfield>host</structfield> 
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <structfield>port</structfield>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <structfield>user</structfield>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <structfield>pass</structfield>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <structfield>path</structfield>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
        <structfield>query</structfield>  - after the question mark <literal>?</literal>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <structfield>fragment</structfield> -  after the hashmark <literal>#</literal>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
    <para>
     See also <function>pathinfo</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.rawurldecode">
   <refnamediv>
    <refname>rawurldecode</refname>
    <refpurpose>Decode URL-encoded strings</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>rawurldecode</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns a string in which the sequences with percent
     (<literal>%</literal>) signs followed by two hex digits have been
     replaced with literal characters.  For example, the string
     <screen>foo%20bar%40baz</screen> decodes into <screen>foo bar@baz</screen>.
    </para>
    <note>
     <para>
      <function>rawurldecode</function> does not decode plus symbols ('+')
      into spaces. <function>urldecode</function> does.
     </para>
    </note>
    <simpara>
     See also <function>rawurlencode</function>,
     <function>urldecode</function>,
     <function>urlencode</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.rawurlencode">
   <refnamediv>
    <refname>rawurlencode</refname>
    <refpurpose>URL-encode according to RFC1738</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>rawurlencode</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns a string in which all non-alphanumeric characters except
     <screen>-_.</screen> have been replaced with a percent
     (<literal>%</literal>) sign followed by two hex digits.  This is
     the encoding described in RFC1738 for protecting literal
     characters from being interpreted as special URL delimiters, and
     for protecting URL's from being mangled by transmission media
     with character conversions (like some email systems).  For
     example, if you want to include a password in an FTP URL:
    </para>
    <example>
     <title><function>rawurlencode</function> example 1</title>
     <programlisting role="php">
<![CDATA[
echo '<a href="ftp://user:', rawurlencode('foo @+%/'),
     '@ftp.my.com/x.txt">';
]]>
     </programlisting>
    </example>
    <para>
     Or, if you pass information in a PATH_INFO component of the URL:
    </para>
    <example>
     <title><function>rawurlencode</function> example 2</title>
     <programlisting role="php">
<![CDATA[
echo '<a href="http://x.com/department_list_script/',
    rawurlencode('sales and marketing/Miami'), '">';
]]>
     </programlisting>
    </example>
    <simpara>
     See also <function>rawurldecode</function>,
     <function>urldecode</function>,
     <function>urlencode</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.urldecode">
   <refnamediv>
    <refname>urldecode</refname>
    <refpurpose>Decodes URL-encoded string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>urldecode</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
     </methodsynopsis>
    <para>
     Decodes any <literal>%<replaceable>##</replaceable></literal>
     encoding in the given string.  The decoded string is returned.
     <example>
      <title><function>urldecode</function> example</title>
      <programlisting role="php">
<![CDATA[
$a = explode('&', $QUERY_STRING);
$i = 0;
while ($i < count($a)) {
    $b = split('=', $a[$i]);
    echo 'Value for parameter ', htmlspecialchars(urldecode($b[0])),
         ' is ', htmlspecialchars(urldecode($b[1])), "<br />\n";
    $i++;
}
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>urlencode</function>,
     <function>rawurlencode</function>,
     <function>rawurldecode</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.urlencode">
   <refnamediv>
    <refname>urlencode</refname>
    <refpurpose>URL-encodes string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>urlencode</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns a string in which all non-alphanumeric characters except
     <literal>-_.</literal> have been replaced with a percent
     (<literal>%</literal>) sign followed by two hex digits and spaces
     encoded as plus (<literal>+</literal>) signs.  It is encoded the
     same way that the posted data from a WWW form is encoded, that is
     the same way as in
     <literal>application/x-www-form-urlencoded</literal> media type.
     This differs from the RFC1738 encoding (see
     <function>rawurlencode</function>) in that for historical
     reasons, spaces are encoded as plus (+) signs.  This function is
     convenient when encoding a string to be used in a query part of
     an URL, as a convenient way to pass variables to the next page:
     <example>
      <title><function>urlencode</function> example</title>
      <programlisting role="php">
<![CDATA[
echo '<a href="mycgi?foo=', urlencode($userinput), '">';
]]>
      </programlisting>
     </example>
    </para>
    <para>
    Note: Be careful about variables that may match HTML entities.  
    Things like &amp;amp, &amp;copy and &amp;pound are parsed by the
    browser and the actual entity is used instead of the desired
    variable name.  This is an obvious hassle that the W3C has been
    telling people about for years. The reference is here:
    <ulink url="&url.argsep;">&url.argsep;</ulink> PHP supports
    changing the argument separator to the W3C-suggested semi-colon
    through the arg_separator .ini directive.  Unfortunately most user
    agents do not send form data in this semi-colon separated format.
    A more portable way around this is to use &amp;amp; instead of
    &amp; as the separator.  You don't need to change PHP's
    arg_separator for this.  Leave it as &amp;, but simply encode
    your URLs using <function>htmlentities</function>(urlencode($data)).
     <example>
      <title><function>urlencode/htmlentities</function> example</title>
      <programlisting role="php">
<![CDATA[
echo '<a href="mycgi?foo=', htmlentities(urlencode($userinput)), '">';
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>urldecode</function>,
     <function>htmlentities</function>,
     <function>rawurldecode</function>,
     <function>rawurlencode</function>.
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- 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
-->