<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 299643 $ -->
 <chapter xml:id="faq.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Installation</title>
  <titleabbrev>Installation</titleabbrev>

  <para>
   This section holds common questions about the way to install
   PHP. PHP is available for almost any OS (except maybe for 
   MacOS before OSX), and almost any web server.
  </para>
  <para>
   To install PHP, follow the instructions in <xref linkend="install"/>.
  </para>

  <qandaset>
   <qandaentry xml:id="faq.installation.apache2">
    <question>
     <para>
      Why shouldn't I use Apache2 with a threaded MPM in a production environment?
     </para>
    </question>
    <answer>
     <para>
      PHP is glue. It is the glue used to build cool web applications by
      sticking dozens of 3rd-party libraries together and making it all appear
      as one coherent entity through an intuitive and easy to learn language
      interface. The flexibility and power of PHP relies on the stability and
      robustness of the underlying platform. It needs a working OS, a working
      web server and working 3rd-party libraries to glue together. When any of
      these stop working PHP needs ways to identify the problems and fix them
      quickly. When you make the underlying framework more complex by not having
      completely separate execution threads, completely separate memory
      segments and a strong sandbox for each request to play in, further
      weaknesses are introduced into PHP's system.
     </para>
     <para>
      If you feel you have to use a threaded MPM, look at a FastCGI configuration
      where PHP is running in its own memory space.  
     </para>
     <para>
      And finally, this warning against using a threaded MPM is not as strong for
      Windows systems because most libraries on that platform tend to be threadsafe.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.phpini">
    <question>
     <para>
      Unix/Windows: Where should my &php.ini; file be
      located?
     </para>
    </question>
    <answer>
     <para>
      By default on Unix it should be in <filename>/usr/local/lib</filename>
      which is <filename>&lt;install-path&gt;/lib</filename>.
      Most people will want to change this at compile-time with the 
      <link linkend="configure.with-config-file-path">--with-config-file-path</link>
      flag. You would, for example, set it with something like:
      <programlisting role="shell">
--with-config-file-path=/etc
      </programlisting>
      And then you would copy <filename>php.ini-development</filename> from 
      the distribution to <filename>/etc/php.ini</filename> and
      edit it to make any local changes you want.
     </para>
      <programlisting role="shell">
--with-config-file-scan-dir=PATH 
      </programlisting>
     <para>
      On Windows the default path for the &php.ini; file is the Windows
      directory. If you're using the Apache webserver, &php.ini; is first
      searched in the Apaches install directory, e.g. <filename>c:\program
      files\apache group\apache</filename>. This way you can have
      different &php.ini; files for different versions of Apache on the same
      machine.
     </para>
     <para>
     See also the chapter about the <link
     linkend="configuration.file">configuration file</link>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.nodata">
    <question>
     <para>
      Unix: I installed PHP, but every time I load a document, I get the 
      message 'Document Contains No Data'! What's going on here?
     </para>
    </question>
    <answer>
     <para>
      This probably means that PHP is having some sort of problem
      and is core-dumping. Look in your server error log to see if
      this is the case, and then try to reproduce the problem with
      a small test case. If you know how to use 'gdb', it is very
      helpful when you can provide a backtrace with your bug report
      to help the developers pinpoint the problem.  If you are using
      PHP as an Apache module try something like:
      <itemizedlist>
       <listitem>
        <para>
         Stop your httpd processes
        </para>
       </listitem>
       <listitem>
        <para>
         gdb httpd
        </para>
       </listitem>
       <listitem>
        <para>
         Stop your httpd processes
        </para>
       </listitem>
       <listitem>
        <para>
         &gt; run -X -f /path/to/httpd.conf
        </para>
       </listitem>
       <listitem>
        <para>
         Then fetch the URL causing the problem with your browser
        </para>
       </listitem>      
       <listitem>
        <para>
         &gt; run -X -f /path/to/httpd.conf
        </para>
       </listitem>      
       <listitem>
        <para>
         If you are getting a core dump, gdb should inform you of this now
        </para>
       </listitem>      
       <listitem>
        <para>
         type: bt
        </para>
       </listitem>
       <listitem>
        <para>
         You should include your backtrace in your bug report. This should be submitted to 
         <link xlink:href="&url.php.bugs;">&url.php.bugs;</link> 
        </para>
       </listitem>
      </itemizedlist>
     </para>
     <para>
      If your script uses the regular expression functions
      (<function>preg_match</function> and friends), you should make sure 
      that you compiled PHP and Apache with the same regular 
      expression package. This should happen automatically with
      PHP and Apache 1.3.x
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.processing">
    <question>
     <para>
      Unix: I installed PHP using RPMS, but Apache isn't processing the 
      PHP pages! What's going on here?
     </para>
    </question>
    <answer>
     <para>
      Assuming you installed both Apache and PHP from RPM packages, 
      you need to uncomment or add some or all of the following lines
      in your &httpd.conf; file:
      <programlisting role="apache-conf">
