svn: /phpdoc/en/trunk/reference/filesystem/functions/ basename.xml dirname.xml

From: Date: Sun, 07 Nov 2010 03:55:45 +0000
Subject: svn: /phpdoc/en/trunk/reference/filesystem/functions/ basename.xml dirname.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-7382@lists.php.net to get a copy of this message
frozenfire Sun, 07 Nov 2010 03:55:45 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=305142 Log: Clarified behaviour of dirname and basename, as per bug #51830. Bug: http://bugs.php.net/51830 (Open) dirname() and basename() documentation unclear/incorrect Changed paths: U phpdoc/en/trunk/reference/filesystem/functions/basename.xml U phpdoc/en/trunk/reference/filesystem/functions/dirname.xml Modified: phpdoc/en/trunk/reference/filesystem/functions/basename.xml =================================================================== --- phpdoc/en/trunk/reference/filesystem/functions/basename.xml 2010-11-07 01:49:04 UTC (rev 305141) +++ phpdoc/en/trunk/reference/filesystem/functions/basename.xml 2010-11-07 03:55:45 UTC (rev 305142) @@ -3,7 +3,7 @@ <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.basename"> <refnamediv> <refname>basename</refname> - <refpurpose>Returns filename component of path</refpurpose> + <refpurpose>Returns trailing name component of path</refpurpose> </refnamediv> <refsect1 role="description"> @@ -14,8 +14,8 @@ <methodparam choice="opt"><type>string</type><parameter>suffix</parameter></methodparam> </methodsynopsis> <para> - Given a string containing a path to a file, this function will return the - base name of the file. + Given a string containing the path to a file or directory, this function + will return the trailing name component. </para> </refsect1> @@ -40,7 +40,7 @@ <term><parameter>suffix</parameter></term> <listitem> <para> - If the filename ends in <parameter>suffix</parameter> this will also + If the name component ends in <parameter>suffix</parameter> this will also be cut off. </para> </listitem> @@ -88,15 +88,38 @@ <programlisting role="php"> <![CDATA[ <?php -$path = "/home/httpd/html/index.php"; -$file = basename($path); // $file is set to "index.php" -$file = basename($path, ".php"); // $file is set to "index" +echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL; +echo "2) ".basename("/etc/passwd").PHP_EOL; +echo "3) ".basename("/etc/").PHP_EOL; +echo "4) ".basename(".").PHP_EOL; +echo "5) ".basename("/"); ?> ]]> </programlisting> + &example.outputs; + <screen> +<![CDATA[ +1) sudoers +2) passwd +3) etc +4) . +5) +]]> + </screen> </example> </para> </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + <function>basename</function> operates naively on the input string, + and is not aware of the actual filesystem, or path components such + as "<literal>..</literal>". + </para> + </note> + </refsect1> <refsect1 role="seealso"> &reftitle.seealso; Modified: phpdoc/en/trunk/reference/filesystem/functions/dirname.xml =================================================================== --- phpdoc/en/trunk/reference/filesystem/functions/dirname.xml 2010-11-07 01:49:04 UTC (rev 305141) +++ phpdoc/en/trunk/reference/filesystem/functions/dirname.xml 2010-11-07 03:55:45 UTC (rev 305142) @@ -3,7 +3,7 @@ <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.dirname"> <refnamediv> <refname>dirname</refname> - <refpurpose>Returns directory name component of path</refpurpose> + <refpurpose>Returns parent directory's path</refpurpose> </refnamediv> <refsect1 role="description"> @@ -13,8 +13,8 @@ <methodparam><type>string</type><parameter>path</parameter></methodparam> </methodsynopsis> <para> - Given a string containing a path to a file, this function will return the - name of the directory. + Given a string containing the path of a file or directory, + this function will return the parent directory's path. </para> </refsect1> @@ -42,7 +42,7 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - Returns the name of the directory. If there are no slashes in + Returns the path of the parent directory. If there are no slashes in <parameter>path</parameter>, a dot ('<literal>.</literal>') is returned, indicating the current directory. Otherwise, the returned string is <parameter>path</parameter> with any trailing @@ -88,11 +88,20 @@ <programlisting role="php"> <![CDATA[ <?php -$path = "/etc/passwd"; -$file = dirname($path); // $file is set to "/etc" +echo "1) ".dirname("/etc/passwd").PHP_EOL; +echo "2) ".dirname("/etc/").PHP_EOL; +echo "3) ".dirname("."); ?> ]]> </programlisting> + &example.outputs; + <screen> +<![CDATA[ +1) /etc +2) / +3) . +]]> + </screen> </example> </para> </refsect1> @@ -101,6 +110,13 @@ &reftitle.notes; <note> <para> + <function>dirname</function> operates naively on the input string, + and is not aware of the actual filesystem, or path components such + as "<literal>..</literal>". + </para> + </note> + <note> + <para> Since PHP 4.3.0, you will often get a slash or a dot back from <function>dirname</function> in situations where the older functionality would have given you the empty string.

« previous php.doc.cvs (#7382) next »