Document/tidy up/clarify some more streams related information.

Add notes about URL support for GD functions.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@97008 c90b9560-bf6c-de11-be94-00142212c4b1

language-snippets.ent

@@ -16,9 +16,9 @@ Use this function at your own risk.</simpara></warning>'>
 currently not documented; only the argument list is
 available.</simpara></warning>'>
 
-<!ENTITY warn.no-win32-fopen-wrapper '<warning><para>The Windows
-version of <literal>PHP</literal> currently does not support accessing
-remote files via this function, even if
+<!ENTITY warn.no-win32-fopen-wrapper '<warning><para>Windows
+versions of <literal>PHP</literal> prior to PHP 4.3 do not
+support accessing remote files via this function, even if
 <link linkend="ini.allow-url-fopen">allow_url_fopen</link> is enabled.
 </para></warning>'>
 
@@ -29,8 +29,11 @@ the output of this function, and save it in a
 <type>string</type> (for example).</simpara></tip>'>
 
 <!ENTITY tip.fopen-wrapper '<tip><simpara>You can use a URL as a
-filename with this function if the "fopen wrappers" have been enabled.
-See <function>fopen</function> for more details.</simpara></tip>'>
+filename with this function if the <link linkend="ini.allow-url-fopen"
+>fopen wrappers</link> have been enabled.
+See <function>fopen</function> for more details on how to specify
+the filename and <xref linkend="wrappers"/> for a list of supported
+URL protocols.</simpara></tip>'>
 
 <!ENTITY return.success 'Returns &true; on success or &false; on failure.'>
 
@@ -50,6 +53,13 @@ is not (yet) binary safe!</simpara></warning>'>
 <!ENTITY note.bin-safe '<note><simpara>This function is
 binary-safe.</simpara></note>'>
 
+<!ENTITY note.line-endings '<note><simpara>If you are having problems
+with <literal>PHP</literal> not recognizing the line endings when
+reading files either on or created by a Macintosh computer, you
+might want to enable the <link linkend="ini.auto-detect-line-endings"
+>auto_detect_line_endings</link> run-time configuration option.</simpara>
+</note>'>
+
 <!ENTITY note.no-windows '<note><simpara>This function is not
 implemented on Windows platforms.</simpara></note>'>
 

language/control-structures.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.64 $ -->
+<!-- $Revision: 1.65 $ -->
  <chapter id="control-structures">
   <title>Control Structures</title>
 
@@ -1185,8 +1185,9 @@ echo "A $color $fruit";   // A green
    <simpara>
      If "<link linkend="ini.allow-url-fopen">URL fopen wrappers</link>"
      are enabled in PHP (which they are in the default configuration),
-     you can specify the file to be included using an URL (via HTTP)
-     instead of a local pathname.  If the target server interprets
+     you can specify the file to be included using an URL (via HTTP or
+     other supported wrapper - see <xref linkend="wrappers"/> for a list
+     of protocols) instead of a local pathname.  If the target server interprets
      the target file as PHP code, variables may be passed to the included
      file using an URL request string as used with HTTP GET.  This is
      not strictly speaking the same thing as including the file and having

reference/filesystem/functions/copy.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.copy">
    <refnamediv>
@@ -32,6 +32,8 @@ if (!copy($file, $file.'.bak')) {
       As of PHP 4.3.0, both <parameter>source</parameter> and
       <parameter>dest</parameter> may be URLs if the "fopen wrappers"
       have been enabled.  See <function>fopen</function> for more details.
+      If <parameter>dest</parameter> is an URL, the copy operation may
+      fail if the wrapper does not support overwriting of existing files.
      </para>
     </note>
     <warning>

reference/filesystem/functions/file.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.file">
    <refnamediv>
@@ -26,6 +26,7 @@
       ending present.
      </para>
     </note>
+    &note.line-endings;
     <para>
      You can use the optional second parameter and set it to "1", if
      you want to search for the file in the <link

reference/filesystem/functions/fpassthru.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.fpassthru">
    <refnamediv>
@@ -14,7 +14,7 @@
      </methodsynopsis>
     <simpara>
      Reads to EOF on the given file pointer from the current position and
-     writes the results to standard output.
+     writes the results to the output buffer.
     </simpara>
     <simpara>
      If an error occurs, <function>fpassthru</function> returns
@@ -30,7 +30,8 @@
      <parameter>fp</parameter> useless).
     </simpara>
     <simpara>
-     If you just want to dump the contents of a file to stdout you may
+     If you just want to dump the contents of a file to the output buffer,
+     without first modifying it or seeking to a particular offset, you may
      want to use the <function>readfile</function>, which saves you
      the <function>fopen</function> call.
     </simpara>
@@ -41,6 +42,11 @@
       appending a <literal>b</literal> to the mode used in the call to
       <function>fopen</function>.
      </para>