<![CDATA[
# Extra Modules
AddModule mod_php.c
AddModule mod_php.c
AddModule mod_perl.c

# Extra Modules
LoadModule php_module         modules/mod_php.so
LoadModule php5_module        modules/libphp5.so
LoadModule perl_module        modules/libperl.so
]]>
      </programlisting>
      And add:
      <programlisting role="apache-conf">
<![CDATA[
AddType application/x-httpd-php .php
]]>
      </programlisting>
      ... to the global properties, or to the properties of the 
      VirtualDomain you want to have PHP support added to.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.frontpage">
    <question>
     <para>
      Unix: I patched Apache with the FrontPage extensions patch, and
      suddenly PHP stopped working. Is PHP incompatible with the
      Apache FrontPage extensions?
     </para>
    </question>
    <answer>
     <para>
      No, PHP works fine with the FrontPage extensions. The problem
      is that the FrontPage patch modifies several Apache structures,
      that PHP relies on. Recompiling PHP (using 'make clean ; make')
      after the FP patch is applied would solve the problem.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.blankscreen">
    <question>
     <para>
      Unix/Windows: I have installed PHP, but when I try to
      access a PHP script file via my browser, I get a blank screen.
     </para>
    </question>
    <answer>
     <para>
      Do a 'view source' in the web browser and you will probably
      find that you can see the source code of your PHP script.
      This means that the web server did not send the script to
      PHP for interpretation. Something is wrong with the server
      configuration - double check the server configuration against
      the PHP installation instructions.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.500error">
    <question>
     <para>
      Unix/Windows: I have installed PHP, but when try to
      access a PHP script file via my browser, I get a
      server 500 error.
     </para>
    </question>
    <answer>
     <para>
      Something went wrong when the server tried to run PHP. To
      get to see a sensible error message, from the command line,
      change to the directory containing the PHP executable
      (<filename>php.exe</filename> on Windows) and run
      <command>php -i</command>. If PHP has any problems running,
      then a suitable error message will be displayed which will
      give you a clue as to what needs to be done next. If you
      get a screen full of HTML codes (the output of the
      <function>phpinfo</function> function) then PHP is working,
      and your problem may be related to your server configuration
      which you should double check.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.undefinedsyms">
    <question>
     <para> 
      Some operating systems: I have installed PHP without errors,
      but when I try to start Apache I get undefined symbol errors:
      <programlisting role="shell">
[mybox:user /src/php5] root# apachectl configtest
 apachectl: /usr/local/apache/bin/httpd Undefined symbols:
  _compress
  _uncompress
      </programlisting>
     </para>
    </question>
    <answer>
     <para>
      This has actually nothing to do with PHP, but with the MySQL
      client libraries. Some need <option
      role="configure">--with-zlib</option>, others do not. This
      is also covered in the MySQL FAQ.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.cgierror">
    <question>
     <para>
      Windows: I have installed PHP, but when I try to access
      a PHP script file via my browser, I get the error:
      <screen>
