archived-doc-ja/install/pecl.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d1fa3096926b6cbaf9da1f831b6fe3302ae2e490 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka,takagi,mumumu -->

 <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>
   &pecl.moving.to.pie;
   <simpara>
    &link.pecl; は PHP 拡張モジュールのリポジトリで、
    <link xlink:href="&url.php.pear;">PEAR</link> パッケージシステムを経由して使用可能です。
    ここでは PECL 拡張モジュールを取得してインストールする方法を解説します。
   </simpara>
   <simpara>
    以下に示す手順では、PHP のソース配布物へのパスが <literal>/path/to/php/src/dir/</literal>
    であり、PECL 拡張モジュールの名前が <literal>extname</literal>
    であると仮定しています。適切に変更してください。また、
    <link xlink:href="&url.php.pear.cli;">pear コマンド</link>
    についても理解していることとします。
    PEAR マニュアルにある <literal>pear</literal> コマンドについての情報は、
    そのまま <literal>pecl</literal> コマンドにもあてはまります。
   </simpara>
   <simpara>
    便利な機能を使用するには、拡張モジュールをビルドし、
    インストールして読み込まなければなりません。
    拡張モジュールのビルドとインストールについては以下でさまざまな方法を説明しますが、
    モジュールの読み込みは自動的には行われません。モジュールを読み込むには、
    &php.ini; ファイルに <link linkend="ini.extension">extension</link>
    ディレクティブを追加するか、<function>dl</function> 関数を使用します。
   </simpara>
   <simpara>
    拡張モジュールのビルドにあたっては、適切なバージョンのツール
    (autoconf, automake, libtool など) を使用することが重要です。
    必要なツールとそのバージョンについては、
    <link xlink:href="&url.php.anongit;">Anonymous Git の手順</link> を参照ください。
   </simpara>
  </sect1>

  <sect1 xml:id="install.pecl.downloads">
   <title>PECL 拡張モジュールをダウンロードする</title>
   &pecl.moving.to.pie;
   <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 開発チームが提供する
      さまざまな拡張モジュールについての情報が公開されています。
      ChangeLog やリリースノート、必要な要件、リビジョンといった情報が参照可能です。
     </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 に置かれています。
      <!-- TODO Expand -->
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <acronym>SVN</acronym>
     </simpara>
     <simpara>
      <acronym>SVN</acronym> にも収められている PECL 拡張モジュールもあります。
      <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 プロジェクトでは、大半の PECL 拡張モジュールの Windows 用コンパイル済み DLL
     を提供しています。各パッケージのページをごらんください。
     </simpara>
    </listitem>
   </itemizedlist>
  </sect1>

 <sect1 xml:id="install.pecl.windows">
  <title>PHP 拡張モジュールの Windows へのインストール</title>
  <para>
   Windows では、PHP の拡張モジュールを読み込む方法は 2 通りあります。
   コンパイル時に PHP に組み込む方法と、DLL として読む込む方法です。
   コンパイル済みの拡張モジュールを読み込む方法のほうが簡単で、おすすめです。
  </para>
  <para>
   拡張モジュールを読み込むには、".dll" ファイルをシステム上に用意する必要があります。
   すべての拡張モジュールは、PHP Group によって定期的に自動コンパイルされています
   (ダウンロード先は次の節を参照ください)。
  </para>
  <para>
   コンパイル時に拡張モジュールを PHP に組み込む方法については、
   <link linkend="install.windows.building">ソースからのビルド</link>
   に関するドキュメントを参照ください。
  </para>
  <para>
   単体の拡張モジュール (DLL ファイル) をコンパイルする方法については
   <link linkend="install.windows.building">ソースからのビルド</link>
   に関するドキュメントを参照ください。
   PHP の配布パッケージにも PECL にも DLL ファイルが存在しなければ、
   まずコンパイルをしないとその拡張モジュールは使えないでしょう。
  </para>

  <sect2 xml:id="install.pecl.windows.find">
   <title>拡張モジュールの探し方は？</title>
   <para>
    PHP の拡張モジュールは、通常は "php_*.dll" (* の部分に拡張モジュールの名前が入ります)
    という名前で "PHP\ext" フォルダに存在します。
   </para>
   <para>
    PHP には、大半の開発者にとって有用である拡張モジュールが同梱されています。
    これらは <emphasis>"コア"</emphasis> 拡張モジュールと呼ばれます。
   </para>
   <para>
    しかし、コア拡張モジュールに含まれない機能が必要となった場合はそのモジュールを
    &link.pecl; で探す必要があります。
    The PHP Extension Community Library (PECL) は PHP
    拡張モジュール用のリポジトリで、すべての拡張モジュールの一覧機能や
    PHP 拡張モジュールの開発やダウンロードをホスティングする仕組みを提供します。
   </para>
   <para>
    自分で拡張モジュールの開発をしている方は、
    それを PECL で公開して他の人たちにも使ってもらいたいと思われることでしょう。
    そうすれば、彼らからフィードバックを得たり (うまくいけば)
    感謝の言葉をもらえたり、バグレポートやバグ修正パッチをもらえたりするかもしれません。
    自作の拡張モジュールを PECL で公開したい場合は
    <link xlink:href="&url.pecl.submit;">PECL submit</link>
    を参照ください。
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.which">
   <title>どれをダウンロードすればいいの？</title>
   <para>
    <emphasis>
     各 DLL について、いくつかのバージョンが見つかることがあります。
    </emphasis>
    <itemizedlist>
     <listitem>
      <simpara>
       バージョン番号が異なるもの (少なくとも先頭の 2 つの数字は一致している)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       スレッドセーフの設定が異なるもの
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       プロセッサのアーキテクチャ (x86, 64 bits...) が異なるもの
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       デバッグ設定が異なるもの
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>その他</literal>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    注意して欲しいのは、拡張モジュールの設定とそれを動かす
    PHP 実行ファイルの設定をそろえておかなければならないということです。
    次の PHP スクリプトを実行すると、PHP に関する
    <emphasis>すべての</emphasis> 設定を取得することができます。
   </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 以降では、拡張モジュールの名前が、拡張モジュールのファイル名の代わりに使えるようになりました。
    これは OS に依存せず、特に初心者に簡単な仕組みです。
    これは、読み込む拡張モジュールを指定する推奨できるやり方になっています。
    それより前のバージョンとの互換性を確保するため、ファイル名の指定もまだサポートされています。
   </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 の場所がおかしい、
    &php.ini; の
    "<link linkend="ini.extension-dir">extension_dir</link>" がおかしい、
    コンパイル時の設定が違うなどが、よくある問題です。
   </para>
   <para>
    コンパイル時の設定が違うことが原因だった場合は、おそらく間違った DLL
    をダウンロードしてしまったのでしょう。
    もういちど、正しい設定の拡張モジュールをダウンロードしましょう。
    正しい設定とは？ 改めて言います。<function>phpinfo</function>
    を参考にしましょう。
   </para>
  </sect2>

 </sect1>

  <sect1 xml:id="install.pecl.pear">
   <title>共有 PECL 拡張モジュールを、pecl コマンドを用いてコンパイルする</title>
   <simpara>
    PECL を用いると、共有 PECL 拡張モジュールを容易に作成することができます。
    以下のように <link xlink:href="&url.php.pear.cli;">pecl コマンド</link> を用います。
   </simpara>
  <screen>
