pecl.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 111535af69b070980330fe83ed2eab5ca759c73d Maintainer: rjhdby Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="install.pecl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Установка модулей PECL</title>

 <sect1 xml:id="install.pecl.intro">
  <title>Введение в установку PECL</title>
  <simpara>
   &link.pecl; — репозиторий модулей PHP,
   доступ к которым предоставляется через систему распространения PHP-компонентов <link xlink:href="&url.php.pear;">PEAR</link>.
   Эта часть руководства рассказывает, как получить и установить модули PECL.
  </simpara>
  <simpara>
   Эти инструкции подразумевают, что <literal>/path/to/php/src/dir/</literal> — путь
   к каталогу с дистрибутивом исходного кода PHP, а <literal>extname</literal> — имя
   модуля PECL, так что вносите соответствующие коррективы. Эти инструкции также подразумевают
   знакомство с <link xlink:href="&url.php.pear.cli;">командой pear</link>.
   Информация в руководстве PEAR для команды <command>pear</command> также применима
   для команды <command>pecl</command>.
  </simpara>
  <simpara>
   Чтобы модуль можно было использовать, общедоступное расширение требуется создать,
   установить и загрузить. Описанные ниже методы предоставляют различные рекомендации
   по сборке и установке модулей, но без применения их автоматической загрузки.
   Модули загружают через директиву <link linkend="ini.extension">extension</link>
   в файле &php.ini; или функцией <function>dl</function>.
  </simpara>
  <simpara>
   В процессе сборки PHP-модулей важно иметь нужные версии необходимых утилит
   (autoconf, automake, libtool и т. д.). Информацию об этих утилитах и их версиях можно посмотреть
   в разделе "<link xlink:href="&url.php.anongit;">Инструкции
   по анонимному доступу к Git</link>".
  </simpara>
 </sect1>

 <sect1 xml:id="install.pecl.downloads">
  <title>Загрузка модулей PECL</title>
  <simpara>
   Есть несколько вариантов для загрузки модулей PECL, в том числе:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     Команда <command>pecl install extname</command> автоматически скачивает
     код модуля, поэтому в этом случае нет нужды в отдельной
     загрузке этих файлов.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link xlink:href="&url.pecl;">&url.pecl;</link>
    </simpara>
    <simpara>
     Веб-сайт PECL содержит информацию о различных модулях, предоставляемых
     командой разработчиков PHP. Доступная на этом веб-сайте информация включает:
     лог изменений, новости релизов, требования и другие подобные детали.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <command>pecl download extname</command>
    </simpara>
    <simpara>
     Модули PECL, выпуски которых перечислены на сайте PECL, доступны для
     скачивания и установки с помощью <link xlink:href="&url.php.pear.cli;">команды pecl</link>.
     Можно также указать отдельные ревизии для установки.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>git</acronym>
    </simpara>
    <simpara>
     Многие модули PECL находятся на GitHub.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>SVN</acronym>
    </simpara>
    <simpara>
     Некоторые модули PECL также находятся в <acronym>SVN</acronym>. Веб-интерфейс
     для просмотра доступен по адресу <link xlink:href="&url.php.svn;pecl/">&url.php.svn;pecl/</link>.
     Для загрузки напрямую из <acronym>SVN</acronym> можно выполнить следующую последовательность
     команд:
    </simpara>
    <screen>
