pecl.xml

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

<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>
 &pecl.moving.to.pie;

 <sect1 xml:id="install.pecl.intro">
  <title>Introduction to PECL Installations</title>
  &pecl.moving.to.pie;
  <simpara>
   &link.pecl; is a repository of PHP extensions that are made available 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>/path/to/php/src/dir/</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
   <command>pear</command>
   command also applies to the
   <command>pecl</command>
   command.
  </simpara>
  <simpara>
   A shared extension must be built, installed, and loaded to be useful.
   The methods described below provide 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 the &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.anongit;">Anonymous Git Instructions</link>
   for details on the required tools and required versions.
  </simpara>
 </sect1>

 <sect1 xml:id="install.pecl.downloads">
  <title>Downloading PECL extensions</title>
  &pecl.moving.to.pie;
  <simpara>
   There are several options for downloading PECL extensions, such as:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     The <command>pecl install extname</command> 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 website 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>
     <command>pecl download extname</command>
    </simpara>
    <simpara>
     PECL extensions that have releases listed on the PECL website 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>git</acronym>
    </simpara>
    <simpara>
     Many PECL extensions reside on GitHub.
     <!-- TODO Expand -->
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>SVN</acronym>
    </simpara>
    <simpara>
     Some 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>
    <screen>
<![CDATA[
$ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname
]]>
    </screen>
   </listitem>
   <listitem>
    <simpara>
     Windows downloads
    </simpara>
    <simpara>
     The PHP project compiles and offers Windows DLLs for most PECL extensions
     on the package page.
    </simpara>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 xml:id="install.pecl.windows">
  <title>Installing a PHP extension on Windows</title>
  &pecl.moving.to.pie;
  <para>
   There are two ways to load a PHP extension on Windows: 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, it has to be available as a
   <filename>.dll</filename>
   file on the 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 the
   <link linkend="install.windows.building">building from source</link>
   documentation.
  </para>
  <para>
   To compile a standalone extension (aka a DLL file), please refer to the
   <link linkend="install.windows.building">building from source</link>
   documentation.
   If the DLL file is available neither with the PHP distribution nor in PECL,
   it may be necessary to compile it before the extension can be used.
  </para>
  <sect2 xml:id="install.pecl.windows.find">
   <title>Where to find an extension?</title>
   <para>
    PHP extensions are usually called <filename>php_*.dll</filename> (where the
    star represents the name of the extension), and they are located under the
    <filename>PHP\ext</filename>
    folder.
   </para>
   <para>
    PHP ships with the extensions most useful to the majority of developers.
    They are called <emphasis>bundled</emphasis> extensions.
   </para>
   <para>
    However, if the bundled extensions do not provide the needed functionality,
    one extension that does may still be found in &link.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 developing PHP extensions.
   </para>
   <para>
    If an extension has been developed for particular uses, it may be hosted on
    PECL so that others with the same needs can benefit from it.
    A nice side effect is that it's a good chance to receive feedback,
    (hopefully) thanks, bug reports and even fixes/patches.
    Before submitting an extension for hosting on PECL, please read
    <link xlink:href="&url.pecl.submit;">PECL submit</link>.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.which">
   <title>Which extension to download?</title>
   <para>
    <emphasis>
     Many times, there will be several versions of each DLL available:
    </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>
    Keep in mind that the extension settings should match all the settings of
    the PHP executable being used.
    The following PHP script will tell <emphasis>all</emphasis> about the 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
    the &php.ini; configuration file.
    Please note that many extensions are already present in the &php.ini; and
    that the semicolon only needs to be removed to activate them.
   </para>
   <para>
    Note that, as of PHP 7.2.0, the extension name may be used
    instead of the extension's file name.
    As this is OS-independent and easier, especially for newcomers, it becomes
    the recommended way of specifying extensions to load.
    File names remain supported for compatibility with prior versions.
   </para>
   <screen>
<![CDATA[
;extension=php_extname.dll
]]>
   </screen>
   <screen>
<![CDATA[
extension=php_extname.dll
]]>
   </screen>
   <screen>
<![CDATA[
; As of PHP 7.2.0, prefer:
extension=extname
zend_extension=another_extension
]]>
   </screen>
   <para>
    However, some web servers are confusing because they do not use
    the &php.ini; located alongside the PHP executable.
    To find out where the actual &php.ini; resides, look for its path
    in <function>phpinfo</function>:
   </para>
   <screen>
<![CDATA[
Configuration File (php.ini) Path  C:\WINDOWS
]]>
   </screen>
   <screen>
<![CDATA[
Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini
]]>
   </screen>
   <para>
    After activating an extension, save &php.ini;, 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>,
    the logs should be checked to learn where the problem comes from.
   </para>
   <para>
    If PHP is being used from the command line (CLI), the extension loading
    error can be read directly on the screen.
   </para>
   <para>
    If PHP is being used with a web server, the location and format of the logs
    vary depending on the software.
    Please read the web server documentation to locate the logs, as it has
    nothing to do with PHP itself.
   </para>
   <para>
    Common problems are the location of the DLL and the DLLs it depends on, the
    value of the "<link linkend="ini.extension-dir">extension_dir</link>"
    setting inside &php.ini; and compile-time setting mismatches.
   </para>
   <para>
    If the problem lies in a compile-time setting mismatch, probably the DLL
    downloaded is not the right one.
    Try downloading the extension again with the proper 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>
  &pecl.moving.to.pie;
  <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>
  <screen>
