source: general/prog/php.xml@ d19fb65

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

  <!ENTITY php-download-http "http://www.php.net/distributions/php-&php-version;.tar.xz">
  <!--<!ENTITY php-download-ftp  "ftp://ftp.isu.edu.tw/pub/Unix/Web/PHP/distributions/php-&php-version;.tar.xz">-->
  <!ENTITY php-download-ftp  " ">
  <!ENTITY php-md5sum        "ce5964672e4ec0b66ff088a6bafde8c7">
  <!ENTITY php-size          "11 MB">
  <!ENTITY php-buildsize     "564 MB (with the tests). Documentation adds 106 MB">
  <!ENTITY php-time          "6.3 SBU (with the tests)">
]>

<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.  It is also useful as a
      general purpose scripting language.
    </para>

    &lfs78_checked;

    <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>
          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">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="apache"/> and
      <xref linkend="libxml2"/>
    </para>

    <bridgehead renderas="sect4">Optional System Utilities and Libraries</bridgehead>
    <para role="optional">
      <xref linkend="aspell"/>,
      <xref linkend="enchant"/>,
      <xref linkend="libxslt"/>,
      an <xref linkend="server-mail"/> (that provides a
      <command>sendmail</command> command),
      <xref linkend="pcre"/>,
      <xref linkend="pth"/>,
      <ulink url="http://dmalloc.com/">Dmalloc</ulink>,
      <ulink url="http://www.net-snmp.org/">Net-SNMP</ulink>,
      <ulink url="http://www.ossp.org/pkg/lib/mm/">OSSP mm</ulink>,
      <ulink url="http://re2c.org/">re2c</ulink>, and
      <ulink url="http://xmlrpc-epi.sourceforge.net/main.php?t=php_about">XMLRPC-EPI</ulink>
    </para>

    <bridgehead renderas="sect4">Optional Graphics Utilities and Libraries</bridgehead>
    <para role="optional">
      <xref linkend="freetype2"/>,
      <xref linkend="libexif"/>,
      <xref linkend="libjpeg"/>,
      <xref linkend="libpng"/>,
      <xref linkend="libtiff"/>,
      <xref linkend="x-window-system"/>,
      <ulink url="http://www.fastio.com/">ClibPDF</ulink>,
      <ulink url="http://www.adobe.com/devnet/acrobat/fdftoolkit.html">FDF Toolkit</ulink>,
      <ulink url="https://bitbucket.org/libgd/gd-libgd/downloads">GD</ulink>, and
      <ulink url="http://fossies.org/linux/misc/t1lib-5.1.2.tar.gz/">t1lib</ulink>
    </para>

    <bridgehead renderas="sect4">Optional Web Utilities</bridgehead>
    <para role="optional">
      <xref linkend="curl"/>,
      <xref linkend="html-tidy"/>,
      <ulink url="http://sourceforge.net/projects/caudium/">Caudium</ulink>,
      <ulink url="http://www.hyperwave.com/">Hyperwave</ulink>,
      <ulink url="http://www.mnogosearch.org/">mnoGoSearch</ulink>,
      <ulink url="http://www.roxen.com/products/webserver/">Roxen WebServer</ulink>, and
      <ulink url="https://wddxnet.codeplex.com/">WDDX</ulink>
    </para>

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

    <para>
      <application>PHP</application> also provides support for many
      commercial database tools such as <application>Oracle</application>,
      <application>SAP</application> and
      <application>ODBC Router</application>.
    </para>

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

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/php"/>
    </para>

  </sect2>

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

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

    <note>
      <para>
        <application>PHP</application> has many more
        <command>configure</command> options that will enable support for
        various 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. An example
        of a <command>configure</command> command that utilizes many of the
        most common dependencies can be found at <ulink
        url="&sources-anduin-http;/files/php_configure.txt"/>.
      </para>

      <para>
        If, for whatever reason, you don't have <xref linkend="libxml2"/>
        installed, you need to add <option>--disable-libxml</option> to the
        <command>configure</command> command in the instructions below. Note
        that this will prevent the <command>pear</command> command from being
        built.
      </para>
    </note>

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

