<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.filter.set.realpath">
    <title>RealPath</title>

    <para>
        This filter will resolve given links and pathnames and returns canonicalized absolute
        pathnames.
    </para>

    <sect3 id="zend.filter.set.realpath.options">
        <title>Supported options for Zend_Filter_RealPath</title>

        <para>
            The following options are supported for <classname>Zend_Filter_RealPath</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>exists</property></emphasis>: This option defaults to
                    <constant>TRUE</constant> which checks if the given path really exists.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.filter.set.realpath.basic">
        <title>Basic usage</title>

        <para>
            For any given link of pathname its absolute path will be returned.
            References to '<filename>/./</filename>', '<filename>/../</filename>' and extra
            '<filename>/</filename>' characters in the input path will be stripped. The resulting
            path will not have any symbolic link, '<filename>/./</filename>' or
            '<filename>/../</filename>' character.
        </para>

        <para>
            <classname>Zend_Filter_RealPath</classname> will return <constant>FALSE</constant> on
            failure, e.g. if the file does not exist. On <acronym>BSD</acronym> systems
            <classname>Zend_Filter_RealPath</classname> doesn't fail if only the last path component
            doesn't exist, while other systems will return <constant>FALSE</constant>.
        </para>

        <programlisting language="php"><![CDATA[
$filter = new Zend_Filter_RealPath();
$path   = '/www/var/path/../../mypath';
$filtered = $filter->filter($path);

// returns '/www/mypath'
]]></programlisting>
    </sect3>

    <sect3 id="zend.filter.set.realpath.exists">
        <title>Non existing paths</title>

        <para>
            Sometimes it is useful to get also paths when they don't exist, f.e. when you want to
            get the real path for a path which you want to create. You can then either give a
            <constant>FALSE</constant> at initiation, or use <methodname>setExists()</methodname> to
            set it.
        </para>

        <programlisting language="php"><![CDATA[
$filter = new Zend_Filter_RealPath(false);
$path   = '/www/var/path/../../non/existing/path';
$filtered = $filter->filter($path);

// returns '/www/non/existing/path'
// even when file_exists or realpath would return false
]]></programlisting>
    </sect3>
</sect2>