<![CDATA[
cgi error:
 The specified CGI application misbehaved by not
 returning a complete set of HTTP headers.
 The headers it did return are:
]]>
      </screen>
     </para>
    </question>
    <answer>
     <para>
      This error message means that PHP failed to output anything
      at all. To get to see a sensible error message, from the
      command line, change to the directory containing the PHP
      executable (<filename>php.exe</filename> on Windows) and run
      <command>php -i</command>. If PHP has any problems running,
      then a suitable error message will be displayed which will
      give you a clue as to what needs to be done next. If you
      get a screen full of HTML codes (the output of the
      <function>phpinfo</function> function) then PHP is working.
     </para>
     <para>
      Once PHP is working at the command line, try accessing the
      script via the browser again. If it still fails then it
      could be one of the following:
     </para>
     <itemizedlist>
      <listitem>
       <simpara>
        File permissions on your PHP script,
        <filename>php.exe</filename>, <filename>php5ts.dll</filename>,
        &php.ini; or any PHP extensions you are trying to load are such
        that the anonymous internet user
        <literal>ISUR_&lt;machinename&gt;</literal> cannot access them.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        The script file does not exist (or possibly isn't where you
        think it is relative to your web root directory). Note that
        for IIS you can trap this error by ticking the 'check file
        exists' box when setting up the script mappings in the
        Internet Services Manager. If a script file does not exist
        then the server will return a 404 error instead. There is
        also the additional benefit that IIS will do any
        authentication required for you based on the NTLanMan
        permissions on your script file.
       </simpara>
      </listitem>
     </itemizedlist>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.phpandiis">
    <question>
     <para>
      Windows: I've followed all the instructions, but still can't
      get PHP and IIS to work together!
     </para>
    </question>
    <answer>
     <para>
      Make sure any user who needs to run a PHP script has the rights
      to run <filename>php.exe</filename>! IIS uses an anonymous user
      which is added at the time IIS is installed. This user needs
      rights to <filename>php.exe</filename>. Also, any authenticated
      user will also need rights to execute <filename>php.exe</filename>.
      And for IIS4 you need to tell it that PHP is a script engine.
      Also, you will want to read 
      <link linkend="faq.installation.forceredirect">this faq</link>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.forceredirect">
    <question>
     <para>
       When running PHP as CGI with IIS, PWS, OmniHTTPD or Xitami,
       I get the following error: <literal>Security Alert! PHP CGI 
       cannot be accessed directly.</literal>.
     </para>
    </question>
    <answer>
     <para>
      You must set the <link linkend="ini.cgi.force-redirect">
      cgi.force_redirect</link> directive to <literal>0</literal>.
      It defaults to <literal>1</literal> so be sure the directive
      isn't commented out (with a <literal>;</literal>).  Like
      all directives, this is set in &php.ini;
     </para>
     <para>
      Because the default is <literal>1</literal>, it's critical
      that you're 100% sure that the correct &php.ini; file is being 
      read.  Read <link linkend="faq.installation.findphpini">this faq</link>
      for details.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.findphpini">
    <question>
     <para>
      How do I know if my &php.ini; is being found and read?  It
      seems like it isn't as my changes aren't being implemented.
     </para>
    </question>
    <answer>
     <para>
      To be sure your &php.ini; is being read by PHP, make a call to
      <function>phpinfo</function>. Near the top, there will be a
      listing called <literal>Configuration File (php.ini)</literal>.
      This will tell you where PHP is looking for &php.ini; and
      whether or not it's being read.  If just a directory PATH exists,
      then it's not being read, and you should put your &php.ini;
      in that directory.  If &php.ini; is included within the PATH, 
      it is being read.
     </para>
     <para>
      If &php.ini; is being read and you're running PHP as a module,
      then be sure to restart your web server after making changes to
      &php.ini; 
     </para>
     <para>
      See also <function>php_ini_loaded_file</function>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.addtopath">
    <question>
     <para>
      How do I add my PHP directory to the <varname>PATH</varname>
      on Windows?
     </para>
    </question>
    <answer>
     <para>
      On Windows NT+ and Windows Server 2000+:
      <itemizedlist>
       <listitem><para>
        Go to Control Panel and open the System icon (Start -&gt; Settings
        -&gt; Control Panel -&gt; System, or just Start -&gt; Control Panel
        -&gt; System for Windows XP/2003+)
       </para></listitem>
       <listitem><para>
        Go to the Advanced tab
       </para></listitem>
       <listitem><para>
        Click on the 'Environment Variables' button
       </para></listitem>
       <listitem><para>
        Look into the 'System Variables' pane
       </para></listitem>
       <listitem><para>
        Find the Path entry (you may need to scroll to find it)
       </para></listitem>
       <listitem><para>
        Double click on the Path entry
       </para></listitem>
       <listitem><para>
        Enter your PHP directory at the end, including ';' before (e.g.
        <literal>;C:\php</literal>)
       </para></listitem>
       <listitem><para>
        Press OK
       </para></listitem>
      </itemizedlist>
     </para>
     <para>
      On Windows 98/Me you need to edit the <filename>autoexec.bat</filename>
      file:
      <itemizedlist>
       <listitem><para>
        Open the Notepad (Start -&gt; Run and enter notepad)
       </para></listitem>
       <listitem><para>
        Open the <filename>C:\autoexec.bat</filename> file
       </para></listitem>
       <listitem><para>
        Locate the line with PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;..... and add:
        <literal>;C:\php</literal> to the end of the line
       </para></listitem>
       <listitem><para>
        Save the file and restart your computer
       </para></listitem>
      </itemizedlist>
     </para>
     <note>
      <simpara>
       Be sure to reboot after following the steps above to ensure that the 
       <varname>PATH</varname> changes are applied.
      </simpara>
     </note>
     <para> 
      The PHP manual used to promote the copying of files into the Windows 
      system directory, this is because this directory  
      (<filename>C:\Windows</filename>, <filename>C:\WINNT</filename>, etc.)
      is by default in the systems PATH.  Copying files into the Windows 
      system directory has long since been deprecated and may cause problems.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.phprc">
    <question>
     <para>
      How do I make the &php.ini; file available to PHP on windows?
     </para>
    </question>
    <answer>
     <para>
      There are several ways of doing this. If you are using Apache, read
      their installation specific instructions (<link
       linkend="install.windows.apache1">Apache 1</link>, <link
       linkend="install.windows.apache2">Apache 2</link>), otherwise you must
      set the <varname>PHPRC</varname> environment variable:
     </para>
     <para>
      On Windows NT, 2000, XP and 2003:
      <itemizedlist>
       <listitem><para>
        Go to Control Panel and open the System icon (Start -&gt; Settings
        -&gt; Control Panel -&gt; System, or just Start -&gt; Control Panel
        -&gt; System for Windows XP/2003)
       </para></listitem>
       <listitem><para>
        Go to the Advanced tab
       </para></listitem>
       <listitem><para>
        Click on the 'Environment Variables' button
       </para></listitem>
       <listitem><para>
        Look into the 'System variables' pane
       </para></listitem>
       <listitem><para>
         Click on 'New' and enter 'PHPRC' as the variable name and the
         directory where &php.ini; is located as the variable value (e.g.
         <literal>C:\php</literal>)
       </para></listitem>
       <listitem><para>
        Press OK and restart your computer
       </para></listitem>
      </itemizedlist>
     </para>
     <para>
      On Windows 98/Me you need to edit the <filename>autoexec.bat</filename>
      file:
      <itemizedlist>
       <listitem><para>
        Open the Notepad (Start -&gt; Run and enter notepad)
       </para></listitem>
       <listitem><para>
        Open the <filename>C:\autoexec.bat</filename> file
       </para></listitem>
       <listitem><para>
        Add a new line to the end of the file: <literal>set
         PHPRC=C:\php</literal> (replace <literal>C:\php</literal> with the
        directory where &php.ini; is located). Please note that the path
        cannot contain spaces. For instance, if you have installed PHP in
        <filename>C:\Program Files\PHP</filename>, you would enter
        <filename>C:\PROGRA~1\PHP</filename> instead.
       </para></listitem>
       <listitem><para>
        Save the file and restart your computer
       </para></listitem>
      </itemizedlist>
     </para>      
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.apache.multiviews">
    <question>
     <para>
      Is it possible to use Apache content negotiation (MultiViews option)
      with PHP?
     </para>
    </question>
    <answer>
     <para>
      If links to PHP files include extension, everything works perfect. This
      FAQ is only for the case when links to PHP files don't include extension
      and you want to use content negotiation to choose PHP files from URL
      with no extension.
      In this case, replace the line <literal>AddType application/x-httpd-php
      .php</literal> with:
      <programlisting role="apache-conf">
<![CDATA[
AddHandler php5-script php
AddType text/html php
]]>
     </programlisting>
     This solution doesn't work for Apache 1 as PHP module doesn't catch
     <literal>php-script</literal>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.installation.requestmethods">
    <question>
     <para>
      Is PHP limited to process GET and POST request methods only?
     </para>
    </question>
    <answer>
     <para>
      No, it is possible to handle any request method, e.g. CONNECT. Proper
      response status can be sent with <function>header</function>.
      If only GET and POST methods should be handled, it can be achieved with
      this Apache configuration:
      <programlisting role="apache-conf">
<![CDATA[
<LimitExcept GET POST>
Deny from all
</LimitExcept>
]]>
     </programlisting>
     </para>
    </answer>
   </qandaentry>

  </qandaset>
 </chapter>

<!-- 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:"~/.phpdoc/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
-->