<![CDATA[
$ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname
]]>
    </screen>
   </listitem>
   <listitem>
    <simpara>
     Загрузка для Windows
    </simpara>
    <simpara>
     Проект PHP компилирует и предлагает файлы DLL для Windows для большинства модулей PECL на странице с пакетами.
    </simpara>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 xml:id="install.pecl.windows">
  <title>Установка PHP-модуля в Windows</title>
  <para>
   Существует два способа загрузки PHP-модуля в Windows (здесь идёт речь не о скачивании модуля,
   а о том, чтобы PHP применял его в работе): скомпилировать
   его вместе с PHP или загрузить DLL. Загрузка заранее
   скомпилированного модуля — самый простой и рекомендуемый способ.
  </para>
  <para>
   Загрузить модуль можно, если он существует
   в системе в виде файла <filename>.dll</filename>.
   Все модули автоматически и периодически компилируются командой
   PHP (подробнее о скачивании рассказано в следующем разделе).
  </para>
  <para>
   Чтобы скомпилировать модуль внутри PHP, обратитесь к разделу документации
   «<link linkend="install.windows.building">Сборка из исходников</link>».
  </para>
  <para>
   Для компиляции отдельного модуля в виде DLL-файла,
   обратитесь к разделу
   «<link linkend="install.windows.building">Сборка из исходников</link>».
   Если DLL-файла нет ни в стандартной поставке PHP,
   ни в PECL, возможно, потребуется скомпилировать его, прежде чем можно будет использовать модуль.
  </para>

  <sect2 xml:id="install.pecl.windows.find">
   <title>Где найти модуль?</title>
   <para>
    PHP-модулям обычно присваивают имена вида <filename>php_*.dll</filename> (где звёздочка означает
    имя модуля), и они размещаются в папке <filename>PHP\ext</filename>.
   </para>
   <para>
    PHP поставляется с наиболее полезными для большей части разработчиков модулями.
    Такие модули называются <emphasis>входящими в комплект</emphasis> (“bundled”).
   </para>
   <para>
    Однако, если входящие в комплект модули не дают нужной функциональности,
    нужный модуль всё ещё может быть найден на сайте &link.pecl;.
    Библиотека модулей сообщества PHP
    (The PHP Extension Community Library, PECL) — это
    хранилище модулей PHP, в котором расположен каталог всех известных модулей,
    и оборудование, которое даёт место для хранения скачиваемых и разрабатываемых PHP-модулей.
   </para>
   <para>
    Разработанный для отдельных целей модуль можно загрузить
    в библиотеку PECL, чтобы другие люди, которым он может быть нужен, могли извлечь из него пользу.
    Неплохим побочным последствием этого будет хорошая вероятность получить отзывы,
    благодарности (надеемся, что так и будет), сообщения об ошибках
    и даже исправления/патчи. Пожалуйста, прочтите <link xlink:href="&url.pecl.submit;">публикацию PECL</link>
    перед отправкой модуля в PECL.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.which">
   <title>Какой модуль нужно загрузить?</title>
   <para>
    <emphasis>
     Часто будет доступно несколько версий каждого модуля DLL:
    </emphasis>
    <itemizedlist>
     <listitem>
      <simpara>
       Разные номера версий (по крайней мере, первые две цифры должны совпадать)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Различные настройки потокобезопасности
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Различная архитектура процессора (x86, x64,…)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Различные настройки отладки
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>и т. д.</literal>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    Помните, настройки модулей должны совпадать
    со всеми настройками бинарного файла PHP.
    Следующий PHP-скрипт выведет <emphasis>все</emphasis>
    настройки PHP:
   </para>
   <para>
    <example>
     <title>
      Вызов функции <function>phpinfo</function>
     </title>
     <programlisting role="php">
