source: general/prog/php.xml@ c35d927

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY php-download-http "http://us2.php.net/distributions/php-&php-version;.tar.bz2">
  <!ENTITY php-download-ftp  "ftp://ftp.isu.edu.tw/pub/Unix/Web/PHP/distributions/php-&php-version;.tar.bz2">
  <!ENTITY php-md5sum        "b5d4ca75bbb11ee5b830fa67213d9f7f">
  <!ENTITY php-size          "4.7 MB">
  <!ENTITY php-buildsize     "138 MB">
  <!ENTITY php-time          "1.9 SBU">
]>

<sect1 id="php" xreflabel="PHP-&php-version;">
  <?dbhtml filename="php.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>PHP-&php-version;</title>

  <indexterm zone="php">
    <primary sortas="a-PHP">PHP</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to PHP</title>

    <para><application>PHP</application> is the PHP Hypertext Preprocessor.
    Primarily used in dynamic web sites, it allows for programming code to be
    directly embedded into the HTML markup.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&php-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&php-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &php-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &php-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &php-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &php-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Required patch for Berkeley DB: <ulink
        url="&patch-root;/php-&php-version;-db43-1.patch"/></para>
      </listitem>
      <listitem>
        <para>Pre-built documentation (optional): <ulink
        url="http://www.php.net/download-docs.php"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">PHP Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para><xref linkend="apache"/></para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para><xref linkend="libxml2"/></para>

    <bridgehead renderas="sect4">Optional System Utilities and Libraries</bridgehead>
    <para><xref linkend="libxslt"/>,
    <xref linkend="gamin"/>,
    <xref linkend="gmp"/>,
    <xref linkend="pcre"/>,
    <xref linkend="aspell"/>,
    <xref linkend="pkgconfig"/>,
    <xref linkend="expat"/> (deprecated alternative to <xref linkend="libxml2"/>),
    <ulink url="http://www.ossp.org/pkg/lib/mm/">OSSP mm</ulink>,
    <ulink url="http://www.net-snmp.org/">Net-SNMP</ulink>,
    <ulink url="http://dmalloc.com/">Dmalloc</ulink>,
    <ulink url="http://www.gnu.org/software/recode/">recode</ulink> and
    an <ulink url="../server/mail.html">MTA</ulink></para>

    <bridgehead renderas="sect4">Optional Graphics Utilities and Libraries</bridgehead>
    <para><xref linkend="libjpeg"/>,
    <xref linkend="libtiff"/>,
    <xref linkend="libpng"/>,
    <xref linkend="freetype2"/>,
    X (<xref linkend="xorg"/> or <xref linkend="xfree86"/>),
    <ulink url="http://www.fastio.com/">ClibPDF</ulink>,
    <ulink url="http://www.boutell.com/gd/">GD</ulink>,
    <ulink url="http://gd.tuwien.ac.at/visual/ibiblio/libs/graphics/t1lib-5.1.0.tar.gz">
    t1lib</ulink> and
    <ulink url="http://partners.adobe.com/asn/acrobat/forms.jsp">FDF Toolkit</ulink></para>

    <bridgehead renderas="sect4">Optional Web Utilities</bridgehead>
    <para><xref linkend="curl"/>,
    <xref linkend="html-tidy"/>,
    <ulink url="http://www.mnogosearch.org/">mnoGoSearch</ulink>,
    <ulink url="http://www.hyperwave.com/">Hyperwave</ulink>,
    <ulink url="http://caudium.net/">Caudium</ulink> and
    <ulink url="http://www.openwddx.org/">WDDX</ulink></para>

    <bridgehead renderas="sect4">Optional Data Management Utilities and Libraries</bridgehead>
    <para><xref linkend="openldap"/>,
    <xref linkend="gdbm"/>,
    <xref linkend="db"/>,
    <xref linkend="mysql"/>,
    <xref linkend="postgresql"/>,
    <xref linkend="unixodbc"/>,
    <ulink url="http://qdbm.sourceforge.net/">QDBM</ulink>,
    <ulink url="http://cr.yp.to/cdb.html">cdb</ulink>,
    <ulink url="http://www.sqlite.org/">SQLite</ulink>,
    <ulink url="http://www.hughes.com.au/products/msql/">Mini SQL</ulink>,
    <ulink url="http://www.empress.com/">Empress</ulink>,
    <ulink url="http://www.birdstep.com/">Birdstep</ulink>,
    <ulink url="http://www.dbmaker.com/">DBMaker</ulink>,
    <ulink url="http://www.softwareag.com/">Adabas</ulink>,
    <ulink url="http://www.frontbase.com/">FrontBase</ulink> and
    <ulink url="http://www.mainstreetsoftworks.com/">Monetra</ulink></para>

    <bridgehead renderas="sect4">Optional Security/Encryption Utilities and Libraries</bridgehead>
    <para><xref linkend="openssl"/>,
    <xref linkend="cyrus-sasl"/>,
    <xref linkend="mitkrb"/> or <xref linkend="heimdal"/>,
    <ulink url="http://mcrypt.sourceforge.net/">libmcrypt</ulink> and
    <ulink url="http://mhash.sourceforge.net/">mhash</ulink></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of PHP</title>

    <note>
      <para>You can use <application>PHP</application>
      for server-side scripting, command line scripting or client-side
      GUI applications. The book provides instructions for
      setting up <application>PHP</application> for
      server-side scripting as it is the most common form.</para>
    </note>

    <para>If you have <application>Berkeley DB</application> installed and
    wish to utilize it, apply the following patch:</para>

