mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
2221e0e7e0
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@350464 c90b9560-bf6c-de11-be94-00142212c4b1
551 lines
18 KiB
XML
551 lines
18 KiB
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>
|
|
|
|
<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 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>
|
|
<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>
|
|
The PHP project compiles and offers Windows DLLs for most
|
|
PECL extensions on the respective package page.
|
|
</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.legacy.building">
|
|
building from source</link> documentation.
|
|
</para>
|
|
<para>
|
|
To compile a standalone extension (aka a DLL file), please refer to <link linkend="install.windows.legacy.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" 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 <link xlink:href="&url.pecl;">PECL</link>. 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
|
|
<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, 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.
|
|
</para>
|
|
<para>
|
|
Note that, on PHP version 7.2.0 and up, 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[
|
|
; On PHP version 7.2 and up, prefer :
|
|
extension=extname
|
|
zend_extension=another_extension
|
|
]]>
|
|
</screen>
|
|
<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>:
|
|
</para>
|
|
<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>
|
|
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.php-config">
|
|
<title>php-config</title>
|
|
|
|
<para>
|
|
php-config is a simple shell script for obtaining information about the
|
|
installed PHP configuration.
|
|
</para>
|
|
|
|
<para>
|
|
When compiling extensions, if you have multiple PHP versions installed, you
|
|
may specify for which installation you'd like to build by using the
|
|
<literal>--with-php-config</literal> option during configuration, specifying
|
|
the path of the respective php-config script.
|
|
</para>
|
|
|
|
<para>
|
|
The list of command line options provided by the php-config script can be queried
|
|
anytime by running php-config 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 -I options with all include files</entry>
|
|
</row>
|
|
<row>
|
|
<entry>--ldflags</entry>
|
|
<entry>LD 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>
|
|
<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>/your/phpsrcdir/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
|
|
-->
|