<![CDATA[
<?php
phpinfo();
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Или запустите из командной строки:
    <screen>
<![CDATA[
drive:\path\to\php\executable\php.exe -i
]]>
    </screen>
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.loading">
   <title>Загрузка модуля</title>
   <para>
    Самый распространённый способ загрузить PHP-модуль —
    включить модуль в конфигурационном файле &php.ini;.
    Обратите внимание, что файл &php.ini; уже содержит записи большей части модулей,
    и для их активации потребуется только удалить точку с запятой.
   </para>
   <para>
    Обратите внимание, начиная с PHP 7.2.0 вместо названия файла модуля
    разрешается указывать название модуля. Такой способ становится рекомендованным
    для определения списка загружаемых модулей, поскольку это самый простой и платформонезависимый способ.
    Поддержка имён файлов всё ещё сохраняется для совместимости с предыдущими версиями.
   </para>
   <screen>
<![CDATA[
;extension=php_extname.dll
]]>
   </screen>
   <screen>
<![CDATA[
extension=php_extname.dll
]]>
   </screen>
   <screen>
<![CDATA[
; Начиная с PHP 7.2 лучше делать так:
extension=extname
zend_extension=another_extension
]]>
   </screen>
   <para>
    Однако некоторые веб-серверы создают путаницу, поскольку они
    не используют файл &php.ini;, который лежит в дистрибутиве PHP.
    Путь расположения файла &php.ini;
    указывается в выводе функции <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>
    После активации модуля сохраняют файл &php.ini;, перезагружают веб-сервер
    и повторно проверяют вывод функции <function>phpinfo</function>.
    Для нового модуля появится отдельный раздел.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.problemsolving">
   <title>Решение проблем</title>
   <para>
    Лог-файлы помогают узнать причину ошибки,
    когда модуль не появляется в выводе функции <function>phpinfo</function>.
   </para>
   <para>
    При работе с PHP из командной строки, в режиме CLI, ошибки загрузки
    сообщение об ошибке загрузки модуля появится на экране.
   </para>
   <para>
    Расположение и формат лог-файлов при работе PHP на веб-сервере
    зависят от программного обеспечения.
    О расположении лог-файлов рассказывает документация веб-сервера,
    место хранения журналов не зависит от PHP.
   </para>
   <para>
    Часто проблемы возникают из-за неправильного расположения DLL-модуля и DLL-файлов, от которых он зависит,
    неправильного значения директивы "<link linkend="ini.extension-dir">extension_dir</link>" в файле <filename>php.ini</filename>,
    и из-за несовпадения настроек компиляции.
   </para>
   <para>
    Если проблема возникает из-за несовпадения настроек компиляции,
    то, возможно, скачали неправильный DLL-файл. Попробуйте скачать
    модуль снова с правильными настройками. И снова в таких ситуациях
    помогает информация, которую выводит функция <function>phpinfo</function>.
   </para>
  </sect2>

 </sect1>

 <sect1 xml:id="install.pecl.pear">
  <title>Компиляция разделяемых модулей с помощью команды pecl</title>
  <simpara>
   PECL упрощает создание общедоступных модулей PHP. Выполните следующую
   <link xlink:href="&url.php.pear.cli;">команду pecl</link>:
  </simpara>
  <screen>
<![CDATA[
$ pecl install extname
]]>
  </screen>
  <simpara>
   Эта команда загрузит исходный код для модуля <emphasis>extname</emphasis>,
   скомпилирует и установит файл <filename>extname.so</filename> в директорию
   <link linkend="ini.extension-dir">extension_dir</link>. Затем файл
   <filename>extname.so</filename> может быть загружен через файл &php.ini;
  </simpara>
  <simpara>
   По умолчанию команда <literal>pecl</literal> не будет устанавливать пакеты,
   отмеченные состоянием <literal>alpha</literal> или <literal>beta</literal>.
   <literal>beta</literal>-версию пакета устанавливают следующей командой,
   если <literal>stable</literal>-версии пакетов недоступны:
  </simpara>
  <screen>
<![CDATA[
$ pecl install extname-beta
]]>
  </screen>
  <para>
   Следующая команда установит конкретную версию:
  </para>
  <screen>
<![CDATA[
$ pecl install extname-0.1
]]>
  </screen>
  <note>
   <para>
    После подключения модуля в файле &php.ini; потребуется перезапустить веб-сервер,
    чтобы изменения вступили в силу.
   </para>
  </note>
 </sect1>

 <sect1 xml:id="install.pecl.phpize">
  <title>Компиляция разделяемых модулей командой phpize</title>
  <simpara>
   Иногда компиляция модулей через установщик <literal>pecl</literal> невозможна.
   Это связано с брандмауэром или с тем, что модуль, который требуется установить,
   недоступен как PECL-совместимый пакет,
   например, модули из системы управления версиями (git), у которых ещё не было выпусков.
   Такой модуль собирают вручную через низкоуровневые утилиты сборки.
  </simpara>
  <simpara>
   Команду <command>phpize</command> выполняют для подготовки окружения сборки
   PHP-модуля. В следующем примере исходные коды модуля лежат
   в директории с названием <filename>extname</filename>:
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd extname
$ phpize
$ ./configure
$ make
# make install
]]>
   </screen>
  </para>
  <simpara>
   Успешная установка создаст <link linkend="ini.extension-dir">в директории PHP-модулей</link>
   файл <filename>extname.so</filename>.
   Модуль будет доступен для работы после корректировки
   файла &php.ini; — в него потребуется добавить
   строку <literal>extension=extname.so</literal>.
  </simpara>
  <simpara>
   Если в системе нет команды <command>phpize</command>, но доступна работа
   с предустановленными пакетами (наподобие RPM), необходимо убедиться, что также установлена
   соответствующая версия пакета PHP для разработчиков, поскольку они часто
   содержат команду <command>phpize</command> с правильными файлами заголовков
   для сборки PHP и его модулей.
  </simpara>
  <simpara>
   Для дополнительной информации выполните команду <command>phpize --help</command>.
  </simpara>
 </sect1>

 <sect1 xml:id="install.pecl.php-config">
  <title>
   php-config
  </title>

  <para>
   <command>php-config</command> — простой скрипт командной строки для получения информации о конфигурации
   установленного PHP.
  </para>

  <para>
   Когда модули компилируются в системах с несколькими установленными версиями PHP,
   установка, для которой началась сборка, разрешается определять во время конфигурации
   командой <command>php-config</command> с параметром <option role="configure">--with-php-config</option>,
   в котором указывают путь до нужного скрипта.
  </para>

  <para>
   Список доступных для скрипта <command>php-config</command> параметров командной строки
   доступен в любое время
   при запуске команды <command>php-config</command> с параметром <option>-h</option>:
   <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>Опции скрипта</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Опция</entry>
       <entry>Описание</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>--prefix</entry>
       <entry>Директория, в которой установили PHP, например /usr/local</entry>
      </row>
      <row>
       <entry>--includes</entry>
       <entry>
        Список <literal>-I</literal> параметров со всеми подключаемыми файлами
       </entry>
      </row>
      <row>
       <entry>--ldflags</entry>
       <entry>
        <literal>LD</literal>, с которыми скомпилировали PHP
       </entry>
      </row>
      <row>
       <entry>--libs</entry>
       <entry>Внешние библиотеки, с которыми скомпилировали PHP</entry>
      </row>
      <row>
       <entry>--extension-dir</entry>
       <entry>Директория, в которой по умолчанию ищутся модули</entry>
      </row>
      <row>
       <entry>--include-dir</entry>
       <entry>
        Префикс директории, в которую по умолчанию устанавливаются заголовочные файлы
       </entry>
      </row>
      <row>
       <entry>--php-binary</entry>
       <entry>Полный путь до исполняемых файлов php для режимов CLI или CGI</entry>
      </row>
      <row>
       <entry>--php-sapis</entry>
       <entry>Показывает все доступные модули SAPI</entry>
      </row>
      <row>
       <entry>--configure-options</entry>
       <entry>
        Конфигурационные опции для воссоздания настроек текущей установки PHP.
       </entry>
      </row>
      <row>
       <entry>--version</entry>
       <entry>Версия PHP</entry>
      </row>
      <row>
       <entry>--vernum</entry>
       <entry>Версия PHP в виде целого числа</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </sect1>

 <sect1 xml:id="install.pecl.static">
  <title>Компиляция модулей PECL статически в PHP</title>
  <simpara>
   Возможно, потребуется собрать модуль PECL статично в бинарный файл PHP.
   Для этого исходный код модуля размещают в каталоге
   <filename>/path/to/php/src/dir/ext/</filename> и вызывают перегенерацию конфигурационных скриптов
   через систему сборки PHP.
  </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>
   Это создаст следующую директорию:
  </simpara>
  <screen>
<![CDATA[
/path/to/php/src/dir/ext/extname
]]>
  </screen>
  <simpara>
   Затем PHP потребуется принудительно пересобрать скрипт конфигурации,
   после чего скрипт конфигурации собирается как обычно:
  </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>
    Для запуска скрипта <command>buildconf</command> потребуется
    команда <command>autoconf</command> версии <literal>2.68</literal>
    и команда <command>automake</command> версии <literal>1.4+</literal>.
    Иногда работают и более новые версии скрипта <command>autoconf</command>,
    но не поддерживаются.
   </simpara>
  </note>
  <simpara>
   В зависимости от модуля будет использован один из двух
   параметров — <option role="configure">--enable-extname</option>
   или <option role="configure">--with-extname</option>.
   Обычно модуль, который не требует внешних библиотек,
   использует параметр <option role="configure">--enable</option>.
   Это проверяют командой <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
-->