<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->

<chapter xml:id="install.pecl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Installation of PECL extensions</title>

 <sect1 xml:id="install.pecl.intro">
  <title>Introduction to PECL Installations</title>
  <simpara>
   <link xlink:href="&url.pecl;">PECL</link> is a repository of PHP extensions that
   are made available to you via the <link xlink:href="&url.php.pear;">PEAR</link>
   packaging system.  This section of the manual is intended to demonstrate
   how to obtain and install PECL extensions.
  </simpara>
  <simpara>
   These instructions assume <literal>/your/phpsrcdir/</literal> is the path
   to the PHP source distribution, and that <literal>extname</literal> is the name of the
   PECL extension.  Adjust accordingly.  These instructions also assume a 
   familiarity with the <link xlink:href="&url.php.pear.cli;">pear command</link>.
   The information in the PEAR manual for the <literal>pear</literal> command also
   applies to the <literal>pecl</literal> command.
  </simpara>
  <simpara>
   To be useful, a shared extension must be built, installed, and loaded.  The
   methods described below provide you with various instructions on how to
   build and install the extensions, but they do not automatically load them.
   Extensions can be loaded by adding an <link
   linkend="ini.extension">extension</link> directive.  To this &php.ini;
   file, or through the use of the <function>dl</function> function.
  </simpara>
  <simpara>
   When building PHP modules, it's important to have known-good versions 
   of the required tools (autoconf, automake, libtool, etc.) See the 
   <link xlink:href="&url.php.anonsvn;">Anonymous SVN Instructions</link> for 
   details on the required tools, and required versions.
  </simpara>
 </sect1>

 <sect1 xml:id="install.pecl.downloads">
  <title>Downloading PECL extensions</title>
  <simpara>
   There are several options for downloading PECL extensions, such as:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     The <literal>pecl install extname</literal> command downloads the
     extensions code automatically, so in this case there is no need
     for a separate download.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link xlink:href="&url.pecl;">&url.pecl;</link>
    </simpara>
    <simpara>
     The PECL web site contains information about the different extensions
     that are offered by the PHP Development Team.  The information available
     here includes: ChangeLog, release notes, requirements and other similar
     details.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <literal>pecl download extname</literal>
    </simpara>
    <simpara>
     PECL extensions that have releases listed on the PECL web site are
     available for download and installation using the <link
     xlink:href="&url.php.pear.cli;">pecl command</link>.
     Specific revisions may also be specified.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>SVN</acronym>
    </simpara>
    <simpara>
     Most PECL extensions also reside in <acronym>SVN</acronym>.  A web-based view may
     be seen at <link xlink:href="&url.php.svn;pecl/">&url.php.svn;pecl/</link>.  
     To download straight from <acronym>SVN</acronym>, the following 
     sequence of commands may be used:
    </simpara>
    <para>
     <screen>