<screen><userinput>sed -i "s|lsystemd-daemon|lsystemd|g" configure &amp;&amp;

./configure --prefix=/usr                \
            --sysconfdir=/etc            \
            --localstatedir=/var         \
            --datadir=/usr/share/php     \
            --mandir=/usr/share/man      \
            --enable-fpm                 \
            --with-fpm-user=apache       \
            --with-fpm-group=apache      \
            --with-fpm-systemd           \
            --with-config-file-path=/etc \
            --with-zlib                  \
            --enable-bcmath              \
            --with-bz2                   \
            --enable-calendar            \
            --enable-dba=shared          \
            --with-gdbm                  \
            --with-gmp                   \
            --enable-ftp                 \
            --with-gettext               \
            --enable-mbstring            \
            --with-readline              &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make test</command>. A few
      tests may fail, in which case you are asked whether you want to send
      the report to the PHP developpers. If you want to automate the test,
      you may prefix the command with <command>yes "n" | </command>.
    </para>

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

<!-- dev note: make INSTALL_ROOT=<DESTDIR> install -->

<screen role="root"><userinput>make install                                         &amp;&amp;
install -v -m644 php.ini-production /etc/php.ini     &amp;&amp;
mv -v /etc/php-fpm.conf{.default,}                   &amp;&amp;

install -v -m755 -d /usr/share/doc/php-&php-version; &amp;&amp;
install -v -m644    CODING_STANDARDS EXTENSIONS INSTALL NEWS README* UPGRADING* php.gif \
                    /usr/share/doc/php-&php-version; &amp;&amp;
ln -v -sfn          /usr/lib/php/doc/Archive_Tar/docs/Archive_Tar.txt \
                    /usr/share/doc/php-&php-version; &amp;&amp;
ln -v -sfn          /usr/lib/php/doc/Structures_Graph/docs \
                    /usr/share/doc/php-&php-version;</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 one large individual file, which is useful for using the
      search utility of your browser. If you downloaded either, or both, of the
      documentation files, issue the following commands as the
      <systemitem class='username'>root</systemitem> user to install them (note
      these instructions assume English docs, modify the tarball names below if
      necessary).
    </para>

    <para>
      For the <quote>Single HTML</quote> file:
    </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>tar -xvf ../php_manual_en.tar.gz \
    -C /usr/share/doc/php-&php-version; --no-same-owner</userinput></screen>

  </sect2>

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

      <para>
        <command>sed -i "s|lsystemd-daemon|lsystemd|g" configure</command>:
        This command fixes the detection of the systemd library.
      </para>

      <para>
        <parameter>--with-datadir=/usr/share/php</parameter>: This works
        around a bug in the build machinery, which installs some data to a
        wrong location.
      </para>

      <para>
        <parameter>--enable-fpm</parameter>: This parameter allows
        building the fastCGI Process Manager.
      </para>

      <para>
        <parameter>--with-fpm-systemd</parameter>: This parameter allows
        the FastCGI Process Manager to integrate with systemd.
      </para>

      <para>
        <parameter>--with-config-file-path=/etc</parameter>: This parameter
        makes <application>PHP</application> look for 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=shared</parameter>: This parameter enables
        support for database (dbm-style) abstraction layer functions.
      </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-readline</parameter>: This parameter
        enables command line <application>Readline</application> support.
      </para>

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

      <para>
        <option>--with-apxs2</option>: Instead of building the fastCGI process
        manager, it is possible to build an <application>apache</application>
        module.  This has some performance penalty for heavy loaded servers,
        but may be easier to set up. This switch is incompatible with the
        <parameter>--enable-fpm</parameter> and
        <parameter>--with-fpm-...</parameter> switches.
      </para>

      <para>
        <option>--with-mysqli=/usr/bin/mysql_config</option>: This option
        includes MySQLi support.
      </para>

      <para>
        <option>--with-mysql-sock=/run/mysqld/mysqld.sock</option>: Location of
        the MySQL unix socket pointer.
      </para>

      <para>
        <option>--with-pdo-mysql=/usr</option>: This option includes PDO: MySQL
        support.
      </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>,
        <filename>/etc/php-fpm.conf</filename>, and
        <filename>/etc/php-fpm.d/www.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>

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

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

    </sect3>

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

      <para>
       Without the file <filename>/etc/php-fpm.d/www.conf</filename>,
       the process manager does not start. However, it is the file
       <filename>/etc/php-fpm.d/www.conf.default</filename>, that is
       installed. To solve this, issue as the
       <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>cp -v /etc/php-fpm.d/www.conf.default /etc/php-fpm.d/www.conf</userinput></screen>

      <para>
        The file used as the default <filename>/etc/php.ini</filename>
        configuration file is recommended by the <application>PHP</application>
        development team. This file modifies the default behavior of
        <application>PHP</application>.  If no <filename>/etc/php.ini</filename>
        is used, all configuration settings fall to the defaults. You should
        review the comments in this file and ensure the changes are acceptable
        in your particular environment.
      </para>

      <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 fastCGI support in the <application>Apache</application>
        web server, two LoadModule directives must be added to the
        <filename>httpd.conf</filename> file. They are commented out, so just
        issue the following command as
        <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>sed -i -e '/proxy_module/s/^#//'      \
       -e '/proxy_fcgi_module/s/^#//' \
       /etc/httpd/httpd.conf</userinput></screen>

      <para>
        Those modules accept various <command>ProxyPass</command>
        directives. One possibility is (as the
        <systemitem class="username">root</systemitem> user):
      </para>