<screen><userinput>patch -Np1 -i ../php-&php-version;-db43-1.patch</userinput></screen>

    <note>
      <para><application>PHP</application> has many more
      <command>configure</command> options that will enable support for certain
      things. You can use <command>./configure --help</command> to see a full
      list of the available options. Also, use of the
      <ulink url="http://www.php.net/">PHP web site</ulink>
      is highly recommended, as their online docs are very good.</para>
    </note>

    <para>Remove the <parameter>--disable-libxml</parameter> switch if you
    have <xref linkend="libxml2"/> installed otherwise
    <command>pear</command> will not be built.</para>

    <para>Install <application>PHP</application> by
    running the following commands:</para>

<screen><userinput>./configure --prefix=/usr \
            --sysconfdir=/etc \
            --with-apxs2 \
            --with-config-file-path=/etc \
            --with-zlib \
            --enable-bcmath \
            --with-bz2 \
            --enable-calendar \
            --enable-dba \
            --enable-exif \
            --enable-ftp \
            --with-gettext \
            --enable-mbstring \
            --with-ncurses \
            --with-readline \
            --disable-libxml &amp;&amp;
make</userinput></screen>

    <para>To test the results, issue: <command>make test</command>. Note that
    many of the tests are known to fail.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
cp -v php.ini-recommended /etc/php.ini</userinput></screen>

    <para>The pre-built HTML documentation is packaged in two forms: a tarball
    containing many individual files, useful for quick loading into your
    browser, and a tarball of one large file, which is useful for using the
    search utility of your browser. If you downloaded any of the documentation,
    the instructions below can be issued by the
    <systemitem class='username'>root</systemitem> user to install it (note
    these instructions assume English docs, modify the tarball names below if
    necessary).</para>

    <para>For the <quote>Single HTML</quote> tarball:</para>

<screen role="root"><userinput>install -v -m644 ../php_manual_en.html.gz \
    /usr/share/doc/php-&php-version; &amp;&amp;
gunzip -v /usr/share/doc/php-&php-version;/php_manual_en.html.gz</userinput></screen>

    <para>For the <quote>Many HTML files</quote> tarball:</para>

