/
pecl.xml
601 lines (583 loc) · 23 KB
/
pecl.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9e2d8231b5d8a3795b365c6770fab288e59e6249 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>
<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>
<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>
<para>
<screen>
$ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname
</screen>
</para>
</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>
<para>
<screen>
$ pecl install extname
</screen>
</para>
<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>
<para>
<screen>
$ pecl install extname-beta
</screen>
</para>
<para>
特定のバージョンをインストールするには、次のような変化形を使用します。
</para>
<para>
<screen>
$ pecl install extname-0.1
</screen>
</para>
<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>
<para>
<screen>
/path/to/php/src/dir/ext/extname
</screen>
</para>
<simpara>
これ以降、PHP に configure スクリプトを再実行させ、通常通りに
PHP をビルドします。
</simpara>
<para>
<screen>
$ cd /path/to/php/src/dir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
</screen>
</para>
<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>
<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
-->