<![CDATA[
$ pecl install extname
]]>
  </screen>
   <simpara>
    <emphasis>extname</emphasis> のソースがダウンロードされ、
    コンパイルおよび <link linkend="ini.extension-dir">extension_dir</link>
    への <filename>extname.so</filename> のインストールが行われます。
    <filename>extname.so</filename> は、&php.ini; 経由で読み込まれます。
   </simpara>
   <simpara>
    デフォルトでは、<command>pecl</command> コマンドは
    状態が <literal>alpha</literal> あるいは <literal>beta</literal>
    のパッケージをインストールしません。<literal>stable</literal>
    なパッケージが存在しない場合は、以下のコマンドを使用して
    <literal>beta</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 で共有 PECL 拡張モジュールをコンパイルする方法</title>
   <simpara>
    時には <command>pecl</command> インストーラを使用するという選択肢が使えない場合もあります。
    たとえばファイアウォールの内部で作業をしている場合がそうですし、
    まだリリースされていない git 版のように
    PECL パッケージ形式になっていないものをインストールする場合も
    それにあてはまります。このようなモジュールをビルドする必要がある場合は、
    より低レベルなビルドツールを使用して手動でビルドします。
   </simpara>
   <simpara>
    PHP 拡張モジュールのビルド環境を準備するために、
    <command>phpize</command> コマンドを使用します。以下の例では、
    拡張モジュールのソースが <filename>extname</filename>
    というディレクトリにあると仮定します。
   </simpara>
   <para>
    <screen>
<![CDATA[
$ cd extname
$ phpize
$ ./configure
$ make
# make install
]]>
    </screen>
   </para>
   <simpara>
    上手くいけば、<filename>extname.so</filename> が作成され、
    それが PHP の
    <link linkend="ini.extension-dir">拡張モジュールディレクトリ</link>
    に置かれます。
    この拡張モジュールを使用する前に、&php.ini; に
    <literal>extension=extname.so</literal> という行を追加する必要があります。
   </simpara>
  <simpara>
   コンパイル済みのパッケージ (RPM など) を使用している場合などで、もし
   <command>phpize</command> コマンドが見つからない場合は、適切な
   開発版の PHP パッケージをインストールしましょう。
   PHP や拡張モジュールをビルドするために必要なヘッダファイルや
   <command>phpize</command> コマンドは、このパッケージに含まれます。
  </simpara>
  <simpara>
   使用法についての詳細な情報を表示するには、
   <command>phpize --help</command> を実行します。
  </simpara>
  </sect1>
 
 <sect1 xml:id="install.pecl.php-config">
  <title>
   <command>php-config</command>
  </title>
  
  <para>
   <command>php-config</command> はシンプルなシェルスクリプトで、
   インストールされている PHP の設定情報を取得します。
  </para>

  <para>
   拡張モジュールをコンパイルするときに、もし複数のバージョンの PHP
   がインストールされている場合は、どちらを使ってコンパイルするのかを指定できます。
   configure の <option role="configure">--with-php-config</option> オプションで、
   対応する <command>php-config</command> スクリプトのパスを指定します。
  </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>
        PHP をコンパイルしたときの <literal>LD</literal> フラグ
       </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>CLI あるいは CGI バイナリへのフルパス</entry>
      </row>
      <row>
       <entry>--php-sapis</entry>
       <entry>使用できるすべての SAPI モジュール</entry>
      </row>
      <row>
       <entry>--configure-options</entry>
       <entry>
        現在インストールされている PHP の再作成するための configure オプション
       </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 に configure スクリプトを再実行させ、通常通りに
    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
-->