<screen role="root"><userinput>echo \
'ProxyPassMatch ^/(.*\.php)$ fcgi://127.0.0.1:9000/srv/www/$1' >> \
/etc/httpd/httpd.conf</userinput></screen>

      <para>
        Additionally, it may be useful to add an entry for
        <filename>index.php</filename> to the DirectoryIndex directive of the
        <filename>httpd.conf</filename> file. Lastly, adding a line to setup the
        <filename class='extension'>.phps</filename> extension to show
        highlighted <application>PHP</application> source may be
        desirable:
      </para>

<screen><literal>AddType application/x-httpd-php-source .phps</literal></screen>

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

    <sect3  id="php-init">
      <title>Systemd Units</title>

      <para>
        To start the <command>php-fpm</command> daemon at boot,
        install the systemd unit from the <xref linkend="bootscripts"/>
        package by running the following command as the
        <systemitem class="username">root</systemitem> user:
      </para>

      <indexterm zone="php php-init">
        <primary sortas="f-php-fpm">php-fpm</primary>
      </indexterm>

<screen role="root"><userinput>make install-php-fpm</userinput></screen>
    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>pear, peardev, pecl, phar (symlink), phar.phar, php,
        php-cgi, php-config, php-fpm, phpdbg, and phpize</seg>
        <seg>dba.{so,a} and opcache.{so,a} at
       /usr/lib/php/extensions/no-debug-non-zts-20151012</seg>
        <seg>/etc/php-fpm.d, /usr/{include,lib,share}/php and
        /usr/share/doc/php-&php-version;</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>

      <varlistentry id="php-fpm">
        <term><command>php-fpm</command></term>
        <listitem>
          <para>
            is the fastCGI process manager for PHP.
          </para>
          <indexterm zone="php php-fpm">
            <primary sortas="b-php-fpm">php-fpm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="phpdbg">
        <term><command>phpdbg</command></term>
        <listitem>
          <para>
            is the interactive PHP debugger.
          </para>
          <indexterm zone="php phpdbg">
            <primary sortas="b-phpdbg">phpdbg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>