$ svn checkout http://svn.php.net/repository/pecl/extname/trunk extname
     </screen>
    </para>
   </listitem>
   <listitem>
    <simpara>
     Windows downloads
    </simpara>
    <simpara>
     At this time the PHP project does not compile Windows binaries for
     PECL extensions. However, to compile PHP under Windows see the
     chapter titled
     <link linkend="install.windows.building">building PHP for Windows</link>.
    </simpara>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 xml:id="install.pecl.windows">
  <title>Installing a PHP extension on Windows</title>
  <para>
   On Windows, you have two ways to load a PHP extension: either compile it into PHP, or 
   load the DLL. Loading a pre-compiled extension is the easiest and preferred way.
  </para>
  <para>
   To load an extension, you need to have it available as a ".dll" file on your system. 
   All the extensions are automatically and periodically compiled by the PHP Group 
   (see next section for the download).
  </para>
  <para>
   To compile an extension into PHP, please refer to <link linkend="install.windows.building">
   building from source</link> documentation.
  </para>
  <para>
   To compile a standalone extension (aka a DLL file), please refer to <link linkend="install.windows.building">
   building from source</link> documentation. If the DLL file is available neither with your 
   PHP distribution nor in PECL, you may have to compile it before you can start using the 
   extension.
  </para>

  <sect2 xml:id="install.pecl.windows.find">
   <title>Where to find an extension?</title>
   <para>
    PHP extensions are usually called "php_*.dll" (where the star represents the name of 
    the extension) and   they are located under the "PHP\ext" ("PHP\extensions" in PHP4) 
    folder.
   </para>
   <para>
    PHP ships with the extensions most useful to the majority of developers. They are 
    called "core" extensions.
   </para>
   <para>
    However, if you need functionality not provided by any core extension, you may still be 
    able to find one in PECL. The PHP Extension Community Library (PECL) is a repository for 
    PHP Extensions, providing a directory of all known extensions and hosting facilities for 
    downloading and development of PHP extensions.
   </para>
   <para>
    If you have developed an extension for your own uses, you might want to think about hosting 
    it on PECL so that others with the same needs can benefit from your time. A nice side effect 
    is that you give them a good chance to give you feedback, (hopefully) thanks, bug reports 
    and even fixes/patches. Before you submit your extension for hosting on PECL, please read 
    &url.pecl.submit;.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.which">
   <title>Which extension to download?</title>
   <para>
    <emphasis>Many times, you will find several versions of each DLL:</emphasis>
    <itemizedlist>
     <listitem>
      <simpara>
       Different version numbers (at least the first two numbers should match)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Different thread safety settings
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Different processor architecture (x86, x64, ...)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Different debugging settings
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>etc.</literal>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    You should keep in mind that your extension settings should match all the 
    settings of the PHP executable you are using. The following PHP script will 
    tell you <emphasis>all</emphasis> about your PHP settings:
   </para>
   <para>
    <example>
     <title><function>phpinfo</function> call</title>
     <programlisting role="php">