<screen role="root"><userinput>install -v -m755 -d /usr/share/doc/php-&php-version; &amp;&amp;
tar -xvf ../php_manual_en.tar.gz -C /usr/share/doc/php-&php-version; &amp;&amp;
chown -v -R root:root /usr/share/doc/php-&php-version;/html</userinput></screen>

  </sect2>

  <sect2 role="commands">
      <title>Command Explanations</title>

      <para><parameter>--with-apxs2</parameter>: This parameter
      builds the Apache HTTPD 2.0 module.</para>

      <para><parameter>--with-config-file-path=/etc</parameter>: This parameter
      puts the <filename>php.ini</filename> configuration file in <filename
      class='directory'>/etc</filename>.</para>

      <para><parameter>--with-zlib</parameter>: This parameter adds 
      support for <application>Zlib</application> compression.</para>

      <para><parameter>--enable-bcmath</parameter>: Enables
      <command>bc</command> style precision math functions.</para>
  
      <para><parameter>--with-bz2</parameter>: Adds support for
      <application>Bzip2</application> compression functions.</para>

      <para><parameter>--enable-calendar</parameter>: This parameter
      provides support for calendar conversion.</para>

      <para><parameter>--enable-dba</parameter>: This parameter enables
      support for database (dbm-style) abstraction layer functions.</para>

      <para><parameter>--enable-exif</parameter>: Enables functions
      to access metadata from images.</para>

      <para><parameter>--enable-ftp</parameter>: This parameter
      enables FTP functions.</para>

      <para><parameter>--with-gettext</parameter>: Enables functions
      that use <application>Gettext</application> text translation.</para>

      <para><parameter>--enable-mbstring</parameter>: This parameter
      enables multibyte string support.</para>

      <para><parameter>--with-ncurses</parameter>: Provides ncurses
      terminal independent cursor handling.</para>

      <para><parameter>--with-readline</parameter>: This parameter
      enables command line <application>Readline</application> support.</para>

      <para><parameter>--disable-libxml</parameter>: This parameter
      allows building PHP without <application>Libxml2</application>
      installed.</para>

  </sect2>
                    
  <sect2 role="configuration">
    <title>Configuring PHP</title>

    <sect3 id="php-config">
      <title>Config Files</title>

      <para><filename>/etc/php.ini</filename>,
      <filename>/etc/pear.conf</filename></para>

      <indexterm zone="php php-config">
        <primary sortas="e-etc-php.ini">/etc/php.ini</primary>
      </indexterm>

      <indexterm zone="php php-config">
        <primary sortas="e-etc-pear.conf">/etc/pear.conf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>You may have noticed the following from the output of the
      <command>make install</command> command:</para>

<screen><computeroutput>You may want to add: /usr/lib/php to your php.ini include_path</computeroutput></screen>

      <para>If desired, add the entry using the following command as the
      <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>sed -i 's@php/includes"@&amp;\ninclude_path = ".:/usr/lib/php"@' \
    /etc/php.ini</userinput></screen>

      <para>To enable PHP support in the <application>Apache</application>
      web server, a new LoadModule (which should be handled automatically by the
      <command>make install</command> command) and AddType directives
      must be added to the <filename>httpd.conf</filename> file:</para>

<screen><literal>LoadModule php5_module lib/apache/libphp5.so
AddType application/x-httpd-php .php</literal></screen>

      <para>Also, it can be useful to add an entry for
      <filename>index.php</filename> to the DirectoryIndex directive of the
      <filename>httpd.conf</filename> file.</para>

      <para>You'll need to restart the <application>Apache</application> web server
      after making any modifications to the <filename>httpd.conf</filename>
      file.</para>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>pear, php, php-config, phpextdist, and phpize</seg>
        <seg>libphp5.so</seg>
        <seg>/usr/include/php and /usr/lib/php</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="php-prog">
        <term><command>php</command></term>
        <listitem>
          <para>is a command line interface that enables you to parse and
          execute PHP code.</para>
          <indexterm zone="php php-prog">
            <primary sortas="b-php">php</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pear">
        <term><command>pear</command></term>
        <listitem>
          <para>is the PHP Extension and Application
          Repository (PEAR) package manager.</para>
          <indexterm zone="php pear">
            <primary sortas="b-pear">pear</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>