<![CDATA[
$ pecl install extname
]]>
  </screen>
  <simpara>
   This will download the source for <emphasis>extname</emphasis>,
   compile, and install <filename>extname.so</filename> into the
   <link linkend="ini.extension-dir">extension_dir</link>.
   <filename>extname.so</filename>
   may then be loaded via &php.ini;.
  </simpara>
  <simpara>
   By default, the <command>pecl</command> 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,
   a <literal>beta</literal> package may be installed using the following
   command:
  </simpara>
  <screen>
<![CDATA[
$ pecl install extname-beta
]]>
  </screen>
  <para>
   A specific version may also be installed using this variant:
  </para>
  <screen>
<![CDATA[
$ pecl install extname-0.1
]]>
  </screen>
  <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>
  &pecl.moving.to.pie;
  <simpara>
   Sometimes, using the <command>pecl</command> installer is not an option.
   This could be because there is a firewall or because the extension being
   installed is unavailable as a PECL-compatible package, such as unreleased
   extensions from git.
   If such an extension needs to be built, the lower-level build tools can be
   used to perform the build manually.
  </simpara>
  <simpara>
   The <command>phpize</command> 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>.
   The &php.ini; will need to be adjusted, and an
   <literal>extension=extname.so</literal>
   line will need to be added before the extension can be used.
  </simpara>
  <simpara>
   If the system is missing the <command>phpize</command> command, and
   precompiled packages (like RPM's) are used, be sure to install also the
   appropriate development version of the PHP package as they often include the
   <command>phpize</command>
   command along with the proper 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.php-config">
  <title>
   <command>php-config</command>
  </title>
  &pecl.moving.to.pie;
  <para>
   <command>php-config</command>
   is a simple shell script for obtaining information about the installed PHP
   configuration.
  </para>
  
  <para>
   When the extensions are being compiled, if multiple PHP versions are
   installed, the installation for which to build can be specified by using the
   <option role="configure">--with-php-config</option>
   option during configuration, setting the path of the respective
   <command>php-config</command>
   script.
  </para>
  
  <para>
   The list of command line options provided by the
   <command>php-config</command>
   script can be queried anytime by running
   <command>php-config</command>
   with the <option>-h</option> switch:
   <screen>
<![CDATA[
Usage: /usr/local/bin/php-config [OPTION]
Options:
  --prefix            [...]
  --includes          [...]
  --ldflags           [...]
  --libs              [...]
  --extension-dir     [...]
  --include-dir       [...]
  --php-binary        [...]
  --php-sapis         [...]
  --configure-options [...]
  --version           [...]
  --vernum            [...]
]]>
   </screen>
  </para>
  
  <para>
   <table>
    <title>Command line options</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Option</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>--prefix</entry>
       <entry>Directory prefix where PHP is installed, e.g. /usr/local</entry>
      </row>
      <row>
       <entry>--includes</entry>
       <entry>
        List of <literal>-I</literal> options with all include files
       </entry>
      </row>
      <row>
       <entry>--ldflags</entry>
       <entry>
        <literal>LD</literal>
        flags which PHP was compiled with
       </entry>
      </row>
      <row>
       <entry>--libs</entry>
       <entry>Extra libraries which PHP was compiled with</entry>
      </row>
      <row>
       <entry>--extension-dir</entry>
       <entry>Directory where extensions are searched by default</entry>
      </row>
      <row>
       <entry>--include-dir</entry>
       <entry>
        Directory prefix where header files are installed by default
       </entry>
      </row>
      <row>
       <entry>--php-binary</entry>
       <entry>Full path to php CLI or CGI binary</entry>
      </row>
      <row>
       <entry>--php-sapis</entry>
       <entry>Show all SAPI modules available</entry>
      </row>
      <row>
       <entry>--configure-options</entry>
       <entry>
        Configure options to recreate configuration of current PHP installation
       </entry>
      </row>
      <row>
       <entry>--version</entry>
       <entry>PHP version</entry>
      </row>
      <row>
       <entry>--vernum</entry>
       <entry>PHP version as integer</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </sect1>

 <sect1 xml:id="install.pecl.static">
  <title>Compiling PECL extensions statically into PHP</title>
  &pecl.moving.to.pie;
  <simpara>
   It may be necessary to build a PECL extension statically into the PHP binary.
   To do this, the extension source will need to be placed under the
   <filename>/path/to/php/src/dir/ext/</filename>
   directory, and the PHP build system will be required to regenerate its
   configure script.
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd /path/to/php/src/dir/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>
  <screen>
<![CDATA[
/path/to/php/src/dir/ext/extname
]]>
  </screen>
  <simpara>
   From here, PHP needs to be forced to rebuild the configure script, and then
   it can be built as normal:
  </simpara>
  <screen>
<![CDATA[
$ cd /path/to/php/src/dir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
]]>
  </screen>
  <note>
   <simpara>
    To run the <command>buildconf</command> script, the
    <command>autoconf</command>
    <literal>2.68</literal>
    and
    <command>automake</command>
    <literal>1.4+</literal>
    will be needed.
    Newer versions of <command>autoconf</command> may work but are not
    supported.
   </simpara>
  </note>
  <simpara>
   Whether
   <option role="configure">--enable-extname</option>
   or
   <option role="configure">--with-extname</option>
   is used depends on the extension.
   Typically, an extension that does not require external libraries uses
   <option role="configure">--enable</option>.
   To be sure, run the following after <command>buildconf</command>:
  </simpara>
  <screen>
<![CDATA[
$ ./configure --help | grep extname
]]>
  </screen>
 </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
-->