svn: /phpdoc/en/trunk/reference/filesystem/functions/ basename.xml dirname.xml
| From: | Justin Martin | 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.