<![CDATA[
<?php
phpinfo();
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Or from the command line, run:
    <screen>
<![CDATA[
drive:\\path\to\php\executable\php.exe -i
]]>
    </screen>
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.loading">
   <title>Loading an extension</title>
   <para>
    The most common way to load a PHP extension is to include it in your <filename>php.ini</filename> 
    configuration file. Please note that many extensions are already present in your 
    <filename>php.ini</filename> and that you only need to remove the semicolon to activate them.
    <screen>
<![CDATA[
;extension=php_extname.dll
]]>
    </screen>
    <screen>
<![CDATA[
extension=php_extname.dll
]]>
    </screen>
   </para>
   <para>
    However, some web servers are confusing because they do not use the <filename>php.ini</filename> located alongside 
    your PHP executable. To find out where your actual <filename>php.ini</filename> resides, look 
    for its path in <function>phpinfo</function>:
    <screen>
<![CDATA[
Configuration File (php.ini) Path  C:\WINDOWS
]]>
    </screen>
    <screen>
<![CDATA[
Loaded Configuration File   C:\Program Files\PHP\5.2\php.ini
]]>
    </screen>
   </para>
   <para>
    After activating an extension, save <filename>php.ini</filename>, restart the web server and check 
    <function>phpinfo</function> again. The new extension should now have its own section.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.problemsolving">
   <title>Resolving problems</title>
   <para>
    If the extension does not appear in <function>phpinfo</function>, you should check your logs to 
    learn where the problem comes from.
   </para>
   <para>
    If you are using PHP from the command line (CLI), the extension loading error can be read 
    directly on screen.
   </para>
   <para>
    If you are using PHP with a web server, the location and format of the logs vary depending on 
    your software. Please read your web server documentation to locate the logs, as it does not 
    have anything to do with PHP itself.
   </para>
   <para>
    Common problems are the location of the DLL, the value of the "<link linkend="ini.extension-dir">
    extension_dir</link>" setting inside <filename>php.ini</filename> and compile-time setting mismatches.
   </para>
   <para>
    If the problem lies in a compile-time setting mismatch, you probably didn't download the right DLL. 
    Try downloading again the extension with the right settings. Again, <function>phpinfo</function> 
    can be of great help.
   </para>
  </sect2>

 </sect1>
 
 <sect1 xml:id="install.pecl.pear">
  <title>Compiling shared PECL extensions with the pecl command</title>
  <simpara>
   PECL makes it easy to create shared PHP extensions. Using the 
   <link xlink:href="&url.php.pear.cli;">pecl command</link>, do the following:
  </simpara>
  <para>
   <screen>
$ pecl install extname
   </screen>
  </para>
  <simpara>
   This will download the source for <emphasis>extname</emphasis>, 
   compile, and install <filename>extname.so</filename> into your <link
   linkend="ini.extension-dir">extension_dir</link>.  
   <filename>extname.so</filename> may then be loaded via &php.ini;
  </simpara>
  <simpara>
   By default, the <literal>pecl</literal> command will not install
   packages that are marked with the <literal>alpha</literal> or
   <literal>beta</literal> state.  If no <literal>stable</literal> packages
   are available, you may install a <literal>beta</literal> package using the
   following command:
  </simpara>
  <para>
   <screen>
$ pecl install extname-beta
   </screen>
  </para>
  <para>
   You may also install a specific version using this variant:
  </para>
  <para>
   <screen>
$ pecl install extname-0.1
   </screen>
  </para>
  <note>
   <para>
    After enabling the extension in &php.ini;, restarting the web service is
    required for the changes to be picked up.
   </para>
  </note>
 </sect1>

 <sect1 xml:id="install.pecl.phpize">
  <title>Compiling shared PECL extensions with phpize</title>
  <simpara>
   Sometimes, using the <literal>pecl</literal> installer is not an option.
   This could be because you're behind a firewall, or it could be because the
   extension you want to install is not available as a PECL compatible
   package, such as unreleased extensions from SVN.  If you need to build such
   an extension, you can use the lower-level build tools to perform the build
   manually.
  </simpara>
  <simpara>
   The <literal>phpize</literal> command is used to prepare the build
   environment for a PHP extension.  In the following sample, the sources for
   an extension are in a directory named <filename>extname</filename>:
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd extname
$ phpize
$ ./configure
$ make
# make install
]]>
   </screen>
  </para>
  <simpara>
   A successful install will have created <filename>extname.so</filename> and put it 
   into the PHP 
   <link linkend="ini.extension-dir">extensions directory</link>.  You'll need
   to and adjust &php.ini; and add an <literal>extension=extname.so</literal>
   line before you can use the extension.
  </simpara>
  <simpara>
   If the system is missing the <literal>phpize</literal> command, and precompiled
   packages (like RPM's) are used, be sure to also install the appropriate 
   devel version of the PHP package as they often include the 
   <literal>phpize</literal> command along with the appropriate header files to 
   build PHP and its extensions.
  </simpara>
  <simpara>
   Execute <command>phpize --help</command> to display additional usage information.
  </simpara>
 </sect1>

 <sect1 xml:id="install.pecl.static">
  <title>Compiling PECL extensions statically into PHP</title>
  <simpara>
   You might find that you need to build a PECL extension statically into your
   PHP binary.  To do this, you'll need to place the extension source under
   the <filename>php-src/ext/</filename> directory and tell the PHP build
   system to regenerate its configure script.
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd /your/phpsrcdir/ext
$ pecl download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname
]]>
   </screen>
  </para>
  <simpara>
   This will result in the following directory:
  </simpara>
  <para>
   <screen>
    /your/phpsrcdir/ext/extname
   </screen>
  </para>
  <simpara>
   From here, force PHP to rebuild the configure script, and then build PHP as normal:
  </simpara>
  <para>
   <screen>
$ cd /your/phpsrcdir 
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
   </screen>
  </para>
  <note>
   <simpara>
    To run the 'buildconf' script you need autoconf 2.13 and automake 1.4+
    (newer versions of autoconf may work, but are not supported).
   </simpara>
  </note>
  <simpara>
   Whether <literal>--enable-extname</literal> or <literal>--with-extname
   </literal> is used depends on the extension.  Typically an extension that 
   does not require external libraries uses <literal>--enable</literal>.  To be
   sure, run the following after buildconf:
  </simpara>
  <para>
   <screen>
$ ./configure --help | grep extname
   </screen>
  </para>
 </sect1>
</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
-->