php-doc-en/reference/filesystem/functions/fopen.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
  <refentry id="function.fopen">
   <refnamediv>
    <refname>fopen</refname>
    <refpurpose>Opens file or URL</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>fopen</methodname>
      <methodparam><type>string</type><parameter>filename</parameter></methodparam>
      <methodparam><type>string</type><parameter>mode</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>zcontext</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     If <parameter>filename</parameter> begins with "http://" (not
     case sensitive), an HTTP 1.0 connection is opened to the
     specified server, the page is requested using the HTTP GET
     method, and a file pointer is returned to the beginning
     of the body of the response. A 'Host:' header is sent with the
     request in order to handle name-based virtual hosts.
    </simpara>
    <simpara>
     As of PHP 4.3.0, if you have compiled in support for OpenSSL, 
     you may use "https://" to open an HTTP connection over SSL.
    </simpara>
    <simpara>
     Note that the file pointer allows you to retrieve only the
     <emphasis>body</emphasis> of the response; to retrieve the HTTP
     response header you need to be using PHP 4.0.5 or later;
     The headers will be stored in the $http_response_header variable.
     As of PHP 4.3.0, the header information can be retrieved using 
     <function>file_get_wrapper_data</function>.
    </simpara>
    <simpara>
     HTTP connections are read-only; you cannot write data or copy
     files to an HTTP resource.
    </simpara>
    <simpara>
     Versions prior to PHP 4.0.5 do not handle HTTP redirects. Because
     of this, directories must include trailing slashes.
    </simpara>
    <simpara>
     If <parameter>filename</parameter> begins with "ftp://" (not case
     sensitive), an ftp connection to the specified server is opened
     and a pointer to the requested file is returned. If the server
     does not support passive mode ftp, this will fail. You can open
     files for either reading or writing via ftp (but not both
     simultaneously).  If the remote file already exists on the ftp
     server and you attempt to open it for writing, this will fail.
     If you need to update existing files over ftp, use
     <function>ftp_connect</function>.
    </simpara>
    <simpara>
     As of PHP 4.3.0, if you have compiled in support for OpenSSL, 
     you may use "ftps://" to open an FTP connection that will
     use SSL to encrypt the connection.  PHP will fall-back and
     work just like regular ftp:// if the server does not support
     SSL.
    </simpara>
    <simpara>
     If <parameter>filename</parameter> is one of "php://stdin",
     "php://stdout", or "php://stderr", the corresponding stdio
     stream will be opened.  (This was introduced in PHP 3.0.13;
     in earlier versions, a filename such as "/dev/stdin" or
     "/dev/fd/0" must be used to access the stdio streams.)
    </simpara>
    <simpara>
     If <parameter>filename</parameter> begins with anything else, the
     file will be opened from the filesystem, and a file pointer to
     the file opened is returned.
    </simpara>
    <simpara>
     If the open fails, the function returns &false;.
    </simpara>
    <para>
     <parameter>mode</parameter> may be any of the following:
     <itemizedlist>
      <listitem>
       <simpara>
        'r' - Open for reading only; place the file pointer at the
        beginning of the file.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        'r+' - Open for reading and writing; place the file pointer at
        the beginning of the file.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        'w' - Open for writing only; place the file pointer at the
        beginning of the file and truncate the file to zero length.
        If the file does not exist, attempt to create it.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        'w+' - Open for reading and writing; place the file pointer at
        the beginning of the file and truncate the file to zero
        length.  If the file does not exist, attempt to create it.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        'a' - Open for writing only; place the file pointer at the end
        of the file. If the file does not exist, attempt to create
        it.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        'a+' - Open for reading and writing; place the file pointer at
        the end of the file. If the file does not exist, attempt to
        create it.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <note>
     <para>
      The <parameter>mode</parameter> may contain the letter
      'b'. This is useful only on systems which differentiate between
      binary and text files (i.e. Windows. It's useless on Unix). 
      If not needed, this will be ignored.
     </para>
    </note>
    <para>
     The optional third <parameter>use_include_path</parameter> parameter 
     can be set to '1' or &true; if you want to search for the file in 
     the <link linkend="ini.include-path">include_path</link>, too.
    </para>
    <para>
     The optional fourth <parameter>zcontext</parameter> is used for 
     specifying tuning parameters and callbacks.
    </para>
    <para>
     <example>
      <title><function>fopen</function> example</title>
      <programlisting role="php">
<![CDATA[
<?php
$fp = fopen ("/home/rasmus/file.txt", "r");
$fp = fopen ("/home/rasmus/file.gif", "wb");
$fp = fopen ("http://www.example.com/", "r");
$fp = fopen ("ftp://user:password@example.com/", "w");
?>
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     If you are experiencing problems with reading and writing to
     files and you're using the server module version of PHP, remember
     to make sure that the files and directories you're using are
     accessible to the server process.
    </simpara>
    <para>
     On the Windows platform, be careful to escape any backslashes
     used in the path to the file, or use forward slashes.
     <informalexample>
      <programlisting role="php"> 
<![CDATA[
<?php
$fp = fopen ("c:\\data\\info.txt", "r");
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     See also <xref linkend="wrappers"/>
     <function>fclose</function>,
     <function>fgets</function>, 
     <function>fsockopen</function>,
     <function>file</function>,
     <function>file_exists</function>,
     <function>is_readable</function>,
     <function>socket_set_timeout</function>, and
     <function>popen</function>.
    </simpara>
   </refsect1>
  </refentry>

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