+     <para>
+      You are encouraged to use the <literal>b</literal> flag when dealing
+      with binary files, even if your system does not require it, so that
+      your scripts will be more portable.
+     </para>
     </note>
     <simpara>
      See also <function>readfile</function>,

reference/filesystem/functions/readfile.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.readfile">
    <refnamediv>
@@ -14,34 +14,14 @@
       <methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
      </methodsynopsis>
     <para>
-     Reads a file and writes it to standard output.
+     Reads a file and writes it to the output buffer.
     </para>
     <para>
      Returns the number of bytes read from the file. If an error
      occurs, &false; is returned and unless the function was called as
      @readfile, an error message is printed.
     </para>
-    <para>
-     If <parameter>filename</parameter> begins with "http://"
-     (not case sensitive), an HTTP 1.0 connection is opened to the
-     specified server and the text of the response is written to
-     standard output.
-    </para>
-    <para>
-     Versions prior to PHP 4.0.5 do not handle HTTP redirects. Because
-     of this, directories must include trailing slashes.
-    </para>
-    <para>
-     If <parameter>filename</parameter> begins with "ftp://"
-     (not case sensitive), an ftp connection to the specified server is
-     opened and the requested file is written to standard output. If the server
-     does not support passive mode ftp, this will fail.
-    </para>
-    <para>
-     If <parameter>filename</parameter> begins with neither
-     of these strings, the file will be opened from the filesystem and
-     its contents written to standard output.
-    </para>
+    &tip.fopen-wrapper;
     <para>
      You can use the optional second parameter and set it to "1", if
      you want to search for the file in the <link
@@ -50,8 +30,8 @@
     <para>
      See also <function>fpassthru</function>,
      <function>file</function>, <function>fopen</function>,
-     <function>include</function>, <function>require</function>, and
-     <function>virtual</function>.
+     <function>include</function>, <function>require</function>,
+     <function>virtual</function> and <xref linkend="wrappers"/>.
     </para>
    </refsect1>
   </refentry>

reference/image/functions/imagecreatefromgd.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.67 -->
   <refentry id='function.imagecreatefromgd'>
    <refnamediv>
@@ -15,6 +15,8 @@
     <para>
      &warn.undocumented.func;
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/functions/imagecreatefromgd2.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.67 -->
   <refentry id='function.imagecreatefromgd2'>
    <refnamediv>
@@ -15,6 +15,8 @@
     <para>
      &warn.undocumented.func;
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/functions/imagecreatefromgd2part.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.67 -->
   <refentry id='function.imagecreatefromgd2part'>
    <refnamediv>
@@ -19,6 +19,8 @@
     <para>
      &warn.undocumented.func;
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/functions/imagecreatefromgif.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.2 -->
   <refentry id="function.imagecreatefromgif">
    <refnamediv>
@@ -51,6 +51,8 @@ function LoadGif ($imgname) {
       </para>
      </note>
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/functions/imagecreatefromjpeg.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.4 -->
   <refentry id="function.imagecreatefromjpeg">
    <refnamediv>
@@ -44,6 +44,8 @@ function LoadJpeg ($imgname) {
       </programlisting>
      </example>
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/functions/imagecreatefrompng.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.4 -->
   <refentry id="function.imagecreatefrompng">
    <refnamediv>
@@ -44,6 +44,8 @@ function LoadPNG ($imgname) {
       </programlisting>
      </example>
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/functions/imagecreatefromwbmp.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.30 -->
   <refentry id="function.imagecreatefromwbmp">
    <refnamediv>
@@ -50,6 +50,8 @@ function LoadWBMP ($imgname) {
       against GD-1.8 or later.
      </para>
     </note>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/functions/imagecreatefromxbm.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.61 -->
   <refentry id="function.imagecreatefromxbm">
    <refnamediv>
@@ -16,6 +16,8 @@
      <function>imagecreatefromxbm</function> returns an image identifier
      representing the image obtained from the given filename.
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/functions/imagecreatefromxpm.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/image.xml, last change in rev 1.61 -->
   <refentry id="function.imagecreatefromxpm">
    <refnamediv>
@@ -16,6 +16,8 @@
      <function>imagecreatefromxpm</function> returns an image identifier
      representing the image obtained from the given filename.
     </para>
+    &tip.fopen-wrapper;
+    &warn.no-win32-fopen-wrapper;
    </refsect1>
   </refentry>
 

reference/image/reference.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <reference id="ref.image">
  <title>Image functions</title>
  <titleabbrev>Image</titleabbrev>
@@ -40,7 +40,7 @@
      greater than gd-1.6 support png, not gif.
       <note>
        <simpara>
-        Since PHP 4.3 there is a bundeled version of the GD lib. This bundeled
+        Since PHP 4.3 there is a bundled version of the GD lib. This bundled
         version has some additional features like alpha blending and should
         be used in preference to the external library since it's codebase is
         better maintained and more stable.