PHP マニュアル

著者:
Mehdi Achour
Friedhelm Betz
Antony Dovgal
Nuno Lopes
Hannes Magnusson
Georg Richter
Damien Seguy
Jakub Vrana
その他
2012-05-18
編集: Philip Olson
PHP マニュアル翻訳プロジェクト
© 1997-2012 the PHP Documentation Group

著作権

Copyright © 1997 - 2012 by the PHP Documentation Group. この著作物は、Creative Commons Attribution 3.0 か それ以降で指定された条件と制約に従う限り配布することができます。 Creative Commons Attribution 3.0 license のコピーは本マニュアルとともに配布されており、 ライセンスの最新版は現在のところ、 » http://creativecommons.org/licenses/by/3.0/ で入手可能です。

修正の有無に関わらず本文書の全体または一部を再配布または再出版したい場合や、 質問がある場合には、 » doc-license@lists.php.net 宛で著作権者まで連絡をしてください。 このアドレスは、一般にアーカイブが公開されているメーリングリストへマップされていることに 注意して下さい。

(訳注)本日本語訳の記述内容により生じたいかなる損害についても 著作権所有者および翻訳者は責任を負いません。

PHP マニュアル

序文

PHP は、"PHP: Hypertext Preprocessor" を意味し、広く使用されているオープンソースの汎用スクリプト言語です。 HTML に埋め込むことができ、Web アプリケーションの開発に特に適しています。 PHP の構文の多くは C、Java、Perl 言語から転用したもので、 簡単に習得することができます。この言語は、動的に生成されるウェブページを Web 開発者が速やかに作成できるようにすることを主な目標として つくられました。しかし、それだけにとどまらず、 もっと多くのことを PHP を使って行うことができます。

このマニュアルは、 関数リファレンス を中心として、言語リファレンス、 PHP の主な機能、 そして、その他の 付録 から構成されています。

本マニュアルを様々な形式で » http://www.php.net/download-docs.php からダウンロードすることが出来ます。 このマニュアルがどのように作成されているか、といった詳細な情報は 付録の 本マニュアルについて にあります。 PHP の歴史 に興味がある場合は、 関連する付録も参照して下さい。

著者と貢献者

我々は、現在最も活動的な人々をこのマニュアルの先頭に掲げています。 しかし、他にも多くの我々の活動を支援してくれる人がおり、 また、過去にこのプロジェクトを支援してくれた人がいます。 マニュアルのユーザー注記により支援してくれた名前がわからない人々がいますが、 彼らの支援は非常に有益です。以下に掲げたリストはアルファベット順です。

著者と編集者

以下の方々は本マニュアルに ついてコンテンツを提供したことで大きな貢献をしています。 Bill Abt, Jouni Ahto, Alexander Aulbach, Daniel Beckham, Stig Bakken, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Richard Quadling, Derick Rethans, Rob Richards, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Masahiro Takagi, Yannick Torres, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar そして Andrei Zmievski.

以下の方々は本マニュアルについて多くの編集作業を行ったことで大きな貢献を しています。 Stig Bakken, Gabor Hojtsy, Hartmut Holzgraefe そして Egon Schmid.

ユーザー注記の管理者

現在最もアクティブな管理者。 Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda そして Maciek Sokolewicz.

以下の方々もユーザー注記の管理に注力してくれました。 Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles そして Jeroen van Wolffelaar.

翻訳者

本マニュアルの日本語への翻訳は、PHP マニュアル翻訳プロジェクトにて行われています。 主な翻訳者は、以下の通りです（名前のアルファベット順）。

Chihiro Higuchi, Haruki Setoyama, Hideyuki Shimooka, Kazuhiro Ogura, Machino Satoshi, Masaharu Iwai, Masahiro Takagi, Masaki Fujimoto, Masaki Kagaya, Michihide Hotta, Moriyoshi Koizumi, Rui Hirokawa, Satoru Yoshida, Shigeru Kanemoto, Tadashi Jokagi, Yasuo Ohgaki, Yoshinari Takaoka, Yu Watanabe, Yusuke Hata.

はじめに

入門

目次

PHP とはなんでしょう?

PHP (PHP: Hypertext Preprocessor を再帰的に略したものです) は、広く使われているオープンソースの汎用スクリプト言語です。 PHP は、特に Web 開発に適しており、HTML に埋め込むことができます。

で、結局のところどういう意味なのでしょう? 以下に例を示します。

例1 初歩的な例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>Example</title>
    </head>
    <body>

        <?php
            echo "Hi, I'm a PHP script!";
        ?>

     </body>
</html>

HTMLを出力するために多くのコマンドを記述する (C や Perl のように) 代わりに、PHP のページは "何か" (この例では、"Hi, I'm a PHP script!" と出力) を行うコードを HTML に埋め込むことになります。 PHP のコードは特別な 開始および終了の処理命令 <?php と ?> で囲まれており、これによって "PHP モード" の切り替えを行います。

PHP がクライアントサイド JavaScript のようなものと異なっている点は、 コードがサーバーで実行され、その結果がクライアントに送信されるということです。 クライアントは、スクリプトを実行した結果を受け取りますが、 その出力を作成したコードがどんなものなのかを知ることはできません。 全てのHTMLファイルをPHPで処理するようにWebサーバー を設定することさえ可能で、この場合、ユーザーが袖の内に何があるかを 見分けることは不可能になることでしょう。

PHPを使用する上で最も優れている点は、初心者に対しては非常に分かり 易いと同時に、プロフェッショナルのプログラマに対しては多くの進んだ 機能を提供している点です。PHPの機能を羅列した長い一覧表を読まなけ ればならないのかと心配する必要はありません。PHPはすぐに始められま すし、数時間の内に簡単なスクリプトが書けるようになります。

PHPを使用した開発ではサーバーサイドでの動作に焦点が当てられますが、 他にも多くのことが可能です。 PHPにできることは?まで読み進めてみてください。 Webプログラミングのみに関心がある場合には、 簡易チュートリアルに進んでください。

PHPにできることは?

あらゆることができます。PHPでは主にサーバーサイドでの活用に焦点が 当てられているため、フォームからデータを取得したり、動的にページ の内容を生成したり、クッキーを送信・受信するといった他のCGI プログラムに出来ることは全て行うことが出来ます。しかし、これが 全てではありません。

PHPスクリプトが使用される場所は主に3つあります。

  • サーバーサイドでのスクリプティング。これは最も古くからあり PHPの中心となる分野です。ここでPHPを動作させるには 3つのものが必要です。PHPパーサ(CGIもしくはサーバーモジュール)、 ウェブサーバー、そしてブラウザです。ウェブサーバーは インストールされたPHPと連結して起動されなければなりません。 ブラウザでウェブサーバーにアクセスし、PHPページを閲覧することで PHPプログラムの出力を得ることが出来ます。インストール手順の章に詳しい 情報があります。
  • コマンドラインでのスクリプティング。PHPスクリプトは サーバーもブラウザも無しで動作させるようにすることも出来ます。 この場合、PHPパーサだけが必要となります。このタイプは cron(Windowsではタスクスケジューラ)を使用して一定間隔で スクリプトを実行したい場合や、ちょっとした文書処理を 行うのに最適な方法です。 コマンドラインでPHPを使うの章に詳しい情報があります。
  • クライアントサイドでのGUIアプリケーション。PHPはおそらく ウィンドウを使用したアプリケーションを書くのに最適な言語 では無いと思いますが、PHPに非常に慣れている場合には、そして PHPの進んだ機能をクライアントサイドでのアプリケーションで 使用した場合にはPHP-GTKを使ってプログラムを書くことが出来ます。 同様の方法でクロスプラットフォーム名アプリケーションを書く ことも出来ます。PHP-GTKはPHPを拡張するもので、通常の ディストリビューションには含まれません。もし興味があるなら » PHP-GTKのサイトを 訪れてみてください。

PHPは Linux, 多くのUnix系システム(HP-UX, Solaris, OpenBSD等), Microsoft Windows, Mac OS X, RISC OS, その他全ての有名なOSで 動作します。 PHPはまた現在使用されているほとんど全てのウェブサーバーを サポートします。Apache や IIS、その他多くのサーバーをです。 また、FastCGI PHP バイナリを使える lighttpd や nginx などにも対応しています。PHP はモジュールとしても動作しますし、 CGI としても動作します。

つまりPHPを使用する場合にはOSとウェブサーバーを自由に選ぶことが出来ます。 さらに手続き型のプログラミングかオブジェクト指向のプログラミングか、 もしくはそれらを混在させるかといった選択を行うこともできます。

PHPはHTMLを出力するだけではありません。PHPはイメージやPDFファイル、 そして(libswfやMingを使って)Flashムービーまでもをその場で生成する 機能を備えています。またXHTMLやXMLといったその他の文書も自動的に 生成することが出来ますし、ファイルシステムに保存したり、印刷したり サーバー側でキャッシュすることも出来ます。

PHP の機能の中で最も強力で優れているのは、 広範なデータベースをサポートしている ことでしょう。データベース機能を用いたWebページの作成は非常に簡単です。 データベースごとに用意された拡張モジュール (e.g., for mysql) を使うこともできれば PDO のような抽象化レイヤーを使うこともでき、 ODBC に対応しているデータベースなら ODBC 拡張モジュールを使って接続することもできます。その他には、 cURL あるいは ソケット を使う CouchDB のような例もあります。

PHP は、IMAP、SNMP、NNTP、POP3、HTTP、COM (Windowsのみ) やその他 数え切れない程多くのプロトコルを用いる他のサービスの状態を追跡する 機能もサポートしています。低レベルのネットワークソケットをオープンし、 他のプロトコルを用いて通信を行うことも可能です。また、PHPはWDDXを サポートし、基本的に全てのウェブプログラミング言語間で複雑なデータ交換 を行うことができます。相互接続機能としては、他にJavaオブジェクトの インスタンスを作成してそれをPHPのオブジェクトとして透過的にアクセス する機能があります。

PHP には便利な テキスト処理 機能が用意されています。 Perl 互換の正規表現 (PCRE) や、 XML 文書のパースや XML 文書へのアクセス のための数多くの拡張モジュール・ツールなどです。PHP の XML 関連の拡張モジュールはすべて libxml2 をベースとしており、その機能を継承して SimpleXML や XMLReader、そして XMLWriter がサポートされています。

他にも興味深い拡張モジュールがあり、 アルファベット順 および カテゴリ別 のページで調べることができます。またさらに、PECL 拡張モジュールの中には » XDebug などのように PHP のマニュアルに記載されていないものもあります。

お分かりの通り、このページではPHPの機能やPHPを使用することの利点を全て 紹介することは出来ません。PHPのインストール の章を読んでみてください。紹介された拡張モジュールに関しては関数リファレンスを読んでみてください。

簡易チュートリアル

目次

ここで、PHP の基礎の基礎について簡単なチュートリアルで説明したいと思います。 PHP は Web ページを作成する機能だけを有しているわけではありませんが、 ここでは PHP で動的な Web ページを作成することのみを扱います。詳細は、 PHP でできること と題するセクションを参照してください。

PHP を使用できる Web ページは、通常の HTML ページと全く同様に扱われ、 通常の HTML ページを作成するのと同様の方法で編集することができます。

必要なものは?

本チュートリアルでは、使用するサーバーで PHP が使用可能であり、 .php で終わる全てのファイルが PHP で処理されることを仮定します。多くのサーバーでは、PHP ファイルに関してこれがデフォルトの拡張子ですが、 確実なのはサーバーの管理者にきいてみることです。サーバーが PHP をサポートする場合、何もする必要はありません。 .php ファイルを 作成して Web ディレクトリに置くだけで、 サーバーがこれを自動的にパースしてくれます。 何もコンパイルする必要はなく、他のツールをインストールする必要もありません。 PHP のファイルは、あなたが行なう全ての処理を実装した特殊なタグを通常の HTML ファイルに追加したものと考えると良いでしょう。 ほとんどの Web ホストは PHP サポートを提供していますが、 使用しているホストがサポートしていない場合、 » PHP リンク集のセクションで PHP が利用可能な Web ホストを探すためのリソースを読んでみてください。

ここでは、貴重なネットワーク帯域を節約するために、 ローカルに開発を行うことにしましょう。この場合、 » Apache のような Web サーバーと、 当然、» PHP をインストールすることになります。また、多くの場合には、 » MySQL のようなデータベースもインストールすることになるでしょう。

これらは個別にインストールすることもできますし、 より簡単な方法でインストールすることも可能です。 このマニュアルには、 PHP のインストール手順 (Web サーバーが設定済みであると仮定しています) があります。 PHP 自体をインストールする際に問題が発生した場合、 » インストールに関する メーリングリストで質問することをお薦めします。 より簡単にインストールを行いたい場合には、 使用するオペレーティングシステム用の » 設定済みのパッケージ を利用することもできます。これにより、 数回のマウスクリックで自動的にこれらをインストールすることができます。 MacOSX、Linux や Windows を含む、あらゆるオペレーティングシステムにおいて Web サーバーで PHP を使用できるように設定することは簡単です。 Linux の場合、RPM の場所を知るために » rpmfind と » PBone が有用でしょう。 Debian 用パッケージをみつけるには、» apt-get にアクセスするとよいでしょう。

PHP を使用する初めてのページ

以下の内容で hello.php という名前のファイルを作成し、Web サーバーのルートディレクトリ (DOCUMENT_ROOT) に置いてください。

例1 初めての PHP スクリプト: hello.php

<html>
 <head>
  <title>PHP Test</title>
 </head>
 <body>
 <?php echo '<p>Hello World</p>'; ?> 
 </body>
</html>

ブラウザを使用して、/hello.php で終わる Web アクセス用 URL を指定し、 このファイルにアクセスしてください。 ローカルに開発を行っている場合、この URL は http://localhost/hello.php または http://127.0.0.1/hello.php のようになります。 しかし、これは Web サーバーの設定に依存します。 全てが正しく設定されている場合、 このファイルは PHP によりパースされ、以下の出力がブラウザに送信されます。 

<html>
 <head>
  <title>PHP Test</title>
 </head>
 <body>
 Hello World<p>
 </body>
</html>

このプログラムは非常に簡単なので、実際には、このようなページを 作成するために PHP を使用する必要はありません。 Hello World を PHP の echo 命令により出力しているだけです。 このファイルは、実行ファイルまたは特殊なファイルとする必要がないことに注意してください。 このファイルが拡張子 ".php" を有し、このファイルが PHP に渡される必要があると設定されているため、サーバーは PHP により解釈されるファイルを見付けることができます。 このファイルは、多くの面白いことを可能にする特別なタグを利用できる、 通常の HTML ファイルと考えることができます。

この例を試しても何も出力されない場合、または、 ダウンロード用のプロンプトが表示されるか、 テキストとしてファイル全体が表示された場合、 利用しているサーバーで PHP が利用できない可能性があります。本マニュアルの インストール の章により PHP を利用できるようにするよう管理者にきいてみてください。 ローカルに開発を行っている場合も、 インストールの章を読んで設定が全て正しく行われていることを確認してください。 解決しない問題がある場合は、多くの » PHP サポート の選択肢のどれかを利用してみてください。

この例の目的は、特殊な PHP タグ形式を示すことです。 この例では、<?php が PHP タグの開始を示しています。この後、PHP 命令を置き、終了タグ ?> を記述することにより、PHP モードを抜けています。 このように任意の場所で PHP モードを抜けて HTML ファイルに移ることができます。詳細は、 基本的な構文のセクションを参照ください。

注意: 改行に関する注意

HTML においては改行にはほとんど意味がありません。ただ、 HTML の見栄えをよくするためにも適宜改行を入れておくとよいでしょう。 ?> の直後の改行は、PHP によって取り除かれます。 複数の PHP ブロックを使用している場合や、 何かを出力するのかどうかがわからないファイルを include する際などに、 この挙動は非常に便利です。と同時に少々混乱するかもしれません。 強制的に改行させるには、?> の後に空白を置くか、 あるいは PHP ブロック内の最後の echo/print で明示的に改行を出力します。

注意: テキストエディタに関する注意

PHP ファイルを作成、編集、監理する際に使用できる、 多くのテキストエディタや統合開発環境 (IDE) があります。 これらのツールのリストの一部は、» PHP エディタのリスト で整理されています。あるエディタを推薦したい場合、上記のページを訪れ、 ページの監理者にそのエディタをリストに加えてくれないかとたずねてみてください。

注意: ワードプロセッサに関する注意

StarOffice Writer, Microsoft Word および Abiword のようなワードプロセッサは、PHP ファイルの編集には向いていません。 これらのワープロ上でテストスクリプトを編集する場合は、 ファイルをプレーンテキストとして保存していることを確認してください。 さもないと、PHP はスクリプトを読み込んで実行できません。

注意: Windows のメモ帳に関する注意

Windows のメモ帳を使用して PHP スクリプトを書く場合には、ファイルに 拡張子 .php を付けて保存したかどうかを確認する必要があります (メモ帳は、以下の防止策のどらかを適用しない限り、拡張子 .txt を自動的に付加します)。ファイルを保存する際に、 ファイル名を入力するプロンプトでファイル名を引用符で括ります (すなわち、"hello.php" とします)。 もしくは、保存ダイアログボックスにおいてドロップダウンメニュー "テキスト文書"をクリックし、"すべてのファイル" に設定を変更します。 これにより、引用符を付けずにファイル名を入力することができます。

さて、動作する簡単な PHP スクリプトを作成することができましたので、 最も有名な PHP スクリプトを作成してみましょう! phpinfo() 関数をコールすることにより、 定義済み変数、 ロードされている PHP モジュール、設定 等のシステムに関する多くの有用な情報を得ることができます。 この重要な情報を見てみてください。

例2 PHP からシステムに関する情報を取得する

<?php phpinfo(); ?>

実用的な例

次に、より実用的なことをしてみましょう。 ページを見ているユーザーが使用しているブラウザの種類を確認してみます。 これを行なうには、ブラウザが HTTP リクエストの一部として送信した user agent 文字列を調べます。 この情報は、変数 に保存されています。PHP では、変数名は常にドル記号で始まります。 ここで使用する変数は、$_SERVER['HTTP_USER_AGENT'] です。

注意:

$_SERVER は、 Web サーバー関連情報を全て保持する PHP の特別な予約変数です。詳細は、 スーパーグローバル を参照してください。 これらの特別な変数は、» 4.1.0 で導入されました。これ以前は、 $HTTP_SERVER_VARS のような古い配列 $HTTP_*_VARS を代わりに使用していました。 古いとはいえ、これらの変数はまだ存在しています (古いコードに関する注記も 参照してください)。

この変数を表示するには、以下のようにします。

例1 変数を出力する (配列要素)

<?php
echo $_SERVER['HTTP_USER_AGENT'];
?>

このスクリプトの出力例は以下のようになります。


Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)

PHP で利用可能な変数の型 には多くの種類があります。上の例では、 配列 の要素を出力しています。配列は、非常に有用です。

$_SERVER は、PHP で自動的に利用可能な変数のひとつに過ぎません。マニュアルの 定義済の変数 のセクションでリストを参照することができます。 あるいは、完全なリストを取得するには、さきほどのセクションで使用した phpinfo() 関数の出力を確認します。

PHP タグの中に複数の PHP 命令を置くことができ、echo 文以上のことを行なうコードブロックを作成することができます。 例えば、インターネット・エクスプローラかどうかを調べたい場合は、 以下のようにします。

例2 制御構造 および 関数の使用例

<?php
if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== false) {
  echo 'あなたはInternet Explorerを使用しています<br />';
}
?>

このスクリプトの出力例は以下のようになります。 

あなたはInternet Explorerを使用しています<br />

ここで、新しい概念をいくつか導入します。 if 文を使用しています。 C 言語の基本構文を知っているとしたら、理解できると思います。 C 言語や上記の構文を使用する他の言語をあまり知らない場合には、 PHP の入門書を手にとって最初の数章を読むか、このマニュアルの 言語リファレンスの部分を読むべきです。

二番目の新しい概念は、strpos() 関数のコールです。 strpos() は PHP に組み込まれた関数で、 文字列の中である文字列を探します。この場合、 $_SERVER['HTTP_USER_AGENT'] (いわゆる干し草の山 【haystack】) の中で "MSIE" (いわゆる針【needle】) を探しています。 この文字列が見つかった場合、 この関数はこの関数は文字列の相対的な位置を返し、 見つからなかった場合には FALSE を返します。 この関数が FALSE を返さなければ、 if 文は TRUE と評価し、その{波括弧}の中のコードが実行されます。 そうでない場合は、実行されません。 if, else と strtoupper() や strlen() のような他の関数で、似たような例を作ってみてください。 関連するマニュアルの各ページにも例が載っています。 関数の使用法に自信がない場合には、マニュアルの 関数定義の読み方および PHP関数のセクションの両方を 読んでみると良いでしょう。

この例を少し発展させて、PHP ブロックの中からでも PHP モードから出たり入ったりすることができることを以下に示します。

例3 HTML および PHP モードの両方を混在させる

<?php
if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== false) {
?>
<h3>strposが非falseを返しました</h3>
<center><b>あなたはInternet Explorerを使用しています</b></center>
<?php
} else {
?>
<h3>strposがfalseを返しました</h3>
<center><b>あなたはInternet Explorerを使用していません</b></center>
<?php
}
?>

この例の出力は以下のようになります。 

<h3>strposが非falseを返しました</h3>
<center><b>あなたはInternet Explorerを使用しています</b></center>

何かを出力する際に PHP の echo 文を使用する代わりに、PHP モードを抜けて通常の HTML を送信しています。ここで注意すべき重要で強力な点は、 スクリプトの論理フローが損なわれないということです。 strpos() が TRUE または FALSE のどちらを返すか、言い換えるとMSIE が見つかったかどうかに基づき、HTML ブロックだけが見る側に送信されることになります。

フォームの処理

PHP の最も強力な機能の一つは、HTML フォームを処理する手段です。 理解するべき重要な基本概念は、あるフォームの中の全てのフォーム要素が、 自動的に PHP スクリプトで利用可能になるということです。 詳細は、マニュアルのセクション 外部から来る変数 および PHP でフォームを使用する例を参照してください。以下に HTML フォームの例を示します。

例1 簡単な HTML フォーム

<form action="action.php" method="post">
 名前: <input type="text" name="name" />
 年齢: <input type="text" name="age" />
 <input type="submit" />
</form>

このフォームに関して特別なところはありません。これは通常の HTML フォームで特殊なタグは全く使用していません。 ユーザーがこのフォームを記入し、投稿ボタンを押した時、 action.php ページがコールされます。 このファイルには、以下のようなコードを記述します。

例2 フォームからのデータを出力する

こんにちは、<?php echo htmlspecialchars($_POST['name']); ?>さん。
あなたは、<?php echo (int)$_POST['age']; ?> 歳です。

このスクリプトの出力例は次のようになります。 

こんにちは、Joe さん。あなたは、22 歳です。

htmlspecialchars() および (int) の部分以外は、何を行っているかは明らかでしょう。 htmlspecialchars() は、html での特殊な文字を適切にエンコードし、 HTML タグや Javascript をページ内に仕込めないようにします。 また、age フィールドには数値が入ることがわかっているので、これを integer 型に 変換 します。これにより、おかしな文字が入力されることを防ぎます。 これらの処理を PHP に自動的に行わせるためには、 filter 拡張モジュールを使用します。 変数 $_POST['name'] と $_POST['age'] は PHP により自動的に設定されます。 前の部分では、スーパーグローバル$_SERVER を使用しましたが、 ここでは、全ての POST データを保持するスーパーグローバル $_POST を導入しています。 フォームのメソッドが POST であることに注意してください。 GET メソッドを使用している場合、 フォームの情報は代わりにスーパーグローバル $_GET に代入されます。リクエストデータの発信源に留意しない場合には、 スーパーグローバル変数 $_REQUEST を使用することもできます。この変数は、GET, POST, COOKIE, FILE データの混ざったものが含まれます。 import_request_variables() 関数も参照してください。

XForms の入力を PHP で扱うことも可能ですが、たいていの場合は HTML フォームのほうが快適に使用できるでしょう。 XForms は初心者向けのものではありませんが、気になる人もいるかもしれません。 機能概要の節にある XForm から受信したデータの処理方法 を参照ください。

新しいバージョンの PHP で古いコードを使用する

今や PHP は有名なスクリプト言語となってきており、 各自のスクリプトで再利用可能なコードとして、 多くのリソースが公開されています。PHP 言語の開発者の大部分は、 過去のバージョンとの互換性を保とうとしており、 過去のバージョン用に書かれたスクリプトは (理想的には) より新しいバージョンの PHP で変更せずに動作するはずです。 しかし、実際には、通常いくつかの変更が必要となります。

古いコードに影響を与える最近の重要な二つの変更点を以下に示します。

  • $HTTP_*_VARS 配列が過去のものとなったこと (これは、関数またはメソッドの中で使用する際にグローバル変数として 宣言を行なう必要がありました)。以下の スーパーグローバル 配列が » 4.1.0 で導入されました。これらを以下に示します。 $_GET, $_POST, $_COOKIE, $_SERVER, $_ENV, $_REQUEST, $_SESSION. 従来の $HTTP_POST_VARS のような配列 $HTTP_*_VARS もまだ存在します。 PHP 5.0.0 以降、PHP の長い 定義済みの変数 配列は register_long_arrays ディレクティブにより無効にすることができます。
  • 外部変数は、もはやデフォルトでグローバルスコープに登録されません。 言い換えると、PHP » 4.2.0 以降、PHP ディレクティブ register_globals は、 php.ini においてデフォルトで off となっています。 外部変数の値にアクセスするときには、 先ほど説明したスーパーグローバル配列を使うことを推奨します。 古いスクリプトや本、 チュートリアルはこのディレクティブに依存している可能性があります。 このディレクティブが on の場合、 例えば、URL http://www.example.com/foo.php?id=42 から $id を使用することができます。 on、off によらず $_GET['id'] は利用可能です。
これらの変更に関する詳細は、 定義済みの変数 のセクションおよびそこにあるリンクを参照してください。

次にするべきことは?

ここで得た知識により、マニュアルのほとんどの部分、 そしてサンプルのアーカイブにある多くのスクリプトの例を理解できるようになったはずです。 他の例を Web サイト php.net にあるリンクセクション » http://www.php.net/links.php で探すこともできます。

この他 PHP でできる多くのことを示すスライドプレゼンテーションを見るには、 PHP カンファレンスマテリアルサイト » http://talks.php.net/ を参照してください。

インストールと設定

インストールにあたっての一般的な注意事項

インストールを行う前に、PHP を使用する用途を明確にしておく必要があります。 PHP を適用可能な分野としては、 「PHP にできることは？」 のセクションに記述されている通り、主に次の 3 つがあります。

  • Web サイトや Web アプリケーション (サーバーサイドのスクリプト)
  • コマンドラインのスクリプト
  • デスクトップ (GUI) アプリケーション

最初の用途がもっとも一般的で、この場合、PHP 本体、Web サーバー、Web ブラウザ の 3 つが必要となります。Web ブラウザは既にお持ちだと思います。 使用しているオペレーティングシステムのセットアップの状況によっては、 さらに Web サーバーも稼働しているかもしれません（例、Linux 上の Apache や Windows 上の IIS）。また、ホスティング会社で Web 用のスペースを 借りることもできるでしょう。この場合は、自分自身でセットアップを行う必要はなく、 PHP スクリプトを作成し、借りているサーバーにアップロードするだけで、 ブラウザを使って処理結果を見ることができます。

一方、Web サーバーと PHP を自分でセットアップする場合、 サーバーに PHP を組み込む方法が 2 種類あります。 多くのサーバーに対して、各サーバー独自のモジュールインターフェイス (SAPI とも呼ばれます) を通じて、ダイレクトに PHP を動作させることができます。 Apache、Microsoft Internet Information Server、 Netscape、iPlanet サーバーなどがサポートされています。 ISAPI と呼ばれるマイクロソフト互換のモジュールインターフェイスを 持つ Web サーバー（OmniHTTPd など）もサポートされます。 PHP がモジュールのサポートをしていない Web サーバーに対しては、 CGI もしくは FastCGI プロセサとして PHP を使用することができます。 つまり、PHP ファイルへのリクエストの処理を、 PHP のコマンドライン版の実行ファイルを使って行うよう Web サーバーを設定することができます。

コマンドラインでのスクリプト実行に PHP を使用する （たとえば、オフラインで画像を自動生成するスクリプトを書いたり、 指定した引数に応じてテキストファイルを処理したりといった） 場合は、コマンドライン版の実行ファイルが必要となります。 詳細な情報については、 「PHP をコマンドラインから使用する」 の章を参照してください。この場合、サーバーとブラウザは不要です。

PHP-GTK 拡張モジュールを使って、PHP でクライアントサイドの GUI アプリケーションを作成することも可能です。この場合のアプローチは Web ページの 作成とは完全に異なり、HTML を出力するのではなく、 ウインドウやその中のオブジェクトの管理を行うことになります。PHP-GTK に関する より詳細な情報については、 » PHP-GTK 拡張モジュールのサイト を参照してください。PHP-GTK は、PHP の公式アーカイブには含まれていません。

以降、この節では Unix や Windows 上の Web サーバーに サーバーモジュールインターフェイスおよび CGI 実行ファイルとして PHP をセットアップする方法を説明します。 コマンドラインの実行ファイルについての情報も、 これ以降の節で得られるでしょう。

PHP のソースコードと Windows 用のバイナリアーカイブは、 » http://www.php.net/ にあります。 アーカイブをダウンロードする際には、最も近い» ミラーサイト を使用するようにしてください。

Unix システムへのインストール

目次

本章では、UNIX 系のシステムへの PHP のインストールと設定に関する 手引きを示します。使用するプラットフォームや Web サーバーについての セクションを参照して、インストールを行ってください。

このマニュアルでは、 「インストールにあたっての一般的な注意事項」 の章で述べたように、Web 用のセットアップを主に扱います。加えて、 コマンドラインから PHP を使うためのセットアップについても扱います。

Unix プラットホームに PHP をインストールする方法はいくつかあり、 コンパイルして設定するやり方と（コンパイル済みの）パッケージを使う方法とに 別けられます。この手引きでは、コンパイルして設定する方法を主に取り上げます。 Unix 系システムには、パッケージを用いるインストールシステムを持つものも多く、 一般的なセットアップを行うには、パッケージが役に立つでしょう。ただし、 （セキュアサーバーや様々なデータベースドライバなど）少々特殊な機能が必要な場合、 PHP や Web サーバーをビルドする必要が有るかもしれません。ソフトウエアの ビルドに不慣れな場合は、必要な機能を含めてビルドされたパッケージを 誰か他の人が作成済みでないかを調べてみると良いでしょう。

コンパイルにあたって必要な知識とソフトウエアを以下に示します。

  • UNIX に関する基本的な知識 ("make" および C コンパイラを使える程度)
  • ANSI C コンパイラ
  • Web サーバー
  • 個別のモジュール関連のコンポーネント (GD や PDF ライブラリなど)

SVN のソースや、自分でカスタマイズしたソースをビルドするには さらにこれらが必要です。

  • autoconf: 2.13+ (PHP < 5.4.0), 2.59+ (PHP >= 5.4.0)
  • automake: 1.4+
  • libtool: 1.4.x+ (ただし 1.4.2 は除く)
  • re2c: バージョン 0.13.4 以降
  • flex: バージョン 2.5.4 (PHP <= 5.2 の場合)
  • bison: バージョン 1.28 (推奨)、1.35 あるいは 1.75

PHP の初期設定および設定プロセスは、configure スクリプトに与えられたコマンドラインオプションによりコントロールされます。 ./configure --help とすると、 オプションの一覧と簡単な解説が表示されます。 本マニュアルでは、オプションの種類ごとに別けて解説されています。 PHP 本体のオプションの一覧は 付録 にまとめられています。 各拡張モジュール特有のオプションは、関数リファレンスのページに記述されています。

PHP の configure が完了していないと、 拡張モジュールや本体の実行ファイルのビルドができません。 make コマンドの実行にあたっては、注意してください。 configure がうまく行かず原因もよくわからない場合は、 問題が起きた場合 についての章を参照してください。

Apache 1.3.x (Unix システム用)

このセクションでは、PHP を Unix プラットフォームの Apache 1.3.x にインストールする際の 手引きと注意事項について説明します。Apache 2 に関する手引きと注意 は 別のセクションにあります。

以下の説明では、バージョン番号が意図的に省略されています。 'xxx' の部分を使用するファイルに対応する番号に置き換えてください。 また、手順 10 で configure に与える引数は、 configure のすべてのオプション から選択できます。

例1 PHP インストール 手順 (Apache 共有モジュール版) 

1.  gunzip apache_xxx.tar.gz
2.  tar -xvf apache_xxx.tar
3.  gunzip php-xxx.tar.gz
4.  tar -xvf php-xxx.tar
5.  cd apache_xxx
6.  ./configure --prefix=/www --enable-module=so
7.  make
8.  make install
9.  cd ../php-xxx

10. PHP の configure を行います。ここでは、様々なオプションを指定して、
    特定の拡張モジュールを有効にするといった、カスタマイズを行います。
    指定可能なオプションの一覧は、./configure --help を実行すると得られ
    ます。以下に、簡単な設定例を示します。Apache 1 と MySQL のサポートを
    有効にする例です。apxs のパスは、Apache のインストールパスによって
    異なる場合があります。

      ./configure --with-mysql --with-apxs=/www/bin/apxs

11. make
12. make install

    configure オプションを変更して再インストールする場合は、最後の 3 つ
    の手順を繰り返します。共有モジュールとしてコンパイルされた PHP を
    有効にするには Apache を再起動するだけです。Apache の再コンパイルは
    必要ありません。

    特に指定がない限り、'make install' は、PEAR, phpize のような様々な
    関連ツール、CLI 版 PHP などもインストールすることに注意してください。

13. php.ini ファイルをセットアップ

      cp php.ini-development /usr/local/lib/php.ini

    PHP の実行時設定を変更するには、.ini ファイルを編集します。
    このファイルを他の場所に置きたい場合は、手順 10 で、
    オプション --with-config-file-path=/path を使用します。

    php.ini-development ではなく、php.ini-production を使用する場合は、PHP の
    動作が変化しますので、ファイル中に記載されている変更点の一覧を確認する
    ようにしてください。

14. httpd.conf を編集し、PHP の共有モジュールをロードするよう設定します。
    LoadModule 命令の右側に記述するパスは、システムの PHP 共有モジュール
    を指している必要があります。上記の make install により既にこの設定は
    追加されている場合もありますが、確認が必要です。

      LoadModule php5_module libexec/libphp5.so

15. httpd.conf の AddModule セクションに以下を追加します。
    ClearModuleList の下あたりに追加してください。

      AddModule mod_php5.c

16. Apache が特定の拡張子のファイルを PHP としてパースするよう（httpd.conf
    を編集して）設定します。例えば、Apache が拡張子 .php のファイルを PHP
    としてパースするように設定します。複数の拡張子も、空白で区切って記述する
    だけで PHP としてパースさせることができます。以下の例は .php と .phtml
    とを指定した場合です。

      AddType application/x-httpd-php .php .phtml

    PHP のソースをハイライト表示させるために、拡張子 .phps を設定することも
    よく行われます。

      AddType application/x-httpd-php-source .phps

17. Apache サーバーを、通常の手順通り、起動させます（HUP または USR1
    シグナルを 使用してリロードするのではなく、サーバーを停止させてから
    再起動する必要があります）。

PHP を静的オブジェクトとしてインストールすることも可能です。

例2 PHP インストール手順 (Apache 静的モジュール) 

1.  gunzip -c apache_1.3.x.tar.gz | tar xf -
2.  cd apache_1.3.x
3.  ./configure
4.  cd ..

5.  gunzip -c php-5.x.y.tar.gz | tar xf -
6.  cd php-5.x.y
7.  ./configure --with-mysql --with-apache=../apache_1.3.x
8.  make
9.  make install

10. cd ../apache_1.3.x

11. ./configure --prefix=/www --activate-module=src/modules/php5/libphp5.a

    (上の行は間違いではありません。この段階で libphp5.a は存在していませんが
    この時点での存在は必須ではなく、後に作成されます。)

12. make

    (httpd バイナリが作成され、Apache バイナリディレクトリにコピーすることが
    できます。最初のインストールの場合は、この後 "make install" を行います。)

13. cd ../php-5.x.y
14. cp php.ini-development /usr/local/lib/php.ini

15. /usr/local/lib/php.ini を編集すると、PHP の実行時設定を変更できます。
    httpd.conf もしくは srm.conf ファイルを編集し、以下を追記します。
    AddType application/x-httpd-php .php

インストールされている Apache や UNIX の種類によりますが、サーバーの停止・再起動の 方法はいくつもあります。いろいろな Apache/UNIX の組合せを想定して、 サーバーを再起動する典型的な方法を以下に示します。 /path/to/ を使用するシステムのアプリケーション へのパスに置き換えてください。

例3 Apache を再起動するためのコマンドの例

1. Linux および System V 系
/etc/rc.d/init.d/httpd restart

2. apachectl スクリプトを使用する方法
/path/to/apachectl stop
/path/to/apachectl start

3. (OpenSSL を使用している場合) httpdctl および httpsdctl を使用する方法
/path/to/httpsdctl stop
/path/to/httpsdctl start

4. mod_ssl や他の SSL サーバーを使用している場合、手動で stop や start する
/path/to/apachectl stop
/path/to/apachectl startssl

apachectl および http(s)dctl の実行ファイルの位置は、システムにより 異なります。システムが locate もしくは whereis、which コマンドを サポートしているなら、これらサーバー制御用プログラムを見つけるために使用すると 便利でしょう。

PHP を Apache 用にコンパイルするには、いくつかの方法があります。以下に例を示します。 

./configure --with-apxs --with-pgsql

この例では、Apache がロードする共有モジュールのライブラリ libphp5.so が作成されます。この共有ライブラリの読み込みは、Apache の設定ファイル httpd.conf の LoadModule の行にて設定します。また、このライブラリには、 PostgreSQL サポートが埋め込まれます。 

./configure --with-apxs --with-pgsql=shared

この例でも Apache 用 libphp5.so 共有ライブラリ が作成されます。加えて、（PHP 拡張モジュールの）共有ライブラリ pgsql.so も作成されます。この共有ライブラリ は、PHP 設定ファイル php.ini の extension ディレクティブにより、 もしくは PHP スクリプト内で明示的に dl() 関数により ロードされます。 

./configure --with-apache=/path/to/apache_source --with-pgsql

この例では、libmodphp5.a ライブラリと mod_php5.c およびいくつかの付属ファイルが 作成され、Apache のソースツリーのディレクトリ src/modules/php5 にコピーされます。続いて、 --activate-module=src/modules/php5/libphp5.a と指定して Apache をコンパイルしてください。Apache のビルドシステムにより、libphp5.a が作成され、 httpd バイナリに静的にリンクされます。 PostgreSQL サポートはこの httpd バイナリに 直接埋め込まれるため、最終的な結果としては、Apache 全体と PHP 全体を含む 単一の httpd バイナリが出来上がります。 

./configure --with-apache=/path/to/apache_source --with-pgsql=shared

この例は、上と同様ですが、最終的な httpd バイナリに PostgreSQL サポートは直接埋め込まれません。共有ライブラリ pgsql.so が作成され、PHP 設定ファイル php.ini、もしくは dl() 関数により明示的に PHP にロードすることができます。

PHP のビルド方法を選択する際には、各方法の利点と欠点を考慮する必要 があります。共有モジュールのオブジェクトとしてビルドすると、Apache とは別に コンパイルすることができ、PHP を追加または変更する際に全体を 再コンパイルする必要がありません。PHP を Apache に（静的に）組み込むと、 PHP はより高速にロード・実行されます。詳細な情報については、 Apache の Web ページ 「» 動的共有オブジェクト (DSO) サポート」 を参照してください。

注意:

Apache のデフォルトの httpd.conf には、次のように記述されたセクションがあります。 

User nobody
Group "#-1"
これを "Group nogroup" （や "Group daemon"）等に変更しないと、 PHP はファイルをオープンすることができません。

注意:

--with-apxs=/path/to/apxs オプションを 指定する場合には実際にシステムにインストールされている apxs を指定してください。 Apache のソースディレクトリ内にある apxs を指定してはいけません。

Apache 2.x (Unixシステム用)

このセクションでは、PHPを Unix システム上の Apache 2.x にインストールする際の 手引きと注意事項について説明します。

警告

Apache2 の MPM マルチスレッドモードを実運用環境で使用することは推奨されません。 代わりに prefork MPM を使ってください。これは Apache 2.0 および 2.2 におけるデフォルトの MPM です。prefork MPM を使う理由については、 マルチスレッド版 MPM の Apache2の FAQ エントリを参照してください。

» Apache ドキュメンテーション を参照し、Apache 2.x の基本的な事項について理解しておくことを強く推奨します。 Apache のインストールオプションについてのより詳しい情報が得られます。

最新バージョンの Apache HTTP Server を » Apache ダウンロードサイト からダウンロードし、上述のいずれかのバージョンの PHP を用意してください。 この手引きでは Apache 2.x で PHP を動作させるための 基本的な部分しかカバーしていません。さらに詳しい情報については、» Apache ドキュメンテーション を参照してください。 情報が古く不正確になってしまうため、以下では詳細なバージョン番号は 記述されていません。'NN' という文字列をご使用のバージョンに適宜置き換えて ください。

現在、Apache 2.x には 2.0 と 2.2 の二種類があります。 どちらを選ぶにしてもそれなりの理由があるでしょうが、 2.2 が現在の最新版です。もし選択の余地があるのなら 2.2 を使うことを推奨します。しかし、この例では 2.0 と 2.2 のどちらでも使えるようにしています。

  1. Apache HTTP server を上のサイトから取得して展開します。

    gzip -d httpd-2_x_NN.tar.gz
tar -xf httpd-2_x_NN.tar

  2. 同じく、PHP のソースを取得して展開します。

    gunzip php-NN.tar.gz
tar -xf php-NN.tar

  3. Apache をビルドしてインストールします。Apache のビルドに関する詳細は Apache のドキュメントを参照ください。 

    cd httpd-2_x_NN
./configure --enable-so
make
make install

  4. 以上で Apache 2.x.NN が、モジュールの動的ロードとデフォルトの MPM（マルチプロセッシングモジュール）である prefork が有効になった 状態で、/usr/local/apache2 にインストールされます。 インストールが正常か調べるには、以下のようにして Apache サーバーを立ち上げます。 

    /usr/local/apache2/bin/apachectl start
    サーバーを止めて、PHP 用の設定を進めましょう。 
    /usr/local/apache2/bin/apachectl stop

  5. PHP の configure を行います。ここでは、様々なオプションを指定し、 特定の拡張モジュールを有効にするといったカスタマイズを行います。 指定可能なオプションの一覧は、./configure --help を実行すると得られます。 以下に、Apache 2 と MySQL のサポートを有効にする、簡単な設定例を示します。

    上で説明したように Apache をソースからビルドした場合は、 apxs のパスも下の例のとおりになっているでしょう。しかし、 もし別の方法で Apache をインストールした場合は apxs のパスを適切に変更しなければなりません。 ディストリビューションによっては、apxs の名前が apxs2 と変更されていることもあるので注意しましょう。 

    cd ../php-NN
./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql
make
make install

    configure オプションを変更して再インストールする場合は、 configure, make, make install の手順を繰り返さなければなりません。 共有モジュールとしてコンパイルされた PHP を有効にするには Apache を再起動するだけです。Apache の再コンパイルは不要です。

    特に断りがない限り、'make install' は、PEAR、phpize のような様々な 関連ツール、CLI 版 PHP などもインストールすることに注意してください。

  6. php.ini ファイルを設定する 

    cp php.ini-development /usr/local/lib/php.ini

    PHP の実行時設定を変更するには、.ini ファイルを編集します。 このファイルを他の場所に置きたい場合は、手順 5 で、 オプション --with-config-file-path=/path を使用します。

    php.ini-development ではなく、php.ini-production を使用する場合は、PHP の 動作が変化しますので、ファイル中に記載されている変更点の一覧を確認する ようにしてください。

  7. httpd.conf を編集し、PHP の共有モジュールをロードするよう設定します。 LoadModule 命令の右側に記述するパスは、システムの PHP 共有モジュール を指している必要があります。上記の make install により既にこの設定は 追加されている場合もありますが、確認が必要です。 

    LoadModule php5_module modules/libphp5.so

  8. Apache が特定の拡張子のファイルを PHP としてパースするよう設定します。 たとえば、Apache が拡張子 .php のファイルを PHP としてパースするようにします。 単に Apache の AddType ディレクティブを使うだけではなく、 悪意を持ってアップロード (あるいは作成) された exploit.php.jpg のようなファイルが PHP として実行されてしまわないようにしたいものです。 この例では、PHP としてパースさせたい任意の拡張子を追加していくだけです。 ためしに .phtml を追加してみましょう。 

    <FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

    あるいは、拡張子 .php, .php2, .php3, .php4, .php5, .php6, そして .phtml のファイルだけを PHP として実行したいは、このようにします。 

    <FilesMatch "\.ph(p[2-6]?|tml)$">
    SetHandler application/x-httpd-php
</FilesMatch>

    拡張子 .phps のファイルを php ソースフィルタに処理させて 構文ハイライトつきのソースコードとして表示させるには、このようにします。 

    <FilesMatch "\.phps$">
    SetHandler application/x-httpd-php-source
</FilesMatch>

    mod_rewrite を使うと、.phps ファイルに名前を変えたりコピーしたりしなくても 任意の .php ファイルを構文ハイライトつきのソースコードとして表示させることができます。 

    RewriteEngine On
RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]

    php ソースフィルタは、実運用環境では無効にしておかなければなりません。 有効にしてしまうと、ソースコードに埋め込まれた機密情報や重要情報が漏れてしまう危険があります。

  9. Apache サーバーを、通常の手順通り、起動させます。 

    /usr/local/apache2/bin/apachectl start

    OR

    service httpd restart

上記の手順で、Apache2 ウェブサーバー上で SAPI モジュールとして PHP を動作させることができます。もちろん、Apacheと PHP の双方とも、もっと多くの configure オプションを指定することが出来ます。 詳しい情報を得るには、ソースツリーディレクトリで ./configure --help を実行してください。

マルチスレッド版の Apache をビルドするには、Apache のビルド時に標準の prefork MPM ではなく worker MPM を選択します。 そのためには、先ほどの手順 3 のところで ./configure の引数に次のオプションを追加します。


--with-mpm=worker

そうすることで何がどのようになるのかをきちんと認識したうえで、これを行わなければなりません。 詳細については Apacheドキュメントの » マルチプロセッシングモジュール (MPM) を参照してください。

注意:

Apache MultiViews FAQ では、PHP でマルチビューを使う方法について解説しています。

注意:

マルチスレッド版の Apache をビルドするには、ターゲットシステムがスレッドに対応していなければなりません。 その場合は、PHP についても実験的な Zend Thread Safety (ZTS) でビルドしなければなりません。 この構成では使用できない拡張モジュールもあります。推奨される方法は、Apache をデフォルトの prefork MPM モジュールでビルドすることです。

Lighttpd 1.4 (Unix システム用)

ここでは、Unix システム上の Lighttpd 1.4 で PHP を使用する際の注意点とヒントをまとめます。

まず » Lighttpd trac で Lighttpd のインストール方法をよく読んでからこれ以降に進みましょう。

PHP と Lighttpd を組み合わせる際におすすめの SAPI は fastcgi です。 fastcgi は PHP 5.3 以降の php-cgi では自動的に有効になりますが、 それより前のバージョンの場合は php の configure 時に --enable-fastcgi を指定しなければなりません。 PHP で fastcgi が有効になっているかどうかを調べるには、 php -v の結果が PHP 5.2.5 (cgi-fcgi) のようになっているかどうかを確認します。 PHP 5.2.3 以前の場合は、(php-cgi ではなく) php バイナリで fastcgi が使えるようになります。

Lighttpd に php プロセスを起動させる

Lighttpd から php に接続して fastcgi プロセスを立ち上げさせるよう設定するには、 lighttpd.conf を編集します。ローカルシステムの fastcgi プロセスに接続するにはソケットの使用をおすすめします。

例1 lighttpd.conf の抜粋

server.modules += ( "mod_fastcgi" )

fastcgi.server = ( ".php" =>
  ((
    "socket" => "/tmp/php.socket",
    "bin-path" => "/usr/local/bin/php-cgi",
    "bin-environment" => (
      "PHP_FCGI_CHILDREN" => "16",
      "PHP_FCGI_MAX_REQUESTS" => "10000"
    ),
    "min-procs" => 1,
    "max-procs" => 1,
    "idle-timeout" => 20
  ))
)

bin-path ディレクティブにより、lighttpd が fastcgi プロセスを動的に起動できるようになります。 PHP は、環境変数 PHP_FCGI_CHILDREN の内容に応じて子プロセスを起動します。 "bin-environment" ディレクティブは、起動するプロセスの環境を設定します。 リクエストの数が PHP_FCGI_MAX_REQUESTS の値に達すると、 PHP は子プロセスを kill します。ディレクティブ "min-procs" および "max-procs" は、PHP での使用は避けるべきです。 PHP は自身の子プロセスを自前で管理しますし、 APC のような opcode キャッシュは PHP が管理する子プロセスしか共有しません。 "min-procs" を 1 より大きい値に設定すると、 PHP レスポンダの数が PHP_FCGI_CHILDREN にその値をかけたものとなります (2 min-procs * 16 子プロセスで 32 のレスポンダとなります)。

spawn-fcgi での起動

Lighttpd には spawn-fcgi というプログラムが含まれており、 fastcgi プロセスの起動を簡単に行えるようになっています。

php-cgi の起動

spawn-fcgi なしでプロセスを起動することもできますが、多少難易度が上がります。 環境変数 PHP_FCGI_CHILDREN で、PHP がリクエストの処理用に起動する子の数を設定します。 PHP_FCGI_MAX_REQUESTS は、各子プロセスの生存期間 (リクエスト数) を設定します。php レスポンダを起動するシンプルな bash スクリプトの例を以下に示します。

例2 FastCGI レスポンダの起動

#!/bin/sh

# php-cgi バイナリの場所
PHP=/usr/local/bin/php-cgi

# PID ファイルの場所
PHP_PID=/tmp/php.pid

# アドレスへのバインド
#FCGI_BIND_ADDRESS=10.0.1.1:10000
# ドメインソケットへのバインド
FCGI_BIND_ADDRESS=/tmp/php.sock

PHP_FCGI_CHILDREN=16
PHP_FCGI_MAX_REQUESTS=10000

env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
       PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
       $PHP -b $FCGI_BIND_ADDRESS &

echo $! > "$PHP_PID"

リモートの FCGI インスタンスへの接続

fastcgi インスタンスを複数のリモートマシンで起動して、 アプリケーションの規模を拡大することができます。

例3 リモートの php-fastcgi インスタンスへの接続

fastcgi.server = ( ".php" =>
   (( "host" => "10.0.0.2", "port" => 1030 ),
    ( "host" => "10.0.0.3", "port" => 1030 ))
)

Sun, iPlanet, Netscape サーバー（Sun Solaris 用）

このセクションでは、Sun Solaris 上の Sun Java System Web Server, Sun ONE Web Server, iPlanet and Netscape server に PHP をインストールする際の 手引きと注意事項について説明します。

PHP 4.3.3 より、NSAPI モジュール を使って 独自エラーページ および ファイル一覧表示ページの生成 が可能です。 Apache 互換の関数も追加されています。 また、これらの Web サーバーについての サブリクエストに関する注意 も参照してください。

Netscape Enterprise Server (NES) への PHP のインストールに関しては » http://benoit.noss.free.fr/php/install-php4.html にも情報があります。

Sun JSWS/Sun ONE WS/iPlanet/Netscape Web サーバー用に PHP をビルド するには、--with-nsapi=[DIR] オプションに適切なインストールディレクトリを指定してください。 デフォルトのディレクトリは、通常、/opt/netscape/suitespot/ です。 /php-xxx-version/sapi/nsapi/nsapi-readme.txt も参照してください。

  1. 以下のパッケージを、»  http://www.sunfreeware.com/ や他のダウンロードサイトから取得し、 インストールします。

    • autoconf-2.13
    • automake-1.4
    • bison-1_25-sol26-sparc-local
    • flex-2_5_4a-sol26-sparc-local
    • gcc-2_95_2-sol26-sparc-local
    • gzip-1.2.4-sol26-sparc-local
    • m4-1_4-sol26-sparc-local
    • make-3_76_1-sol26-sparc-local
    • mysql-3.23.24-beta (mysql サポートが必要な場合)
    • perl-5_005_03-sol26-sparc-local
    • tar-1.13 (GNU tar)

  2. パスを適切に設定します ( PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin )。 そして、export PATHとし、パスを有効にします。
  3. gunzip php-x.x.x.tar.gz (.gz 配布の場合のみ)
  4. tar xvf php-x.x.x.tar
  5. PHP を展開したディレクトリに移動します cd ../php-x.x.x

  6. 以下のステップを実施します。 /opt/netscape/suitespot/ は netscape サーバーがインストールされている場所です。 異なる場合は、適切なパスに変更してください。 

    ./configure --with-mysql=/usr/local/mysql \
--with-nsapi=/opt/netscape/suitespot/ \
--enable-libgcc

  7. make を実行し、その後 make install を実行します。

基本インストールを実行したら、適当な readme ファイルを参照してください。 いくつかの追加インストール手順を実行する必要があるかもしれません。

Sun/iPlanet/Netscape の設定手順

まず、共有ライブラリの探索のために、環境変数 LD_LIBRARY_PATH にパスをいくつか追加する必要があります。 Webサーバーの開始スクリプトで行うのが最善でしょう。 開始スクリプトは、通常 /path/to/server/https-servername/start にあります。 また、/path/to/server/https-servername/config/ にある設定ファイルの編集も必要です。

  1. mime.typesに次の行を追加します (administration server で行えます。) 

    type=magnus-internal/x-httpd-php exts=php

  2. magnus.conf (サーバー>= 6の場合) または obj.conf (サーバー< 6の場合) を編集し、 以下の行を追加します。 ここで、shlib はシステムにより異なります。 /opt/netscape/suitespot/bin/libphp4.so 等となるでしょう。 mime types init の後に置いてください。 

    Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="/opt/netscape/suitespot/bin/libphp4.so"
Init fn="php4_init" LateInit="yes" errorString="Failed to initialize PHP!" [php_ini="/path/to/php.ini"]
    (PHP >= 4.3.3) php_ini パラメータはオプションですが、 これを指定することにより、Web サーバーの設定ファイルがあるフォルダに php.ini を置くことが可能になります。

  3. obj.conf のデフォルトオブジェクトを設定します （バージョン 6 以降の仮想サーバーの場合は vserver.obj.conf。） 

    <Object name="default">
.
.
.
.#NOTE this next line should happen after all 'ObjectType' and before all 'AddLog' lines
Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...]
.
.
</Object>
    (PHP >= 4.3.3) 追加のパラメータとして、いくつかの特別な php.ini 値を 追加することができます。例えば、コンテキスト php4_execute に対して docroot="/path/to/docroot" を設定するなどです。 また、論理値の場合、0/1 を値として使用してください。 "On","Off",... では正しく動作しません。 例えば、zlib.output_compression="On" ではなく、 zlib.output_compression=1 とします。

  4. 以下は、（cgi-bin ディレクトリ のように） PHP スクリプトだけが置かれるディレクトリを設定したい場合にのみ必要です。 

    <Object name="x-httpd-php">
ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
Service fn=php4_execute [inikey=value inikey=value ...]
</Object>
    こうしておくと、Administration Server に特定のディレクトリを設定し、 これをスタイル x-httpd-php に割り付けることができます。 このディレクトリの中にあるすべてのファイルは PHP スクリプト として実行されます。 これは、ファイルの拡張子を .html に変更し、 PHP が使用されている事を隠したい場合に有用です。

  5. 認証を設定します。PHP による認証は他の認証と併用することはできません。 すべての認証は、PHP スクリプトに渡されます。 サーバー全体に対して PHP 認証を設定する場合は、以下の行を追加してください。 

    <Object name="default">
AuthTrans fn=php4_auth_trans
.
.
.
</Object>

  6. 単一のディレクトリでのみ PHP による認証を行う場合は、次の行を追加します。 

    <Object ppath="d:\path\to\authenticated\dir\*">
AuthTrans fn=php4_auth_trans
</Object>

注意:

PHP が使用するスタックサイズは Web サーバーの設定に依存します。 非常に大きい PHP スクリプトを実行させた際にクラッシュが発生する場合は、 Administration Server でスタックサイズ（"MAGNUS EDITOR"） を大きくすると良いでしょう。

CGI 環境変数と php.ini の変更

Sun JSWS/Sun ONE WS/iPlanet/Netscape がマルチスレッドの Web サーバーだという事が PHP スクリプトを書く際に重要になります。すべてのリクエストは同一の （Web サーバー自体の）プロセス空間で実行され、そのプロセス空間は 1 つの環境変数しか 持っていません。PATH_INFO や HTTP_HOST CGI 変数を取得する場合、 古い PHP で行っていたような方法、つまり getenv() 関数を使用する方法や他の同等な方法 （グローバル変数の登録機能、 $_ENV 等）を使うのは正しい方法ではありません。 Web サーバーの環境変数をただ単に取得するだけと、 正しい CGI 変数は得られないのです。

注意:

なぜ正しくない CGI 変数が登録されているのでしょうか？

それは、Web サーバーのプロセスを Administration Server から起動させる際、 Web サーバーの起動スクリプトが CGI スクリプトとして実行されるためです。したがって、 起動された Web サーバーの環境変数には CGI 変数も含まれることになります。 Administration Server 以外から Web サーバーを起動してみればこのことをテストできるでしょう。 ルートユーザーでコマンドラインを使って、手動で起動してみると、CGI 変数らしき 環境変数が登録されないことが確認できるでしょう。

PHP 4.x のスクリプトで CGI 変数を取得する場合は、スーパーグローバル $_SERVER を用いるのが正しい方法です。また、$HTTP_HOST などを使う古いスクリプトを使用する場合は、php.ini で register_globals をオンにし、変数のパースの順番 (variables_order) を変更してください （"E" を削除。環境変数を読み込む必要は無いため。） 

variables_order = "GPCS"
register_globals = On

独自エラーページおよびファイル一覧表示ページ (PHP >= 4.3.3)

PHP を使って、"404 Not Found" などに対するエラーページを生成することが できます。オーバーライドしたいすべてのエラーページ対して、以下の行を obj.conf 中のオブジェクトに追加してください。 

Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]
ここで、XXX は HTTP のエラーコードです。 追加したものと干渉する Error ディレクティブは削除してください。 発生するすべてのエラーに対応するページを設定したい場合は、 code パラメータを省略してください。スクリプトで HTTP ステータス コードを取得するには、 $_SERVER['ERROR_TYPE'] を使用します。

独自のファイル一覧表示ページを PHP を使って生成することも可能です。 ファイル一覧表示を行う PHP スクリプトを作成し、obj.conf の type="magnus-internal/directory" の行に 書かれているデフォルトの Service 行を以下のように置き換えます。 

Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]
エラーページ、ファイル一覧表示ページのいずれでも、元の URI および 変換後の URI は、それぞれ、$_SERVER['PATH_INFO'] および $_SERVER['PATH_TRANSLATED'] に格納されます。

nsapi_virtual() および サブリクエストに関する注意 (PHP >= 4.3.3)

NSAPI モジュールは、現在、nsapi_virtual() 関数 (エイリアス: virtual()) をサポートしており、 Web サーバーへサブリクエストを行い、結果を Web ページへ挿入することができます。 ただし、この関数は NSAPI ライブラリの文書化されていない機能を若干使用しています。 モジュールは、自動的に必要な関数群を探し、可能であればそれらの関数を 使用ます。もし使用可能でなければ、nsapi_virtual() 関数は 使用不可となります。

注意:

nsapi_virtual() サポートは「実験的」な機能です。

CGI およびコマンドライン

デフォルトでは、PHP は CLI および CGI プログラムとしてビルドされます。 これを使って CGI の処理を行うことができます。 PHP 側で対応するモジュールを用意しているウェブサーバーで実行するときには、 モジュールを使うほうがパフォーマンス面で有利です。 しかし、CGI 版にも利点があります。 PHP を含むページを別のユーザー ID で実行することができるということです。

警告

CGI モードで公開したサーバーは、いくつかの脆弱性の標的となる可能性があります。 これらの攻撃からサーバーを守る方法については、 CGI セキュリティ のセクションを参照してください。

テスト

PHP を CGI 版のプログラムとしてビルドした場合、make test とすることで、ビルドされたバイナリをテストすることが 可能です。常にビルド後のテストを行うことが推奨されます。これにより、 使用するプラットホームにおける PHP の問題を早期に見付けることが可能となり、 後になってその問題に苦しむことがなくなるでしょう。

環境変数の使用

いくつかのサーバーが提供する環境変数 は、現在の » CGI/1.1 規約 において定義されていません。以下の変数だけがこの規約で定義されています。 AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, および SERVER_SOFTWARE 。 その他の環境変数は、「ベンダー拡張」として取り扱うべきです。

HP-UX へのインストール

このセクションでは、HP-UX へインストールする場合特有の注意とコツについて説明します

PHP を HP-UX にインストールするには、二通りの方法があります。 自分でコンパイルするか、あるいはコンパイル済みのバイナリを使用するかのどちらかです。

公式のコンパイル済みパッケージは、こちらにあります。 » http://software.hp.com/

このセクションをきちんと書き直すまで、PHP (および拡張モジュール) を HP-UX でコンパイルする方法についてのドキュメントをいったん削除します。 当面は、以下のドキュメントを参照ください。 » Building Apache and PHP on HP-UX 11.11

OpenBSD へのインストール

このセクションでは、PHP を » OpenBSD 3.6 に インストールする場合に固有の注意事項とヒントについて説明します。

バイナリパッケージの使用

OpenBSD に PHP をインストールするには、バイナリパッケージを使用することが もっとも簡単で、また推奨される方法です。 コアパッケージは他のモジュールと分けられており、別個に インストールしたり、削除したりすることができます。OpenBSD の CD や FTP サイトから 必要なファイルを見つけることができます。

インストールに必要なメインのパッケージは php4-core-4.3.8.tgz です。これには基本エンジン (と gettext と iconv) が含まれています。次に、 php4-mysql-4.3.8.tgz や php4-imap-4.3.8.tgz のようなモジュールパッケージを 探してください。これらのモジュールを php.ini 上で有効/無効にするには phpxs コマンドを使用する必要があります。

例1 OpenBSD パッケージインストールの例

# pkg_add php4-core-4.3.8.tgz
# /usr/local/sbin/phpxs -s
# cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini
  (add in mysql)
# pkg_add php4-mysql-4.3.8.tgz
# /usr/local/sbin/phpxs -a mysql
  (add in imap)
# pkg_add php4-imap-4.3.8.tgz
# /usr/local/sbin/phpxs -a imap
  (remove mysql as a test)
# pkg_delete php4-mysql-4.3.8
# /usr/local/sbin/phpxs -r mysql
  (install the PEAR libraries)
# pkg_add php4-pear-4.3.8.tgz

OpenBSD のバイナリパッケージに関する詳細は、man ページの » packages(7) を 参照してください。

Ports の使用

» ports ツリー を使って PHP のソースを コンパイルすることもできます。ただし、この方法は OpenBSD に詳しいユーザーにのみ 推奨されます。PHP 4 ポートは core, extensions の 2 つのサブディレクトリに 分割されています。extensions ディレクトリはサポートされているすべての PHP モジュールのサブパッケージを生成します。 これらのうちのいずれかのモジュールを生成したくない場合には、 no_* FLAVOR を使用してください。例えば、imap モジュール のビルドをスキップするには FLAVOR を no_imap に セットします。

一般的な問題点

  • Apache は、デフォルトインストールでは、 » chroot(2) jail 内で実行されます。 これにより、PHP は、/var/www 以下のファイルにしか アクセスできないように制限されます。そのため、セッションを使用するには、 /var/www/tmp ディレクトリを作成するか、他のセッションバックエンドを 用いる必要があります。また、データベースのソケットは jail 内に置かれるか、 localhost インターフェイスが listen できるようにする必要があります。 ネットワーク関数を使用する場合は、/etc 内のファイル、たとえば /etc/resolv.conf や /etc/services を、 /var/www/etc に移動させる必要があります。 OpenBSD の PEAR パッケージは、適切な chroot 内のディレクトリに自動的にインストールされますので、 特に修正は必要ありません。OpenBSD における Apache についての詳細は » OpenBSD FAQ を参照してください。
  • OpenBSD 3.6 においては、» gd 拡張モジュールのパッケージは XFree86 のインストールを必要とします。X11 が必要となるいくつかのフォント機能を使わない場合は、 代わりに php4-gd-4.3.8-no_x11.tgz パッケージをインストールしてください。

過去のリリース

OpenBSD の過去のリリースは、静的にリンクされた PHP をコンパイルするために FLAVORS システムを使用していました。 この方法でバイナリパッケージを作成することは困難なため、 この方法は現在は使用されていません。 古い安定版の ports ツリーを使用することもできますが、 これらは OpenBSD チームによりサポートされていません。 これに関するコメントがある場合、port の現在の管理者は Anil Madhavapeddy (avsm at openbsd dot org) です。

Solaris へのインストール

このセクションでは、Solaris に PHP をインストールする際の注意とコツを説明します。

必要なソフトウエア

Solaris には、C コンパイラおよび関連するツールがインストールされていない事が しばしばあります。GNU 版の各種ツールが必要となりますが、その理由については こちらの FAQ をお読みください。

PHP の配布物を展開するために必要なソフトウエアは

  • tar
  • gzip あるいは
  • bzip2

PHP をコンパイルするために必要なのは

  • gcc (推奨。他のC コンパイラも動作するかもしれません)
  • make
  • GNU sed

別の拡張モジュールをビルドしたり PHP のコードをハックしたりするためには、これらも必要になるでしょう。

  • flex (PHP 5.2 まで)
  • re2c
  • bison
  • m4
  • autoconf
  • automake
加えて、(Oracle や MySQLなどの) 使用する設定に応じた追加ソフトウエアを インストール（おそらくはコンパイルも）する必要があります。

パッケージの使用

Solaris へのインストールでは、 pkgadd を使用すれば、必要なコンポーネントのインストール処理を 簡単に行うことができます。 The Image Packaging System (IPS) for Solaris 11 Express にも、pkg コマンドを使ったインストールに必要なコンポーネントの大半が含まれています。

Debian GNU/Linux へのインストール

このセクションでは、» Debian GNU/Linux に PHP をインストールする際の注意事項とヒントについて説明します。

警告

サードパーティが作った非公式のビルドについてはここではサポートしていません。 何かバグを見つけた場合は、 » ダウンロードページ から取得した最新のビルドでそれが再現するかを確認し、 再現しない場合は Debian チームにバグ報告をお願いします。

Unix 上で PHP をビルドする方法は Debian でもそのまま使えます。 しかし、このページではもうひとつの方法として Debian 固有の情報を扱います。 apt-get や aptitude といったコマンドの使い方です。 このマニュアルページでの説明は、これらふたつのコマンドのどちらを使っても実行できます。

APT の使用

まず、Apache 2 と統合する場合は libapache2-mod-php5、PEAR を使う場合は php-pear などの関連パッケージが必要となることを知っておきましょう。

次に、パッケージをインストールする前にはパッケージ一覧を最新に更新しておくようにしましょう。 これは、apt-get update コマンドで行います。

例1 Debian で Apache 2 と組み合わせるインストール例

# apt-get install php5-common libapache2-mod-php5 php5-cli

APT により、Apache 2 用の PHP 5 モジュールとその依存モジュールが自動的にインストールされます。 インストール中に Apache を再起動する旨が表示されなかった場合は、手動で再起動する必要があります。

例2 PHP インストール後に Apache を停止・起動させる

# /etc/init.d/apache2 stop
# /etc/init.d/apache2 start

よりよい設定の管理

ここまでのセクションでは、PHP のコアモジュールだけをインストールしました。 おそらく、さらに MySQL や cURL、 GD などの追加モジュールもインストールしたくなることでしょう。 これらも apt-get コマンドでインストールすることができます。

例3 追加の PHP 5 パッケージを探す方法

# apt-cache search php5
# aptitude search php5
# aptitude search php5 |grep -i mysql

上記の出力を見てわかるとおり、(php5-cgi や php5-cli, php5-dev といった 特別なパッケージのほかにも) さまざまなパッケージがあり、インストールすることが可能です。 必要なものを見定めて、apt-get か aptitude でインストールしましょう。 Debian は依存性のチェックを行うので、たとえば MySQL と cURL をインストールする場合はこのようになります。

例4 PHP と MySQL、cURL のインストール

# apt-get install php5-mysql php5-curl

APT は自動的に、 /etc/php5/apache2/php.ini や /etc/php5/conf.d/pdo.ini などの php.ini に適切な行を追加し、extension=foo.so といった内容が書き込まれます。しかし、これらの変更を有効にするにはウェブサーバー (Apache など) を再起動しなければなりません。

よく起きる問題

  • PHP スクリプトがウェブサーバーで実行されない場合は、 おそらく PHP がウェブサーバーの設定ファイルに追加されていないのでしょう。 Debian の場合、設定ファイルは /etc/apache2/apache2.conf のようになります。詳細は Debian のマニュアルを参照ください。
  • 拡張モジュールをインストールしたのに関数が未定義だと言われたら、 適切な ini ファイルが読み込まれているかどうかと インストール後にウェブサーバーを再起動したかどうかを確認しましょう。
  • Debian (およびその派生物) でパッケージをインストールする基本的なコマンドは apt-get と aptitude のふたつです。 しかし、これらのコマンドの微妙な違いについての説明は、このマニュアルでは行いません。

Mac OS X へのインストール

目次

本章では、PHP を Mac OS X 上にインストールする際の注意事項とコツを説明します。 PHP は Mac にバンドルされています。また、コンパイルの手順は Unix へのインストールガイド と同じです。

パッケージの使用

Mac OS X 用にコンパイルされた PHP パッケージがいくつか存在します。 一般的なセットアップを行うにあたって、利用することができます。ただし、 （セキュアサーバーや様々なデータベースドライバなど）少々特殊な機能が必要な場合、 PHP を自分でビルドする必要が有るかもしれません。ソフトウエアの ビルドやコンパイルに不慣れな場合は、必要な機能を含めてビルドされたパッケージを 誰か他の人が作成済みでないかを調べてみると良いでしょう。

以下の場所に、簡単にインストールできる Mac OS 用のコンパイル済み PHP パッケージがあります。

バンドルされている PHP の使用法

PHP は、OS X バージョン 10.0.0 以降の Mac に標準添付されています。 デフォルトのウェブサーバーで PHP を有効にするには、Apache 設定ファイル httpd.conf で数行のコメントを解除する必要があります。 一方、CGI や CLI はデフォルトで有効になっています (ターミナルから簡単に利用できます)。

PHP を有効にするには以下の手順を使用してください。 これは、ローカルの開発環境を手早く設定する方法を示したものです。 常に PHP を最新バージョンに更新することを 強く推奨します。 多くのソフトウェアでは、新しいバージョンでは多くのバグが修正されています。 また機能追加もされています。PHP も同様です。 詳細は、適切な MAC OS X インストールドキュメントを参照ください。 以下の手順は初心者を対象としたもので、 まずデフォルトの設定で動作させるための手順を示しています。 すべてのユーザーが、新しいパッケージ版をコンパイルしてインストールすることを推奨します。

標準的なインストール方法は mod_php を使用するものです。Mac OS X 上の Apache web server (デフォルトのウェブサーバーで、System Preferences からアクセスできます) 上に、mod_php を組み込むには次のようにします。

  1. Apache の設定ファイルを開きます。デフォルトでは /private/etc/apache2/httpd.conf にあります。 Finder あるいは Spotlight を使用してこれを見つけることは難しいでしょう。 このファイルはプライベート設定されており、その所有者は root ユーザーだからです。

    注意: Unix ベースのテキストエディタ、たとえば nano を用いて、ターミナルでこのファイルを開きます。このファイルの所有者は root なので、sudo コマンドを使用して (root として) 開く必要があります。つまり、ターミナル上で sudo nano /private/etc/apache2/httpd.conf と入力します (その後、パスワードを聞かれます)。 覚えておくべき nano コマンドは次のとおりです。^w (検索)、 ^o (保存) そして ^x (終了)。 ここで ^ は Ctrl キーを表します。

    注意: Mac OS X 10.5 より前のバージョンにバンドルされている PHP および Apache は、バージョンが古いものです。その場合、Apache の設定ファイルは /etc/httpd/httpd.conf となります。

  2. テキストエディタで、次のような行 (これらのふたつの行は並んでいないこともあります。 それぞれをファイル中で探してください) のコメントをはずします (# を削除します)。 

    # LoadModule php5_module libexec/httpd/libphp5.so

# AddModule mod_php5.c
    パスに注意しましょう。将来 PHP をビルドする際には 上のファイルは移動するかコメントアウトする必要があります。

  3. 指定した拡張子 (例: .php .html および .inc) が PHP でパースされるようにします。

    以下のような行が httpd.conf にあれば (Mac Panther 以降にはあります)、 PHP を有効にするだけで .php ファイルが自動的に PHP で処理されます。 

    <IfModule mod_php5.c>
    # If php is turned on, we respect .php and .phps files.
    AddType application/x-httpd-php .php
    AddType application/x-httpd-php-source .phps

    # Since most users will want index.php to work we
    # also automatically enable index.php
    <IfModule mod_dir.c>
        DirectoryIndex index.html index.php
    </IfModule>
</IfModule>

    注意:

    OS X 10.5 (Leopard) より前のバージョンには PHP 5 ではなく PHP 4 がバンドルされています。その場合は、ここまでの説明にある 5 という部分を 4 に読み替えてください。

  4. DirectoryIndex でデフォルトインデックスファイルが読み込まれるようにします。 これも httpd.conf で設定します。典型的なパターンは index.php および index.html でしょう。デフォルトでは index.php が有効になります。上で見たような設定がすでにあるからです。 これを適切に調整しましょう。
  5. php.ini の場所を設定するか、デフォルトを使用します。 Mac OS X におけるデフォルトの場所は /usr/local/php/php.ini で、 phpinfo() をコールするとこの情報を表示します。 php.ini を使用しない場合は、PHP はすべてデフォルト値を使用します。 php.ini ファイルはどこにおけばいいのですか? が、関連する FAQ です。
  6. DocumentRoot を配置あるいは設定します。 これは、すべてのウェブファイルのルートディレクトリとなります。 このディレクトリ内のファイルはウェブサーバーで処理されるようになるので、 PHP ファイルは PHP でパースしてからブラウザに出力されます。 典型的なデフォルトのパスは /Library/WebServer/Documents ですが、これは httpd.conf で別の場所にすることができます。 また、各ユーザーの DocumentRoot は /Users/yourusername/Sites となります。
  7. phpinfo() ファイルを作成します。

    phpinfo() 関数は、PHP についての情報を表示します。 DocumentRoot 内に、次のような PHP コードを含むファイルを作成してください。

    <?php phpinfo(); ?>

  8. Apache を再起動し、先ほど作成した PHP ファイルを読み込みます。 再起動するには、シェルで sudo apachectl graceful を実行するか、あるいは OS X System Preferences で "Personal Web Server" オプションを使用して停止/起動します。 デフォルトでは、ローカルファイルをブラウザで読み込むには http://localhost/info.php のような URL を指定します。 あるいは、各ユーザーディレクトリの DocumentRoot の場合は http://localhost/~yourusername/info.php のようになります。

CLI (あるいは旧バージョンの CGI) は、php という名前で、おそらく /usr/bin/php にあります。 ターミナルを開き、PHP マニュアルの Open up the terminal, read the PHP をコマンドラインから使用する を読んだうえで php -v を実行してみましょう。 これは、PHP バイナリのバージョンを表示します。 phpinfo() をコールしても、この情報を取得できます。

Mac OS X 上での PHP のコンパイル

PHP を Mac OS X 上でコンパイルする手順については、 Unix へのインストールガイド をご利用ください。

Windows システムへのインストール

目次

本章は、Windows 98/Me および Windows NT/2000/XP に適用されます。 PHP は、Windows 3.1 などの 16 ビットのプラットフォームでは動作しません。 PHP がサポートする Windows プラットフォーム を Win32 と呼ぶことがあります。

注意:

Windows 98/Me/NT4 は、PHP 5.3.0 以降サポートされなくなりました。

注意:

Windows 95 は、PHP 4.3.0 以降サポートされなくなりました。

PHP を Windows にインストールするには、 マニュアルインストール と インストーラによる方法 の 2 種類があります。

Microsoft Visual Studio などの開発環境を持っていれば、オリジナルのソースコードから PHP を ビルドする ことも可能です。

Windows システムに PHP をインストールした後、機能を追加するために 拡張モジュールのロード が必要な場合があります。

警告

インターネットでオールインワンのインストーラがいくつか見かけられます。 しかし、いずれも PHP.net により公認されたものではありません。 システムを最適化し、また、安全を保つためには、 » http://www.php.net/downloads.php にある公式 Windows パッケージのいずれかを使用することが もっとも良い選択ではないかと我々は考えています。

Windows インストーラ (PHP 5.1.0 以前)

CGI 版の PHP をインストールする Windows 用 PHP インストーラが、 » http://www.php.net/downloads.php から取得可能です。 IIS、PWS、Xitami に対しては Web サーバーの設定も同時に行われます。 このインストーラには、PHP 拡張モジュール (php_*.dll) が含まれていません。 拡張モジュールは、Zip パッケージもしくは PECL ダウンロード からのみ入手できます。

注意:

Windows インストーラは PHP を動作させるための簡便な方法で、 （拡張モジュールの自動設定ができないといった）制約がいくつかあります。 インストーラの利用は、PHP をインストールする最適な方法ではありません。

まずはじめに、使用する HTTP (Web) サーバーを システムにインストールし、完全に動作するようにして下さい。

インストーラを実行し、インストールウイザードの指示に従って下さい。 2 種類のインストール方法がサポートされています。一つ目は standard で、 設定の選択肢についてデフォルト値が示されます。もう一つは advanced で、 選択肢について質問が行われます。

インストールウイザードは、php.ini ファイルを設定し、 PHP が使用可能となるように Web サーバーを設定するために必要な情報を集めます。 ただし、Apache をはじめとするいくつかの web サーバーでは、インストーラによる自動での 設定変更は行われず、手動で設定変更する必要があります。

インストールが完了すると、システムもしくはサーバーを再起動する必要があるのか、 そのまま PHP の使用を開始すればよいのか表示されます。

警告

こうしてインストールされた PHP の設定は安全ではないことに注意して下さい。安全に PHP を設定したい場合は、マニュアルでインストールし、オプションを注意深く設定するべきです。 上記の自動設定により PHP のインストールを瞬時に行うことが可能となりますが、 インターネットに接続されたサーバーで使用されうるものではありません。

Windows インストーラ (PHP 5.2 以降)

Windows 用 PHP インストーラの最新版は、MSI 形式になっています。これは Wix Toolkit (» http://wix.sourceforge.net/) で作成されています。 このインストーラは、インストールおよび PHP の設定、そして組み込みのモジュールと PECL 拡張モジュールの設定だけでなく、 IIS、Apache そして Xitami などといった多くのウェブサーバーの設定も行います。

最初に、お好みの HTTP (ウェブ) サーバーをシステムにインストールし、動作確認をします。 それから、次のうちのいずれかのインストール形式を選択します。

通常のインストール

MSI インストーラを実行し、インストールウィザードの指示に従います。 まず最初に設定するウェブサーバーを選択し、 それに伴って必要となる設定を行います。

次に、さまざまな機能や拡張モジュールの中から インストールして有効にしたいものを選択します。 各項目のドロップダウンメニューで "Will be installed on local hard drive" を選択することで、その機能をインストールするかどうかを切り替えます。 "Entire feature will be installed on local hard drive" を選択すると、 その機能に関連するすべての機能がインストールされます (たとえば "PDO" に対してこのオプションを選択すると、 すべての PDO ドライバがインストールされます)。

警告

すべての項目をデフォルトでインストールしてしまうのはお勧めしません。 それらの多くは、適切に動作させるためには PHP 以外の外部の依存性を解決する必要があるからです。 その代わりに、いったんインストールした後で コントロールパネルの「プログラムの追加と削除」 で修復モードを使用して拡張モジュールを有効にするようにしましょう。

次に、インストーラは Windows で使用する PHP と php.ini ファイルを設定し、ウェブサーバーで PHP を使用できるように設定します。 現在インストーラがサポートしているのは IIS、 Apache、Xitami および Sambar Server のみです。 それ以外のウェブサーバーを使用する場合は、自分で設定する必要があります。

サイレントインストール

このインストーラはサイレントモードもサポートしています。 このモードは、システム管理者が簡単に PHP 環境を構築する際に便利です。 サイレントモードは、次のようにして使用します。 

       
msiexec.exe /i php-VERSION-win32-install.msi /q

インストール先ディレクトリを設定するには、インストール時のパラメータとして指定します。 例えば、e:\php にインストールする場合は次のようになります。 

       
msiexec.exe /i php-VERSION-win32-install.msi /q INSTALLDIR=e:\php
同様にして、Apache の設定ディレクトリ (APACHEDIR) や Sambar Server のディレクトリ (SAMBARDIR)、 そして Xitami Server のディレクトリ (XITAMIDIR) も指定することが可能です。

また、インストールする機能を指定することもできます。例えば、 mysqli 拡張モジュールおよび CGI 実行ファイルをインストールするには次のようにします。 

       
msiexec.exe /i php-VERSION-win32-install.msi /q ADDLOCAL=cgi,ext_php_mysqli

現在、インストールする機能としてサポートされている項目は次のとおりです。 

 
MainExecutable - php.exe 実行ファイル (PHP 5.2.10/5.3.0 以降は存在しません。デフォルトで含まれるようになりました)
ScriptExecutable - php-win.exe 実行ファイル
ext_php_* - 各種拡張モジュール (例: MySQL の場合は ext_php_mysql)
apache13 - Apache 1.3 モジュール
apache20 - Apache 2.0 モジュール
apache22 - Apache 2.2 モジュール
apacheCGI - Apache CGI 実行ファイル
iis4ISAPI - IIS ISAPI モジュール
iis4CGI - IIS CGI 実行ファイル
iis4FastCGI - IIS CGI 実行ファイル
NSAPI - Sun/iPlanet/Netscape サーバーモジュール
netserve - NetServe Web Server CGI 実行ファイル
Xitami - Xitami CGI 実行ファイル
Sambar - Sambar Server ISAPI モジュール
CGI - php-cgi.exe 実行ファイル
PEAR - PEAR インストーラ
Manual - CHM 形式の PHP マニュアル

MSI インストーラをコマンドラインから使用する方法の詳細については » http://msdn.microsoft.com/en-us/library/aa367988.aspx を参照ください。

インストーラによる PHP のアップグレード

アップグレードの際も、ダブルクリックあるいはコマンドラインから通常どおりインストーラを実行します。 インストーラが現在のインストールオプションを読み取り、 現在インストールされているバージョンを削除してから 同じオプションで PHP をインストールしなおします。 インストールディレクトリのファイルを手動で置き換えるのではなく、 この方法で PHP をアップグレードすることを推奨します。

手動でのインストール

この節では、Microsoft Windows 環境に PHP を手動でインストールして設定する方法を説明します。 PHP インストーラを使って PHP や Windows 用ウェブサーバーの設定をしたい場合は Windows インストーラ (PHP 5.2 以降) を参照ください。

PHP 配布パッケージの選択とダウンロード

PHP バイナリの zip 版を » PHP for Windows: Binaries and Sources からダウンロードします。zip パッケージにはいくつかのバージョンがあります。 使うウェブサーバーにあわせたバージョンを選びましょう。

  • PHP を IIS で使う場合は、PHP 5.3 VC9 Non Thread Safe あるいは PHP 5.2 VC6 Non Thread Safe を選びます。

  • PHP 5.3 以降を IIS7 以降で使う場合は、VC9 版のバイナリを使わなければなりません。

  • PHP を Apache 1 あるいは Apache 2 で使う場合は、PHP 5.3 VC6 あるいは PHP 5.2 VC6 を選びます。

注意:

VC9 版は Visual Studio 2008 でコンパイルしており、パフォーマンスや安定性が優れています。 VC9 版を使うには、 » Microsoft 2008 C++ Runtime (x86) あるいは » Microsoft 2008 C++ Runtime (x64) をインストールしなければなりません。

PHP パッケージの構造と内容

zip パッケージを、たとえば C:\PHP\ などのお好みの場所に展開しましょう。 zip を展開した中身は、次のようになります。

例1 PHP 5 パッケージ構造


c:\php
   |
   +--dev
   |  |
   |  |-php5ts.lib                 -- 非スレッドセーフバージョンの場合は php5.lib
   |
   +--ext                          -- PHP 拡張モジュールの DLL
   |  |
   |  |-php_bz2.dll
   |  |
   |  |-php_cpdf.dll
   |  |
   |  |-...
   |
   +--extras                       -- 空
   |
   +--pear                         -- PEAR の初期コピー
   |
   |
   |-go-pear.bat                   -- PEAR セットアップ用スクリプト
   |
   |-...
   |
   |-php-cgi.exe                   -- CGI 実行ファイル
   |
   |-php-win.exe                   -- コマンドプロンプトを開かずにスクリプトを実行する
   |
   |-php.exe                       -- コマンドラインの PHP 実行ファイル (CLI)
   |
   |-...
   |
   |-php.ini-development           -- デフォルトの php.ini 設定
   |
   |-php.ini-production            -- 推奨される php.ini 設定
   |
   |-php5apache2_2.dll             -- 非スレッドセーフバージョンには存在しません
   |
   |-php5apache2_2_filter.dll      -- 非スレッドセーフバージョンには存在しません
   |
   |-...
   |
   |-php5ts.dll                    -- コア PHP DLL ( 非スレッドセーフバージョンの場合は php5.dll )
   | 
   |-...

PHP の zip 版に含まれているモジュールや実行ファイルの一覧をまとめました。

  • go-pear.bat - PEAR セットアップスクリプト。詳細は » Installation (PEAR) を参照ください。

  • php-cgi.exe - CGI 実行ファイル。PHP を IIS 上で CGI あるいは FastCGI として実行するときに使います。

  • php-win.exe - PHP 実行ファイル。コマンドプロンプトを開かずに PHP スクリプトを実行します (Windows GUI を使う PHP アプリケーションなどに使います)。

  • php.exe - PHP 実行ファイル。PHP スクリプトをコマンドラインインターフェイス (CLI) で実行します。

  • php5apache2_2.dll - Apache 2.2.X モジュール。

  • php5apache2_2_filter.dll - Apache 2.2.X フィルタ。

php.ini ファイルの変更

php パッケージを展開したら、php.ini-production を php.ini という名前で同じフォルダにコピーします。 必要に応じて php.ini を別の場所に置くこともできますが、 その場合は PHP 設定ファイル にあるような設定が別途必要となります。

php.ini ファイルには、PHP の設定や動作環境についての情報を記述します。 php.ini ファイルには PHP を Windows 上で動かすための設定項目が数多く用意されています。 その中には必須でないものもあります。 また、環境に合わせて指定するディレクティブも数多くあります。詳細は php.ini ディレクティブのリスト を参照ください。

必須項目

  • extension_dir = <拡張モジュールのディレクトリへのパス> - extension_dir には、 PHP の拡張モジュールがあるディレクトリを指定しなければなりません。 絶対パス ("C:\PHP\ext") あるいは相対パス (i.e. ".\ext") のどちらでもかまいません。php.ini ファイルに書かれている拡張モジュールは、 extension_dir に置かなければなりません。

  • extension = xxxxx.dll - 使いたい拡張モジュールがある場合は、それに対応する "extension=" を書かなければなりません。extension_dir にある拡張モジュールのうち、ここで指定したものが起動時に読み込まれます。

  • log_errors = On - PHP のログ出力機能を使うと、エラーをファイルに記録したり (syslog などの) サービスに渡したりすることができます。これは 次の error_log ディレクティブと組み合わせて使います。 IIS で実行している場合は、log_errors を有効にして error_log を正しく設定しておく必要があります。

  • error_log = <エラーログファイルへのパス> - error_log には、PHP のエラーを記録するファイルを絶対パスあるいは相対パスで指定しなければなりません。 このファイルは、ウェブサーバーから書き込み可能でなければなりません。 このファイルを置く場所として一般的なのは、たとえば "C:\inetpub\temp\php-errors.log" のような TEMP ディレクトリです。

  • cgi.force_redirect = 0 - このディレクティブは、IIS で動かす際に必須となります。 他の多くのウェブサーバーではディレクトリセキュリティ機能を必要としますが、 これを IIS で有効にすると、Windows 上での PHP エンジンの実行に失敗します。

  • cgi.fix_pathinfo = 1 - これは、CGI 仕様に従った path info に PHP からアクセスできるようにします。 IIS の FastCGI 実装では、これを設定しておく必要があります。

  • fastcgi.impersonate = 1 - IIS での FastCGI には、呼び出し元のクライアントのセキュリティトークンをまねる機能があります。 これを指定すると、IIS にリクエストのセキュリティコンテキストを定義します。

  • fastcgi.logging = 0 - FastCGI のログ機能は、IIS では無効にしておかねばなりません。 有効にしたままだと、すべてのクラスから発せられるあらゆるメッセージが FastCGI のエラーとみなされ、IIS が HTTP 500 を返すようになってしまいます。

オプションの項目

  • max_execution_time = ## - このディレクティブでは、スクリプトの実行に費やすことのできる最大時間を PHP に伝えます。デフォルトは 30 秒です。 もし PHP アプリケーションの実行時間が長くなるのなら、このディレクティブの値を増やします。

  • memory_limit = ###M - PHP プロセスが使えるメモリの量をメガバイト単位で指定します。 デフォルトは 128 で、たいていの PHP アプリケーションではこれで十分です。 複雑なアプリケーションではもう少し必要となるかもしれません。

  • display_errors = Off - このディレクティブは、ウェブサーバーに返すストリームに エラーメッセージを含めるかどうかを指定します。 これを "On" にすると、error_reporting で設定したすべてのレベルのエラーを エラーストリームの一部としてウェブサーバーに返します。 セキュリティ上の理由で、実運用環境ではこれを "Off" にしておくことを推奨します。 エラーメッセージにはセキュリティ的に問題となる情報が含まれていることが多く、 それが外部に漏れることを防げます。

  • open_basedir = <ディレクトリへのパス、セミコロン区切り>、 たとえば openbasedir="C:\inetpub\wwwroot;C:\inetpub\temp" - このディレクティブは、PHP からのファイルシステムの操作を許可するディレクトリのパスを指定します。 指定したパス以外でのファイル操作はすべてエラーとなります。 このディレクティブは、共用ホスティング環境に PHP を導入するときに特に有用です。 ウェブサイトのルートディレクトリ以外のファイルを操作させないようにすることができます。

  • upload_max_filesize = ###M および post_max_size = ###M - ファイルのアップロードおよび POST するデータの最大サイズを指定します。 PHP のアプリケーションで写真や動画などの大きなファイルをアップロードさせたい場合は、 これらの値を増やさなければなりません。

以上で、Windows への PHP のインストールが完了しました。ついで、 使用する WEB サーバー にあわせて、PHP を利用可能とするための設定を行います。 目次から使用する WEB サーバーを選択し、該当するセクションを参照してください。

PHP をウェブサーバー経由で実行するだけでなく、 .BAT スクリプトなどでコマンドラインから実行することもできます。 詳細は Microsoft Windows コマンドラインでの PHP を参照ください。

Microsoft IIS

この節では、Microsoft Internet Information Services (IIS) への PHP のインストール手順について扱います。

Microsoft IIS 5.1 および IIS 6.0

この節では、Internet Information Services (IIS) 5.1 および IIS 6.0 を手動で設定して、PHP を Microsoft Windows XP および Windows Server 2003 で動かす方法を説明します。 IIS 7.0 以降のバージョンを Windows Vista, Windows Server 2008, Windows 7 そして Windows Server 2008 R2 で動かす方法については Microsoft IIS 7.0 以降 を参照ください。

IIS で PHP リクエストを処理するための設定

手動インストールの手順 での説明にしたがって、PHP をダウンロードしてインストールします。

注意:

IIS を使う場合は、非スレッドセーフ版の PHP を推奨します。非スレッドセーフ版は » PHP for Windows: Binaries and Sources Releases. で取得できます。

CGI や FastCGI 固有の設定を、php.ini で以下のように行います。

例1 php.ini での CGI および FastCGI 用の設定

fastcgi.impersonate = 1
fastcgi.logging = 0
cgi.fix_pathinfo=1
cgi.force_redirect = 0

» Microsoft FastCGI Extension for IIS 5.1 and 6.0 をダウンロードしてインストールします。32 ビット版と 64 ビット版があるので、 環境にあわせて適切なパッケージを選びましょう。

FastCGI エクステンションを設定し、PHP のリクエストを処理できるようにするには 以下のコマンドを実行します。"-path" パラメータの値は、 php-cgi.exe の絶対パスに置き換えましょう。

例2 FastCGI エクステンションで PHP リクエストを処理するための設定

cscript %windir%\system32\inetsrv\fcgiconfig.js -add -section:"PHP" ^
-extension:php -path:"C:\PHP\php-cgi.exe"

このコマンドは、拡張子 *.php 用の IIS スクリプトマッピングを作成します。 .php で終わるすべての URL を FastCGI エクステンションで処理するようになります。 また、FastCGI エクステンションでの PHP リクエストの処理に php-cgi.exe を使うよう設定しています。

注意:

この時点で、最低限必要なインストールと設定は完了しました。 これ以降の手順は必須ではありませんが、IIS 上で PHP を効果的に動かすために強く推奨するものです。

匿名化およびファイルシステムへのアクセス

PHP を IIS で使う場合は、FastCGI の匿名化を有効にしておくことを推奨します。 これは、php.ini ファイルの fastcgi.impersonate ディレクティブで設定します。 匿名化を有効にすると、PHP はすべてのファイルシステム操作を IIS 認証で定義したユーザーアカウントで行います。 こうしておけば、同じ PHP プロセスを異なる IIS ウェブサイトで共有している場合でも (各サイトで IIS 認証のユーザーアカウントを分けておけば) 一方の PHP スクリプトからもう一方のファイルはアクセスできなくなります。

IIS 5.1 や IIS 6.0 のデフォルト設定では組み込みのユーザーアカウント IUSR_<MACHINE_NAME> による匿名認証が有効になっています。 つまり、IIS で PHP スクリプトを実行する場合は IUSR_<MACHINE_NAME> アカウントにスクリプトの読み込み権限を付与しなければならないということです。 PHP のアプリケーションからファイルへの書き込みやフォルダ内でのファイルの作成などをする場合は、 IUSR_<MACHINE_NAME> アカウントに書き込み権限が必要となります。

IIS 匿名認証で使うユーザーアカウントを設定するには、次のようにします。

  1. Windows のスタートメニューで "ファイル名を指定して実行" を選び、"inetmgr" と入力して "Ok" をクリックする

  2. ツリービューの "Web Sites" ノードにあるウェブサイトの一覧を展開し、 使うウェブサイトの上で右クリックして "プロパティ" を選択する

  3. "ディレクトリセキュリティ" タブを選択する

  4. "Authentication Methods" ダイアログの "User name:" フィールドで設定

IIS 5.1 および IIS 6.0 の匿名認証

ファイルやフォルダのパーミッションを変更するには、エクスプローラあるいは icacls コマンドを使います。

例3 ファイルのアクセス権の設定

icacls C:\inetpub\wwwroot\upload /grant IUSR:(OI)(CI)(M)

IIS のデフォルトドキュメントを index.php にする

ドキュメント名を指定しない HTTP リクエストを受け取ったときには、 IIS のデフォルトドキュメントが使われます。PHP アプリケーションでは、通常は index.php をデフォルトドキュメントとします。 index.php を IIS のデフォルトドキュメントに追加するには、 次のようにします。

  1. Windows のスタートメニューで "ファイル名を指定して実行" を選び、"inetmgr" と入力して "Ok" をクリックする

  2. ツリービューの "Web Sites" ノードを右クリックして "プロパティ" を選択する

  3. "Documents" タブをクリックする

  4. "Add..." ボタンをクリックし、"Default content page:" に "index.php" を入力する

index.php を IIS のデフォルトドキュメントにする

FastCGI および PHP の再利用設定

IIS FastCGI エクステンションで PHP プロセスの再利用を設定するには以下のコマンドを使います。 FastCGI の設定項目 instanceMaxRequests は、 ひとつの php-cgi.exe が何回リクエストを処理すると FastCGI エクステンションがシャットダウンさせるかを表します。 PHP の環境変数 PHP_FCGI_MAX_REQUESTS は、 ひとつの php-cgi.exe プロセスが何回リクエストを処理すると 自分をリサイクルするかを表します。 FastCGI の InstanceMaxRequests で設定した値が PHP_FCGI_MAX_REQUESTS 以下になるようにしましょう。

例4 FastCGI と PHP の再利用設定

cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^
-InstanceMaxRequests:10000

cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^
-EnvironmentVars:PHP_FCGI_MAX_REQUESTS:10000

FastCGI のタイムアウト設定

実行時間が長くなる PHP スクリプトがある場合は、FastCGI エクステンションのタイムアウト設定を増やします。タイムアウトに関連する設定項目は ActivityTimeout と RequestTimeout です。 これらの設定に関する詳細は » Configuring FastCGI Extension for IIS 6.0 を参照ください。

例5 FastCGI のタイムアウト設定

cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^
-ActivityTimeout:90

cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^
-RequestTimeout:90

php.ini ファイルの場所の変更

PHP が php.ini ファイルを探す場所は いくつかあり、 php.ini ファイルのデフォルトの場所を 環境変数 PHPRC で変更することができます。 特定の場所においた設定ファイルを PHP に読み込ませたい場合は、 以下のコマンドを実行します。環境変数 PHPRC には、php.ini ファイルがあるディレクトリへの絶対パスを指定しなければなりません。

例6 php.ini ファイルの場所の変更

cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^
-EnvironmentVars:PHPRC:"C:\Some\Directory\"

Microsoft IIS 7.0 以降

このセクションでは、Internet Information Services (IIS) 7.0 以降を設定して、PHP を Microsoft Windows Vista SP1, Windows 7, Windows Server 2008 および Windows Server 2008 R2 で動かす方法を説明します。 IIS 5.1 や IIS 6.0 を Windows XP および Windows Server 2003 で動かす方法については Microsoft IIS 5.1 および IIS 6.0 を参照ください。

IIS での FastCGI サポートの有効化

FastCGI モジュールは、IIS のデフォルトでは無効になっています。 有効化する手順は、Windows のバージョンによって異なります。

Windows Vista SP1 および Windows 7 で FastCGI サポートを有効化する方法

  1. Windows のスタートメニューで "ファイル名を指定して実行" を選び、 "optionalfeatures.exe" と入力して "Ok" をクリックする

  2. "Windows Features" ダイアログで "Internet Information Services"、"World Wide Web Services"、"Application Development Features" を展開し、"CGI" チェックボックスを有効にする

  3. OK をクリックし、インストールが完了するまで待つ

Windows Vista SP1 および Windows 7 での FastCGI サポートの有効化

Windows Server 2008 および Windows Server 2008 R2 で FastCGI サポートを有効化する方法

  1. Windows のスタートメニューで "ファイル名を指定して実行" を選び、 "CompMgmtLauncher" と入力して "Ok" をクリックする

  2. "Web Server (IIS)" ロールが "Roles" ノードの下に存在しない場合は "Add Roles" をクリックして追加する

  3. "Web Server (IIS)" ロールが存在する場合は、"Add Role Services" をクリックして "Application Development" グループの "CGI" チェックボックスを有効にする

  4. "Next"、そして "Install" をクリックし、 インストールが完了するまで待つ

Windows Server 2008 および Windows Server 2008 R2 での FastCGI サポートの有効化

IIS で PHP リクエストを処理するための設定

手動インストールの手順 での説明にしたがって、PHP をダウンロードしてインストールします。

注意:

IIS を使う場合は、非スレッドセーフ版の PHP を推奨します。非スレッドセーフ版は » PHP for Windows: Binaries and Sources Releases. で取得できます。

CGI や FastCGI 固有の設定を、php.ini で以下のように行います。

例1 php.ini での CGI および FastCGI 用の設定

fastcgi.impersonate = 1
fastcgi.logging = 0
cgi.fix_pathinfo=1
cgi.force_redirect = 0

PHP 用の IIS ハンドラマッピングを設定するには IIS マネージャのユーザーインターフェイス あるいはコマンドラインツールを使います。

IIS マネージャのユーザーインターフェイスを使った PHP 用ハンドラマッピングの作成

PHP 用の IIS ハンドラマッピングを IIS マネージャのユーザーインターフェイスで設定する手順は次のとおりです。

  1. Windows のスタートメニューで "ファイル名を指定して実行" を選び、"inetmgr" と入力して "Ok" をクリックする

  2. IIS マネージャのユーザーインターフェイスで、"Connections" ツリービューのサーバーノードを選ぶ

  3. "Features View" ページで "Handler Mappings" を開く

    PHP 用の IIS ハンドラマッピングの作成 : ハンドラマッピングの場所

  4. "Actions" ペインで "Add Module Mapping..." をクリックする

  5. "Add Module Mapping" ダイアログで次のように入力する

    • Request path: *.php
    • Module: FastCgiModule
    • Executable: C:\[PHP をインストールしたパス]\php-cgi.exe
    • Name: PHP_via_FastCGI

  6. "Request Restrictions" ボタンをクリックし、 リクエストがファイルあるいはフォルダにマップされたときだけハンドラが起動するように設定する

  7. すべてのダイアログで OK をクリックし、設定を保存する

PHP 用の IIS ハンドラマッピングの作成 : ハンドラマッピングの追加

コマンドラインツールによる PHP 用ハンドラマッピングの作成

次のコマンドを使うと、IIS FastCGI プロセスプールを作ることができます。 PHP リクエストの処理には php-cgi.exe を使います。 fullPath パラメータの値は php-cgi.exe への絶対パスで置き換えてください。

例2 IIS FastCGI プロセスプールの作成

%windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI ^
/+[fullPath='c:\PHP\php-cgi.exe']

IIS に PHP のリクエストを処理させるには、以下のコマンドを実行します。 scriptProcessor パラメータの値は php-cgi.exe への絶対パスで置き換えてください。

例3 PHP リクエスト用のハンドラマッピングの作成

%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers ^
/+[name='PHP_via_FastCGI', path='*.php',verb='*',modules='FastCgiModule',^
scriptProcessor='c:\PHP\php-cgi.exe',resourceType='Either']

このコマンドは、拡張子 *.php 用の IIS ハンドラマッピングを作成します。 .php で終わるすべての URL を FastCGI モジュールで処理するようになります。

注意:

この時点で、最低限必要なインストールと設定は完了しました。 これ以降の手順は必須ではありませんが、IIS 上で PHP を効果的に動かすために強く推奨するものです。

匿名化およびファイルシステムへのアクセス

PHP を IIS で使う場合は、FastCGI の匿名化を有効にしておくことを推奨します。 これは、php.ini ファイルの fastcgi.impersonate ディレクティブで設定します。 匿名化を有効にすると、PHP はすべてのファイルシステム操作を IIS 認証で定義したユーザーアカウントで行います。 こうしておけば、同じ PHP プロセスを異なる IIS ウェブサイトで共有している場合でも (各サイトで IIS 認証のユーザーアカウントを分けておけば) 一方の PHP スクリプトからもう一方のファイルはアクセスできなくなります。

IIS 7 のデフォルト設定では組み込みのユーザーアカウント IUSR による匿名認証が有効になっています。 つまり、IIS で PHP スクリプトを実行する場合は IUSR アカウントにスクリプトの読み込み権限を付与しなければならないということです。 PHP のアプリケーションからファイルへの書き込みやフォルダ内でのファイルの作成などをする場合は、 IUSR アカウントに書き込み権限が必要となります。

IIS 7 の匿名認証で使うユーザーアカウントを設定するには、次のコマンドを実行します。 "Default Web Site" の部分は、使用する IIS ウェブサイト名に置き換えてください。 出力される XML 設定要素の中から userName 属性を探します。

例4 IIS 匿名認証で使うアカウントの設定

%windir%\system32\inetsrv\appcmd.exe list config "Default Web Site" ^
/section:anonymousAuthentication

<system.webServer>
  <security>
    <authentication>
      <anonymousAuthentication enabled="true" userName="IUSR" />
    </authentication>
   </security>
</system.webServer>

注意:

userName 属性が anonymousAuthentication 要素になかったり、あるいは属性の値が空の文字列になっている場合は、 アプリケーションプールの認証情報をそのウェブサイトの匿名認証で使います。

ファイルやフォルダのパーミッションを変更するには、エクスプローラあるいは icacls コマンドを使います。

例5 ファイルのアクセス権の設定

icacls C:\inetpub\wwwroot\upload /grant IUSR:(OI)(CI)(M)

IIS のデフォルトドキュメントを index.php にする

ドキュメント名を指定しない HTTP リクエストを受け取ったときには、 IIS のデフォルトドキュメントが使われます。PHP アプリケーションでは、通常は index.php をデフォルトドキュメントとします。 index.php を IIS のデフォルトドキュメントに追加するには、 次のようにします。

例6 index.php を IIS のデフォルトドキュメントにする

%windir%\system32\inetsrv\appcmd.exe set config ^
-section:system.webServer/defaultDocument /+"files.[value='index.php']" ^
/commit:apphost

FastCGI および PHP の再利用設定

IIS FastCGI で PHP プロセスの再利用を設定するには以下のコマンドを使います。 FastCGI の設定項目 instanceMaxRequests は、 ひとつの php-cgi.exe が何回リクエストを処理すると FastCGI エクステンションがシャットダウンさせるかを表します。 PHP の環境変数 PHP_FCGI_MAX_REQUESTS は、 ひとつの php-cgi.exe プロセスが何回リクエストを処理すると 自分をリサイクルするかを表します。 FastCGI の InstanceMaxRequests で設定した値が PHP_FCGI_MAX_REQUESTS 以下になるようにしましょう。

例7 FastCGI と PHP の再利用設定

%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^
/[fullPath='c:\php\php-cgi.exe'].instanceMaxRequests:10000

%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^
/+"[fullPath='C:\{php_folder}\php-cgi.exe'].environmentVariables.^
[name='PHP_FCGI_MAX_REQUESTS',value='10000']"

FastCGI のタイムアウト設定

実行時間が長くなる PHP スクリプトがある場合は、FastCGI のタイムアウト設定を増やします。タイムアウトに関連する設定項目は activityTimeout と requestTimeout です。 タイムアウト設定を変更するには以下のコマンドを使います。 fullPath パラメータの値を php-cgi.exe ファイルへの絶対パスに置き換えてください。

例8 FastCGI のタイムアウト設定

%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^
/[fullPath='C:\php\php-cgi.exe',arguments=''].activityTimeout:"90"  /commit:apphost

%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^
/[fullPath='C:\php\php-cgi.exe',arguments=''].requestTimeout:"90"  /commit:apphost

php.ini ファイルの場所の変更

PHP が php.ini ファイルを探す場所は いくつかあり、 php.ini ファイルのデフォルトの場所を 環境変数 PHPRC で変更することができます。 特定の場所においた設定ファイルを PHP に読み込ませたい場合は、 以下のコマンドを実行します。環境変数 PHPRC には、php.ini ファイルがあるディレクトリへの絶対パスを指定しなければなりません。

例9 php.ini ファイルの場所の変更

appcmd.exe set config  -section:system.webServer/fastCgi ^
/+"[fullPath='C:\php\php.exe',arguments=''].environmentVariables.^
[name='PHPRC',value='C:\Some\Directory\']" /commit:apphost

Apache 1.3.x （Microsoft Windows 用）

このセクションでは、Microsoft Windows 上の Apache 1.3.x で PHP を使用する場合について説明します。 Apache 2 で PHP を使用する場合 については別に記載されています。

注意:

まず始めに、マニュアルインストールの手順 をお読みください。

PHP を Windows 上の Apache 1.3.x で動作させるには、2種類の方法が あります。一つは、CGI バイナリ (PHP 4 の場合 php.exe、 PHP 5 の場合 php-cgi.exe) を使用する方法、もう一つ は Apache モジュール DLL を使用する方法です。どちらの場合も httpd.conf を編集して Apache が PHP を利用できるようにした後、 Apache サーバーを再起動する必要があります。

Windwos 環境向けの SAPI モジュールはかなり安定してきているため、 透過性と安全性の面からも CGI バイナリより SAPI モジュールの 使用を推奨します。

Apache で PHP を使うように設定する手順にはいくつかのバリエーションがありますが、 いずれも入門者にもできるほど簡単です。設定ディレクティブに関する詳細については、 Apache のドキュメントも参照してください。

設定ファイルを変更した後、サーバーの再起動を忘れずに行ってください。 Apache を Windows サービスとして実行しているなら、NET STOP APACHE とした後 NET START APACHE とします。 もしくは、スタートメニューのショートカットからも再起動できる場合もあります。

注意: Windows 上で Apache 設定ファイルにパスの値を追加する際、例えば c:\directory\file.ext に含まれるすべてのバックスラッシュは c:/directory/file.ext のように前向きスラッシュに変換する必要があります。 また、ディレクトリを表す際には最後にスラッシュをつけなければなりません。

Apache モジュールの使用

以下の行を Apache の httpd.conf ファイルに追加してください。

例1 Apache 1.3.x でモジュール版の PHP を使用する場合の設定

以下では、PHP は c:\php にインストールされていると仮定します。 そうでない場合はパスを適当に修正してください。

PHP 4 の場合 

# LoadModule セクションの最後に追加
# sapi ディレクトリからこのファイルをコピーするのを忘れないこと!
LoadModule php4_module "C:/php/php4apache.dll"

# AddModule セクションの最後に追加
AddModule mod_php4.c

PHP 5 の場合 

# LoadModule セクションの最後に追加
LoadModule php5_module "C:/php/php5apache.dll"

# AddModule セクションの最後に追加
AddModule mod_php5.c

共通 

# <IfModule mod_mime.c> 条件節の内部に追加
AddType application/x-httpd-php .php

# .phps ファイルを構文ハイライト表示する場合に追加
AddType application/x-httpd-php-source .phps

CGI バイナリの使用

マニュアルインストールの手順 のセクションにある通り、PHP パッケージを C:\php\ に展開したならば、以下を Apache の設定ファイルに追加すれば CGI バイナリを利用可能にできます。

例2 Apache 1.3.x で CGI 版の PHP を使用する場合の設定

ScriptAlias /php/ "c:/php/"
AddType application/x-httpd-php .php

# PHP 4 の場合
Action application/x-httpd-php "/php/php.exe"

# PHP 5 の場合
Action application/x-httpd-php "/php/php-cgi.exe"

# php.ini の場所を設定
SetEnv PHPRC C:/php
上記の 2 行目は、コメントアウトされた状態で httpd.conf に記載されている場合があります。また、c:/php/ は、実際のパスにあわせて修正してください。

警告

CGI モードで公開したサーバーは、いくつかの脆弱性の標的となる可能性があります。 これらの攻撃からサーバーを守る方法については、 CGI セキュリティ のセクションを参照してください。

PHP ソースの構文ハイライト表示については、モジュール版にあるような便利な オプションはありません。Apache で CGI 版の PHP を使用している場合、 highlight_file() 関数を使用してください。 普通に PHP スクリプトを作成し、次のようにコードを記述すれば、構文ハイライト表示が可能です。 <?php highlight_file('ハイライト表示するファイル'); ?>

Apache 2.x （Microsoft Windows 用）

このセクションでは、Microsoft Windows 上の Apache 2.x で PHP を使用する場合について説明します。 Apache 1.3.x で PHP を使用する場合 については別に記載されています。

注意:

まず始めに、マニュアルインストールの手順 をお読みください。

注意: Apache 2.2 のサポート

Apache 2.2 を利用している方は、Apache 2.2 用の DLL ファイルの名前が php5apache2.dll ではなく php5apache2_2.dll であることに注意しましょう。 このファイルは PHP 5.2.0 以降にしか含まれません。 » http://snaps.php.net/ も参照ください。

» Apache ドキュメンテーション を参照し、Apache 2.x サーバーの基本を理解しておくことを強く推奨します。 また、以下の解説を読む前に、Apache 2.x に関する » Windows 固有の情報 についても参照するとよいでしょう。

Apache 2.x は、サーバープラットフォーム用の Windows、 つまり Windows NT 4.0, Windows 2000, Windows XP および Windows 7 で動作するように設計されています。Apache 2.x は Windows 9x でもそれなりに動作しますが、サポートは不完全です。 また、一部うまく動作しない機能もあります。 この問題の解決策はありません。

最新の » Apache 2.x と、 対応するバージョンの PHP をダウンロードしてください。 マニュアルインストールの手順 を実施したら、引き続き以下のとおり PHP と Apache の設定を行ってください。

PHP を Windows 上の Apache 2.x で動かすには三通りの方法があります。 PHP をハンドラとして動かす方法、CGI として動かす方法、そして FastCGI で動かす方法です。

注意: Windows 上で Apache 設定ファイルにパスの値を追加する際、例えば c:\directory\file.ext に含まれるすべてのバックスラッシュは c:/directory/file.ext のように前向きスラッシュに変換する必要があります。 また、ディレクトリを表す際には最後にスラッシュをつけなければなりません。

Apache ハンドラとしてのインストール

以下の行を Apache 設定ファイル httpd.conf に追加して Apache 2.x 用の PHP モジュールを読み込まなければなりません。

例1 PHP を Apache 2.x ハンドラとして使う設定

# 
LoadModule php5_module "c:/php/php5apache2.dll"
AddHandler application/x-httpd-php .php

# php.ini へのパスを設定します
PHPIniDir "C:/php"

注意: 上の例の C:/php/ は実際のパスにあわせて修正してください。 LoadModule ディレクティブで php5apache2.dll と php5apache2_2.dll のどちらを使うのかに注意し、 指定したファイルが実際にその場所にあるかどうかを忘れずに確認しましょう。

上の設定は、拡張子 .php を含むすべてのファイルを PHP で処理するようにします。 たとえそれ以外の拡張子が含まれていたとしてもです。たとえば example.php.txt という名前のファイルも PHP ハンドラが処理します。ファイル名の 最後が .php であるものだけを処理させたい場合は、次のように設定します。 

<FilesMatch \.php$>
      SetHandler application/x-httpd-php
 </FilesMatch>

CGI としての PHP の実行

» Apache CGI ドキュメント を読み、Apache 上の CGI について理解しておきましょう。

PHP を CGI として実行するには、ScriptAlias ディレクティブで CGI ディレクトリとして指定した場所に php-cgi ファイルを置かなければなりません。

さらに、PHP ファイルに #! の行を追加して PHP バイナリの場所を指定しなければなりません。

例2 PHP を Apache 2.x 上で CGI として動かす例

#!C:/php/php.exe
<?php
  phpinfo();
?>

警告

CGI モードで公開したサーバーは、いくつかの脆弱性の標的となる可能性があります。 これらの攻撃からサーバーを守る方法については、 CGI セキュリティ のセクションを参照してください。

PHP を FastCGI で実行する

PHP を FastCGI で動かすのには、CGI として動かすのにくらべると多くの利点があります。 設定方法は単純明快です。

まず mod_fcgid を » http://httpd.apache.org/mod_fcgid/ から取得します。Win32 用のバイナリがこのサイトからダウンロードできます。 そして、説明に従ってモジュールをインストールしましょう。

次にウェブサーバーを以下のように設定します。 パスの部分は適切に変更し、インストールするシステム上の環境にあわせましょう。

例3 PHP を FastCGI として動かす Apache の設定

LoadModule fcgid_module modules/mod_fcgid.so  

# Where is your php.ini file?
FcgidInitialEnv PHPRC        "c:/php" 

AddHandler fcgid-script .php  
FcgidWrapper "c:/php/php-cgi.exe" .php
これで、拡張子 .php のファイルは PHP FastCGI ラッパーが処理するようになります。

Sun, iPlanet, Netscape サーバー（Microsoft Windows 用）

このセクションでは、Windows 上の Sun Java System Web Server, Sun ONE Web Server, iPlanet and Netscape server で PHP を使用する場合について説明します。

PHP 4.3.3 より、NSAPI モジュール を使って 独自エラーページ およびファイル一覧表示ページの生成 が可能です。 Apache 互換の関数も追加されています。 また、これらの WEB サーバー専用の機能については、 「サブリクエストに関する注意」 をお読みください。

Sun, iPlanet, Netscape サーバー で CGI 版の PHP を使用する

CGI 版の PHP を使用する場合は、以下のようにしてください。

  • php4ts.dll をシステムルート （Windows がインストールされているフォルダ）にコピーします。

  • コマンドラインからファイルの関連付けを行います。 次の 2 行をタイプしてください。 

    assoc .php=PHPScript
ftype PHPScript=c:\php\php.exe %1 %*

  • Netscape Enterprise Administration Server で、ダミーの shellcgi ディレクトリを作成し、その後すぐに削除します （このステップにより 5 つの重要な行が obj.conf に作成され、 Web サーバーが shellcgi スクリプトを扱えるようになります。）
  • Netscape Enterprise Administration Server で 新しい mime type を作成します。(Category: type, Content-Type: magnus-internal/shellcgi, File Suffix:php)
  • PHP を実行するすべての Web サーバーインスタンスで上記を実行してください。

CGI 版の PHP を使用する場合の詳細な説明は » http://benoit.noss.free.fr/php/install-php.html を参照してください。

Sun, iPlanet, Netscape サーバー で NSAPI 版の PHP を使用する

NSAPI 版の PHP を使用する場合は、以下のようにしてください。

  • php4ts.dll をシステムルート （Windows がインストールされているディレクトリ）にコピーする。

  • コマンドラインからファイルの関連付けを行います。 次の 2 行をタイプしてください。 

    assoc .php=PHPScript
ftype PHPScript=c:\php\php.exe %1 %*

  • Netscape Enterprise Administration Server において 新しい mime type を作成します。 (Category: type, Content-Type: magnus-internal/shellcgi, File Suffix:php)

  • magnus.conf (サーバー>= 6の場合) または obj.conf (サーバー< 6の場合)を編集し、 以下の行を追加します。 この行は mime types init の後に記述する必要があります。 

    Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll"
Init fn="php4_init" LateInit="yes" errorString="Failed to initialise PHP!" [php_ini="c:/path/to/php.ini"]
    (PHP >= 4.3.3) php_ini パラメータはオプションですが、 これを指定することにより、Web サーバーの設定ファイルがあるフォルダに php.ini を置くことが可能になります。

  • obj.conf のデフォルトオブジェクトを設定します （仮想サーバーの場合、vserver.obj.conf のクラス [SunONE 6.0]。） < Object name="default" > セクションに 次の行を追加してください。この行は、 'ObjectType' の後、'AddLog' の前に記述してください。 

    Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...]
    (PHP >= 4.3.3) 追加のパラメータとして、いくつかの特別な php.ini 値を 追加することができます。例えば、コンテキスト php4_execute をコールする時に docroot="/path/to/docroot" を設定することができます。 論理値の場合、 "On","Off",...（これは正 しく動作しません）ではなく、0/1 を値として使用してください。 例えば、 zlib.output_compression="On" ではなく、 zlib.output_compression=1 とします。

  • 以下は、（cgi-bin ディレクトリ のように）PHP スクリプトのみからなるディレクトリを設定したい場合にだけ必要です。 

    <Object name="x-httpd-php">
ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
Service fn=php4_execute [inikey=value inikey=value ...]
</Object>
    これにより、Administration Server に特定のディレクトリを設定し、 これをスタイル x-httpd-php に割り付けることができ ます。このディレクトリの中にあるすべてのファイルは PHP スクリプト として実行されます。 これは、ファイルの名前を .html に変更し、PHP が使用されている事を隠したい場合に有用です。

  • Web サービスを再起動して設定を反映させます。
  • PHP を実行するすべての Web サーバーインスタンスで上記を行ってください。

注意:

NSAPI 版の PHP の使用についてのより詳細な説明は » http://benoit.noss.free.fr/php/install-php4.html をご覧ください。

注意:

PHP が使用するスタックサイズは WEB サーバーの設定に依存します。 非常に大きい PHP スクリプトを実行させた際にクラッシュする場合は、 Administration Server でスタックサイズ（"MAGNUS EDITOR"） を大きくすると良いでしょう。

CGI 環境変数と php.ini の変更

Sun JSWS/Sun ONE WS/iPlanet/Netscape がマルチスレッドの WEB サーバーだという事が PHP スクリプトを書く際に重要になります。すべてのリクエストは同一の （WEB サーバー自体の）プロセス空間で実行されます。PATH_INFO や HTTP_HOST などの CGI 変数を取得する場合、 古い PHP で行っていたような方法、つまり getenv() 関数を使用する方法や他の同等な方法（グローバル変数の登録機能、 $_ENV 等）を使うのは正しい方法ではありません。WEB サーバーの環境変数をただ単に取得すると、 正しい CGI 変数は得られません。

注意:

なぜ正しくない CGI 変数が登録されているのでしょうか？

それは、WEB サーバーのプロセスを Administration Server から起動させる際、 WEB サーバーの起動スクリプトが CGI スクリプトとして実行されるためです。したがって、 起動された WEB サーバーの環境変数には CGI 変数も含まれることになります。 Administration Server 以外から WEB サーバーを起動してみればこのことをテストできるでしょう。 ルートユーザーでコマンドラインを使って、手動で起動してみると、CGI 変数らしき 環境変数が登録されないことが確認できると思います。

PHP 4.x のスクリプトで CGI 変数を取得する場合は、スーパーグローバル $_SERVER を用いるのが正しい方法です。また、$HTTP_HOST などを使う古いスクリプトを使用する場合は、php.ini で register_globals をオンにし、変数のパースの順番 (variables_order) を変更してください （"E" を削除。環境変数を読み込む必要は無いため。） 

variables_order = "GPCS"
register_globals = On

独自エラーページおよびファイル一覧表示ページ (PHP >= 4.3.3)

PHP を使って、"404 Not Found" などに対するエラーページを生成することが できます。オーバーライドしたいエラーページすべてに対して、以下の行を obj.conf 中のオブジェクトに追加してください。 

Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]
ここで、XXX は HTTP のエラーコードです。 追加したものと干渉する Error ディレクティブは削除してください。 発生するすべてのエラーに対応するページを設定したい場合は、 code パラメータを省略してください。スクリプトで HTTP ステータス コードを取得するには、$_SERVER['ERROR_TYPE'] を使用します。

独自のファイル一覧表示ページを PHP を使って生成することも可能です。 ファイル一覧表示を行う PHP スクリプトを作成し、obj.conf の type="magnus-internal/directory" の行に 書かれているデフォルトのサービスを以下のように置き換えます。 

Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]
エラーページ、ファイル一覧表示ページのどちらでも、元の URI および 変換後の URI は、それぞれ、$_SERVER['PATH_INFO'] および $_SERVER['PATH_TRANSLATED'] に格納されています。

nsapi_virtual() およびサブリクエストに関する注意 (PHP >= 4.3.3)

NSAPI モジュールは、現在、nsapi_virtual() 関数 (エイリアス: virtual()) をサポートしており、 WEB サーバーへサブリクエストを行い、結果を WEB ページへ挿入することができます。 問題としては、この関数は 文書化されていない NSAPI ライブラリの機能を使用して いることにあります。

Unix では、モジュールは自動的に必要な関数群を探し、可能であればそれらの関数を 使用するため、特に問題はありません。もし使用可能でなければ、nsapi_virtual() は 使用不可となります。

Windows では、DLL の扱いに制限があるため、自動認識の使用には 最新の ns-httpdXX.dll ファイルが必要です。 バージョン 6.1 までテストが行われています。もし、より新しい Sun サーバーを使う場合は、 自動認識が動作せず、nsapi_virtual() が使用不可となる可能性が あります。

もしそういった事になった場合は、 magnus.conf/obj.conf の php4_init へ以下のパラメータを追加してください。 

Init fn=php4_init ... server_lib="ns-httpdXX.dll"
ここで、XX は接続する DLL のバージョン番号です。 番号を調べるには、サーバーのルートで、対応する名前のファイルを探してください。 おそらく、最もファイルサイズの大きい DLL が探しているファイルでしょう。

ステータスは phpinfo() 関数を使って確認できます。

注意:

nsapi_virtual() サポートは「実験的」な機能です。

Sambar サーバー（Microsoft Windows 用）

このセクションでは、Windows 上の » Sambar Server で PHP を使用する場合について説明します。

注意:

まず始めに、マニュアルインストールの手順 をお読みください。

以下の手順は、Windows上 の Sambar サーバーで ISAPI モジュール版の PHP を使うように 設定する方法を解説するものです。

  • Sambar をインストールしたフォルダ (の config フォルダ)にある mappings.ini という名前のファイルを探します。

  • mappings.ini を開き、以下の行を [ISAPI] の下に追加します。

    例1 Sambar での ISAPI の設定

    # PHP 4 用
*.php = c:\php\php4isapi.dll

# PHP 5 用
*.php = c:\php\php5isapi.dll
    (PHP が c:\php にインストールされていると 仮定しています。)

  • 変更を有効にするために Sambar サーバーを再起動します。

注意:

PHP で ネットワーク上の他のコンピュータにあるリソースと通信したい場合は、 Sambar Server サービスが使用するアカウントを変更する必要があります。 Sambar Server サービスが使用しているデフォルトのアカウントは LocalSystem で、これはリモートのリソースにアクセスできません。 アカウントを変更するには、コントロールパネルの管理ツールから 「サービス」を使用します。

Xitami（Microsoft Windows 用）

このセクションでは、Windows 上の » Xitami で PHP を使用する場合について説明します。

注意:

まず始めに、マニュアルインストールの手順 をお読みください。

以下の手順は、Windows 上の Xitami でPHP の CGI 版バイナリを動作させる際の 設定方法です。

注意: CGI 版 PHP を使用する場合

cgi.force_redirectに関するFAQ に重要な情報がありますのでお読みください。このディレクティブが 0 にセットされている必要があります。 $_SERVER['PHP_SELF'] を使用する場合は、 cgi.fix_pathinfo をオンにする必要があります。

警告

CGI モードで公開したサーバーは、いくつかの脆弱性の標的となる可能性があります。 これらの攻撃からサーバーを守る方法については、 CGI セキュリティ のセクションを参照してください。

  • Web サーバーが正常に動作していることを確認し、 ブラウザで Xitami 管理用コンソール（通常は http://127.0.0.1/admin）を参照して、「Configuration」を クリックします。

  • 「Filters」を選択し、php にパースさせるファイルの拡張子 (.php など) を 「File extensions (.xxx) 」フィールドに入力します。

  • 「Filter command or script」に、CGI 版 PHP バイナリのパスと名前 (たとえば、c:\php\php.exe) を入力します。

  • 「Save」アイコンを押します。

  • 変更点を反映するためにサーバーを再起動します。

ソースからのビルド

この章では、Windows 上でマイクロソフトのツールを用いて PHP をソースから コンパイルする方法を説明します。PHP を cygwin でコンパイルする場合は Unix システムへのインストール を参照ください。

Wiki のドキュメント » http://wiki.php.net/internals/windows/stepbystepbuild を参照ください。

Windows 用 PHP 拡張モジュール

Windows に PHP を インストールし、Web サーバーの設定ができたら、 次は PHP 拡張モジュールを使うための設定です。 php.ini を使って PHP が起動時にロードする拡張モジュールを設定することができます。 もしくは、スクリプトの中で dl() 関数を使用することにより、 拡張モジュールを動的にロードすることも可能です。

PHP 拡張モジュールの DLL には、ファイル名の前に 'php_' が付いています。

Windows 版の PHP には、多くの拡張モジュールが 組み込まれています。これらの関数を使用する際には、 追加の DLL ファイルや extension ディレクティブの設定は不要です。 追加の DLL が必要となる (あるいはかつて必要だった) 拡張モジュールについては、 Windows 版 PHP 拡張モジュール の表にまとめてあります。以下にあげられている拡張モジュールは、すでに PHP に組み込まれています。

PHP 4 (PHP 4.3.11 時点): BCMath、 Caledar、 COM、 Ctype、 FTP、 MySQL、 ODBC、 Overload、 PCRE、 Session、 Tokenizer、 WDDX、 XML そして Zlib

PHP 5 (PHP 5.0.4 時点) では、さらに以下が組み込まれています。 DOM、 LibXML、 Iconv、 SimpleXML、 SPL そして SQLite。 また、以下は組み込まれなくなりました。 MySQL および Overload。

PHP が拡張モジュールを探すデフォルトの場所は PHP 4 の場合 C:\php4\extensions、 PHP 5 の場合 C:\php5 です。 変更するには php.ini ファイルを編集してください。

  • extension_dir を拡張モジュール があるフォルダに変更する必要があります。 php_*.dllファイルをそこに置いてください。 例えば次のようになります。 

    extension_dir = c:\php\extensions

  • php.ini には、多くの拡張モジュール名がコメントアウトされた状態で記載済みです。 それらの拡張モジュールを有効にするには、php.ini 上の extension=php_*.dll の行をアンコメント（行頭の ; を削除する）してください。

    例1 Windows 版の PHP で Bzip2 拡張モジュールを有効にする

    // この行を以下から
;extension=php_bz2.dll

// このように変更する
extension=php_bz2.dll

  • 拡張モジュールによっては、その動作に外部 DLL が必要な場合があります。 配布パッケージには、一部の外部 DLL がバンドルされています。 PHP 4 の場合は C:\php\dlls\を、 PHP 5 の場合は親フォルダを参照ください。ただし、必要な外部 DLL がバンドルされていないモジュールもあり、たとえば、Oracle モジュール (php_oci8.dll) は、非バンドルの DLL を必要とします。 PHP 4 をインストールする場合、バンドルされた DLL を C:\php\dlls からメインのフォルダ C:\php へコピーしてください。 また、忘れずに C:\php をシステムパスに 追加してください（その方法は、別途 FAQ に記載されています。）

  • これらの DLLs の中には、PHP の配布ファイルに含まれていないものもあります。 詳細は、それぞれの拡張モジュールのドキュメントを参照ください。 また、PECL についての詳細は、マニュアルの PECL 拡張モジュールのインストール という節を参照ください。多くの PHP 拡張モジュールが PECL に移行しつつあり、これらは 個別にダウンロード しなければなりません。

注意: PHP をサーバーモジュールとして実行している場合は、Webサーバーを再起動しないと、 php.ini の設定が反映されません。Web サーバーの再起動を忘れずに行ってください。

以下の表は、使用可能な拡張モジュールと それらの実行に別途必要な DLL のリストです。

PHP 拡張モジュール
拡張モジュール 説明 備考
php_bz2.dll bzip2 圧縮関数  
php_calendar.dll カレンダー 関数 PHP 4.0.3 以降ビルトイン
php_crack.dll Crack 関数  
php_ctype.dll 文字型(ctype) 関数 PHP 4.3.0 以降ビルトイン
php_curl.dll CURL, Client URL Library 関数 libeay32.dll および ssleay32.dll が必要 （バンドル）
php_dba.dll DBA: (dbm 型の) データベース・アブストラクション レイヤー関数  
php_dbase.dll dBase 関数  
php_dbx.dll dbx 関数  
php_domxml.dll DOM XML 関数 PHP <= 4.2.0 では libxml2.dll が必要 （バンドル）, PHP >= 4.3.0 では iconv.dll が必要 （バンドル）
php_dotnet.dll .NET 関数 PHP <= 4.1.1
php_exif.dll EXIF 関数 php_mbstring.dll。php.ini で php_exif.dll は php_mbstring.dll の後で読み込まれる必要がある。
php_fbsql.dll FrontBase 関数 PHP <= 4.2.0
php_fdf.dll FDF: Forms Data Format 関数 fdftk.dll が必要 （バンドル）
php_filepro.dll filePro 関数 読み込みのみ
php_ftp.dll FTP 関数 PHP 4.0.3 以降ビルトイン
php_gd.dll イメージ 関数 (GD ライブラリ) PHP 4.3.2以降で削除。トゥルーカラー関数は GD1 では使用できない。 代わりに php_gd2.dll を使用のこと。
php_gd2.dll イメージ 関数 (GD2 ライブラリ) GD2
php_gettext.dll Gettext 関数 PHP <= 4.2.0 では gnu_gettext.dll が必要 （バンドル）, PHP >= 4.2.3 では libintl-1.dll および iconv.dll が必要（バンドル）
php_hyperwave.dll HyperWave 関数  
php_iconv.dll ICONV 関数 iconv-1.3.dll が必要（バンドル）、 PHP >=4.2.1 iconv.dll
php_ifx.dll Informix 関数 Informix ライブラリが必要
php_iisfunc.dll IIS management 関数  
php_imap.dll IMAP,POP3,NNTP 関数  
php_ingres.dll Ingres 関数 Ingres ライブラリが必要
php_interbase.dll InterBase 関数 gds32.dll が必要（バンドル）
php_java.dll Java 関数 PHP <= 4.0.6 で jvm.dll が必要（バンドル）
php_ldap.dll LDAP 関数 PHP <= 4.2.0 では libsasl.dll が必要（バンドル）, PHP >= 4.3.0 では libeay32.dll と ssleay32.dll が必要（バンドル）
php_mbstring.dll マルチバイト文字列 関数  
php_mcrypt.dll Mcrypt 暗号化 関数 libmcrypt.dll が必要
php_mhash.dll Mhash 関数 PHP >= 4.3.0 で libmhash.dll が必要（バンドル）
php_mime_magic.dll Mimetype 関数 magic.mime が必要（バンドル）
php_ming.dll Ming 関数 (Flash 用)  
php_msql.dll mSQL 関数 msql.dll が必要（バンドル）
php_mssql.dll MSSQL 関数 ntwdblib.dll が必要（バンドル）
php_mysql.dll MySQL 関数 PHP >= 5.0.0。libmysql.dll が必要（バンドル）
php_mysqli.dll MySQLi 関数 PHP >= 5.0.0。libmysql.dll (PHP <= 5.0.2 では libmysqli.dll) が必要（バンドル）
php_oci8.dll Oracle 8 関数 Oracle 8.1+ クライアントライブラリが必要
php_openssl.dll OpenSSL 関数 libeay32.dll が必要（バンドル）
php_overload.dll オブジェクトオーバーロード 関数 PHP 4.3.0 以降ビルトイン
php_pdf.dll PDF 関数  
php_pgsql.dll PostgreSQL 関数  
php_printer.dll プリンタ 関数  
php_shmop.dll 共有メモリ 関数 (shmop)  
php_snmp.dll SNMP 関数 NT のみ
php_soap.dll SOAP 関数 PHP >= 5.0.0
php_sockets.dll ソケット 関数  
php_sybase_ct.dll Sybase 関数 Sybase クライアントライブラリが必要
php_tidy.dll Tidy 関数 PHP >= 5.0.0
php_tokenizer.dll Tokenizer 関数 PHP 4.3.0 以降ビルトイン
php_w32api.dll W32api 関数  
php_xmlrpc.dll XML-RPC 関数 PHP >= 4.2.1 で iconv.dll が必要（バンドル）
php_xslt.dll XSLT 関数 PHP <= 4.2.0 では sablot.dll と expat.dll が必要（バンドル）。 PHP >= 4.2.1 では sablot.dll, expat.dll および iconv.dll が必要（バンドル）
php_yaz.dll YAZ 関数 yaz.dll が必要（バンドル）
php_zip.dll Zip ファイル 関数 読込のみ
php_zlib.dll ZLib 圧縮関数 PHP 4.3.0 以降ビルトイン

Microsoft Windows のコマンドラインでの PHP

この節では、PHP を Windows のコマンドラインで実行するときの注意点やヒントを説明します。

注意:

まず最初に 手動でのインストールの手順 を読みましょう!

特に Windows に手を加えなくても、PHP をコマンドラインから実行することはできます。 

C:\PHP5\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3

しかし、次の手順に従えば、さらにシンプルに実行することができます。 この中にはすでに実行済みのものがあるかもしれませんが、順を追って進めていくために もう一度ここで説明しておきます。

  • PHP の実行ファイル (php.exe、 php-win.exe あるいは php-cli.exe。 PHP のバージョンや設定によって変わります) がある場所を環境変数 PATH に追加します。 PHP のディレクトリを PATH に追加する方法は、FAQ の項目 を参照ください。

  • 拡張子 .PHP を、環境変数 PATHEXT に追加します。これは、環境変数 PATH の変更と同時に行うこともできます。 FAQ に書かれている手順に従いましょう。ただし、環境変数 PATH の部分は PATHEXT に変更します。

    注意:

    .PHP をどの位置に書くかによって、 ファイル名がマッチしたときに実行されるスクリプトあるいはプログラムが決まります。 たとえば .PHP を .BAT より前に書くと、 同じ名前のバッチファイルがあってもスクリプトのほうを優先して実行します。

  • 拡張子 .PHP をファイル形式と関連づけます。 これは、次のコマンドで行います。 

    assoc .php=phpfile

  • ファイル形式 phpfile を適切な PHP 実行ファイルと関連づけます。 これは、次のコマンドで行います。 

    ftype phpfile="C:\PHP5\php.exe" -f "%1" -- %~2

このようにしておくと、どのディレクトリにあるスクリプトを実行するときにも PHP 実行ファイルのパスや拡張子 .PHP をタイプしなくて済むようになります。 また、スクリプトに渡すパラメータを指定することもできます。

次の例は、レジストリの変更の一部を示したものです。これらは手動で行うこともできます。

例1 レジストリの変更

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php]
@="phpfile"
"Content Type"="application/php"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile]
@="PHP Script"
"EditFlags"=dword:00000000
"BrowserFlags"=dword:00000008
"AlwaysShowExt"=""

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon]
@="C:\\PHP5\\php-win.exe,0"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell]
@="Open"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open]
@="&Open"

[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command]
@="\"C:\\PHP5\\php.exe\" -f \"%1\" -- %~2"

これらの変更をすれば、同じコマンドを次のように書くことができます。 

"C:\PHP Scripts\script" -arg1 -arg2 -arg3
また、"C:\PHP Scripts" が環境変数 PATH に含まれていれば、次のように書くこともできます。 
script -arg1 -arg2 -arg3

注意:

これらのテクニックを使って PHP スクリプトをコマンドラインフィルタとして使おうとすると、 ちょっとした問題が発生します。「コマンドラインフィルタとして使う」とは、たとえば 

dir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3
あるいは 
dir | script -arg1 -arg2 -arg3
のように使うということです。 このようにすると、スクリプトがハングして何も出力されなくなります。 これをうまく動作させるには、さらにレジストリを変更しなければなりません。 
Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
"InheritConsoleHandles"=dword:00000001
この件に関する詳細な情報は » Microsoft Knowledgebase Article : 321788 を参照ください。

クラウド･コンピューティング･プラットフォームへのインストール

目次

PHP は、クラウドにインストールします。PHP のクラウドへ！

Microsoft Azure

PHP は、» Azure クラウド･プラットフォームにインストールします。

» Azure SDK for PHPもご覧ください。

Amazon EC2

PHP は、» EC2 クラウド･プラットフォームにインストールします。

» AWS SDK for PHPもご覧ください。

FastCGI Process Manager (FPM)

目次

FPM (FastCGI Process Manager) は PHP の FastCGI 実装のひとつで、 主に高負荷のサイトで有用な追加機能を用意しています。

以下のような機能があります。

  • 緩やかな (graceful) 停止/起動 機能を含む高度なプロセス管理

  • 異なる uid/gid/chroot/environment でのワーカーの開始、 異なるポートでのリスン、異なる php.ini の使用 (safe_mode の代替)

  • 標準出力および標準エラー出力へのログ出力

  • opcode キャッシュが壊れた場合の緊急再起動

  • 高速なアップロードのサポート

  • "slowlog" - 実行時間が非常に長いスクリプトの記録 (スクリプト名だけでなく、PHP バックトレースも記録します。バックトレースを取得するために、 ptrace やそれと同等の仕組みを使ってリモートプロセスの execute_data を読みます)

  • fastcgi_finish_request() - リクエストを終わらせてすべてのデータを出力した後で 何か時間のかかる処理 (動画の変換や統計情報の処理など) をさせるための特殊な関数

  • 動的/静的 な子プロセスの起動

  • 基本的な SAPI の動作状況 (Apache の mod_status と同等)

  • php.ini ベースの設定ファイル

インストール

ソースからのコンパイル

FPM を有効にして PHP をビルドするには、configure 時に --enable-fpm を追加します。

そのほかにも FPM 固有のオプションがいくつかあります (いずれも必須ではありません)。

  • --with-fpm-user - FPM のユーザー (デフォルトは nobody)。

  • --with-fpm-group - FPM のグループ (デフォルトは nobody)。

設定

FPM では、php.ini 形式の構文の設定ファイル php-fpm.conf を使います。

php-fpm.conf のグローバル設定項目

pid string

PID ファイルへのパス。デフォルト値: なし

error_log string

エラーログファイルへのパス。デフォルト値: #INSTALL_PREFIX#/log/php-fpm.log

log_level string

エラーログのレベル。使用可能な値: alert, error, warning, notice, debug、デフォルト値: notice

emergency_restart_threshold int

emergency_restart_interval で設定された間隔で この数以上の子プロセスが SIGSEGV あるいは SIGBUS で終了した場合に FPM は再起動します。0 は 'オフ' を意味します。デフォルト値: 0 (オフ)

emergency_restart_interval mixed

emergency_restart_interval が緩やかな再起動をいつ実行するかを決めるときに使う間隔。 これは、アクセラレータの共有メモリが壊れてしまったときの回避策として有用です。 使用可能な単位: s(秒), m(分), h(時間) あるいは d(日)、 デフォルトの単位: 秒、デフォルト値: 0 (オフ)

process_control_timeout mixed

子プロセスが、マスタからのシグナルの反応を待つ最大時間。 使用可能な単位: s(秒), m(分), h(時間) あるいは d(日)、 デフォルトの単位: 秒、デフォルト値: 0

daemonize boolean

FPM をバックグラウンドに送る。'no' にすると デバッグ用に FPM をフォアグラウンドに置き続けます。 デフォルト値: yes

プール一覧の項目

FPM を使うと、複数のプロセスプールをそれぞれ別の設定で実行することができます。 プール単位での設定を行う項目を以下に示します。

listen string

FastCGI リクエストを受け入れるアドレス。 'ip.add.re.ss:port', 'port', '/path/to/unix/socket' 形式の構文が使えます。 このオプションは、各プール単位で必須となります。

listen.backlog int

listen(2) のバックログを設定します。'-1' は無制限を意味します。 デフォルト値: -1

listen.allowed_clients string

接続を許可されている FastCGI クライアントの ipv4 アドレス一覧。オリジナル版 PHP FastCGI (5.2.2+) における環境変数 FCGI_WEB_SERVER_ADDRS と同じです。 tcp でリスンするソケットに対してのみ意味をなします。 書くアドレスはカンマ区切りで指定します。この値を空にしておくと、任意の ip アドレスからの接続を許可します。 デフォルト値: 任意の ip アドレスを許可

listen.owner string

unix ソケットを使う場合に、そのパーミッションを設定します。Linux では、 読み書きアクセス権限を設定しないとウェブサーバーからの接続を受け付けることができません。 多くの BSD 由来のシステムでは、パーミッションにかかわらず接続を受け付けることができます。 デフォルト値: ユーザーとグループは実行しているユーザーと同じ、モードは 0666

listen.group string

listen.owner を参照ください。

listen.mode string

listen.owner を参照ください。

user string

FPM プロセスの unix ユーザー。このオプションは必須です。

group string

FPM プロセスの unix グループ。未設定の場合は、デフォルトのユーザーのグループを使います。

pm string

プロセスマネージャが子プロセスの数を制御する方法を選択します。 使用可能な値: static, ondemand, dynamic このオプションは必須です。

static - 子プロセスの数は固定 (pm.max_children) です。

ondemand - プロセスを必要に応じて立ち上げます。 dynamic とは対照的に、リクエストされると pm.start_servers で指定しただけサービスを開始します。

dynamic - 子プロセスの数は、 pm.max_children、pm.start_servers、 pm.min_spare_servers、pm.max_spare_servers の内容に基づいて動的に設定されます。

pm.max_children int

pm が static の場合は作成される子プロセスの数、 pm が dynamic の場合は作成される子プロセスの最大数。 このオプションは必須です。

このオプションは、同時に処理できるリクエストの最大数を設定します。 mpm_prefork での ApacheMaxClients ディレクティブや、 オリジナル版の PHP FastCGI における環境変数 PHP_FCGI_CHILDREN と同じです。

pm.start_servers in

起動時に作成される子プロセスの数。pm が dynamic の場合にのみ使います。デフォルト値: min_spare_servers + (max_spare_servers - min_spare_servers) / 2

pm.min_spare_servers int

アイドル状態のサーバープロセス数の最小値。 pm が dynamic の場合にのみ使います。 また、この場合には必須となります。

pm.max_spare_servers int

アイドル状態のサーバープロセス数の最大値。 pm が dynamic の場合にのみ使います。 また、この場合には必須となります。

pm.max_requests int

各子プロセスが、再起動するまでに実行するリクエスト数。 サードパーティのライブラリにおけるメモリリークの回避策として便利です。 再起動せずにずっとリクエストを処理させる場合は '0' を指定します。 PHP_FCGI_MAX_REQUESTS と同じです。デフォルト値: 0

pm.status_path string

FPM の情報ページを見るための URI。この値を省略した場合は、どの URI も情報ページとは見なされません。デフォルト値: なし

ping.path string

FPM のモニタリングページをコールするための ping URI。この値を省略した場合は、どの URI も ping ページとは見なされません。これを使うと、 FPM が生きていて応答するかどうかを外部から確かめることができます。 この値の最初はスラッシュ (/) で始めなければならないことに注意しましょう。

ping.response string

このディレクティブを使うと、ping リクエストに対するレスポンスをカスタマイズすることができます。 このレスポンスは text/plain 形式となり、レスポンスコード 200 で返されます。 デフォルト値: pong

request_terminate_timeout mixed

単一のリクエストを処理する際のタイムアウト。この時間を過ぎるとワーカープロセスが kill されます。 このオプションは、'max_execution_time' ini オプションが何らかの理由でスクリプトの実行を止められなかった場合に使われます。 値 '0' は 'Off' を意味します。 使用可能な単位: s(秒)(デフォルト), m(分), h(時間) あるいは d(日)、 デフォルト値: 0

request_slowlog_timeout mixed

単一のリクエストを処理する際のタイムアウト。この時間を過ぎると PHP のバックトレースが 'slowlog' ファイルに出力されます。 値 '0' は 'Off' を意味します。 使用可能な単位: s(秒)(デフォルト), m(分), h(時間) あるいは d(日)、 デフォルト値: 0

slowlog string

遅いリクエストを記録するログファイル。デフォルト値: #INSTALL_PREFIX#/log/php-fpm.log.slow

rlimit_files int

オープン時のファイル記述子の rlimit。デフォルト値: システムで定義されている値

rlimit_core int

最大コアサイズの rlimit。 使用可能な値: 'unlimited' あるいは 0 以上の整数値、 デフォルト値: システムで定義されている値

chroot string

このディレクトリに chroot して開始位置とします。この値は絶対パスで指定しなければなりません。 この値を省略した場合は、chroot を使いません。

chdir string

このディレクトリに chdir して開始位置とします。この値は絶対パスで指定しなければなりません。 デフォルト値: カレントディレクトリ、あるいは chroot した場合は /

catch_workers_output boolean

ワーカーの標準出力および標準エラー出力を本体のエラーログにリダイレクトします。 省略した場合は、FastCGI の仕様にしたがって標準出力および標準エラー出力を /dev/null にリダイレクトします。 デフォルト値: no

追加の環境変数を渡して、特定のプールだけで PHP の設定を更新することができます。 そのためには、次のオプションを php-fpm.conf に追加しなければなりません。

例1 環境変数や PHP の設定をプールに渡す

env[HOSTNAME] = $HOSTNAME
       env[PATH] = /usr/local/bin:/usr/bin:/bin
       env[TMP] = /tmp
       env[TMPDIR] = /tmp
       env[TEMP] = /tmp

       php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
       php_flag[display_errors] = off
       php_admin_value[error_log] = /var/log/fpm-php.www.log
       php_admin_flag[log_errors] = on
       php_admin_value[memory_limit] = 32M
php_value や php_flag で渡した PHP の設定は、その前に設定されていた内容を上書きします。 ただし disable_functions や disable_classes は別で、 php.ini で定義された値を上書きするのではなく、 新たに指定した値を追記することになります。

php_admin_value や php_admin_flag で設定した値を ini_set() で上書きすることはできません。

PECL 拡張モジュールのインストール

目次

PECL インストール入門

» PECL は PHP 拡張モジュールのリポジトリで、 » PEAR パッケージシステムを経由して使用可能です。 ここでは PECL 拡張モジュールを取得してインストールする方法を解説します。

以下に示す手順では、PHP のソース配布物へのパスが /your/phpsrcdir/ であり、PECL 拡張モジュールの名前が extname であると仮定しています。適切に変更してください。また、 » pear コマンド についても理解していることとします。 PEAR マニュアルにある pear コマンドについての情報は、 そのまま pecl コマンドにもあてはまります。

便利な機能を使用するには、拡張モジュールをビルドし、 インストールして読み込まなければなりません。 拡張モジュールのビルドとインストールについては以下でさまざまな方法を説明しますが、 モジュールの読み込みは自動的には行われません。モジュールを読み込むには、 php.ini ファイルに extension ディレクティブを追加するか、dl() 関数を使用します。

拡張モジュールのビルドにあたっては、適切なバージョンのツール (autoconf, automake, libtool など) を使用することが重要です。 必要なツールとそのバージョンについては、 » Anonymous SVN の手順 を参照してください。

PECL 拡張モジュールをダウンロードする

PECL 拡張モジュールをダウンロードするには、以下に示す通り、いくつかの方法があります。

  • pecl install extname コマンドで、 拡張モジュールのコードを自動的にダウンロードします。 この場合は、個別にダウンロードする必要はありません。
  • » http://pecl.php.net/ PECL のウェブサイトでは、PHP 開発チームが提供する さまざまな拡張モジュールについての情報が公開されています。 ChangeLog やリリース情報、必要な要件、リビジョンといった情報が参照可能です。
  • pecl download extname PECL のウェブサイトで公開されている PECL 拡張モジュールは、 » pecl コマンド を使ってソースファイルをダウンロードすることもできます。 特定のバージョンを指定可能です。
  • SVN 大半の PECL 拡張モジュールは SVN にも収められています。 » http://svn.php.net/viewvc/pecl/ で、 ウェブから参照することができます。 SVN から直接ダウンロードする場合は、 以下の一連のコマンドを使用します。


    $ svn checkout http://svn.php.net/repository/pecl/extname/trunk extname

  • Windows ダウンロード 現在、PHP プロジェクトでは PECL 拡張モジュールの Windows バイナリをコンパイルしていません。しかし、PHP を Windows でコンパイルする方法は Windows 用の PHP のビルド にまとめられています。

PHP 拡張モジュールの Windows へのインストール

Windows では、PHP の拡張モジュールを読み込む方法は 2 通りあります。 コンパイル時に PHP に組み込む方法と、DLL として読む込む方法です。 コンパイル済みの拡張モジュールを読み込む方法のほうが簡単で、おすすめです。

拡張モジュールを読み込むには、".dll" ファイルをシステム上に用意する必要があります。 すべての拡張モジュールは、PHP Group によって定期的に自動コンパイルされています (ダウンロード先は次の節を参照ください)。

コンパイル時に拡張モジュールを PHP に組み込む方法については、 ソースからのビルド に関するドキュメントを参照ください。

単体の拡張モジュール (DLL ファイル) をコンパイルする方法については ソースからのビルド に関するドキュメントを参照ください。 PHP の配布パッケージにも PECL にも DLL ファイルが存在しなければ、 まずコンパイルをしないとその拡張モジュールは使えないでしょう。

拡張モジュールの探し方は？

PHP の拡張モジュールは、通常は "php_*.dll" (* の部分に拡張モジュールの名前が入ります) という名前で "PHP\ext" (PHP 4 の場合は "PHP\extensions") フォルダに存在します。

PHP には、大半の開発者にとって有用である拡張モジュールが同梱されています。 これらは "コア" 拡張モジュールと呼ばれます。

しかし、コア拡張モジュールに含まれない機能が必要となった場合はそのモジュールを PECL で探す必要があります。 The PHP Extension Community Library (PECL) は PHP 拡張モジュール用のリポジトリで、すべての拡張モジュールの一覧機能や PHP 拡張モジュールのダウンロードの仕組みを提供します。

自分で拡張モジュールの開発をしている方は、 それを PECL で公開して他の人たちにも使ってもらいたいと思われることでしょう。 そうすれば、彼らからフィードバックを得たり (うまくいけば) 感謝の言葉をもらえたり、バグレポートやバグ修正パッチをもらえたりするかもしれません。 自作の拡張モジュールを PECL で公開したい場合は http://pecl.php.net/package-new.php を参照ください。

どれをダウンロードすればいいの？

各 DLL について、いくつかのバージョンが見つかることがあります。

  • バージョン番号が異なるもの (少なくとも先頭の 2 つの数字は一致している)
  • スレッドセーフの設定が異なるもの
  • プロセッサのアーキテクチャ (x86, 64 bits...) が異なるもの
  • デバッグ設定が異なるもの
  • その他

注意して欲しいのは、拡張モジュールの設定とそれを動かす PHP 実行ファイルの設定をそろえておかなければならないということです。 次の PHP スクリプトを実行すると、PHP に関する すべての 設定を取得することができます。

例1 phpinfo() のコール

<?php
phpinfo();
?>

あるいは、コマンドラインから次のように実行します。 

drive:\\path\to\php\executable\php.exe -i

拡張モジュールの読み込み

PHP の拡張モジュールを読み込む方法として最も一般的なのは、設定ファイル php.ini に書き込むことです。多くの拡張モジュールはすでに php.ini 上に存在し、 あとはセミコロンを取り除くだけで有効にできるようになっています。 

;extension=php_extname.dll

extension=php_extname.dll

しかし、ウェブサーバーによっては少し迷うことがあるかもしれません。 というのも、php.ini が PHP 実行ファイルとは別の場所にあることもあるからです。 実際に使われている php.ini の場所を見つけるには、 phpinfo() で次のような行を探します。 

Configuration File (php.ini) Path  C:\WINDOWS

Loaded Configuration File   C:\Program Files\PHP\5.2\php.ini

拡張モジュールを有効にしたら、php.ini を保存してウェブサーバーを再起動し、もういちど phpinfo() を確認します。 新しい拡張モジュールについての情報がそこに追加されているはずです。

問題の解決

もし拡張モジュールの情報が phpinfo() に出てこなかった場合は、ログをチェックして何が起こったのかを調べなければなりません。

PHP をコマンドライン (CLI) で使用している場合は、 拡張モジュールの読み込み時のエラーは直接画面に表示されます。

PHP をウェブサーバー上で使用している場合は、ログの場所や書式はソフトウェアによって異なります。 ウェブサーバーのドキュメントを読んでログを見つけましょう。 ログの場所については、PHP 自体とは特に関係のないことです。

DLL の場所がおかしい、php.ini の "extension_dir" がおかしい、 コンパイル時の設定が違うなどが、よくある問題です。

コンパイル時の設定が違うことが原因だった場合は、おそらく間違った DLL をダウンロードしてしまったのでしょう。 もういちど、正しい設定の拡張モジュールをダウンロードしましょう。 正しい設定とは？ 改めて言います。phpinfo() を参考にしましょう。

共有 PECL 拡張モジュールを、pecl コマンドを用いてコンパイルする

PECL を用いると、共有 PECL 拡張モジュールを容易に作成することができます。 以下のように » pecl コマンド を用います。


$ pecl install extname

extname のソースがダウンロードされ、 コンパイルおよび extension_dir への extname.so のインストールが行われます。 extname.so は、php.ini 経由で読み込まれます。

デフォルトでは、pecl コマンドは 状態が alpha あるいは beta のパッケージをインストールしません。stable なパッケージが存在しない場合は、以下のコマンドを使用して beta パッケージをインストールします。


$ pecl install extname-beta

特定のバージョンをインストールするには、次のような変化形を使用します。


$ pecl install extname-0.1

注意:

拡張モジュールを php.ini で有効にしたら、 ウェブサービスを再起動させないとそれは反映されません。

phpize で共有 PECL 拡張モジュールをコンパイルする方法

時には pecl インストーラを使用するという選択肢が使えない場合もあります。 たとえばファイアウォールの内部で作業をしている場合がそうですし、 まだリリースされていない SVN 版のように PECL パッケージ形式になっていないものをインストールする場合も それにあてはまります。このようなモジュールをビルドする必要がある場合は、 より低レベルなビルドツールを使用して手動でビルドします。

PHP 拡張モジュールのビルド環境を準備するために、 phpize コマンドを使用します。以下の例では、 拡張モジュールのソースが extname というディレクトリにあると仮定します。 

$ cd extname
$ phpize
$ ./configure
$ make
# make install

上手くいけば、extname.so が作成され、 それが PHP の 拡張モジュールディレクトリ に置かれます。 この拡張モジュールを使用する前に、php.ini に extension=extname.so という行を追加する必要があります。

コンパイル済みのパッケージ (RPM など) を使用している場合などで、もし phpize コマンドが見つからない場合は、適切な 開発版の PHP パッケージをインストールしましょう。 PHP や拡張モジュールをビルドするために必要なヘッダファイルや phpize コマンドは、このパッケージに含まれます。

使用法についての詳細な情報を表示するには、 phpize --help を実行します。

php-config

php-config はシンプルなシェルスクリプトで、 インストールされている PHP の設定情報を取得します。

拡張モジュールをコンパイルするときに、もし複数のバージョンの PHP がインストールされている場合は、どちらを使ってコンパイルするのかを指定できます。 configure の --with-php-config オプションで、 対応する php-config スクリプトのパスを指定します。

php-config スクリプトのコマンドラインオプション一覧は、 php-config に -h スイッチをつけて実行すれば見られます。 

Usage: /usr/local/bin/php-config [OPTION]
Options:
  --prefix            [...]
  --includes          [...]
  --ldflags           [...]
  --libs              [...]
  --extension-dir     [...]
  --include-dir       [...]
  --php-binary        [...]
  --php-sapis         [...]
  --configure-options [...]
  --version           [...]
  --vernum            [...]

コマンドラインオプション
オプション 説明
--prefix PHP のインストール先ディレクトリのプレフィックス。例: /usr/local
--includes -I オプションとインクルードしたファイルの一覧
--ldflags PHP をコンパイルしたときの LD フラグ
--libs PHP をコンパイルしたときの外部ライブラリ
--extension-dir 拡張モジュールを探すときのデフォルトのディレクトリ
--include-dir ヘッダファイルのデフォルトのインストール先ディレクトリのプレフィックス
--php-binary CLI あるいは CGI バイナリへのフルパス
--php-sapis 使用できるすべての SAPI モジュール
--configure-options 現在インストールされている PHP の再作成するための configure オプション
--version PHP のバージョン
--vernum PHP のバージョンを整数値で表したもの

PECL 拡張モジュールを PHP に静的に組み込む

PECL 拡張モジュールを PHP に静的に組み込みたいと思うこともあるでしょう。 そのためには、拡張モジュールのソースを php-src/ext/ ディレクトリに置き、PHP にその設定スクリプトを生成させる必要があります。 

$ cd /your/phpsrcdir/ext
$ pecl download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname

上記を行うと、以下のディレクトリが作成されます。


/your/phpsrcdir/ext/extname

これ以降、PHP に configure スクリプトを再実行させ、通常通りに PHP をビルドします。


$ cd /your/phpsrcdir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install

注意: 'buildconf' スクリプトを実行するためには、autoconf 2.13 と automake 1.4+ が必要です (新しいバージョンの autoconf では動作するかも知れませんが、 サポートされていません)。

拡張モジュールによって、--enable-extname もしくは --with-extname オプションを指定します。 外部ライブラリを使用しない拡張モジュールについては、 --enable が使われるのが一般的です。 buildconf の後で、以下を行うと確認できます。


$ ./configure --help | grep extname

問題が起きた場合

目次

FAQ を読む

よくある問題とそうでない問題とがあります。 よくある問題（とその答え）の内、代表的なものが » PHP FAQ に記載されています。

FAQ に無い問題

FAQ を参照しても問題が解決しない場合には、PHP インストール用メーリングリストの誰かが 助けてくれるかもしれません。最初に、アーカイブをチェックして、過去に誰かが 自分と同じ問題に関する質問を行い、既に解答を受けていないかをチェックしてください。 アーカイブは、» http://www.php.net/ のサポートページで 公開されています。PHP インストール用メーリングリストに加入するには、空のメールを » php-install-subscribe@lists.php.net に送信してください。メーリングリストのアドレスは、php-install@lists.php.net です。

メーリングリストにおいて質問をする場合は、正確さを心がけ、 解答に必要な使用環境に関する事項（オペレーティングシステムの種類、 PHP のバージョン、Web サーバーの種類、PHP を CGI として使用しているのか サーバーモジュールとして使用しているのか、セーフモード 等）を明らかにするように してください。他の人が問題を再現し、テストできるのに充分なコードを 示すことが望まれます。

バグ報告

PHP のバグを発見した場合は、報告してください。あなたがそのバグを報告しない限り、 PHP の開発者がそのバグを知ることは恐らくなく、修正されることもないでしょう。 バグの報告は、» http://bugs.php.net/ にあるバグ追跡システムを使用して行います。 バグレポートをメーリングリストや個人宛てのメールで送らないでください。

» バグ報告の仕方 を読み、 それにしたがってバグ報告を投稿してください。

実行時設定

目次

設定ファイル

設定ファイル (php.ini) は PHP の起動時に読み込まれます。 PHP のサーバーモジュール版では、Web サーバーの起動時に 一度だけ読み込まれます。CGI 版と CLI 版では、スクリプトが呼び出される度に読み込まれます。

読み込む php.ini は、これらの場所を順に探します。

  • SAPI モジュール特有の場所 (Apache 2 における PHPIniDir ディレクティブ、 CGI/CLI 版における -c コマンドラインオプション、 NSAPI における php_ini パラメータ、 THTTPD における PHP_INI_PATH 環境変数)
  • PHPRC 環境変数。PHP 5.2.0 より前では、 これは、次に挙げるレジストリキーの後にチェックされていました。
  • PHP 5.2.0 以降では、PHP のバージョンごとに別の場所の php.ini を使用することができます。以下のレジストリキーを順に調べて使用します。 [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]、 [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y] および [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]。 x、y および z はそれぞれ PHP のメジャーバージョン、マイナーバージョン、 リリース番号を表します。これらのキーに IniFilePath の値が設定されていれば、最初に見つかった場所の php.ini を使用します (Windows のみ)。
  • [HKEY_LOCAL_MACHINE\SOFTWARE\PHP] にある IniFilePath の値 (Windows のみ)。

  • 現在の作業ディレクトリ (CLI を除く)

  • Web サーバーのディレクトリ (SAPI モジュールの場合)、 もしくは PHP ディレクトリ (そうでない Windows の場合)
  • Windows ディレクトリ (C:\windows もしくは C:\winnt)) (Windows の場合) 、もしくはコンパイル時のオプション --with-config-file-path

php-SAPI.ini (ここで SAPI は使用する SAPI 名。 たとえば php-cli.ini や php-apache.ini) が存在する場合、 php.ini の代わりに使用されます。 SAPI 名は php_sapi_name() によって決定されます。

注意:

Apache web サーバーは、スタート時にディレクトリをルート に変更するので、ファイルシステムのルートに php.ini が存在する場合、PHP はそれを読もうとします。

拡張モジュールに対する php.ini ディレクティブは、 各拡張モジュールのドキュメントで解説されています。 コア ディレクティブ （PHP 本体に対するディレクティブ）のリストは付録にまとめられています。 ただし、（更新の都合上）すべての PHP ディレクティブが 本マニュアル中で解説されている訳ではありません。 使っているバージョンの PHP で指定可能なすべてのディレクティブについては、 php.ini ファイル内に詳細なコメントが記されていますので、参照してください。 もしくは、SVN から入手可能な »  最新の php.ini も有用でしょう。

例1 php.ini の例

; 引用符をつけないセミコロン(;)の後のテキストは、すべて無視されます
[php] ; セクションマーカ (角括弧の中のテキスト) は無視されます
; 論理値は、次のいずれかで指定します
;    true, on, yes
; または false, off, no, none
register_globals = off
magic_quotes_gpc = yes

; 文字列を二重引用符で括ることも可能です
include_path = ".:/usr/local/lib/php"

; バックスラッシュは他の文字と同様に処理されます
include_path = ".;c:\php\lib"

PHP 5.1.0 以降、ini ファイル内で既存の ini 変数を参照することが可能です。 例: open_basedir = ${open_basedir} ":/new/dir"

.user.ini ファイル

PHP 5.3.0 以降、PHP はディレクトリ単位での .htaccess 風の INI ファイルをサポートするようになりました。 このファイルは、CGI/FastCGI SAPI の場合にのみ処理されます。 この機能は、PECL htscanner 拡張モジュールを置き換えるものです。 Apache を使用している場合は .htaccess ファイルを使えば同じ機能を実現できます。

メイン php.ini ファイルに加えて、PHP が各ディレクトリの INI ファイルをスキャンします。 リクエストされた PHP ファイルがあるディレクトリから始まり、 現在のドキュメントルート ($_SERVER['DOCUMENT_ROOT']) まで順にたどっていきます。PHP ファイルがドキュメントルート配下以外の場所にある場合は、 PHP ファイルがあるディレクトリだけをスキャンします。

.user.ini 形式の INI ファイルがサポートするのは、 モードが PHP_INI_PERDIR および PHP_INI_USER の項目のみです。

新しい INI ディレクティブ user_ini.filename および user_ini.cache_ttl で、ユーザー INI ファイルの使用法を制御します。

user_ini.filename は、PHP が各ディレクトリで探すファイルの名前を設定します。 空文字列を指定した場合は何も探しません。デフォルトは .user.ini です。

user_ini.cache_ttl は、ユーザー INI ファイルの再読込頻度を設定します。 デフォルトは 300 秒 (5 分) です。

どこで設定を行うのか

これらのモードは、ある PHP ディレクティブがいつどこで設定できるのかを表すものです。 マニュアルに記載されているすべてのディレクティブには、これらのモードのいずれかが指定されています。 たとえば、PHP スクリプト中で ini_set() で設定できるものもあれば php.ini や httpd.conf でなければ設定できないものもあります。

たとえば output_buffering は PHP_INI_PERDIR なので、 ini_set() で設定することはできません。 一方 display_errors は PHP_INI_ALL なのでどこででも設定でき、当然 ini_set() ででも設定できます。

PHP_INI_* モードの定義
モード 意味
PHP_INI_USER ユーザースクリプト (ini_set() などで) または Windows レジストリ で設定可能なエントリ
PHP_INI_PERDIR php.ini、.htaccess または httpd.conf で設定可能なエントリ
PHP_INI_SYSTEM php.ini または httpd.confで設定可能なエントリ
PHP_INI_ALL どこでも設定可能なエントリ

設定を変更するには

Apache モジュールとして PHP を実行している場合

PHP を Apache モジュールとして使用している場合、Apache 設定ファイル (例、httpd.conf) もしくは .htaccess ファイルにディレクティブを記述することで、PHP の設定の変更を行うことが 可能です。このようにして設定変更を行うには、"AllowOverride Options" もしくは "AllowOverride All" 権限が必要です。

Apache 設定ファイルから PHP の設定を変更するには、 以下に示す Apache ディレクティブを使用します。 各設定オプションの変更の可否 (PHP_INI_ALL, PHP_INI_PERDIR, または PHP_INI_SYSTEM) については、付録 php.ini ディレクティブのリスト を参照してください。

php_value name value

指定した設定オプションに値を設定します。変更の可否が、 PHP_INI_ALL もしくは PHP_INI_PERDIR である設定オプションに対し利用できます。 セット済みの値をクリアしたい場合は、none を 値として使用してください。

注意: 論理値を設定する場合には php_value を使用しないでください。代わりに、php_flag （下記参照）を使用する必要があります。

php_flag name on|off

設定オプションに論理値を設定するために使用します。変更の可否が、 PHP_INI_ALL もしくは PHP_INI_PERDIR である設定オプションで利用できます。

php_admin_value name value

指定した設定オプションに値を設定します。このディレクティブは、.htaccess ファイルでは利用できません。また、 php_admin_value で設定された設定オプションの値は、.htaccess や ini_set() では上書きできません。 セット済みの値をクリアしたい場合は、none を値として使用してください。

php_admin_flag name on|off

設定オプションに論理値を設定するために使用します。 このディレクティブは、.htaccess ファイルでは利用できません。 php_admin_value で設定された設定オプションの値は、.htaccess や ini_set() では上書きできません。

例1 Apache 設定の例

<IfModule mod_php5.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>

警告

PHP 定数は PHP 以外では使用できません。たとえば、 httpd.conf の中で error_reporting オプションを設定しようとして E_ALL や E_NOTICE のような PHP 定数を使用することは できません。これらは意味を有さないため、 0 と評価されてしまいます。 代わりに、対応するビットマスク値を使用してください。 php.ini の中では、これらの PHP 定数を使用することができます。

Windows レジストリによる PHP の設定の変更

Windows 上で PHP を実行している場合、Windows レジストリを使用して設定値を ディレクトリ毎に変更することができます。 設定値は、レジストリキー HKLM\SOFTWARE\PHP\Per Directory Values に保存され、そのサブキーがパス名となります。例えば、ディレクトリ c:\inetpub\wwwroot に対する設定値は、 キー HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot に保存されます。ディレクトリに対する設定は、そのディレクトリ、 およびそのサブディレクトリで実行されるすべてのスクリプトで有効となります。 PHP 設定オプションのディレクティブを名前とする文字列値をキーに登録してください。 また、値のデータに PHP 定数を記述しても解釈されませんので、注意してください。 しかし、PHP_INI_USER で変更可能な設定値はこの方法で設定することが可能ですが、 PHP_INI_PERDIR である設定値は設定できません。

他の方法

どのように PHP を実行しているかに係わらず、ini_set() 関数を 用いて、スクリプトの実行時に一部のオプションの設定値を変更することができます。詳細は、 ini_set() 関数のリファレンスを参照してください。

使用しているシステムにおける現在のオプション設定値の完全なリストを得たい場合は、 phpinfo() 関数を実行し、出力された結果を参照してください。 また、ini_get() 関数または get_cfg_var() 関数を用いて、個々のオプションの設定値にアクセスすることも可能です。

言語リファレンス

基本的な構文

目次

PHP タグ

PHP はファイルを解析して開始タグと終了タグ (<?php と ?>) を探します。 タグが見つかると、PHP はコードの実行を開始したり終了したりします。 このような仕組みにより、PHP を他のあらゆる形式のドキュメント中に 埋め込むことができるのです。つまり、開始タグと終了タグで囲まれている 箇所以外のすべての部分は、PHP パーサに無視されます。

PHP では、短い形式のタグ <? および ?> も使えます (しかしこれはおすすめしません。というのも、この形式のタグは php.ini で short_open_tag を有効にするか --enable-short-tags オプションつきで PHP を configure した場合でないと使えないからです)。

ファイル全体が純粋な PHP コードである場合は、ファイルの最後の終了タグは省略するのがおすすめです。 終了タグの後に余分な空白や改行があると、予期せぬ挙動を引き起こす場合があるからです。 余分な空白や改行のせいで PHP が出力バッファリングを開始し、その時点の内容を意図せず出力してしまうことになります。

<?php
echo "みなさん、こんにちは";

// ... いろんなコードたち

echo "最後のごあいさつ";

// PHP 終了タグを書かずに、ここでスクリプトを終わります。

HTML からの脱出

PHP のパーサは、開始タグと終了タグに囲まれていない部分をすべて無視します。 そのおかげで、PHP のファイルにそれ以外のコンテンツを混在させることができるのです。 たとえば PHP を HTML ドキュメントに組み込んで、テンプレートを作ったりすることもできます。

<p>この部分は PHP から無視され、そのままブラウザには表示されます。</p>
<?php echo '一方、この部分はパースされます。'; ?>
<p>この部分も PHP から無視され、そのままブラウザには表示されます。</p>
これは期待通りに動作します。なぜなら、PHP インタプリタは ?> 終了タグを見つけると それ以降新たに開始タグを見つけるまでの内容を何でも出力するからです (終了タグの直後の改行は別です。 命令の分離 を参照ください)。 しかし、PHP が条件文の中にいる場合は話が別です。 その場合は、まず条件式の結果を判定してから何をスキップするかを判断します。 次の例を参照ください。

条件文を使った例です。

例1 条件文を使った高度な脱出

<?php if ($expression == true): ?>
  条件式が真の場合にこれが表示されます。
<?php else: ?>
  それ以外の場合にこちらが表示されます。
<?php endif; ?>
この例では、PHP は条件を満たさないブロックを処理しません。たとえそれが PHP の開始タグと終了タグに囲まれた部分でなくても、条件文にしたがってそこを読み飛ばします。 というのも、PHP のインタプリタは条件を満たさない箇所をブロックごと読み飛ばすからです。

大量のテキストを出力する際に echo や print を用いることを考えると、このように一度 PHP のパースモードを抜けるほうが効率的です。

PHP で用いられるタグは 4 種類あります。 これらのうちの 2 つ、<?php ?> と <script language="php"> </script> は常に使用することができます。 残りの 2 つは短縮型のタグと ASP スタイルの タグで、これらは php.ini ファイルによって有効か無効かを切り替えられます。 中には短縮型のタグや ASP スタイルのタグを 便利に感じる人がいるかも知れませんが、長いタグに比べると移植性に欠けます。 また一般的には推奨されていません。

注意:

さらに注意しなければならないことがあります。PHP コードを XML や XHTML に 埋め込む場合には、標準規格に従うために <?php ?> タグを使用する 必要があるでしょう。

例2 PHP の開始タグと終了タグ

1.  <?php echo 'XHTMLまたはXMLドキュメントを処理したい場合は、この方法が良いでしょう'; ?>

2.  <script language="php">
        echo '(FrontPageのような) いくつかのエディタ は処理命令を好み
        ません';
    </script>

3.  <? echo 'これは、SGML を処理する最もシンプルな方法です'; ?>
    <?= expression ?> This is a shortcut for "<? echo expression ?>"

4.  <% echo 'オプションでASP形式のタグを使用可能です'; %>
    <%= $variable; # これは、"<%echo .." のショートカットです。%>

例の 1. と 2. のタグは常に利用可能です。中でも 1. のタグは最も一般的で 推奨される方法です。

短縮型のタグ（例 3.）が有効なのは、php.ini 設定ファイルのディレクティブ short_open_tag が 有効になっている場合か PHP が --enable-short-tags オプションつきで configure されている場合のみです。

ASP 型のタグ（例 4.）が有効なのは、 php.ini 設定ファイルのディレクティブ asp_tags が有効になっている場合のみです。

注意:

再利用されるか、または、自分の制御下にないPHPサーバーで運用される アプリケーションまたはライブラリを開発する場合、短縮型のタグの 使用は避けるべきです。これは、短縮型のタグがターゲットサーバー でサポートされていない可能性があるためです。 可搬性のある、再配布可能なコードでは、短縮型のタグを使用しない ようにしてください。

注意:

PHP 5.2 以前では、開始タグ <?php だけを書いてそれ以外に何も書いていないファイルは パーサが処理することができませんでした。PHP 5.3 以降では、開始タグの後に空白が一文字でもあればそのようなファイルもパースできます。

注意:

PHP 5.4 以降では、短い形式の echo タグ <?= は常に有効なタグとして認識されるようになりました。 short_open_tag の設定には影響を受けません。

命令の分離

C や Perl と同様に、PHP でもステートメントを区切りにはセミコロンが必要と なります。PHP コードブロックの終了タグには自動的にセミコロンが含まれていると 認識されます。 従って PHP コードの最終行にはセミコロンを記述する必要はありません。 ブロックの終了タグは、直後に改行がある場合、それを含んだものになります。

<?php
    echo 'テストです';
?>

<?php echo 'テストです' ?>

<?php echo '終了タグを省略しました';

注意:

ファイル終端における PHP ブロックの終了タグはオプション（任意）です。 include や require を利用する際には、 終了タグを省略する方が無難です。というのは、そうすることでファイルの最後に 予期せぬ空白文字があらわれてしまうことを防げますし、後でレスポンスに ヘッダを付加することも可能となるからです。また、出力バッファリングを 使用しており、include したファイルの生成する部分の最後に余計な空白を つけたくない場合などにも便利です。

コメント

PHP は、'C', 'C++' および Unix シェル型（Perl 型）のコメントをサポートします。 例えば、

<?php
echo 'テストです'; // C++型の単一行用のコメント
/* 複数行用のコメント
   もう一行分のコメント */
echo 'もうひとつのテストです';
echo '最後のテストです'; # シェル型の単一行用のコメント
?>

"一行"コメントは、改行または PHP コードのブロックの終わり のうちどちらか最初にくる方までです。 つまり、// ... ?> あるいは # ... ?> の後に続く HTML コードは 表示されるということです。?> により PHP モードを終了して HTML モードに戻ると、そこでは // あるいは # は何の影響も 及ぼしません。asp_tags 設定ディレクティブが有効になっている場合、// %> および # %> でも同じような動作になります。しかし、一行コメントの中の </script> では PHP モードを終了することは ありません。

<h1>これは <?php # echo 'シンプルな';?> 例</h1>
<p>上の見出しは 'これは  例です。' となります。

'C' 型のコメントは、最初に */ が現れた時点で終了します。 'C' 型のコメントがネストしないように注意する必要があります。 大きなブロックをコメントアウトしようとする際に、この間違いを犯しがちです。

<?php
 /*
    echo 'テストです'; /* このコメントが問題を生じます */
 */
?>

型

目次

導入

PHP は、8 種類の基本型をサポートします。

4 種類のスカラー型:

  • 論理値 (boolean)
  • 整数 (integer)
  • float (浮動小数点数, double も同じ)
  • 文字列 (string)

2 種類の複合型:

  • 配列 (array)
  • オブジェクト (object)

そして、最後に 3 種類の特別な型:

  • リソース (resource)
  • ヌル (NULL)
  • callable

本マニュアルでは、可読性を向上させるため、以下のような擬似的な型も使用します。

そして擬似変数 $...。

マニュアル内のいくつかの場所で "double" 型という記述が残っているかもしれません。 double は float と同じものだと考えてください。2 種類の名前が存在するのは、 歴史的な理由によるものです。

変数の型は、基本的にプログラマが設定するものではありません。 その変数が使用される文脈に応じ、PHP が実行時に決定します。

注意: 式の型と値を正確に知りたい場合は、 var_dump() 関数を使用してください。

デバッグのために、単純に人間が読みやすい形で型を表示したい場合には gettype() を使用してください。型をチェックする場合には gettype() を使用してはいけません 。is_type 関数を使用してください。いくつかの例を以下に示します。

<?php
$a_bool = TRUE;   // a boolean
$a_str  = "foo";  // a string
$a_str2 = 'foo';  // a string
$an_int = 12;     // an integer

echo gettype($a_bool); // prints out:  boolean
echo gettype($a_str);  // prints out:  string

// 数値であれば、4を足す
if (is_int($an_int)) {
    $an_int += 4;
}

// $a_bool が文字列であれば, それをprintする
// (そうでなければ何も出力されない)
if (is_string($a_bool)) {
    echo "String: $a_bool";
}
?>

ある変数の型を強制的に他の型に変換したい場合、変数を キャスト するか、 settype() 関数を使用します。

変数は、その型に依存して異なった動作をする場合があることに注意してください。 詳細な情報については、 型の変換 のセクションを参照ください。 またPHP 型の比較表 もご覧ください。さまざまな型の変数の比較に関する例があります。

論理型 (boolean)

論理型は、最も簡単な型です。boolean は、真偽の値を表します。 この値は、TRUE または FALSE のどちらかになります。

構文

boolean リテラルを指定するには、キーワード TRUE または FALSE を指定してください。 両方とも大文字小文字に依存しません。

<?php
$foo = True; // 値TRUEを$fooに代入する
?>

通常、boolean 型の値を返す演算子を使用してから、 制御構造にその結果を渡します。

<?php
// == は、boolean型を返す演算子
if ($action == "show_version") {
    echo "バージョンは1.23です。";
}

// これは冗長
if ($show_separators == TRUE) {
    echo "<hr>\n";
}

// 上の例は次のように簡単に書くことができます。
if ($show_separators) {
    echo "<hr>\n";
}
?>

boolean への変換

boolean に明示的に変換を行うには、キャスト (bool) または (boolean) を使用します。しかし、演算子、関数、制御構造が boolean 型の引数を必要とする場合には、値は自動的に変換されるため、 多くの場合はキャストは不要です。

型の相互変換 も参照ください。

boolean に変換する場合、次の値は FALSE とみなされます。

その他の値は全て TRUE とみなされます (全ての resourceを含みます)。

警告

-1 は、他のゼロでない数と同様に (正負によらず) TRUE とみなされます。

<?php
var_dump((bool) "");        // bool(false)
var_dump((bool) 1);         // bool(true)
var_dump((bool) -2);        // bool(true)
var_dump((bool) "foo");     // bool(true)
var_dump((bool) 2.3e5);     // bool(true)
var_dump((bool) array(12)); // bool(true)
var_dump((bool) array());   // bool(false)
var_dump((bool) "false");   // bool(true)
?>

整数

integer は、ℤ = {..., -2, -1, 0, 1, 2, ...} という集合です。

以下も参照ください。

構文

整数 (integer) は、10 進数(基数 10)、16 進数 (基数 16)、8 進数 (基数 8) あるいは 2 進数 (基数 2) 表記で指定可能です。オプションで、符号(-または+)を前に付けることが可能です。

2 進数の整数リテラルは、PHP 5.4.0 から利用可能となりました。

8 進数表記を使用する場合、数の前に 0 (ゼロ) を付ける必要があります。また、16 進数表記を使用するには、数の前に 0x を付ける必要があります。 2 進数表記を使用する場合、数の前に 0b を付ける必要があります。

例1 整数リテラル

<?php
$a = 1234; // 10進整数
$a = -123; // 負の数
$a = 0123; // 8進数 (10進数の83と等価)
$a = 0x1A; // 16進数 (10進数の26と等価)
?>

使用可能な整数リテラルの形式は以下のように定義されています。 

decimal     : [1-9][0-9]*
            | 0

hexadecimal : 0[xX][0-9a-fA-F]+

octal       : 0[0-7]+

binary      : 0b[01]+

integer     : [+-]?decimal
            | [+-]?hexadecimal
            | [+-]?octal
            | [+-]?binary

整数のサイズはプラットフォームに依存しますが、 約 20 億 (32 ビット符号付) が一般的な値です。 64 ビットプラットフォームでの通常の最大値は、約 9E18 です。 PHP は符号無し整数をサポートしていません。 整数のサイズは PHP_INT_SIZE で決まります。 最大値は、PHP 4.4.0 から PHP 5.0.5 までは PHP_INT_MAX でした。

警告

8 進数の整数値として不正な数字（例: 8 または 9）が渡された場合、 数値の残りの部分は無視されます。

例2 おかしな 8 進数

<?php
var_dump(01090); // 010（8 進数）= 8（10 進数）
?>

整数のオーバーフロー

integer型の範囲外の数を指定した場合、かわりに floatとして解釈されます。また、結果が integer型の範囲外の数となるような計算を行うと floatが代わりに返されます。

例3 32 ビットシステムにおける整数のオーバーフロー

<?php
$large_number = 2147483647;
var_dump($large_number);                     // int(2147483647)

$large_number = 2147483648;
var_dump($large_number);                     // float(2147483648)

$million = 1000000;
$large_number =  50000 * $million;
var_dump($large_number);                     // float(50000000000)
?>

例4 64 ビットシステムにおける整数のオーバーフロー

<?php
$large_number = 9223372036854775807;
var_dump($large_number);                     // int(9223372036854775807)

$large_number = 9223372036854775808;
var_dump($large_number);                     // float(9.2233720368548E+18)

$million = 1000000;
$large_number =  50000000000000 * $million;
var_dump($large_number);                     // float(5.0E+19)
?>

PHP には整数の割り算はありません。1/2 は float 型の 0.5 になります。 下方向の整数値に値を丸めるためにキャストを使用することができ、 また、round() 関数を使用することもできます。

<?php
var_dump(25/7);         // float(3.5714285714286) 
var_dump((int) (25/7)); // int(3)
var_dump(round(25/7));  // float(4) 
?>

整数への変換

integer に値を明示的に変換するには、キャスト (int) または (integer) のどちらかを使用してください。しかし、多くの場合、演算子、関数、制御構造が integer 引数を必要とする場合、値は自動的に変換されるため、 キャストを使用する必要はありません。 関数 intval() を用いて値を整数に変換することも可能です。

型の相互変換 を参照ください。

booleans から

FALSE は、0 (ゼロ) となり、 TRUE は、1 となります。

浮動小数点数から

float から整数に変換する場合、その数はゼロのほうに丸められます。

float が整数の範囲 (通常は、32 ビットプラットフォームでは +/- 2.15e+9 = 2^31、64 ビットプラットフォームでは +/- 9.22e+18 = 2^63 ) を越える場合、結果は undefined となります。これは、 その float が正しい整数の結果を得るために十分な精度を得られなかったからです。 この場合、警告も通知も発生しません!

警告

未知の端数を integer にキャストしないでください。 この場合、予期しない結果となることがあります。

<?php
echo (int) ( (0.1+0.7) * 10 ); // 7が出力されます!
?>

より詳細な情報については、 float の精度に関する注意を参照ください。

文字列から

文字列変換 を参照ください。

他の型から

警告

整数への変換の動作は、他の型については定義されません。 現在の動作は、その値がまず 論理値に変換された 場合と同じです。しかし、この動作は予告なく変更されることがありえるので、 これを前提にしてはいけません。

浮動小数点数

浮動小数点数 (あるいは "float", "double", "実数") は、次の構文により指定できます。

<?php
$a = 1.234; 
$b = 1.2e3; 
$c = 7E-10;
?>

規約: 

LNUM          [0-9]+
DNUM          ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM [+-]?(({LNUM} | {DNUM}) [eE][+-]? {LNUM})

float の大きさはプラットフォーム依存です。ただし、通常はおよそ 10 進数で 14 桁の精度があり、最大値は ~1.8e308 (これは 64ビット IEEE フォーマットです) となります。

警告

浮動小数点数の精度

浮動小数点数の精度は有限です。 システムに依存しますが、PHP は通常 IEEE 754 倍精度フォーマットを使います。 この形式は、1.11e-16 のオーダーでの丸め処理で誤差が発生します。 複雑な算術演算をすると、誤差はさらに大きくなるでしょう。そしてもちろん、 いくつかの演算を組み合わせる場合にも誤差を考慮しなければなりません。

さらに、十進数では正確な小数で表せる有理数、たとえば 0.1 や 0.7 は、 二進数の浮動小数点数としては正確に表現できません。 これは、仮数部をいくら大きくしても同じです。 したがって、それを内部的な二進数表現に変換する際には、どうしても多少精度が落ちてしまいます。 その結果、不思議な結果を引き起こすことがあります。たとえば、 floor((0.1+0.7)*10) の結果はたいてい 7 となるでしょう。おそらくは 8 を想定していらっしゃるでしょうが、そのようにはなりません。 これは、(この計算結果の) 内部的な値が 7.9999999999999991118... のようになっているからです。

よって、小数の最後の桁を信用してはいけませんし、 小数を直接比較して等しいかどうかを調べてはいけません。より高い精度が必要な場合には、 任意精度数学関数または gmp 関数を代わりに使用してください。

float への変換

文字列型がどのようにして浮動小数点数に変換されるかに関する詳細な情報は、 文字列の数値型への変換 のセクションをご覧ください。 そのほかの型の浮動小数点数への変換については、整数型への変換と同様です。 詳細は整数型への変換 のセクションをご覧ください。 PHP 5 以降、オブジェクトを浮動小数点数に変換しようとした場合には、 通知がスローされます。

float の比較

先ほど警告したように、浮動小数点数値が等しいかどうかを比較するのには問題があります。 これは、浮動小数点数値の内部表現形式に起因するものです。 しかし、この制限を回避して浮動小数点数値の値を比較する方法もあります。

浮動小数点数値が等しいかどうかを調べるには、比較時の丸め誤差の上界を用います。 この値は計算機イプシロンあるいは丸め単位と呼ばれ、 計算時に扱える最小の差分を表します。

$a と $b は、精度 5 桁では等しくなります。

<?php
$a = 1.23456789;
$b = 1.23456780;
$epsilon = 0.00001;

if(abs($a-$b) < $epsilon) {
    echo "true";
}
?>

NaN

数値演算の結果が、定数 NAN で表される値になることがあります。 この定数は、浮動小数点演算における未定義の値あるいは表現不能な値を表します。 この値を他の値と比較した場合、たとえ自分自身との比較であっても結果は FALSE になります。 緩やかな比較の場合も厳格な比較の場合の同様です。

NAN はさまざまな値の数を表すものなので、 NAN を他の値を比較してはいけません。たとえ自分自身とであってもです。 チェックをする場合には、かわりに is_nan() を使います。

文字列

string は、文字が連結されたものです。PHP では、 文字は 1 バイトと同じです。つまり、256 個の異なる文字を使用可能です。 これは、PHP が Unicode をネイティブにサポートしていないことも意味します。 文字列型の詳細を参照ください。

注意: 文字列の最大長は 2GB です。

構文

文字列リテラルは、4 つの異なる方法で指定することが可能です。

引用符

文字列を指定する最も簡単な方法は、引用符 (文字 ') で括ることです。

引用符をリテラルとして指定するには、バックスラッシュ (\) でエスケープする必要があります。 バックスラッシュをリテラルとして指定するには、二重 (\\) にします。 それ以外の場面で登場するバックスラッシュは、すべてバックスラッシュそのものとして扱われます。 つまり、\r や \n といったおなじみのエスケープシーケンスを書いても特別な効果は得られず、 書いたままの形式で出力されます。

注意: ダブルクォート 構文や heredoc 構文とは異なり、 変数と特殊文字のエスケープシーケンスは、 引用符 (シングルクオート) で括られた文字列にある場合には展開されません。

<?php
echo 'this is a simple string';

echo 'You can also have embedded newlines in 
strings this way as it is
okay to do';

// 出力: Arnold once said: "I'll be back"
echo 'Arnold once said: "I\'ll be back"';

// 出力: You deleted C:\*.*?
echo 'You deleted C:\\*.*?';

// 出力: You deleted C:\*.*?
echo 'You deleted C:\*.*?';

// 出力: This will not expand: \n a newline
echo 'This will not expand: \n a newline';

// 出力: Variables do not $expand $either
echo 'Variables do not $expand $either';
?>

二重引用符

文字列が二重引用符 (") で括られた場合、 PHP は、より多くの特殊文字のエスケープシーケンスを理解します。

エスケープされた文字
記述 意味
\n ラインフィード (LF またはアスキーの 0x0A (10))
\r キャリッジリターン (CR またはアスキーの 0x0D (13))
\t 水平タブ (HT またはアスキーの 0x09 (9))
\v 垂直タブ (VT またはアスキーの 0x0B (11)) (PHP 5.2.5 以降)
\e エスケープ (ESC あるいはアスキーの 0x1B (27)) (PHP 5.4.0 以降)
\f フォームフィード (FF またはアスキーの 0x0C (12)) (PHP 5.2.5 以降)
\\ バックスラッシュ
\$ ドル記号
\" 二重引用符
\[0-7]{1,3} 正規表現にマッチする文字シーケンスは、8 進数表記の 1 文字です。
\x[0-9A-Fa-f]{1,2} 正規表現にマッチする文字シーケンスは、16 進数表記の 1 文字です。

繰り返しますが、この他の文字をエスケープしようとした場合には、 バックスラッシュも出力されます! PHP 5.1.1 より前のバージョンでは、\{$var} のバックスラッシュは出力されません。

しかし、二重引用符で括られた文字列で最も重要なのは、 変数名が展開されるところです。詳細は、文字列のパースを参照ください。

ヒアドキュメント

文字列を区切る別の方法としてヒアドキュメント構文 ("<<<") があります。この場合、ある ID (と、それに続けて改行文字) を <<< の後に指定し、文字列を置いた後で、同じ ID を括りを閉じるために置きます。

終端 ID は、その行の最初のカラムから始める必要があります。 使用するラベルは、PHP の他のラベルと同様の命名規則に従う必要があります。 つまり、英数字およびアンダースコアのみを含み、 数字でない文字またはアンダースコアで始まる必要があります。

警告

非常に重要なことですが、終端 ID がある行には、セミコロン (;) 以外の他の文字が含まれていてはならないことに注意しましょう。 これは、特に ID はインデントしてはならないということ、 セミコロンの前に空白やタブを付けてはいけないことを意味します。 終端 ID の前の最初の文字は、使用するオペレーティングシステムで定義された 改行である必要があることにも注意を要します。 これは、例えば、Macintoshでは \r となります。 最後の区切り文字 (たいていはその後にセミコロンが続きます) の後にもまた、改行を入れる必要があります。

この規則が破られて終端 ID が "clean" でない場合、 終端 ID と認識されず、PHP はさらに終端 ID を探し続けます。 適当な終了 ID がみつからない場合、 スクリプトの最終行でパースエラーが発生します。

ヒアドキュメント構文を、クラスのプロパティの初期化に用いることはできません。 PHP 5.3 以降では、変数を含まないヒアドキュメントではこの制約はなくなりました。

例1 間違った例

<?php
class foo {
    public $bar = <<<EOT
bar
    EOT;
}
?>

ヒアドキュメントは二重引用符を使用しませんが、 二重引用符で括られた文字列と全く同様に動作します。 しかし、この場合でも上記のリストでエスケープされたコードを使用することも可能です。 変数は展開されますが、文字列の場合と同様に ヒアドキュメントの内部で複雑な変数を表わす場合には注意が必要です。

例2 ヒアドキュメントで文字列を括る例

<?php
$str = <<<EOD
Example of string
spanning multiple lines
using heredoc syntax.
EOD;

/* 変数を使用するより複雑な例 */
class foo
{
    var $foo;
    var $bar;

    function foo()
    {
        $this->foo = 'Foo';
        $this->bar = array('Bar1', 'Bar2', 'Bar3');
    }
}

$foo = new foo();
$name = 'MyName';

echo <<<EOT
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should print a capital 'A': \x41
EOT;
?>

上の例の出力は以下となります。

My name is "MyName". I am printing some Foo.
Now, I am printing some Bar2.
This should print a capital 'A': A

ヒアドキュメント構文を用いて、 関数の引数にデータを渡すこともできます。

例3 ヒアドキュメントを引数に使用する例

<?php
var_dump(array(<<<EOD
foobar!
EOD
));
?>

PHP 5.3.0 以降、静的な変数やクラスのプロパティ/定数を ヒアドキュメント構文で初期化できるようになりました。

例4 ヒアドキュメントを用いた静的な値の初期化

<?php
// 静的変数
function foo()
{
    static $bar = <<<LABEL
Nothing in here...
LABEL;
}

// クラスのプロパティ/定数
class foo
{
    const BAR = <<<FOOBAR
Constant example
FOOBAR;

    public $baz = <<<FOOBAR
Property example
FOOBAR;
}
?>

PHP 5.3.0 以降では、ヒアドキュメントの宣言をダブルクォートで囲めるようにもなりました。

例5 ヒアドキュメントでのダブルクォート

<?php
echo <<<"FOOBAR"
Hello World!
FOOBAR;
?>

Nowdoc

Nowdoc はヒアドキュメントと似ていますが、 ヒアドキュメントがダブルクォートで囲んだ文字列として扱われるのに対して、 Nowdoc はシングルクォートで囲んだ文字列として扱われます。 Nowdoc の使用方法はヒアドキュメントとほぼ同じですが、 その中身について パース処理を行いません。 PHP のコードや大量のテキストを埋め込む際に、 エスケープが不要になるので便利です。この機能は、SGML の <![CDATA[ ]]> (ブロック内のテキストをパースしないことを宣言する) と同じようなものです。

Nowdoc の書き方は、ヒアドキュメントと同じように <<< を使用します。 しかし、その後に続く識別子をシングルクォートで囲んで <<<'EOT' のようにします。 ヒアドキュメントの識別子に関する決まりがすべて Nowdoc の識別子にも当てはまります。特に終了識別子の書き方に関する決まりに注意しましょう。

例6 Nowdoc による文字列のクォートの例

<?php
$str = <<<'EOD'
Example of string
spanning multiple lines
using nowdoc syntax.
EOD;

/* 変数を使った、より複雑な例 */
class foo
{
    public $foo;
    public $bar;

    function foo()
    {
        $this->foo = 'Foo';
        $this->bar = array('Bar1', 'Bar2', 'Bar3');
    }
}

$foo = new foo();
$name = 'MyName';

echo <<<'EOT'
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should not print a capital 'A': \x41
EOT;
?>

上の例の出力は以下となります。

My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should not print a capital 'A': \x41

注意:

ヒアドキュメントと異なり、Nowdoc は任意の静的データコンテキストで使用できます。 典型的な使用例は、クラスのプロパティや定数の初期化です。

例7 静的データの例

<?php
class foo {
    public $bar = <<<'EOT'
bar
EOT;
}
?>

注意:

Nowdoc のサポートは PHP 5.3.0 で追加されました。

変数のパース

スクリプトが二重引用符で括られるかヒアドキュメントで指定された場合、 その中の変数はパースされます。

構文の型には、単純な構文と 複雑な 構文の 2 種類があります。簡単な構文は、最も一般的で便利です。 この構文では、変数、配列値やオブジェクトのプロパティをパースすることが可能です。

複雑な構文は、式を波括弧で括ることにより認識されます。

簡単な構文

ドル記号 ($) を見付けると、 パーサは、有効な変数名を形成することが可能な最長のトークンを取得します。 変数名の終りを明示的に指定したい場合は、変数名を波括弧で括ってください。

<?php
$juice = "apple";

echo "He drank some $juice juice.".PHP_EOL;
// 動作しません。"s" は、変数名として有効な文字ですが、実際の変数名は $juice です。
echo "He drank some juice made of $juices.";
?>

上の例の出力は以下となります。

He drank some apple juice.
He drank some juice made of .

同様に、配列添字とオブジェクトのプロパティをパースすることも可能です。 配列添字の場合、閉じ角括弧 (]) は添字の終りを意味します。 シンプルな変数の場合と同じ規則が、オブジェクトのプロパティに対しても適用されます。

例8 簡単な構文の例

<?php
$juices = array("apple", "orange", "koolaid1" => "purple");

echo "He drank some $juices[0] juice.".PHP_EOL;
echo "He drank some $juices[1] juice.".PHP_EOL;
echo "He drank some juice made of $juice[0]s.".PHP_EOL; // 動作しません
echo "He drank some $juices[koolaid1] juice.".PHP_EOL;

class people {
    public $john = "John Smith";
    public $jane = "Jane Smith";
    public $robert = "Robert Paulsen";
    
    public $smith = "Smith";
}

$people = new people();

echo "$people->john drank some $juices[0] juice.".PHP_EOL;
echo "$people->john then said hello to $people->jane.".PHP_EOL;
echo "$people->john's wife greeted $people->robert.".PHP_EOL;
echo "$people->robert greeted the two $people->smiths."; // 動作しません
?>

上の例の出力は以下となります。

He drank some apple juice.
He drank some orange juice.
He drank some juice made of s.
He drank some purple juice.
John Smith drank some apple juice.
John Smith then said hello to Jane Smith.
John Smith's wife greeted Robert Paulsen.
Robert Paulsen greeted the two .

より複雑な場合は、複雑な構文を使用する必要があります。

複雑な (波括弧) 構文

この構文が「複雑(complex)な構文」と呼ばれているのは、 構文が複雑であるからではなく、 この方法では複雑な式を含めることができるからです。

どんなスカラー変数、配列の要素あるいはオブジェクトのプロパティの文字列表現であっても この構文で含めることができます。 文字列の外側に置く場合と同様に式を書き、これを { と } の間に含めてください。'{' はエスケープすることができないため、 この構文は $ が { のすぐ後に続く場合にのみ認識されます (リテラル "{$" を指定するには、"{\$" を使用してください)。 以下のいくつかの例を見ると理解しやすくなるでしょう。

<?php
// すべてのエラーを表示します
error_reporting(E_ALL);

$great = 'fantastic';

// うまく動作しません。出力: This is { fantastic}
echo "This is { $great}";

// うまく動作します。出力: This is fantastic
echo "This is {$great}";
echo "This is ${great}";

// 動作します
echo "This square is {$square->width}00 centimeters broad."; 


// 動作します。クォートしたキーを使う場合は、波括弧構文を使わなければなりません
echo "This works: {$arr['key']}";


// 動作します
echo "This works: {$arr[4][3]}";

// これが動作しない理由は、文字列の外で $foo[bar]
// が動作しない理由と同じです。
// 言い換えると、これは動作するともいえます。しかし、
// PHP はまず最初に foo という名前の定数を探すため、
// E_NOTICE レベルのエラー(未定義の定数) となります。
echo "This is wrong: {$arr[foo][3]}"; 

// 動作します。多次元配列を使用する際は、
// 文字列の中では必ず配列を波括弧で囲むようにします。
echo "This works: {$arr['foo'][3]}";

// 動作します
echo "This works: " . $arr['foo'][3];

echo "You can even write {$obj->values[3]->name}";

echo "This is the value of the var named $name: {${$name}}";

echo "This is the value of the var named by the return value of getName(): {${getName()}}";

echo "This is the value of the var named by the return value of \$object->getName(): {${$object->getName()}}";

// 動作しません。出力: This is the return value of getName(): {getName()}
echo "This is the return value of getName(): {getName()}";
?>

文字列内で、変数を使ってクラスのプロパティにアクセスすることもできます。 このような構文を使います。

<?php
class foo {
    var $bar = 'I am bar.';
}

$foo = new foo();
$bar = 'bar';
$baz = array('foo', 'bar', 'baz', 'quux');
echo "{$foo->$bar}\n";
echo "{$foo->$baz[1]}\n";
?>

上の例の出力は以下となります。

I am bar.
I am bar.

注意:

{$} の内部における 関数やメソッドのコール、静的クラス変数、クラス定数は、PHP 5 から動作します。 しかし、アクセスする値は文字列が定義されたスコープにおける変数名として解釈します。 ひとつの波括弧 ({}) では、 関数やメソッドの返り値、クラス定数や静的クラス変数の値にはアクセスできません。

<?php
// すべてのエラーを表示します
error_reporting(E_ALL);

class beers {
    const softdrink = 'rootbeer';
    public static $ale = 'ipa';
}

$rootbeer = 'A & W';
$ipa = 'Alexander Keith\'s';

// これは動作し、出力は I'd like an A & W となります
echo "I'd like an {${beers::softdrink}}\n";

// これも動作し、出力は I'd like an Alexander Keith's となります
echo "I'd like an {${beers::$ale}}\n";
?>

文字列への文字単位のアクセスと修正

$str[42] のように、 角括弧を使用してゼロから始まるオフセットを指定すると、 文字列内の任意の文字にアクセスし、修正することが可能です。 つまり、文字列を文字の配列として考えるわけです。 複数の文字を取り出したり変更したりしたいときは、関数 substr() および substr_replace() が使えます。

注意: $str{42} のように波括弧を使用してアクセスすることも可能です。

警告

範囲外のオフセットに書き込んだ場合は、空いた部分に空白文字が埋められます。 整数型以外の型は整数型に変換されます。 無効なオフセット形式を指定した場合は E_NOTICE を発行します。 負のオフセットを指定した場合は、書き込み時は E_NOTICE を発行しますが読み込み時は空の文字列を返します。 文字列を代入した場合は最初の文字だけを使用します。 空文字列を代入した場合は NULL バイトを代入します。

例9 文字列の例

<?php
// 文字列の最初の文字を取得します
$str = 'This is a test.';
$first = $str[0];

// 文字列の 3 番目の文字を取得します
$third = $str[2];

// 文字列の最後の文字を取得します
$str = 'This is still a test.';
$last = $str[strlen($str)-1]; 

// 文字列の最後の文字を変更します
$str = 'Look at the sea';
$str[strlen($str)-1] = 'e';

// {} を使用した、もうひとつの方法 (PHP 6 で廃止予定) です
$third = $str{2};

?>

注意:

その他の型の変数 (配列や、適切なインターフェイスを実装したオブジェクトを除く) に対して [] や {} でアクセスすると、何もメッセージを出さずに単に NULL を返します。

便利な関数および演算子

文字列は、'.' (ドット) 結合演算子で結合することが可能です。'+' (加算) 演算子はこの例では出てこないことに注意してください。詳細については 文字列演算子 を参照ください。

文字列の修正を行う場合には、便利な関数がたくさん用意されています。

一般的な関数については、文字列関数の節 を参照ください。高度な検索/置換を行う正規表現関数については Perl および POSIX 拡張 の 2 種類がありますが、 それぞれの節を参照ください。

URL 文字列用関数や文字列の暗号化/ 復号用の関数 (mcrypt および mhash) もあります。

最後に、探しているものがまだ見付からない場合には、 文字型の関数も参照ください。

文字列への変換

(string) キャストや strval() 関数を使って変数を文字列へ変換することができます。 文字列型を必要とする式のスコープにおいて、文字列への変換は自動的に行われます。 echo や print 関数を使うとき、 あるいは可変変数を文字列を比較するときにこの自動変換が行われます。 マニュアルの型 と 型の相互変換 の項を読むとわかりやすいでしょう。 settype()も参照してください。

boolean の TRUE は文字列の "1" に、 FALSE は "" (空文字列) に変換されます。 これにより boolean と文字列の値を相互に変換することができます。

integer (整数) や浮動小数点数 (float) は その数値の数字として文字列に変換されます (指数の表記や浮動小数点数を含めて)。 浮動小数点数は、指数表記 (4.1E+6) を使用して変換されます。

注意:

小数点を表す文字は、スクリプトのロケール (LC_NUMERIC カテゴリ) によって決まります。 setlocale() を参照ください。

配列は常に "Array" という文字列に変換されるので、 array の中を見るために echo や print を使ってダンプさせることはできません。 一つの要素を見るためには、echo $arr['foo'] のようにしてください。内容の全てをダンプ/見るためには以降の TIP をご覧ください。

PHP 4 のオブジェクトは、常に "Object" という文字列に変換されます。 デバッグ等のために object の内部の変数を出力するような場合には、 以下をご覧ください。オブジェクトがなんという名前のクラスの インスタンスなのかを知るには get_class() をご覧ください。 PHP 5 以降では、もし存在すれば __toString() メソッドを使用します。

リソースは常に "Resource id #1" という文字列に変換されます。1 は実行中の PHP によって割り当てられる resource のユニークな番号です。 リソースの型を知るためには get_resource_type() を使用してください。

NULL は常に空文字列に変換されます。

以上に述べたように、配列、オブジェクト、リソースをプリントアウトしても その値に関する有益な情報を得られるわけではありません。 デバッグのために値を出力するのによりよい方法が知りたければ、 print_r() や var_dump() を参照ください。

PHP 変数を恒久的に保存するための文字列に変換することもできます。 この方法はシリアライゼーションと呼ばれ、 serialize() 関数によって実現できます。 WDDX サポートを有効にして PHP をセットアップすれば、PHP 変数を XML 構造にシリアライズすることもできます。

文字列の数値への変換

数値として文字列が評価された時、結果の値と型は次のように定義されます。

文字列の中に '.' や 'e'、'E' といった文字が含まれず、 数値が integer 型の範囲内 (PHP_INT_MAX で定義されています) におさまる場合は integer として評価されます。それ以外の場合は、すべて float として評価されます。

文字列の最初の部分により値が決まります。文字列が、 有効な数値データから始まる場合、この値が使用されます。その他の場合、 値は 0 (ゼロ) となります。有効な数値データは符号(オプション)の後に、 1 つ以上の数字 (オプションとして小数点を 1 つ含む)、 オプションとして指数部が続きます。指数部は 'e' または 'E' の後に 1 つ以上の数字が続く形式です。

<?php
$foo = 1 + "10.5";              // $foo は float です (11.5)
$foo = 1 + "-1.3e3";            // $foo は float です (-1299)
$foo = 1 + "bob-1.3e3";         // $foo は integer です (1)
$foo = 1 + "bob3";              // $foo は integer です (1)
$foo = 1 + "10 Small Pigs";     // $foo は integer です (11)
$foo = 1 + "10 Little Piggies"; // $foo は integer です (11)
$foo = "10.0 pigs " + 1;        // $foo は integer です (11)
$foo = "10.0 pigs " + 1.0;      // $foo は float です (11)
?>

この変換に関する詳細は、Unix のマニュアルページで strtod(3) を参照ください。

本節の例を試したい場合、その例をカットアンドペーストしてから 動作を確認するために次の行を挿入してください。

<?php
echo "\$foo==$foo; type is " . gettype ($foo) . "<br />\n";
?>

(C 言語で行われるように) 数値に変換することで 一つの文字のコードを取得できると期待してはいけません。 文字と文字コードを相互に変換するには ord() および chr() 関数を使用してください。

文字列型の詳細

PHP における文字列型は、バイトの配列と整数値 (バッファ長) で実装されています。 バイト列を文字列に変換する方法については何の情報も持っておらず、完全にプログラマ任せとなっています。 文字列を構成する値には何の制限もありません。特に気をつけるべきなのは、 値 0 のバイト (いわゆる “NUL バイト”) を文字列内のどの部分にでも使えるという点です (しかし、このマニュアル上で「バイナリセーフではない」とされている一部の関数では、 受け取った文字列をライブラリに渡すときに NUL バイト以降を無視することがあります)。

PHP の文字列型の正体を知ってしまえば、なぜ PHP には「バイト型」が存在しないのかもわかります。 つまり、文字列型がその役割を受け持っているのです。テキスト以外のデータ、 たとえばネットワークソケットから読み込んだ任意のデータを返す関数も、 文字列で値を返します。

PHP が文字列に対して特定のエンコーディングを強制しないのなら、 いったいどのようにして文字列リテラルをエンコードしているのでしょう? たとえば、文字列 "á" と同等なのは "\xE1" (ISO-8859-1)、 "\xC3\xA1" (UTF-8, C form)、 "\x61\xCC\x81" (UTF-8, D form) のどれでしょう? あるいはそれ以外の何かなのでしょうか? 実は、文字列のエンコードはスクリプトファイルのエンコード方式に従って行われるというのが正解です。 したがって、もしスクリプトが ISO-8859-1 で書かれているのなら、文字列も ISO-8859-1 でエンコードされます。その他のエンコードの場合も同様です。 しかし、Zend Multibyte が有効になっている場合は話が別です。 この場合は、スクリプトはどんなエンコーディングで書いてもかまいません (明示的に宣言することもできるし、自動検出させることもできます)。 スクリプトはその後で内部エンコーディングに変換されるので、 文字列リテラルも内部エンコーディングと同じ方式で符号化されます。 スクリプトのエンコーディング (あるいは、Zend Multibyte を有効にした場合の内部エンコーディング) には、一部制限があることに注意しましょう。 ひとことで言うと、ASCII の上位互換 でなければならないということです。 UTF-8 や ISO-8859-1 などがこれにあたります。 しかし、状態に依存する (たとえば、同じバイト値が、先頭にあるときとシフト状態にあるときで違う意味になる) エンコーディングは、問題になる可能性があります。

もちろん、利便性を考慮すれば、テキストを操作する関数が文字列のエンコードを扱う際に 何らかの前提に基づかざるを得ないこともあります。 残念ながら、PHP の各関数が文字列のエンコーディングを判断する方法はまったく統一されていません。

  • いくつかの関数は、文字列が何らかのシングルバイトエンコーディングで符号化されているものと見なします。 しかし、文字列内の各バイトが必ずしも特定の文字に変換できなくてもかまいません。 このタイプの関数は、substr() や strpos()、strlen()、 strcmp() などです。 これらの関数については、文字列を扱うというよりメモリ上のバッファを扱うものととらえてもよいでしょう。 つまり、バイト列とバイトオフセットで考えるということです。
  • 文字列のエンコーディングを受け取る関数もあります。 エンコーディング情報を省略したときにはデフォルトを用意していることもあるでしょう。 このタイプの関数の例は、htmlentities() や 大半の mbstring 関数です。
  • 現在のロケール (setlocale() を参照ください) を使うけれども、 処理はバイト単位で行う関数もあります。 このタイプの関数は strcasecmp() や strtoupper() そして ucfirst() です。 つまり、これらの関数はシングルバイトエンコーディングでしか使えず、 さらにエンコーディングとロケールがマッチしていなければならないということです。 たとえば、strtoupper("á") が正しく "Á" を返すには、ロケールを正しく設定したうえで á をシングルバイトで符号化しておかなければなりません。仮に UTF-8 を使っていたとすると、 正しい結果は返されないでしょう。さらに、現在のロケール設定によっては 返される文字列が壊れてしまう可能性もあります。
  • 最後に、文字列が特定のエンコーディング (たいていは UTF-8) であることを前提としている関数があります。 intl の関数や PCRE の関数 (u 修飾子を使う場合のみ) の多くがこのタイプになります。また、その関数の目的上、 utf8_decode() 関数は入力が UTF-8 であることを前提とし、 utf8_encode() 関数は入力が ISO-8859-1 であることを前提としています。

結局、Unicode を使うプログラムをきちんと書くには、 うまく動かない関数の使わないよう注意するしかないということです。 特にデータを破壊してしまう可能性のある関数の使用は避け、 きちんと動作する関数を使うようにしましょう。 intl や mbstring の関数を選択するとよいでしょう。 しかし、Unicode をまともに扱える関数を使うというのは単なる始まりに過ぎません。 たとえ関数側で Unicode を扱う機能があったとしても、 Unicode の仕様に関する知識は不可欠です。 たとえば、世の中には大文字と小文字しか存在しないという思い込みで作ったプログラムは、 うまく動かない可能性があります。

配列

PHP の配列は、実際には順番付けられたマップです。マップは型の一種で、 値をキーに関連付けます。 この型は、いくつかの手法で最適化されます。このため、 実際の配列またはリスト (ベクトル)、(あるマップの実装である) ハッシュテーブル、ディレクトリ、コレクション、スタック、 キュー等として使用することが可能です。 PHP の配列には他の PHP 配列を値として保持することができるため、 非常に簡単にツリー構造を表現することが可能です。

これらのデータ構造に関する説明は本マニュアルの範囲外ですが、 これらの構造に各々に関する例を少なくとも一つ見付けることが可能です。 この分野は広範囲にまたがるので、 より詳細な情報については他の書籍を参照ください。

構文

array() で指定

配列 は、言語に組み込まれた array() で作成することが可能です。この構造は、 特定の数のカンマで区切られた キー => 値 の組を引数とします。 

array(
    key  => value,
    key2 => value2,
    key3 => value3,
    ...
)

最後の要素のあとのカンマは、書いても書かなくてもかまいません。 配列を一行で定義する場合は、ふつうは最後のカンマを省略します。つまり、 array(1, 2) のほうが array(1, 2, ) よりおすすめだということです。 しかし複数行で定義する場合は、最後のカンマをつけることが一般的です。 そうしておけば、配列の最後に要素を追加するのが容易になるからです。

PHP 5.4 以降では配列の短縮構文が追加され、 array() の代わりに [] を使えるようになりました。

例1 シンプルな配列定義

<?php
$array = array(
    "foo" => "bar",
    "bar" => "foo",
);

// PHP 5.4 ではこのようにも書けます
$array = [
    "foo" => "bar",
    "bar" => "foo",
];
?>

key は、整数 または 文字列です。 value には任意の型を指定できます。

さらに、次のような key のキャストが発生します。

  • integer として妥当な形式の文字列は integer 型にキャストされます。 つまり、キーに "8" を指定すると、実際には 8 として格納されるということです。一方 "08" はキャストされません。これは十進数として妥当な形式ではないからです。
  • floats もまた integer にキャストされます。つまり、 小数部分は切り捨てられるということです。たとえばキーに 8.7 を指定すると、実際には 8 として格納されます。
  • bool も integer にキャストされます。つまり、 キーに true を指定すると実際には 1 に格納され、 同様にキーを false とすると実際には 0 となります。
  • Null は空文字列にキャストされます。つまり、キーに null を指定すると、実際には "" として格納されます。
  • array や object は、キーとして使えません。 キーとして使おうとすると Illegal offset type という警告が発生します。

PHP 5.4 以降では、文字列のオフセット指定の挙動が一貫性のあるものになりました。 その結果として、以前のバージョンとは挙動が変わることがあります。 PHP 5.4 以降で文字列のオフセットとして指定できるのは整数あるいは整数とみなせる文字列だけであり、 それ以外の場合は警告が発生します。

例2 文字列のオフセット指定の例

<?php
$str = 'abc';

var_dump($str['1']);
var_dump(isset($str['1']));

var_dump($str['1.0']);
var_dump(isset($str['1.0']));

var_dump($str['x']);
var_dump(isset($str['x']));

var_dump($str['1x']);
var_dump(isset($str['1x']));
?>

上の例の PHP 5.3 での出力は、このようになります。

string(1) "b"
bool(true)
string(1) "b"
bool(true)
string(1) "a"
bool(true)
string(1) "b"
bool(true)

上の例の PHP 5.4 での出力は、このようになります。

string(1) "b"
bool(true)

Warning: Illegal string offset '1.0' in /tmp/t.php on line 7
string(1) "b"
bool(false)

Warning: Illegal string offset 'x' in /tmp/t.php on line 9
string(1) "a"
bool(false)
string(1) "b"
bool(false)

配列の宣言時に同じキーで複数の要素を指定すると、 最後に指定したものがそれまでの値を上書きします。

例3 型のキャストと値の上書きの例

<?php
$array = array(
    1    => "a",
    "1"  => "b",
    1.5  => "c",
    true => "d",
);
var_dump($array);
?>

上の例の出力は以下となります。

array(1) {
  [1]=>
  string(1) "d"
}

上の例では、すべてのキーが 1 にキャストされます。 そして後から指定した値がどんどん前の値を上安芸市定期、最終的には最後に代入された "d" だけが残ります。

PHP においては添字配列と連想配列の間に違いはなく、配列型は 1 つだけで、 同じ配列で整数のインデックスと文字列のインデックスを同時に使えます。

例4 整数と文字列のキーの混在例

<?php
$array = array(
    "foo" => "bar",
    "bar" => "foo",
    100   => -100,
    -100  => 100,
);
var_dump($array);
?>

上の例の出力は以下となります。

array(4) {
  ["foo"]=>
  string(3) "bar"
  ["bar"]=>
  string(3) "foo"
  [100]=>
  int(-100)
  [-100]=>
  int(100)
}

key はオプションです。省略した場合、PHP はこれまでに使われた整数のキーの中で最大のものに 1 を加えた値を使います。

例5 数値添字配列でキーを省略する例

<?php
$array = array("foo", "bar", "hallo", "world");
var_dump($array);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(5) "hallo"
  [3]=>
  string(5) "world"
}

一部の要素にだけキーを指定することもできます。

例6 一部の要素にだけキーを指定する例

<?php
$array = array(
         "a",
         "b",
    6 => "c",
         "d",
);
var_dump($array);
?>

上の例の出力は以下となります。

array(4) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [6]=>
  string(1) "c"
  [7]=>
  string(1) "d"
}

ごらんの通り、最後の値である "d" のキーは 7 となります。それまでにキーとして使われた最大の整数が 6 だからです。

角括弧構文による配列要素へのアクセス

配列の要素へのアクセスには array[key] 構文を使います。

例7 配列の要素へのアクセス

<?php
$array = array(
    "foo" => "bar",
    42    => 24,
    "multi" => array(
         "dimensional" => array(
             "array" => "foo"
         )
    )
);

var_dump($array["foo"]);
var_dump($array[42]);
var_dump($array["multi"]["dimensional"]["array"]);
?>

上の例の出力は以下となります。

string(3) "bar"
int(24)
string(3) "foo"

PHP 5.4 以降では、関数やメソッドの返す結果を直接配列として扱えるようになりました。 以前は、いったん一次変数に代入しないと配列としては扱えませんでした。

例8 配列のデリファレンス

<?php
function getArray() {
    return array(1, 2, 3);
}

// PHP 5.4 ではこのように書けます。
$secondElement = getArray()[1];

// 以前は、このようにするか
$tmp = getArray();
$secondElement = $tmp[1];

// あるいはこのようにしなければなりませんでした。
list(, $secondElement) = getArray();
?>

注意:

配列に定義されていないキーへアクセスしたときの挙動は、 未定義の変数にアクセスしたときと同じです。 E_NOTICE メッセージが発行され、 返される結果は NULL となります。

角括弧構文で作成/修正

明示的に値を設定することにより、既存の配列を修正することも可能です。

これは、角括弧の中にキーを指定し、配列に値を代入することにより行います。 キーを省略することも可能です。この場合、空の角括弧 ("[]") の変数名として追加してください。 

$arr[キー] = 値;
$arr[] = value;
// キー は 文字列 または
// 非負の整数のどちらかです。
// 値 は何でもかまいません

$arr がまだ存在しない場合は、新しく作成します。 つまり、これは配列を作成する方法のひとつでもあります。 とはいえ、この方法を使うことはおすすめしません。なぜなら、既に $arr に何らかの値 (リクエスト変数からの文字列など) が入っている場合にはその値がそのまま残り、 [] が実際には 文字列アクセス演算子 を表してしまうからです。 変数を初期化するときには、直接代入するほうがよいでしょう。

ある値を変更するには、 新しい値に値を代入します。特定のキー/値の組を削除したい場合には、 unset() を使用する必要があります。

<?php
$arr = array(5 => 1, 12 => 2);

$arr[] = 56;    // このスクリプトのこの位置に記述した場合、
                // $arr[13] = 56; と同じです

$arr["x"] = 42; // キー"x"の新しい要素を配列に追加します
                
unset($arr[5]); // 配列から要素を削除します

unset($arr);    // 配列全体を削除します
?>

注意:

上記のように、キーを省略して新規要素を追加する場合、 追加される数値添字は、使用されている添字の最大値 +1 (ただし、少なくとも 0 以上) になります。 まだ数値添字が存在しない場合は、添字は 0 (ゼロ) となります。

警告

PHP 4.3.0 以降、上記のような添字生成動作は変更されました。 現在では、配列に追加する際に、 その配列の最大添字が負である場合は次の添え字はゼロ (0) となります。 以前は、正の添字の場合と同様に新しい添字は最大添字に +1 したものがセットされました。

次のキー生成において、オフセットとして使われる整数値 (添字の最大値) に対応するエントリーが、 必ずしも配列内に存在するわけではないことに注意してください。 しかし、その値は、多くの場合、 配列にある整数のキー値の最大値と等しいはずです。以下に例を示します。

<?php
// 簡単な配列を生成します。
$array = array(1, 2, 3, 4, 5);
print_r($array);

// 全てのアイテムを削除しますが、配列自体は削除しないでおきます。
foreach ($array as $i => $value) {
    unset($array[$i]);
}
print_r($array);

// アイテムを追加します(新しい添え字は0ではなく
// 5となることに注意)
$array[] = 6;
print_r($array);

// 添え字を振りなおします。
$array = array_values($array);
$array[] = 7;
print_r($array);
?>

上の例の出力は以下となります。

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)
Array
(
)
Array
(
    [5] => 6
)
Array
(
    [0] => 6
    [1] => 7
)

有用な関数

配列で使用する便利な関数がたくさんあります。 配列関数 の節を参照ください。

注意:

unset()関数は配列のキーを削除することが出来ます。 ただし、これによってインデックスの再構築が行われるわけではないことに 注意してください。 "通常の整数添字" (0 から始まり、1 つずつ増加) のみを使用している場合、 array_values() を用いてインデックスを再構築することができます。

<?php
$a = array(1 => 'one', 2 => 'two', 3 => 'three');
unset($a[2]);
/* これにより配列は以下の様に定義されます。
   $a = array(1 => 'one', 3 => 'three');
   以下ではありません：
   $a = array(1 => 'one', 2 =>'three');
*/

$b = array_values($a);
// $b は、array(0 => 'one', 1 =>'three')となります
?>

配列専用の制御構造として foreach があります。 この構造は、配列の要素に簡単に連続的にアクセスする手段を提供します。

配列ですべきこととしてはならないこと

なぜ、$foo[bar] は使用できないのか?

連想配列の添字の前後は常に引用符で括る必要があります。 例えば、$foo[bar] ではなく $foo['bar'] を使用してください。 しかし、$foo[bar] はなぜ誤りなのでしょうか? 古いスクリプトで次のような構文を見たことがあるかもしれません。

<?php
$foo[bar] = 'enemy';
echo $foo[bar];
// etc
?>

これは間違っていますが、動作します。では、なぜ間違っているのでしょう? その理由は、このコードには文字列 ('bar' - 引用符で括られている) ではなく未定義の定数 (bar) が使用されており、PHP が同じ名前の定数を不幸にして同じコードの中に定義する可能性があるためです。 下位互換性の維持のため、未定義の定数は同じ名前の文字列に自動的に変換されます。 そのため、このコードは動作します。 例えば、bar という名前の定義されていない定数があるとすると、 PHP は 'bar' という文字列でそれを置換して使用します。

注意: これは、添字を常にクォートするという意味ではありません。 定数や 変数 を添字として使う際には、クォートしてしまうと PHP はそれを解釈できなくなってしまいます。

<?php
error_reporting(E_ALL);
ini_set('display_errors', true);
ini_set('html_errors', false);
// 単純な配列
$array = array(1, 2);
$count = count($array);
for ($i = 0; $i < $count; $i++) {
    echo "\nChecking $i: \n";
    echo "Bad: " . $array['$i'] . "\n";
    echo "Good: " . $array[$i] . "\n";
    echo "Bad: {$array['$i']}\n";
    echo "Good: {$array[$i]}\n";
}
?>

上の例の出力は以下となります。

Checking 0: 
Notice: Undefined index:  $i in /path/to/script.html on line 9
Bad: 
Good: 1
Notice: Undefined index:  $i in /path/to/script.html on line 11
Bad: 
Good: 1

Checking 1: 
Notice: Undefined index:  $i in /path/to/script.html on line 9
Bad: 
Good: 2
Notice: Undefined index:  $i in /path/to/script.html on line 11
Bad: 
Good: 2

この具体例を以下に示します。

<?php
// エラーを全て表示するよう設定
error_reporting(E_ALL);

$arr = array('fruit' => 'apple', 'veggie' => 'carrot');

// 正しい
print $arr['fruit'];  // apple
print $arr['veggie']; // carrot

// 間違い。これは動作しますが、未定義の定数fruitを使用しているため、
// 同時にE_NOTICEレベルのPHPエラーを発生します
//
// Notice: Use of undefined constant fruit - assumed 'fruit' in...
print $arr[fruit];    // apple

// 検証のため、定数を定義してみましょう。
// fruitという名前の定数に値'veggie'を代入します。
define('fruit', 'veggie');

// ここでは、出力が異なることに注意してください。
print $arr['fruit'];  // apple
print $arr[fruit];    // carrot

// 以下は文字列の中であるためOKです。定数は、文字列の中では解釈されな
// いため、E_NOTICEエラーはここでは発生しません。
print "Hello $arr[fruit]";      // Hello apple

// 例外が１つあり、文字列の中で波括弧で配列を括った場合には、
// 定数が解釈されます
print "Hello {$arr[fruit]}";    // Hello carrot
print "Hello {$arr['fruit']}";  // Hello apple

// これは動作せず、以下のようなパースエラーを発生します:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// 文字列の中でスーパーグローバルを使用した場合も無論同様です。
print "Hello $arr['fruit']";
print "Hello $_GET['foo']";

// 文字列結合で同じことをすることもできます。
print "Hello " . $arr['fruit']; // Hello apple
?>

error_reporting() で (E_ALL を指定する等により) E_NOTICE レベルのエラー出力を有効にした場合、 上記のエラーが出力されます。 デフォルトでは、 error_reporting はこれらを表示しない設定になっています。

構文の節に記述したように、角括弧 ('[' および ']') の間には、式がなければなりません。これは、 次のように書くことが可能であることを意味します。

<?php
echo $arr[somefunc($bar)];
?>

これは、関数の戻り値を配列の添字として使用する例です。PHP は定数についても認識します。以下のような E_* の使用例を見たことがあるかもしれません。

<?php
$error_descriptions[E_ERROR]   = "A fatal error has occured";
$error_descriptions[E_WARNING] = "PHP issued a warning";
$error_descriptions[E_NOTICE]  = "This is just an informal notice";
?>

最初の例の bar と全く同様に E_ERROR も有効な添字であることに注意してください。 しかし、実際には最後の例は次のように書くことと同じです。

<?php
$error_descriptions[1] = "A fatal error has occured";
$error_descriptions[2] = "PHP issued a warning";
$error_descriptions[8] = "This is just an informal notice";
?>

これは、E_ERROR が 1 と等しいこと等によります。

では、なぜ $foo[bar] は動作することが可能なのでしょう? それは、bar が定数式であることを 期待される構文で使用されているためです。しかし、この場合、 bar という名前の定数は存在しません。PHP は、 この場合、あなたが文字列"bar" のようにリテラル bar を指定したが引用符を忘れたと仮定します。

では、なぜ間違っているのでしょう?

将来的に、PHP 開発チームが他の定数またはキーワードを追加したいと思うかもしれず、 問題となる可能性があります。例えば、現在でも、 単語 empty および defaultを使用することはできません。 これは、これらが特別な 予約済みのキーワードであるためです。

注意: 二重引用符で括られた文字列の中では 引用符で配列の添字を括らないことができ、このため、 "$foo[bar]" は有効です。 この理由の詳細については、上記の例や 文字列中での変数のパースを参照してください。

配列への変換

integer, float, string, boolean, resourceのいずれの型においても、 array に変換する場合、 最初のスカラー値が割り当てられている一つの要素 (添字は 0) を持つ配列を得ることになります。

objectを配列にする場合には、配列の要素として オブジェクトの属性 (メンバ変数) を持つ配列を得ることになります。 添字はメンバ変数名となりますが、いくつか注意すべき例外があります。 整数のプロパティはアクセス不能になります。 private 変数の場合、変数名の頭にクラス名がつきます。また、 protected 変数の場合は、変数名の頭に '*' がつきます。 このとき、頭に追加される値の前後に null バイトがついてきます。 その結果、予期せぬ振る舞いをすることがあります。

<?php

class A {
    private $A; // これは '\0A\0A' となります
}

class B extends A {
    private $A; // これは '\0B\0A' となります
    public $AA; // これは 'AA' となります
}

var_dump((array) new B());
?>

上の例では 'AA' というキーがふたつあるように見えますが、 そのうちひとつは、実際は '\0A\0A' ということになります。

NULL を配列に変換すると、空の配列を得ます。

比較

array_diff() と 配列演算子 を用いると、配列を比較することができます。

例

PHP の配列型は、いろいろな使い方ができます。配列の強力な機能を示すため、 ここでいくつかの例を紹介します。

<?php
// これは、
$a = array( 'color' => 'red',
            'taste' => 'sweet',
            'shape' => 'round',
            'name'  => 'apple',
            4        // キーは0になります
          );

$b = array('a', 'b', 'c');

// は、完全にこれと同じです。
$a = array();
$a['color'] = 'red';
$a['taste'] = 'sweet';
$a['shape'] = 'round';
$a['name']  = 'apple';
$a[]        = 4;        // キーは0になります

$b = array();
$b[] = 'a';
$b[] = 'b';
$b[] = 'c';

// 上のコードを実行すると、$a は次のような配列
// array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round', 
// 'name' => 'apple', 0 => 4) となり、$b は
// array(0 => 'a', 1 => 'b', 2 => 'c') あるいは単に array('a', 'b', 'c') となります
?>

例9 array() の使用例

<?php
// マップを行う配列
$map = array( 'version'    => 4,
              'OS'         => 'Linux',
              'lang'       => 'english',
              'short_tags' => true
            );
            
// 数値キーのみを有する
$array = array( 7,
                8,
                0,
                156,
                -10
              );
// これは、array( 0 => 7, 1 => 8, ...) と同じです

$switching = array(         10, // key = 0
                    5    =>  6,
                    3    =>  7, 
                    'a'  =>  4,
                            11, // key = 6 (最大の添字は5です)
                    '8'  =>  2, // key = 8 (整数!)
                    '02' => 77, // key = '02'
                    0    => 12  // 値10は12で上書きされます
                  );
                  
// 空の配列
$empty = array();         
?>

例10 コレクション

<?php
$colors = array('red', 'blue', 'green', 'yellow');

foreach ($colors as $color) {
    echo "Do you like $color?\n";
}

?>

上の例の出力は以下となります。

Do you like red?
Do you like blue?
Do you like green?
Do you like yellow?

PHP 5 以降では、配列を参照渡しすることでその値を直接変更できるようになりました。 それ以前のバージョンでは、以下のような回避策が必要です。

例11 ループ内での要素の変更

<?php
// PHP 5
foreach ($colors as &$color) {
    $color = strtoupper($color);
}
unset($color); /* これ以降の $color への書き込みが
配列の要素を書き換えてしまわないことを保証する */

// 旧バージョンでの回避策
foreach ($colors as $key => $color) {
    $colors[$key] = strtoupper($color);
}

print_r($colors);
?>

上の例の出力は以下となります。

Array
(
    [0] => RED
    [1] => BLUE
    [2] => GREEN
    [3] => YELLOW
)

この例は、1 から始まる配列を作成します。

例12 1 から始まる添字

<?php
$firstquarter  = array(1 => 'January', 'February', 'March');
print_r($firstquarter);
?>

上の例の出力は以下となります。

Array 
(
    [1] => 'January'
    [2] => 'February'
    [3] => 'March'
)

例13 配列に代入する

<?php
// ディレクトリから全てのアイテムを配列に代入する
$handle = opendir('.');
while (false !== ($file = readdir($handle))) {
    $files[] = $file;
}
closedir($handle); 
?>

配列には順番が付けられます。異なったソート関数を用いて順番を変更することも可能です。 より詳細な情報については、配列関数 を参照ください。 count() 関数を使用することで、 配列の要素数を数えることが可能です。

例14 配列のソート

<?php
sort($files);
print_r($files);
?>

配列の値は何でも良いため、その値を他の配列とすることも可能です。 これにより、再帰的な配列や多次元の配列を作成することが可能です。

例15 再帰および多次元配列

<?php
$fruits = array ( "fruits"  => array ( "a" => "orange",
                                       "b" => "banana",
                                       "c" => "apple"
                                     ),
                  "numbers" => array ( 1,
                                       2,
                                       3,
                                       4,
                                       5,
                                       6
                                     ),
                  "holes"   => array (      "first",
                                       5 => "second",
                                            "third"
                                     )
                );

// 上の配列の内容を取得するための例
echo $fruits["holes"][5];    // "second" を表示します
echo $fruits["fruits"]["a"]; // "orange" を表示します
unset($fruits["holes"][0]);  // "first"  を削除します

// 新しい多次元配列を作成します
$juices["apple"]["green"] = "good"; 
?>

配列への代入においては、常に値がコピーされることに注意してください。 配列をリファレンスでコピーする場合には、 リファレンス演算子を使う必要があります。

<?php
$arr1 = array(2, 3);
$arr2 = $arr1;
$arr2[] = 4; // $arr2 が変更されます。
             // $arr1 は array(2,3) のままです。
             
$arr3 = &$arr1;
$arr3[] = 4; // $arr1 と $arr3 は同じ内容になります。
?>

オブジェクト

オブジェクトの初期化

オブジェクトを初期化するためには、new 命令によりオブジェクトのインスタンスを変数に作成します。

<?php
class foo
{
    function do_foo()
    {
        echo "foo を実行します。";
    }
}

$bar = new foo;
$bar->do_foo();
?>

詳細な事項については、 クラスおよびオブジェクト に関するセクションを参照ください。

オブジェクトへの変換

オブジェクトがオブジェクトに変換される場合、それは修正されません。 他の型の値がオブジェクトに変換される場合、ビルトインクラスである stdClass の新しいインスタンスが生成されます。 値が null の場合、新しいインスタンスは空となります。 配列がオブジェクトに変換される場合、配列のキーがプロパティ名となり、 配列の値がプロパティの値となります。他の値の場合、 scalar という名前のメンバ変数が値を格納します。

<?php
$obj = (object) 'ciao';
echo $obj->scalar;  // 'ciao' を出力します
?>

リソース

リソースは特別な変数であり、外部リソースへのリファレンスを保持しています。 います。リソースは、特別な関数により作成され、使用されます。 これらの関数および対応する全てのリソース型の一覧については、 付録 を参照ください。

get_resource_type() も参照ください。

リソースへの変換

リソース型は、オープンされたファイル、データベース接続、 イメージキャンバスエリアのような特殊なハンドルを保持するため、 他の値をリソースに変換することはできません。

リソースの開放

PHP 4 の Zend エンジンに導入されたリファレンスカウンティングシステムのおかげで、 あるリソースがもう参照されなくなった場合に (Java と全く同様に)、 そのリソースは自動的に削除されます。この場合、このリソースが作成した 全てのリソースは、ガベージコレクタにより開放されます。 このため、free_result 関数を用いて手動でメモリを開放する必要が生じるのはまれです。

注意: 持続的データベース接続は特別で、ガベージコレクタにより破棄されません。 持続的接続 も参照ください。

NULL

特別な NULL 値は、ある変数が値を持たないことを表します。NULL は、NULL 型の唯一の値です。

変数は、以下の場合に NULL とみなされます。

  • 定数 NULL が代入されている場合。

  • まだ値が何も代入されていない場合。

  • unset() されている場合。

構文

NULL 型の値は一つだけで、 大文字小文字を区別しない定数 NULLです。

<?php
$var = NULL;       
?>

is_null() および unset() も参照ください。

NULL へのキャスト

(unset) $var を使って変数を null にキャストすると、 その変数を削除したり値の設定を解除したりはしません。 単に NULL 値を返すだけです。

コールバック

コールバックは、PHP 5.4 以降では callable タイプヒントで表されます。 このページでは、callback 型情報を同じ目的で使っています。 purpose.

call_user_func() や usort() 等の関数は、ユーザーが定義するコールバック関数を引数として受け入れます。 コールバック関数は、単純な関数だけでなく、オブジェクトのメソッド あるいはクラスの静的メソッドであってもかまいません。

受け渡し

PHP 関数はその名前を単に文字列として渡します。 どのようなビルトインまたはユーザー定義の関数も渡すことができます。 ただし、 array(), echo, empty(), eval(), exit(), isset(), list(), print あるいは unset() といった言語構造はコールバックとしては使えないことに注意しましょう。

オブジェクトのインスタンスを渡すには配列を使います。 配列の 0 番目の要素にオブジェクトを、 そして 1 番目の要素にメソッド名を指定します。

静的なクラスメソッドの場合、オブジェクトのインスタンスは不要です。 0 番目の要素として、オブジェクトのかわりにクラス名を指定します。 PHP 5.2.3 以降では、 'ClassName::methodName' 形式で指定することもできます。

一般的なユーザー定義関数とは異なり、create_function() では無名コールバック関数も作成できます。PHP 5.3.0 以降は、 クロージャ をパラメータとして渡せるようになりました。

例1 コールバック関数の例

<?php 

// コールバック関数の例
function my_callback_function() {
    echo 'hello world!';
}

// コールバックメソッドの例
class MyClass {
    static function myCallbackMethod() {
        echo 'Hello World!';
    }
}

// タイプ 1: 単純なコールバック
call_user_func('my_callback_function'); 

// タイプ 2: 静的クラスメソッドのコール
call_user_func(array('MyClass', 'myCallbackMethod')); 

// タイプ 3: オブジェクトメソッドのコール
$obj = new MyClass();
call_user_func(array($obj, 'myCallbackMethod'));

// タイプ 4: 静的クラスメソッドのコール (PHP 5.2.3 以降)
call_user_func('MyClass::myCallbackMethod');

// タイプ 5: 相対指定による静的クラスメソッドのコール (PHP 5.3.0 以降)
class A {
    public static function who() {
        echo "A\n";
    }
}

class B extends A {
    public static function who() {
        echo "B\n";
    }
}

call_user_func(array('B', 'parent::who')); // A
?>

例2 クロージャを使ったコールバックの例

<?php
// クロージャ
$double = function($a) {
    return $a * 2;
};

// 数値の範囲
$numbers = range(1, 5);

// ここでクロージャをコールバックとして使用し、
// 指定した範囲の各要素の二倍の値を計算します
$new_numbers = array_map($double, $numbers);

print implode(' ', $new_numbers);
?>

上の例の出力は以下となります。

2 4 6 8 10

注意: PHP 4 では、実際のオブジェクトを指すコールバックを作成するには、 コピーではなく参照を使わなければなりませんでした。 詳細は 参照についての説明 を参照ください。

注意:

call_user_func() や call_user_func_array() で登録されたコールバックは、 前のコールバックからスローされた例外がキャッチされていない場合はコールされません。

本ドキュメントにおける疑似的な型および変数

mixed

mixed は、引数に多様な型 (全てである必要はない) を使うことができることを示します。

例えば gettype() 関数は全ての PHP の型を受け入れるのに対し、 str_replace() は文字列と配列のみを受け入れます。

number

number は引数が integer または float のどちらでもよいことを示します。

callback

callback 疑似型がこのドキュメントで使われていたのは、PHP 5.4 で callable タイプヒントが導入される前のことでした。両者はまったく同じ意味です。

void

返り値の型が void である場合は、 返り値に意味がないことを表します。パラメータ一覧で void が使用されている場合は、 その関数がパラメータを受け付けないことを表します。

...

関数のプロトタイプ宣言における $... は、 …など を表します。 この変数名を用いるのは、たとえば任意の数の引数を取りうる関数などです。

型の相互変換

PHP は、変数定義時に明示的な型定義を必要と(または、サポート) しません。ある変数の型は、その変数が使用される文により定義されます。 これは、ある文字列を変数 var に代入した場合には、 var は文字列になることを意味しています。 ある整数値を var に代入した場合には、 その変数は整数になります。

PHP の自動型変換の例の一つは、加算演算子 '+' です。 オペランドのどれかが float の場合、全てのオペランドは float として評価され、結果は float になります。 その他の場合、オペランドは整数として解釈され、結果も整数になります。 この自動型変換は、 オペランド自体の型を変更するものではないということに注意してください。 変わるのは、オペランドがどのように評価されるかだけです。

<?php
$foo = "0";  // $foo は文字列です (ASCII 48)
$foo += 2;   // ここでは、$foo は整数です (2)
$foo = $foo + 1.3;  // ここでは、$foo はfloatです (3.3)
$foo = 5 + "10 Little Piggies"; // $foo は整数です (15)
$foo = 5 + "10 Small Pigs";     // $foo は整数です (15)
?>

最後の二つの例が奇妙に思える場合には、 文字列変換 を参照ください。

ある変数を強制的にある特定の型として評価させたい場合には、 型キャスト のセクションを参照ください。ある変数の型を変更したい場合には、 settype() を参照してください。

本節の例をテストしたい場合には、 var_dump() を使用することが可能です。

注意:

配列への自動変換の動作は現時点で定義されていません。

また、PHP では配列の添字と同じ構文を使用した文字列へのアクセスをサポートしているので、 次の例はあらゆるバージョンの PHP で成立します。

<?php
$a    = 'car'; // $a は文字列です
$a[0] = 'b';   // $a はここでも文字列です
echo $a;       // bar
?>

詳細は、 文字として文字列をアクセスするというセクションを参照してください。

型キャスト

PHP の型キャストは、C 言語と同様に動作します。つまり、 変換しようとする型を括弧で括り、キャストする変数の前に置きます。

<?php
$foo = 10;   // $foo は整数です
$bar = (boolean) $foo;   // $bar はbooleanです
?>

使用可能なキャストを以下に示します。

  • (int), (integer) - 整数へのキャスト
  • (bool), (boolean) - 論理値へのキャスト
  • (float), (double), (real) - float へのキャスト
  • (string) - 文字列へのキャスト
  • (array) - 配列へのキャスト
  • (object) - オブジェクトへのキャスト
  • (unset) - NULL へのキャスト (PHP 5)

(binary) によるキャストや b プレフィックスのサポートは、PHP 5.2.1 で追加されました。

括弧の中でタブとスペースを使用することができることに注意してください。 したがって、次の文は機能的に等価です。

<?php
$foo = (int) $bar;
$foo = ( int ) $bar;
?>

リテラル文字列や変数を、バイナリ文字列にキャストします。

<?php
$binary = (binary) $string;
$binary = b"binary string";
?>

注意:

ある変数を文字列にキャストする代わりに、 二重引用符で括ることもできます。

<?php
$foo = 10;            // $foo は整数です
$str = "$foo";        // $str は文字列です
$fst = (string) $foo; // $fst も文字列です

// これは、"they are the same"を出力します
if ($fst === $str) {
    echo "they are the same";
}
?>

型の間でキャストを行う際の動作は、必ずしも明確ではありません。 詳細については、以下の節を参照ください。

変数

目次

基本的な事

PHP の変数はドル記号の後に変数名が続く形式で表されます。 変数名は大文字小文字を区別します。

変数名は、PHPの他のラベルと同じルールに従います。 有効な変数名は文字またはアンダースコアから始まり、任意の数の文字、 数字、アンダースコアが続きます。正規表現によれば、これは次の ように表現することができます。 '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'

注意: ここで言うところの文字とはa-z、A-Z、127から255まで (0x7f-0xff)のバイトを意味します。

注意: $this は特別な変数であり、ここに代入することはできません。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

変数関連の関数に関する情報については、 変数関数リファレンス を参照ください。

$var = 'Bob';
$Var = 'Joe';
echo "$var, $Var";      // "Bob, Joe"を出力します。

$4site = 'not yet';     // 無効：数字で始まっている。
$_4site = 'not yet';    // 有効：アンダースコアで始まっている。
$täyte = 'mansikka';    // 有効：'ä' はアスキーコード228です。

デフォルトでは、変数に代入されるのは常にその値です。 これは、つまり、ある変数にある式を代入する際、元の式の 値全体がコピーされる側の変数にコピーされるということです。 これは、例えば、ある変数の値を他の変数に代入した後で、 これらの変数の1つを変更しても他の変数には影響を与えないという ことを意味します。この種の代入に関するより詳細な情報については、 式 を参照ください。

PHP には、変数に値の代入を行う別の方法も存在します。それは、 参照による代入 です。 この場合、新規の変数は元の変数を参照するだけです。 (言いかえると、元の変数の"エイリアスを作る"または元の変数を"指す") 新規の変数への代入は、元の変数に影響し、その逆も同様となります。

参照により代入を行うには、代入する変数(ソース変数)の先頭に アンパサンドを加えます。たとえば、次の簡単なコードは 'My name is Bob'を二度出力します。

<?php
$foo = 'Bob';              // 値'Bob'を$fooに代入する。
$bar = &$foo;              // $fooを$barにより参照
$bar = "My name is $bar";  // $barを変更...
echo $bar;
echo $foo;                 // $fooも変更される。
?>

注意すべき重要な点として、名前のある変数のみが参照により代入できる ということがあります。

<?php
$foo = 25;
$bar = &$foo;      // これは有効な代入です。
$bar = &(24 * 7);  // 無効です。名前のない式を参照しています。

function test() {
   return 25;
}

$bar = &test();    // 無効。
?>

PHP では変数を初期化する必要はありませんが、そのようにするのはとてもよいことです。 初期化されていない変数の値は、状況に応じたその型のデフォルト値 - boolean なら FALSE、integer や float ならゼロ、 文字列 (echo で使う場合など) なら空の文字列、配列なら空の配列となります。

例1 初期化されていない変数のデフォルト値

<?php
// 設定も参照もされていない (使用中のコンテキストではない) 変数は NULL となります
var_dump($unset_var);

// boolean として使用すると、出力は 'false' となります (この構文の詳細は三項演算子を参照ください)
echo($unset_bool ? "true\n" : "false\n");

// 文字列として使用すると、出力は 'string(3) "abc"' となります
$unset_str .= 'abc';
var_dump($unset_str);

// integer として使用すると、出力は 'int(25)' となります
$unset_int += 25; // 0 + 25 => 25
var_dump($unset_int);

// float/double として使用すると、出力は 'float(1.25)' となります
$unset_float += 1.25;
var_dump($unset_float);

// 配列として使用すると、出力は array(1) {  [3]=>  string(3) "def" } となります
$unset_arr[3] = "def"; // array() + array(3 => "def") => array(3 => "def")
var_dump($unset_arr);

// オブジェクトとして使用し、新しい stdClass オブジェクト (http://www.php.net/manual/ja/reserved.classes.php を参照ください)
// を作成すると、出力は object(stdClass)#1 (1) {  ["foo"]=>  string(3) "bar" } となります
$unset_obj->foo = 'bar';
var_dump($unset_obj);
?>

初期化されていない変数のデフォルト値に依存すると、そのファイルを include している別のファイルで同名の変数が使用されていた場合などに 問題を起こします。また、register_globals が on の場合には重大なセキュリティリスク を抱えることになります。初期化されていない変数を使用すると、 E_NOTICE レベルのエラーが発生します。 しかし、初期化されていない配列に要素を追加する場合はエラーにはなりません。 変数が初期化されているかどうかの判断には、isset() を使用します。

定義済みの変数

PHPは、実行する全てのスクリプトに定義済みの多くの変数を 提供します。しかし、これらの変数の多くは、 実行するサーバーの種類、サーバーのバージョンおよび設定、 その他の要素に依存しており、完全に記述することはできません。 これらの変数のいくつかは、PHPを コマンドライン で実行した場合には利用できません。 これらの変数の一覧については、 予約済みの定義済みの変数 のセクションを参照してください。

警告

PHP 4.2.0以降では、PHPディレクティブ register_globalsの デフォルト値がoffに変更されています。 これは、PHPにおける大きな変更です。 register_globalsをoffにすると、 グローバルスコープに定義済みの変数に影響を与えます。 例えば、DOCUMENT_ROOTを取得するには、 $DOCUMENT_ROOTのかわりに $_SERVER['DOCUMENT_ROOT']を使用することに なります。また、URL http://www.example.com/test.php?id=3　から $idの代わりに$_GET['id']、 $HOMEのかわりに$_ENV['HOME']を 使用します。

この変更に関する情報については、 register_globalsに関する設定 エントリ、セキュリティに関する章の register_globalsの使用、 また、» 4.1.0および » 4.2.0の Release Announcementsを参照してください。

スーパーグローバル 配列のようなPHPの予約済みの定義済み変数を使用することが 推奨されます。

バージョン4.1.0以降、PHPに(使用する場合)Webサーバー、環境変数、 ユーザー入力からの変数を値とする定義済みの配列が追加されています。 これらの新しいは配列は、自動グローバル、すなわち、自動的に全ての スコープで利用可能です。このため、これらは "スーパーグローバル" といわれることもあります。 (PHPには、ユーザー定義のスーパーグローバルという機構はありません。) スーパーグローバルのリストを以下に示します。 しかし、これらの内容のリストおよび定義済みのPHP変数とそれらの特性に 関する更なる議論については、 定義済みの予約変数の セクションを参照してください。 より古い定義済みの変数($HTTP_*_VARS)もまだ 存在します。 PHP 5.0.0 以降、PHP の長い 定義済みの変数 配列は register_long_arrays ディレクティブにより無効にすることができます。

注意: 可変変数

可変変数として スーパーグローバルを使うことはできません。

注意:

スーパーグローバルと HTTP_*_VARS は同時に存在させることができますが、 お互い同一ではありません。つまり、一方を変更してももう一方はそのままです。

variables_orderに ある変数が設定されていない場合、これらに対応するPHPの定義済み 変数も空のままとなります。

変数のスコープ

変数のスコープは、その変数が定義されたコンテキストです。ほとんどの PHP 変数は、スコープを1つだけ有しています。このスコープの範囲は、 includeやrequireにより読みこまれたファイルも含みます。例えば、

<?php
$a = 1;
include 'b.inc';
?>

この例で、変数$aはインクルードされた b.inc スクリプトの中でも利用可能です。しかし、 ユーザー定義の関数の中では変数の有効範囲はローカル関数の中となりま す。関数の中で使用された変数はデフォルトで有効範囲が関数内部に制限 されます。例えば、

<?php
$a = 1; /* グローバルスコープ */ 

function test()
{ 
    echo $a; /* ローカルスコープ変数の参照 */ 
} 

test();
?>

このスクリプトは、出力を全く行いません。これは、echo 命令がローカ ル版の $a 変数を参照しているにもかかわらず、こ のスコープでは値が代入されていないからです。この動作は、特にローカ ルな定義で上書きしない限りグローバル変数が自動的に関数で使用可能で ある C 言語と少々異なっていると気がつかれるかもしれません。C言語の ような場合、グローバル変数を不注意で変更してしまうという問題を生じ る可能性があります。PHP では、グローバル変数は、関数の内部で使用す る場合、関数の内部でグローバルとして宣言する必要があります。

global キーワード

まず、globalの使用例を示します。

例1 global の使用

<?php
$a = 1;
$b = 2;

function Sum() 
{
    global $a, $b;

    $b = $a + $b;
} 

Sum();
echo $b;
?>

上のスクリプトは、3 を出力します。関数の内部で $a、$b をグローバル宣言を行うことにより、両変数への参照は、グローバル変数 の方を参照することになります。ある関数により操作できるグローバル変 数の数は無制限です。

グローバルスコープから変数をアクセスする2番目の方法は、PHPが定義す る配列$GLOBALSを使用することです。先の例は、次 のように書き換えることができます。

例2 globalのかわりに$GLOBALSを使用する

<?php
$a = 1;
$b = 2;

function Sum() 
{
    $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
} 

Sum();
echo $b;
?>

配列$GLOBALSは連想配列であり、グローバル変数の 名前がキー、その変数の内容が配列要素の値となっています。 $GLOBALS は スーパーグローバル であるため、$GLOBALSは全てのスコープに存在します。 以下にスーパーグローバルの効果を示す例を示します。

例3 スーパーグローバルとスコープの例

<?php
function test_global()
{
    // ほとんどの定義済み変数は"スーパー"ではなく、関数内の
    // ローカルスコープで有効とするには'global'をコールする必要があります。
    global $HTTP_POST_VARS;
    
    echo $HTTP_POST_VARS['name'];
    
    // スーパーグローバルはどのスコープでも有効であり
    // 'global'をコールする必要がありません。
    // スーパーグローバルはPHP4.1.0以降で利用できます。
    // HTTP_POST_VARS は今や非推奨とされています。
    echo $_POST['name'];
}
?>

注意:

global キーワードを関数の外部で使ってもエラーにはなりません。 そのファイルが関数の内部からインクルードされたときに使うことができます。

静的変数の使用

変数のスコープに関する別の重要な機能は、静的 (static) 変数です。静的変数はローカル関数スコープのみに 存在しますが、プログラム実行がこのスコープの外で行われるようになっ てもその値を失わないません。次の例を見てください。

例4 静的変数が必要な場面の例

<?php
function test()
{
    $a = 0;
    echo $a;
    $a++;
}
?>

この関数は、コールされる度に$aを 0にセットし、0 を出力するのでほとん ど役にたちません。変数を1増やす $a++ は、関数から外に出ると変数 $aが消えてしまうために目的を達成しません。現在 のカウントの追跡ができるようにカウント関数を使用できるようにするた めには、変数$aをstaticとして宣言します。

例5 静的変数の使用例

<?php
function test()
{
    static $a = 0;
    echo $a;
    $a++;
}
?>

こうすると、$a は関数が最初にコールされたときにのみ初期化され、 test() 関数がコールされるたびに $a の値を出力してその値を増加させます。

static変数は、再帰関数を実現する1つの手段としても使用されます。再帰 関数は、自分自身をコールする関数です。再帰関数を書くときには、無限 に再帰を行う可能性があるため、注意する必要があります。適当な方法に より再帰を確実に終了させる必要があります。次の簡単な関数は、中止す るタイミングを知るためにstatic変数$countを用いて、 10 回まで再帰を行います。

例6 再帰関数での静的変数の使用

<?php
function test()
{
    static $count = 0;

    $count++;
    echo $count;
    if ($count < 10) {
        test();
    }
    $count--;
}
?>

注意:

静的変数は、上の例に見られるような方法で宣言されます。 式の結果を静的変数に代入しようとすると、パースエラーが 発生します。

例7 静的変数の宣言

<?php
function foo(){
    static $int = 0;          // 正しい
    static $int = 1+2;        // 間違い（式を代入しています）
    static $int = sqrt(121);  // 間違い（同じく式を代入しています）

    $int++;
    echo $int;
}
?>

注意:

静的な宣言は、コンパイル時に解決されます。

注意:

global キーワードを関数の外部で使ってもエラーにはなりません。 そのファイルが関数の内部からインクルードされたときに使うことができます。

グローバル変数と静的変数のリファレンス

PHP4を駆動するZend Engine 1では、 リファレンス変数の修正子 static および global を実装しています。 例えば、関数スコープ内にglobal 命令により実際にインポートされた真のグローバル変数は、 実際にグローバル変数へのリファレンスを作成します。 これにより、以下の例が示すように予測できない動作を引き起こす可能性 があります。

<?php
function test_global_ref() {
    global $obj;
    $obj = &new stdclass;
}

function test_global_noref() {
    global $obj;
    $obj = new stdclass;
}

test_global_ref();
var_dump($obj);
test_global_noref();
var_dump($obj);
?>

上の例の出力は以下となります。


NULL
object(stdClass)(0) {
}

類似の動作がstatic命令にも適用されます。 リファレンスは静的に保存することができません。

<?php
function &get_instance_ref() {
    static $obj;

    echo 'Static object: ';
    var_dump($obj);
    if (!isset($obj)) {
        // Assign a reference to the static variable
        $obj = &new stdclass;
    }
    $obj->property++;
    return $obj;
}

function &get_instance_noref() {
    static $obj;

    echo 'Static object: ';
    var_dump($obj);
    if (!isset($obj)) {
        // Assign the object to the static variable
        $obj = new stdclass;
    }
    $obj->property++;
    return $obj;
}

$obj1 = get_instance_ref();
$still_obj1 = get_instance_ref();
echo "\n";
$obj2 = get_instance_noref();
$still_obj2 = get_instance_noref();
?>

この例を実行すると以下の出力となります。


Static object: NULL
Static object: NULL

Static object: NULL
Static object: object(stdClass)(1) {
["property"]=>
int(1)
}

この例は、static変数にリファレンスを代入した時に &get_instance_ref()関数を2回目に コールした際に保持されていないことを示しています。

可変変数

変数名を可変にできると便利なことが時々あります。可変変数では、変数 名を動的にセットし使用できます。通常の変数は、次のような命令でセッ トします。

<?php
$a = 'hello';
?>

可変変数は、変数の値をとり、変数の名前として扱います。上の例では、 hello は、ドル記号を二つ使用することにより、 変数の名前として使用することができます。つまり、

<?php
$$a = 'world';
?>

ここまでで、二つの変数が定義され、PHP シンボルツリーに定義されてい ます。これらは、"hello" を値とする$aと "world" を値とする$helloです。そこで、次の命令

<?php
echo "$a ${$a}";
?>

の出力は、次の命令と全く同じとなります。

<?php
echo "$a $hello";
?>

すなわち、両方共、hello worldを出 力します。

可変変数を配列で使用する際には、曖昧さの問題を解決する必要がありま す。つまり、$$a[1]と書いた場合、 $a[1]を変数として使用したいのか、 $$aを変数とし [1] を変数の添え字としたいのかを、 パーサが知る必要があるのです。この曖昧さを解決するには、前者では ${$a[1]}とし、後者では ${$a}[1]とする構文を用います。

クラスのプロパティには、可変プロパティ名でアクセスすることができます。 可変プロパティ名の解決は、呼び出し元のスコープで行われます。 たとえば $foo->$bar のようにするとローカルスコープで $bar を調べ、その値を $foo のプロパティ名として使います。 $bar が配列へのアクセスであっても同じです。

例1 可変プロパティの例

<?php
class foo {
    var $bar = 'I am bar.';
}

$foo = new foo();
$bar = 'bar';
$baz = array('foo', 'bar', 'baz', 'quux');
echo $foo->$bar . "\n";
echo $foo->$baz[1] . "\n";
?>

上の例の出力は以下となります。


I am bar.
I am bar.

警告

関数やクラスメソッドの内部で、可変変数と PHP の スーパーグローバル配列 とを組み合わせては使用できないということに注意してください。 $this も特別な変数であり、 動的に参照することはできません。

外部から来る変数

HTML フォーム (GET と POST)

フォームが PHP スクリプトに投稿された時、フォームから渡された全て の変数は PHP により自動的にスクリプトから使用可能となります。 この情報にアクセスする手段は複数あります。例を以下に示します。

例1 簡単なHTMLフォーム

<form action="foo.php" method="post">
    Name:  <input type="text" name="username" /><br />
    Email: <input type="text" name="email" /><br />
    <input type="submit" name="submit" value="Submit me!" />
</form>

特定の設定や個別の設定に依存し、HTMLフォームからのデータにアクセス する手段は多くあります。いくつかの例を以下に示します。

例2 簡単なPOST HTMLフォームからのデータにアクセスする

<?php 
// PHP 4.1.0以降で利用可能

   echo $_POST['username'];
   echo $_REQUEST['username'];

   import_request_variables('p', 'p_');
   echo $p_username;

// PHP 5.0.0 以降、これらの長い形式の定義済み変数は
// register_long_arrays ディレクティブで無効化できます。

   echo $HTTP_POST_VARS['username'];

// PHPディレクティブregister_globals = onの場合に利用可能。
// PHP 4.2.0以降、register_globalsのデフォルト値はoffとなっています。
// この方法の使用/依存は推奨されません。

   echo $username;
?>

GETフォームを使用した場合も同じですが、かわりに適当な定義済みの GET変数を使用するところが異なります。 GETは、QUERY_STRING (URLの'?'の後の情報)にも代入されます。 例えば、 http://www.example.com/test.php?id=3には、 $_GET['id']によりアクセス可能なGETデータ が含まれます。 $_REQUEST および import_request_variables()も参照ください。

注意:

$_POSTおよび$_GETのような スーパーグローバル 配列がPHP 4.1.0で利用可能となっています。

注意:

変数名のドットやスペースはアンダースコアに変換されます。 たとえば <input name="a.b" /> は $_REQUEST["a_b"] となります。

前記のようにPHP 4.2.0より前のバージョンでは、 register_globals のデフォルト値はonでした。 PHPコミュニティは、このディレクティブに依存しないことを推奨し、 このオプションがoffでのコードの動作を仮定 することを推奨しています。

注意:

magic_quotes_gpcの設定 はGET、POSTそしてCookieの値に影響します。onになっていると (It's "PHP!") という値は自動的に (It\'s \"PHP!\") となり、DBへの挿入時の エスケープが不要になります。addslashes()、 stripslashes()そしてmagic_quotes_sybaseも 参照してください。

PHPではフォーム変数のコンテキスト内で配列が使用可能です(FAQの関連箇所も参照してください)。 例えば、関連する変数をグループ化したり、select inputで複数の値を 取得するといったことが可能です。フォームを同じスクリプトに投稿し、 投稿したデータを表示する例を示します。

例3 より複雑なフォーム変数

<?php
if ($_POST) {
    echo '<pre>';
    echo htmlspecialchars(print_r($_POST, true));
    echo '</pre>';
}
?>
<form action="" method="post">
    Name:  <input type="text" name="personal[name]" /><br />
    Email: <input type="text" name="personal[email]" /><br />
    Beer: <br />
    <select multiple name="beer[]">
        <option value="warthog">Warthog</option>
        <option value="guinness">Guinness</option>
        <option value="stuttgarter">Stuttgarter Schwabenbräu</option>
    </select><br />
    <input type="submit" value="submit me!" />
</form>

IMAGE SUBMIT 変数名

フォームを投稿する際、次のタグのように標準の投稿ボタンの代わりに 画像を使用することができます。 

<input type="image" src="image.gif" name="sub" />

画像のどこかがクリックされた場合、二つの変数 sub_x および sub_y が付け加えられてこのフォームはサーバーに転送されます。これらの変 数は、ユーザーがこの画像をクリックした座標を示しています。経験の ある人は、ブラウザにより送られた変数の名前においてアンダースコア がピリオドになってしまっていることを心配するかもしれません。 しかし、PHP はピリオドをアンダースコアに自動的に変換します。

HTTP Cookie

PHP は、» RFC 6265 に定義されたHTTP Cookieを完全にサポートします。Cookieは、リモート ブラウザにデータを保持し、再訪するユーザーを追跡し、特定する機構 です。setcookie() 関数によりCookieをセットす ることができます。Cookieは、HTTP ヘッダの一部なので、SetCookie 関数をブラウザに何かを出力する前にコールする必要があります。 この制約は、header() 関数のものと同じです。 Cookieのデータは、$_COOKIE, $HTTP_COOKIE_VARSのような適当なCookieデータ 配列で参照可能です。また、 $_REQUESTでも 参照可能です。詳細および例については、 setcookie()のマニュアルページを参照してください。

単一のCookieに複数の値を代入したい場合は、配列として 代入することが可能です。以下に例を示します。

<?php
  setcookie("MyCookie[foo]", 'Testing 1', time()+3600);
  setcookie("MyCookie[bar]", 'Testing 2', time()+3600);
?>

上記スクリプトにおいては、2つの異なるCookieを生成されますが、 この場合、スクリプトでは MyCookie という単一の配列になります。 一つのCookieに複数の値を設定したい場合、最初の値に serialize()または explode()を用いることを考えてください。

Cookieは、パスまたはドメインが異ならない限り、 以前のクッキーをブラウザ上の同じ名前の変数に置き換えることに 注意してください。 さて、買い物かご(Shopping Cart) プログラムの場合、カウンタを保持し、 受け渡したいと思うかもしれません。 これは、次のようになります。

例4 setcookie()の例

<?php
if (isset($_COOKIE['count'])) {
    $count = $_COOKIE['count'] + 1;
} else {
    $count = 1;
}
setcookie('count', $count, time()+3600);
setcookie("Cart[$count]", $item, time()+3600);
?>

外部変数名のドット

通常、PHP はスクリプトに渡された変数の名前を変更しません。しかし、 ドット(ピリオド、終止符)はPHPの変数名で有効な文字ではないというこ とに注意する必要があります。次の例を見てみましょう。

<?php
$varname.ext;  /* 無効な変数名 */
?>
ここで、パーサは、$varnameという名前の変数の後に 文字列結合演算子があり、その後に、裸の文字列(すなわち、既知のキー または予約語にマッチしない引用符無しの文字列) 'ext' が続くとして 解釈します。この場合、明らかに意図する結果にはなりません。

重要なことを記述しておくと、このため、外部変数に含まれるドットを PHP は自動的にアンダースコアに変換します。

変数の型の定義

PHPは、変数の型を定義し、必要に応じて変換します。このため、ある変 数の型がある時点で常に明らかであるわけではありません。PHPは、変数 の型を調べる複数の関数をサポートしています。それらは、 gettype(), is_array(), is_float(), is_int(), is_object(), is_string() です。 型の章も参照ください。

定数

目次

定数は簡単な値のためのID(名前)です。この名前が示すように、定数の値は スクリプト実行中に変更できません (マジック定数 は例外で、これらは実際は定数ではありません)。 デフォルトで定数では大文字小文字を区別します。慣習的に、 定数は常に大文字で表記されます。

定数の名前は、PHP のラベルと同じ規則に従います。有効な定数の名前は、 文字またはアンダースコアで始まり、任意の数の文字、数字、 アンダースコアが後に続きます。正規表現で示すと次のようになります。 [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*

ヒント

ユーザーレベルでの命名の手引き も参照ください。

例1 有効/無効な定数名の例

<?php

// 有効な定数名
define("FOO",     "something");
define("FOO2",    "something else");
define("FOO_BAR", "something more");

// 無効な定数名
define("2FOO",    "something");

// 有効だが、避けるべき。
// 将来 PHP に定数の予約語が追加された場合に
// スクリプトが動作しなくなる可能性がある
define("__FOO__", "something"); 

?>

注意: 本節の目的においては、文字は a-z, A-Z, および127から255まで (0x7f-0xff)のASCII文字を指します。

superglobalsと同様に定数のスコープはグローバルです。 つまり、スコープによらずスクリプトの中ではどこでも定数に アクセスできます。スコープの詳細についてはマニュアルの 変数のスコープ をご覧ください。

構文

define() 関数を使用することにより、 定数を定義することが可能です。PHP 5.3.0 以降では、 クラス定義の外部で const キーワードを使って定数を定義することもできます。 定数が一度定義されると、 変更または未定義とすることはできません。

定数に指定できるのは、スカラデータ (boolean, integer, double, string) のみです。 resource の定数を指定することもできますが、 予期せぬ結果を引き起こすことがあるので避けるべきです。

単に定数の名前を指定することにより、その値を得ることが可能です。 変数とは異なり、その前に $ は不要です。 定数の名前を動的に得る必要がある場合、定数の値を読むために関数 constant() を使用することも可能です。 定義済の定数の一覧を得るには、 get_defined_constants() を使用してください。

注意: 定数と(グローバル)変数は、異なる名前空間にあります。 例えば、TRUE と $TRUE は違うものを意味します。

未定義の定数を使用した場合、ちょうどstringとして コールしたかのように(CONSTANT vs "CONSTANT")、 PHPはその定数自体の名前を使用したと仮定します。 この際、E_NOTICE が発生します。 ある定数が設定されているかどうかを知るには、 defined() 関数を使用してください。 なぜ $foo[bar]が間違っている （まずbarを定数としてdefine()しなければ） のかというマニュアルもご覧ください。 定数がセットされているかを単にチェックするには defined()を使用してください。

変数との違いは次のようになります。

  • 定数は、前にドル記号($)を要しません。
  • 定数を定義することができるのは、define()関数 のみです。単なる代入による定義はできません。
  • 定数は、定義することができ、変数のスコープ規則に関係なく、あら ゆる場所からアクセス可能です。
  • 定数は一度設定されると再定義または未定義とすることはできません。
  • 定数は、スカラー値としてのみ評価可能です。

例1 定数の定義

<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // "Hello world."を出力
echo Constant; // "Constant" を出力し、警告 (notice) を発行
?>

例2 const キーワードによる定数の定義

<?php
// PHP 5.3.0 以降で動作します
const CONSTANT = 'Hello World';

echo CONSTANT;
?>

注意:

define() による定数の定義とは反対に、 const キーワードで定義した定数はトップレベルのスコープで宣言しなければなりません。 これはコンパイル時に定義されるからです。 つまり、関数やループ、そして if 文の内部では宣言できないということです。

オブジェクト定数 も参照ください。

自動的に定義される定数

PHPには実行されるスクリプトで使用可能な多くの 定義済みの定数があります。 しかし、これらの定数の多くは、種々の拡張モジュールにより作成され、 動的なロードやコンパイル時の組込みにより、これらの拡張モジュールが 使用可能である場合にのみ定義されます。

使われ方によって変化する自動的に定義される定数（マジカル定数）が 8 つあります。 例えば、__LINE__はスクリプト上において 呼び出された行番号です。特別定数は大文字小文字を区別しません。 内容は以下のとおりです:

PHP の "マジック" 定数
名前 説明
__LINE__ ファイル上の現在の行番号。
__FILE__ ファイルのフルパスとファイル名。インクルードされるファイルの 中で使用された場合、インクルードされるファイルの名前が返されます。 PHP 4.0.2 以降では __FILE__ は常に絶対パスで、シンボリックリンクは解決されます。 それより前のバージョンでは、場合によっては相対パスが返されることもあります。
__DIR__ そのファイルの存在するディレクトリ。include の中で使用すると、 インクルードされるファイルの存在するディレクトリを返します。 つまり、これは dirname(__FILE__) と同じ意味です。 ルートディレクトリである場合を除き、ディレクトリ名の末尾にスラッシュはつきません (PHP 5.3.0 で追加されました)。
__FUNCTION__ 関数名（PHP4.3.0で追加されました）。 PHP 5以降、この定数は宣言時の関数名(ケース依存)を返します。 PHP 4では、この値は常に小文字で返されました。
__CLASS__ クラス名（PHP4.3.0で追加されました）。 PHP 5以降、この定数は宣言時のクラス名(ケース依存)を返します。 PHP 4では、この値は常に小文字で返されました。 クラス名には、そのクラスが宣言されている名前空間も含みます (例 Foo\Bar)。 PHP 5.4 以降では、__CLASS__ がトレイトでも使えることに注意しましょう。トレイトのメソッド内で __CLASS__ を使うと、そのトレイトを use しているクラスの名前を返します。
__TRAIT__ トレイト名 (PHP 5.4.0 で追加されました)。PHP 5.4 以降では、 この定数はトレイト名を宣言時のままで返します (大文字小文字を区別します)。 トレイト名には、宣言された名前空間も含みます (例 Foo\Bar)。
__METHOD__ クラスのメソッド名（PHP5.0.0で追加されました）。 メソッド名は宣言時と同じ(ケース依存)を返します。
__NAMESPACE__ 現在の名前空間の名前 (大文字小文字を区別します)。 この定数はコンパイル時に定義されます (PHP 5.3.0 で追加されました)。

get_class(), get_object_vars(), file_exists(), function_exists()も参照してください。

式

式は、PHP における最も重要な基盤石です。PHPにおいては、 ほとんど全てのものは式で記述されます。 最も簡単で最も正確な式の定義は、"全ての式には値がある。" です。

考えられる簡単な例は、定数と変数です。 "$a = 5" と入力すると、$a に '5' を代入することになります。 '5' は、明らかに、 5 という値です。 言葉を変えると '5' は 5 という値を有する式なのです。 (この場合、'5' は整数定数です。)

この代入の後、$a の値は、5 であることが期待されます。 よって、$b = $a と書いた場合、$b = 5 と書いたのと 同じように動作することが期待されます。 言い換えると $a は 5 という値を持つ式なのです。 全てが正しく動作する場合、何が起こるかをこのことが正確に表現しています。

式をもう少し複雑にしたのが関数です。 例えば、次の関数を考えてみましょう。

<?php
function foo () {
    return 5;
}
?>

あなたが関数の概念に慣れていると仮定すると (そうでない場合は、関数 に関する章を参照ください。)、 $c = foo() と入力することは、 $c = 5 と書くことと本質的に全く同じで あると予想されたかもしれません。この予想は、正しいです。 関数は、その返り値を値とする式なのです。 foo() は 5 を返すので、式 'foo()' の値は 5 です。 通常、関数は、決まった数だけを返すのではなく、何かを計算します。

もちろん、PHP の値は整数である必要はありませんし、 多くの場合、そうではありません。 PHP は、4 種類のスカラー型: 整数(integer)、 浮動小数点数(float)、文字列(string)、 真偽値(boolean) をサポートします。 (スカラーとは、配列とかと異なり、より小さな部分に'分割する'ことが できない値のことです。) PHP は、2種類の複合(非スカラー)型(配列とオブジェクト)もサポートします。 これらの型の値は、変数に代入することができ、 関数からの返り値とすることができます。

PHP は、他の多くの言語が行うのと同じ手法で、 更に多くの式を使用可能です。 PHP は、ほとんど全てが式であるという意味で、式指向の言語です。 既に取り扱った '$a = 5' という例について考えてみましょう。 この式には、整数定数の '5' と 5 に更新された $a の値という 2 つの値が現れているということに容易に気づくことでしょう。 しかし、実際には、ここにはもうひとつの値が含まれています。 それは、代入自体の値です。 代入式は、それ自体、代入値を評価します。 この場合、その値は 5 になります。 このことは、実際には、'$a = 5' は、それが何をするかによらず、 値 5 を有する式であることを意味します。 つまり、 '$b = ($a = 5)' のように書くことは、 '$a = 5; $b = 5;' と書くのと 同様なのです。(セミコロンは、文の終わりを示します。) 代入は、右から左へ実行されるため、'$b = $a = 5' と書くことも 可能です。

式の配置に関する別の良い例は、前置、後置加算子、あるいは減算子です。 PHP と他の多くの言語のユーザーは、variable++ や variable-- といった表記法に慣れていることでしょう。 これらは、加算子および減算子です。 PHP においては、C 言語のように、 前置加算と後置加算という、2 種類の加算があります。 前置加算と後置加算は、両方とも、基本的には変数を増加させ、 変数に対する効果は同じです。 異なっているのは、加算する式の値です。 前置加算は、'++$variable' と書かれますが、 加算後の値を評価します (PHP はその値を読む前に変数を増加させるので、'前置加算(pre-increment)' という名前がついています)。 後置加算は、'$variable++' と書かれますが、加算される前の $variable の元の値を評価します。 (PHP は、その値を読んだ後に変数を増加させるので、 '後置加算(post-increment)' という名前がついています。)

比較演算子は、 極めて標準的な式です。 比較演算子は、FALSE または TRUE のどちらかを値とします。 PHPは、>(大なり)、 >=(大なりイコール)、=(イコール)、 <(小なり)、<=(小なりイコール)をサポートします。 PHP 言語は、いくつかの厳密な等価演算子: === (イコールかつ同じ型) そして !== (イコールではないまたは型が違う) も サポートします。 これらの式は、if文のような条件式の内部で一般的に 使用されます。

式の最後の例として、ここでは、演算子+代入式の複合演算式 を扱います。 既にご存知のように、$a に 1 を加えたい場合は、'$a++' または '++$a' と書くだけで十分です。 しかし、1より大きな数、例えば 3 を加えたい場合は、どうすればよいのでしょう? '$a++' を複数回使うこともできますが、当然これはあまり効率的で快適な手法ではありません。 ふつうは、'$a = $a + 3' と書きます。 '$a + 3' の部分で $a の値に 3 を加えた値を評価し、 その結果を $a に代入するというわけです。 この結果、$a に 3 が加えられます。 PHP においては、C のような他の言語と同様に、 この例をより短かく書くことができます。 これにより、より明確になり、同時に理解も迅速になります。 $a の現在の値に 3 を加える式は、 '$a += 3' と書くことができます。 この式の正確な意味は、 "$a の値を取得し、それに 3 を加え、$a に再代入しなさい。" です。 より短く、明確になっただけでなく、実行もより高速になります。 '$a += 3' の値は、通常の代入と同様に、代入された値です。 この値は 3 ではなく、$a に 3 を加えた加算値 (この値が、$a に代入された値です)であることに注意してください。 '$a -= 5' ($a から 5 を引く) や '$b *= 7' ($b に 7 をかける)等のように、 全ての 2 項演算子は、この演算子+代入式のモードで使用することができます。

もう一種類、terniary 条件文という式がありますが、 他の言語で見たことがない場合には理解できないかもしれません。

<?php
$first ? $second : $third
?>
最初の部分式の値が TRUE (非ゼロ)の場合、二番目の部分式が評価され、 この条件文の結果となります。 そうでない場合、三番目の部分式が評価され、この文の値となります。

次の例は、前置および後置加算子と多少一般的な式の理解を 助けてくれることでしょう。 

<?php
function double($i) {
    return $i*2;
}
$b = $a = 5;        /* 値 5 を $a と $b に代入します */
$c = $a++;          /* 後置加算なので、$c に代入される値は、$a の
                       元の値 (5) です */
$e = $d = ++$b;     /* 前置加算なので、$d と $e に代入される値は、
                       加算後の $b の値 (6) です */

/* ここままで、$d と $e は、6 です */

$f = double($d++);  /* $f には、$d が加算される前の値を2倍した値、
                       つまり 2*6 = 12 が、代入されます。
$g = double(++$e);  /* $g には、$e が加算された後の値を2倍した値、
                        つまり 2*7 = 14 が、代入されます。
$h = $g += 10;      /* まず、$g に 10 が加算され、24 になります。
                       代入値 (24) は、$h に代入されます。
                       そして、$h も同様に 24 になります。 */
?>

式が、文として扱われることがあります。 この場合、文は、'式 ;' 、つまり式の後にセミコロンがついた形式です。 '$b = $a =5;' において、'$a = 5' は有効な式ですが、 自身を値とする文では ありません。しかし、'$b = $a = 5;' は有効な文です。

最後に、有益な事項として式の論理値について説明します。 多くのイベント、主に条件付き実行とループにおいて、 式の特定な値には関心がないが、TRUE または FALSE のどちらを 意味するかに関心があるということがあります。 定数TRUEとFALSE(大文字小文字を区別しない)は、論理型の値がとり得る 値です。必要に応じて式は論理値に変換されます。詳細な手法については、 型キャストに関するセクション を参照ください。

PHP は、完全で強力な式の実装を提供します。 それを完全に記述することは、このマニュアルの範囲を超えています。 上記の例は、式とは何か、そして、便利な式をどうやって作るかということ に関して良いアイデアを与えるに違いありません。 本マニュアルの残りの部分ではexprという マークを使用しますが、これは PHP の有効な式を意味します。

演算子

目次

演算子とは、ひとつ以上の値 (あるいはプログラミング用語における「式」) から別の値 (制御構造が式になるように) を生み出すものです。

演算子は、受け取る値の数によって分類することができます。単項演算子はひとつの値だけを受け取るもので、 ! ( 論理否定演算子) や ++ ( 加算子) などです。二項演算子はふたつの値を受け取ります。おなじみの 代数演算子 である + (加算) や - (減算) など PHP の演算子の大半はこの分類に含まれます。最後は三つの値を受け取る 三項演算子 で、これは ? : だけしかありません。この演算子はしばしば、単に "三項演算子" と呼ばれます (しかし、より適切な呼び方としては 条件演算子と呼ぶほうがよいでしょう)。

PHP の演算子の完全な一覧は、 演算子の優先順位 の欄にあります。ここでは演算子の優先順位と結合性についての設営をしています。 複数の演算子を組み合わせたときにどう評価されるのかは、優先順位と結合性で決まります。

演算子の優先順位

演算子の優先順位は、二つの式が"緊密に"結合している度合いを指定します。 例えば、式 1 + 5 * 3 の答えは 16 になり、18 とはなりません。 これは乗算演算子("*")は、加算演算子("+")より高い優先順位を有するか らです。必要に応じて強制的に優先順位を設定するために括弧を使用する ことが可能です。例えば、18と評価するためには、 (1 + 5) * 3 とします。

演算子の優先順位が等しい場合は、その結合性によって評価順 (右から評価するのか、あるいは左から評価するのか) が決まります。 以下の例を参照ください。

次の表では、優先順位が高い順に演算子を挙げています。 同じ行にある演算子は優先順位が等しくなります。そのような場合は、 結合時の評価にしたがって評価順が決まります。

演算子の優先順位
結合時の評価 演算子 追加情報
結合しない clone new clone および new
left [ array()
結合しない ++ -- 加算子/減算子
right ~ - (int) (float) (string) (array) (object) (bool) @ 型
結合しない instanceof 型
right ! 論理演算子
left * / % 代数演算子
left + - . 代数演算子 そして 文字列演算子
left << >> ビット演算子
結合しない < <= > >= <> 比較演算子
結合しない == != === !== 比較演算子
left & ビット演算子 そして リファレンス
left ^ ビット演算子
left | ビット演算子
left && 論理演算子
left || 論理演算子
left ? : 三項演算子
right = += -= *= /= .= %= &= |= ^= <<= >>= => 代入演算子
left and 論理演算子
left xor 論理演算子
left or 論理演算子
left , さまざまな利用法

演算子の優先順位が同じ場合、 結合時の評価が left の場合は式が左から右に評価され、一方 right の場合は その逆となります。

例1 結合時の評価

<?php
$a = 3 * 3 % 5; // (3 * 3) % 5 = 4
$a = true ? 0 : true ? 1 : 2; // (true ? 0 : true) ? 1 : 2 = 2

$a = 1;
$b = 2;
$a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5

// ++ と + を同時に使ったときの挙動は未定義です
$a = 1;
echo ++$a + $a++; // 4 になるかもしれないし、5 になるかもしれません
?>
厳密には不要な場所であっても、括弧をつけておけばコードの可読性があがります。

注意:

= は他のほとんどの演算子よりも優先順位が低いはずなのにもかかわらず、 PHP は依然として if (!$a = foo()) のような式も許します。この場合は foo() の返り値が $a に代入されます。

代数演算子

学校で習った基礎代数を憶えていますか? この演算子はそれらと同様に動作します。

代数演算子
例 名前 結果
-$a 負にする $a の逆
$a + $b 加算 $a および $b の合計
$a - $b 減算 $a と $b の差
$a * $b 乗算 $a および $b の積
$a / $b 除算 $a および $b の商
$a % $b 剰余 $a を $b で割った余り

除算演算子 ("/") の返す値は浮動小数点数となります。 ただし、ふたつのオペランドがともに整数 (あるいは整数に変換できる文字列) であり、かつ結果が割り切れる場合には整数値を返します。

剰余演算子は、まず両方のオペランドを整数に直し (小数点以下を切り捨てます) てから処理を行います。

剰余演算子 % の結果の符号は、被除数の符号と同じになります。 つまり、$a % $b の結果の符号は $a と同じになるということです。

<?php

echo (5 % 3)."\n";           // 2
echo (5 % -3)."\n";          // 2
echo (-5 % 3)."\n";          // -2
echo (-5 % -3)."\n";         // -2

?>

マニュアルの 数学関数の項も参照してください。

代入演算子

代入演算子の基本となるものは "=" です。この演算子に関して最初に 思い付く意味は"等しい"であるかもしれません。しかし、そうではありません。 本当は、左オペランドに右オペランドの式の値を設定する("得て代入する") ことを意味します。

代入式の値は、代入される値です。つまり、"$a = 3" の値は、3 です。 これにより、以下のようなトリッキーなことができるようになります。

<?php

$a = ($b = 4) + 5; // $a は 9 に等しくなり、$b には 4 が代入されます

?>

配列の場合、キーの名前を指定して値を代入するには "=>" 演算子を使います。この演算子の 優先順位 は、その他の代入演算子と同じです。

基本代入演算子に加えて、全ての バイナリ演算子、配列結合および文字列演算子に関して 「複合演算子」があります。 これにより、式の中の値を使用し、その値をその式の結果とすることができます。 例えば、

<?php

$a = 3;
$a += 5; // $a を 8 にセットします。$a = $a + 5; と同じです。
$b = "Hello ";
$b .= "There!"; // $bを"Hello There!"にセットします。$b = $b . "There!";と同じです。

?>

代入は、元の変数を新しい変数にコピーする(値による代入)ため、 片方の変数に対する変更はもう片方に影響を与えないということに 注意してください。この動作により、密なループの内側で大きな配列のようなものを コピーする必要がある場合には問題を生じる可能性があります。

PHP では通常は値による代入になりますが、オブジェクト型については例外です。 PHP 5 以降、オブジェクトは参照で代入されるようになりました。オブジェクトを明示的にコピーするには clone キーワードを使います。

参照による代入

参照による代入もサポートしており、 "$var = &$othervar;" 構文で使うことができます。 参照による代入とは、両方の変数が同じデータを指すようにするということです。 データのコピーは発生しません。

例1 参照による代入

<?php
$a = 3;
$b = &$a; // $b は $a への参照です

print "$a\n"; // 表示: 3
print "$b\n"; // 表示: 3

$a = 4; // change $a

print "$a\n"; // 表示: 4
print "$b\n"; // 表示: 4
              // $b の参照先は $a であり、その値が変わったからです
?>

PHP 5 以降では、new 演算子が自動的に参照を返すようになりました。そのため、 new の結果を参照で代入しようとすると PHP 5.3 以降では E_DEPRECATED、それより前のバージョンでは E_STRICT が発生します。

たとえば、このコードは警告が発生します。

<?php
class C {}

/* 次の行を実行すると、このようなエラーメッセージが出ます
 * Deprecated: Assigning the return value of new by reference is deprecated in...
 */
$o = &new C;
?>

参照に関する詳細な情報やその使い方については、このマニュアルの 参照に関する説明 をご覧ください。

ビット演算子

ビット演算子は、整数値の特定のビットの評価や操作を行います。

ビット演算子
例 名前 結果
$a & $b ビット積 $a および $b の両方にセットされているビットがセットされます
$a | $b ビット和 $a または $b のどちらかにセットされているビットがセットされます
$a ^ $b 排他的論理和 $a または $b のどちらか一方にセットされており、両方にセットされていないビットがセットされます
~ $a 否定 $a にセットされているビットはセットせず、そうでないものは逆にします
$a << $b 左シフト $a のビットを左に $b ビットシフトする (各シフトは "2をかける" ことを意味します)
$a >> $b 右シフト $a のビットを右に $b ビットシフトします (各シフトは "2で割る" ことを意味します)

PHP のシフト処理は算術シフトです。両端からあふれたビットは捨てられます。 左シフトをすると右側にはゼロが埋められます。 符号ビットは左端からあふれて消えます。 つまり、オペランドの符号は維持されないということです。 右シフトの際には、符号ビットと同じ内容が左端から埋められます。 つまり、この場合はオペランドの符号が維持されます。

括弧を使うことで、望みどおりの 優先順位 で処理させることができます。たとえば、$a & $b == true はまず等価かどうかを評価してからビット演算を行いますが ($a & $b) == true はまずビット演算を行ってから等価かどうかを評価します。

データ型の変換に注意しましょう。両辺のパラメータが文字列の場合、 ビット演算子は文字の ASCII コードで演算を行います。 

PHP の ini 設定 error_reporting はビット値を用いています。
これを用いて、特定のビットを落とす演算の例を見てみましょう。
notice 以外のすべてのエラーを表示させるには、
php.ini ファイルで
E_ALL & ~E_NOTICE
と指定することになります。
      

まずは E_ALL。
00000000000000000111011111111111
そして E_NOTICE...。
00000000000000000000000000001000
... これを ~ で逆転させます。
11111111111111111111111111110111
最後に AND (&) を使い、両方ともビットが立っているところをみつけます。
00000000000000000111011111110111
      

同じ結果を得るもうひとつの方法として、 XOR (^)
を使ってどちらか一方だけ立っているビットを探すという方法もあります。
E_ALL ^ E_NOTICE
      

error_reporting を使って、特定のビットを立てる処理の例を見てみましょう。
通常のエラーとリカバー可能なエラーだけを表示させるには、次のようにします。
E_ERROR | E_RECOVERABLE_ERROR
      

この処理は、 E_ERROR
00000000000000000000000000000001
と
00000000000000000001000000000000
を OR (|) 演算子でつないで、
少なくともどちらかのビットが立っているところを取得します。
00000000000000000001000000000001

例1 整数値におけるビット AND、OR および XOR 演算

<?php
/*
 * このへんは無視してください。
 * たんに結果をきれいに表示させるためだけのものです。
 */

$format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
        . ' %3$s (%4$2d = %4$04b)' . "\n";

echo <<<EOH
 ---------     ---------  -- ---------
 result        value      op test
 ---------     ---------  -- ---------
EOH;


/*
 * ここからが本番
 */

$values = array(0, 1, 2, 4, 8);
$test = 1 + 4;

echo "\n Bitwise AND \n";
foreach ($values as $value) {
    $result = $value & $test;
    printf($format, $result, $value, '&', $test);
}

echo "\n Bitwise Inclusive OR \n";
foreach ($values as $value) {
    $result = $value | $test;
    printf($format, $result, $value, '|', $test);
}

echo "\n Bitwise Exclusive OR (XOR) \n";
foreach ($values as $value) {
    $result = $value ^ $test;
    printf($format, $result, $value, '^', $test);
}
?>

上の例の出力は以下となります。

 ---------     ---------  -- ---------
 result        value      op test
 ---------     ---------  -- ---------
 Bitwise AND
( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101)
( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101)
( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101)
( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101)
( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101)

 Bitwise Inclusive OR
( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101)
( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101)
( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101)
( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101)
(13 = 1101) = ( 8 = 1000) | ( 5 = 0101)

 Bitwise Exclusive OR (XOR)
( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101)
( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101)
( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101)
( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101)
(13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)

例2 文字列でのビット XOR 演算

<?php
echo 12 ^ 9; // 出力は '5'

echo "12" ^ "9"; // 出力はバックスペース文字 (ascii 8)
                 // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

echo "hallo" ^ "hello"; // 出力は、ascii コード #0 #4 #0 #0 #0
                        // 'a' ^ 'e' = #4

echo 2 ^ "3"; // 出力は 1
              // 2 ^ ((int)"3") == 1

echo "2" ^ 3; // 出力は 1
              // ((int)"2") ^ 3 == 1
?>

例3 整数値のビットシフト

<?php
/*
 * これが例です
 */

echo "\n--- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---\n";

$val = 4;
$places = 1;
$res = $val >> $places;
p($res, $val, '>>', $places, 'copy of sign bit shifted into left side');

$val = 4;
$places = 2;
$res = $val >> $places;
p($res, $val, '>>', $places);

$val = 4;
$places = 3;
$res = $val >> $places;
p($res, $val, '>>', $places, 'bits shift out right side');

$val = 4;
$places = 4;
$res = $val >> $places;
p($res, $val, '>>', $places, 'same result as above; can not shift beyond 0');


echo "\n--- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---\n";

$val = -4;
$places = 1;
$res = $val >> $places;
p($res, $val, '>>', $places, 'copy of sign bit shifted into left side');

$val = -4;
$places = 2;
$res = $val >> $places;
p($res, $val, '>>', $places, 'bits shift out right side');

$val = -4;
$places = 3;
$res = $val >> $places;
p($res, $val, '>>', $places, 'same result as above; can not shift beyond -1');


echo "\n--- BIT SHIFT LEFT ON POSITIVE INTEGERS ---\n";

$val = 4;
$places = 1;
$res = $val << $places;
p($res, $val, '<<', $places, 'zeros fill in right side');

$val = 4;
$places = (PHP_INT_SIZE * 8) - 4;
$res = $val << $places;
p($res, $val, '<<', $places);

$val = 4;
$places = (PHP_INT_SIZE * 8) - 3;
$res = $val << $places;
p($res, $val, '<<', $places, 'sign bits get shifted out');

$val = 4;
$places = (PHP_INT_SIZE * 8) - 2;
$res = $val << $places;
p($res, $val, '<<', $places, 'bits shift out left side');


echo "\n--- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---\n";

$val = -4;
$places = 1;
$res = $val << $places;
p($res, $val, '<<', $places, 'zeros fill in right side');

$val = -4;
$places = (PHP_INT_SIZE * 8) - 3;
$res = $val << $places;
p($res, $val, '<<', $places);

$val = -4;
$places = (PHP_INT_SIZE * 8) - 2;
$res = $val << $places;
p($res, $val, '<<', $places, 'bits shift out left side, including sign bit');


/*
 * このへんは無視してください。
 * たんに結果をきれいに表示させるためだけのものです。
 */

function p($res, $val, $op, $places, $note = '') {
    $format = '%0' . (PHP_INT_SIZE * 8) . "b\n";

    printf("Expression: %d = %d %s %d\n", $res, $val, $op, $places);

    echo " Decimal:\n";
    printf("  val=%d\n", $val);
    printf("  res=%d\n", $res);

    echo " Binary:\n";
    printf('  val=' . $format, $val);
    printf('  res=' . $format, $res);

    if ($note) {
        echo " NOTE: $note\n";
    }

    echo "\n";
}
?>

上の例の 32 ビットマシンでの出力は、このようになります。


--- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---
Expression: 2 = 4 >> 1
 Decimal:
  val=4
  res=2
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000010
 NOTE: copy of sign bit shifted into left side

Expression: 1 = 4 >> 2
 Decimal:
  val=4
  res=1
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000001

Expression: 0 = 4 >> 3
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: bits shift out right side

Expression: 0 = 4 >> 4
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: same result as above; can not shift beyond 0


--- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---
Expression: -2 = -4 >> 1
 Decimal:
  val=-4
  res=-2
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111110
 NOTE: copy of sign bit shifted into left side

Expression: -1 = -4 >> 2
 Decimal:
  val=-4
  res=-1
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111111
 NOTE: bits shift out right side

Expression: -1 = -4 >> 3
 Decimal:
  val=-4
  res=-1
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111111
 NOTE: same result as above; can not shift beyond -1


--- BIT SHIFT LEFT ON POSITIVE INTEGERS ---
Expression: 8 = 4 << 1
 Decimal:
  val=4
  res=8
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000001000
 NOTE: zeros fill in right side

Expression: 1073741824 = 4 << 28
 Decimal:
  val=4
  res=1073741824
 Binary:
  val=00000000000000000000000000000100
  res=01000000000000000000000000000000

Expression: -2147483648 = 4 << 29
 Decimal:
  val=4
  res=-2147483648
 Binary:
  val=00000000000000000000000000000100
  res=10000000000000000000000000000000
 NOTE: sign bits get shifted out

Expression: 0 = 4 << 30
 Decimal:
  val=4
  res=0
 Binary:
  val=00000000000000000000000000000100
  res=00000000000000000000000000000000
 NOTE: bits shift out left side


--- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---
Expression: -8 = -4 << 1
 Decimal:
  val=-4
  res=-8
 Binary:
  val=11111111111111111111111111111100
  res=11111111111111111111111111111000
 NOTE: zeros fill in right side

Expression: -2147483648 = -4 << 29
 Decimal:
  val=-4
  res=-2147483648
 Binary:
  val=11111111111111111111111111111100
  res=10000000000000000000000000000000

Expression: 0 = -4 << 30
 Decimal:
  val=-4
  res=0
 Binary:
  val=11111111111111111111111111111100
  res=00000000000000000000000000000000
 NOTE: bits shift out left side, including sign bit

上の例の 64 ビットマシンでの出力は、このようになります。


--- BIT SHIFT RIGHT ON POSITIVE INTEGERS ---
Expression: 2 = 4 >> 1
 Decimal:
  val=4
  res=2
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000010
 NOTE: copy of sign bit shifted into left side

Expression: 1 = 4 >> 2
 Decimal:
  val=4
  res=1
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000001

Expression: 0 = 4 >> 3
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bits shift out right side

Expression: 0 = 4 >> 4
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: same result as above; can not shift beyond 0


--- BIT SHIFT RIGHT ON NEGATIVE INTEGERS ---
Expression: -2 = -4 >> 1
 Decimal:
  val=-4
  res=-2
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111110
 NOTE: copy of sign bit shifted into left side

Expression: -1 = -4 >> 2
 Decimal:
  val=-4
  res=-1
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111111
 NOTE: bits shift out right side

Expression: -1 = -4 >> 3
 Decimal:
  val=-4
  res=-1
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111111
 NOTE: same result as above; can not shift beyond -1


--- BIT SHIFT LEFT ON POSITIVE INTEGERS ---
Expression: 8 = 4 << 1
 Decimal:
  val=4
  res=8
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000001000
 NOTE: zeros fill in right side

Expression: 4611686018427387904 = 4 << 60
 Decimal:
  val=4
  res=4611686018427387904
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0100000000000000000000000000000000000000000000000000000000000000

Expression: -9223372036854775808 = 4 << 61
 Decimal:
  val=4
  res=-9223372036854775808
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=1000000000000000000000000000000000000000000000000000000000000000
 NOTE: sign bits get shifted out

Expression: 0 = 4 << 62
 Decimal:
  val=4
  res=0
 Binary:
  val=0000000000000000000000000000000000000000000000000000000000000100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bits shift out left side


--- BIT SHIFT LEFT ON NEGATIVE INTEGERS ---
Expression: -8 = -4 << 1
 Decimal:
  val=-4
  res=-8
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1111111111111111111111111111111111111111111111111111111111111000
 NOTE: zeros fill in right side

Expression: -9223372036854775808 = -4 << 61
 Decimal:
  val=-4
  res=-9223372036854775808
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=1000000000000000000000000000000000000000000000000000000000000000

Expression: 0 = -4 << 62
 Decimal:
  val=-4
  res=0
 Binary:
  val=1111111111111111111111111111111111111111111111111111111111111100
  res=0000000000000000000000000000000000000000000000000000000000000000
 NOTE: bits shift out left side, including sign bit

警告

32 ビットシステムでは 32 ビット以上の右シフトは行わないでください。 また、結果が 32 ビットを超えてしまうような左シフトも行わないでください。 PHP_INT_MAX を超える数のビット演算には、gmp 拡張モジュールの関数を使用します。

pack(), unpack(), gmp_and(), gmp_or(), gmp_xor(), gmp_testbit(), gmp_clrbit() も参照ください。

比較演算子

比較演算子は、その名前が示すように、二つの値を比較します。 型の比較表 に、型に関連するさまざまな比較の例があります。

比較演算子
例 名前 結果
$a == $b 等しい 型の相互変換をした後で $a が $b に等しい時に TRUE。
$a === $b 等しい $a が $b に等しく、および同じ型である場合に TRUE 。
$a != $b 等しくない 型の相互変換をした後で $a が $b に等しくない場合に TRUE。
$a <> $b 等しくない 型の相互変換をした後で $a が $b に等しくない場合に TRUE。
$a !== $b 等しくない $a が $b と等しくないか、同じ型でない場合に TRUE 。
$a < $b より少ない $a が $b より少ない時に TRUE。
$a > $b より多い $a が $b より多い時に TRUE。
$a <= $b より少ないか等しい $a が $b より少ないか等しい時に TRUE。
$a >= $b より多いか等しい $a が $b より多いか等しい時に TRUE。

整数値を文字列と比較したり、比較に数値形式の文字が含まれる場合は、文字列が 数値に変換され、 数値としての比較を行います。これらのルールは、 switch 文にも適用されます。 === あるいは !== による比較では型変換は発生しません。 この場合は値だけでなく型も比較します。

<?php
var_dump(0 == "a"); // 0 == 0 -> true
var_dump("1" == "01"); // 1 == 1 -> true
var_dump("10" == "1e1"); // 10 == 10 -> true
var_dump(100 == "1e2"); // 100 == 100 -> true

switch ("a") {
case 0:
    echo "0";
    break;
case "a": // "a" は 0 にマッチするので、決してここにはたどりつきません
    echo "a";
    break;
}
?>

多くの型では、以下の表に（上から順に）したがって比較が行われます。

さまざまな型の比較
第 1 オペランドの型 第 2 オペランドの型 結果
null または string string NULL を "" に変換し、数値または文字として比較します
bool または null あらゆる型 bool に変換し、FALSE < TRUE と判断します
object object 組み込みクラスには独自の比較基準が定義されています。それ以外の クラスは比較できません。同じクラスであるかどうかは - プロパティが 同じ値であるかどうかを配列形式で比較（PHP 4）、PHP 5 では ここで説明されています。
string, resource または number string, resource または number 文字列やリソースを数値に変換し、算術演算を行います
array array 要素数の少ない配列のほうが小さくなります。オペランド 1 のキーが オペランド 2 に存在しない場合、配列は比較できません。そうでない場合は 個々の要素の値を比較します（以下の例を参照ください）
array あらゆる型 array のほうが常に大きくなります
object あらゆる型 object のほうが常に大きくなります

例1 一般的な配列の比較

<?php
// 標準の比較演算子を用いて、配列はこのように比較されます
function standard_array_compare($op1, $op2)
{
    if (count($op1) < count($op2)) {
        return -1; // $op1 < $op2
    } elseif (count($op1) > count($op2)) {
        return 1; // $op1 > $op2
    }
    foreach ($op1 as $key => $val) {
        if (!array_key_exists($key, $op2)) {
            return null; // uncomparable
        } elseif ($val < $op2[$key]) {
            return -1;
        } elseif ($val > $op2[$key]) {
            return 1;
        }
    }
    return 0; // $op1 == $op2
}
?>

strcasecmp(), strcmp()、 配列演算子, マニュアルの 型 のセクションも参照してください。

警告

浮動小数点数値の比較

ふたつの float 値が等しいかどうかを調べてはいけません。 float の内部的な表現方法がその理由です。

詳細な情報は float のドキュメントを参照ください。

三項演算子

もうひとつの条件演算子として "?:"（あるいは三項）演算子があります。

例2 デフォルト値を設定する

<?php
// 三項演算子の使用例
$action = (empty($_POST['action'])) ? 'default' : $_POST['action'];

// 上記は以下の if/else 式と同じです。
if (empty($_POST['action'])) {
    $action = 'default';
} else {
    $action = $_POST['action'];
}

?>
(expr1) ? (expr2) : (expr3) という式は、式1 が TRUE の場合に 式2 を、 式1 が FALSE の場合に 式3 を値とします。

PHP 5.3 以降では、三項演算子のまんなかの部分をなくすこともできるようになりました。 式 expr1 ?: expr3 の結果は、expr1 が TRUE と同等の場合は expr1、 それ以外の場合は expr3 となります。

注意: 三項演算子は式であり、値としては評価されずに式の結果として評価される ことに注意してください。演算結果をリファレンスとして返したい場合に、 これを知っておくことが大切です。結果をリファレンスとして返す関数で return $var == 42 ? $a : $b; とすることはできず、 新しいバージョンの PHP では警告を発生します。

注意:

三項演算子を "積み重ねて" 使用することは避けましょう。 ひとつの文の中で複数の三項演算子を使用した際の PHP の振る舞いは、 少々わかりにくいものです。

例3 三項演算子のわかりにくい挙動

<?php
// ぱっと見た感じでは、これは 'true' と表示されると思うでしょう。
echo (true?'true':false?'t':'f');

// しかし、実際には上の出力結果は 't' です。
// なぜなら、三項演算子は左から右へ順に評価されるからです。

// 上のコードをもう少しわかりやすく書くと、このようになります。
echo ((true ? 'true' : false) ? 't' : 'f');

// まず、最初の式が 'true' と評価されます。この 'true' は
// (bool)true と評価されるので、それをもとに二番目の三項
// 演算子が評価されます。
?>

エラー制御演算子

PHP はエラー制御演算子(@)をサポートしています。PHP の式の前に付けた場合、 その式により生成されたエラーメッセージは無視されます。

set_error_handler() で自作のエラーハンドラを設定した場合は エラー制御演算子があってもそのエラーハンドラがコールされます。 しかし、自作のエラーハンドラの中で error_reporting() をコールすれば、@ つきの式で生成されたエラーの場合は返り値が 0 になるのでこの値で区別することができます。 自作のエラーハンドラの中ではこの方法による区別を行うべきです。

track_errors 機能が 有効な場合、式により生成されたエラーメッセージはグローバル変数 $php_errormsg に保存されます。この変数はエラーが発生するたびに上書きされます。 そのため、この変数を使用したい場合には速やかに確認する必要があります。

<?php
/* 意図的なエラー */
$my_file = @file ('non_existent_file') or
    die ("Failed opening file: error was '$php_errormsg'");

// この演算子は関数だけでなく、全ての式で動作します。
$value = @$cache[$key]; 
// インデックス $key が存在しない場合でも、警告を発生しません。

?>

注意: @演算子は、式 でのみ動作します。基本的なルールは次のようになります。 値を得ることができるものの場合、@ 演算子を前に付けることが可能です。 例えば、変数、関数、include コール、定数等の 前にこの演算子をつけることが可能です。関数またはクラスの定義や if や foreach 等のような 条件構造の前にこの演算子を付けることはできません。

error_reporting() と、 エラー処理とログ出力関数 も参照してください。

警告

現在、エラー制御演算子プレフィックス"@"は、スクリプトの実行を 終了するような致命的なエラーの出力さえ抑圧します。このため、ある関数の エラー出力を抑制するために "@" を使用した場合、その関数が 利用できなかったり、ミスタイプがあった場合でも、原因を示すことなく その場所でスクリプトは終了してしまいます。

実行演算子

PHP は 1 種類の実行演算子、バッククォート (``) をサポートします。 シングルクォートではないことに注意してください! PHP は、バッククォートの 中身をシェルコマンドとして実行しようとします。出力が返されます (すなわち、出力を単にダンプするのではなく、変数に代入することが できます) 。 バッククォート演算子の使用は shell_exec() と等価です。

<?php
$output = `ls -al`;
echo "<pre>$output</pre>";
?>

注意:

バッククォート演算子は、セーフモード が有効な場合 もしくは shell_exec() が無効な場合は無効となります。

注意:

他の言語とは異なり、バッククォート演算子を ダブるクォートで囲まれた文字列の中で使うことはできません。

escapeshellcmd(), exec(), passthru(), popen(), shell_exec(), system() PHPをコマンドラインから使用する も参照してください。

加算子/減算子

PHP は C 言語形式の加算子/減算子（前置・後置ともに）をサポートします。

注意: 加算子/減算子は bool 型の値には何も変更を加えません。 同じく NULL に減算子を適用しても何も起こりませんが、NULL に加算子を 適用すると 1 となります。

加算子/減算子
例 名前 効果
++$a 前置加算子 $a に 1 を加え、$a を返します。
$a++ 後置加算子 $a を返し、$a に1を加えます。
--$a 前置減算子 $a から 1 を引き、$a を返します。
$a-- 後置減算子 $a を返し、$a から 1 を引きます。

以下に簡単なスクリプトの例を示します。

<?php
echo "<h3>後置加算</h3>";
$a = 5;
echo "5 となります: " . $a++ . "<br>\n";
echo "6 となります: " . $a . "<br>\n";
 
echo "<h3>前置加算</h3>";
$a = 5;
echo "6 となります: " . ++$a . "<br>\n";
echo "6 となります: " . $a . "<br>\n";

echo "<h3>後置減算</h3>";
$a = 5;
echo "5 となります: " . $a-- . "<br>\n";
echo "4 となります: " . $a . "<br>\n";

echo "<h3>前置減算</h3>";
$a = 5;
echo "4 となります: " . --$a . "<br>\n";
echo "4 となります: " . $a . "<br>\n";
?>

PHP は、算術演算子で文字変数を扱った場合に C ではなく Perl の慣習に 従います。例えば、PHP や Perl では $a = 'Z'; $a++; の結果として $a が 'AA' になりますが C では a = 'Z'; a++; の結果として a は '[' になります ('Z' の ASCII 値は 90、そして '[' の ASCII 値は 91 です)。 文字変数はインクリメントされることは可能ですがデクリメントは不可能であるということ、 またプレーンな ASCII 文字 (a-z および A-Z) のみがサポートされるということに注意しましょう。 その他の文字変数のインクリメント/デクリメントは何の効果もなく、元の文字列は変更されません。

例1 文字変数に対する算術演算子の使用

<?php
$i = 'W';
for ($n=0; $n<6; $n++) {
    echo ++$i . "\n";
}
?>

上の例の出力は以下となります。

X
Y
Z
AA
AB
AC

論理型に対する加算/減算は何の影響も及ぼしません。

論理演算子

論理演算子
例 名前 結果
$a and $b 論理積 $a および $b が共に TRUE の場合に TRUE
$a or $b 論理和 $a または $b のどちらかが TRUE の場合に TRUE
$a xor $b 排他的論理和 $a または $b のどちらかが TRUE でかつ両方とも TRUE でない場合に TRUE
! $a 否定 $a が TRUE でない場合 TRUE
$a && $b 論理積 $a および $b が共に TRUE の場合に TRUE
$a || $b 論理和 $a または $b のどちらかが TRUE の場合に TRUE

"and" および "or" 演算子が 2 種類あるのは、演算が行われる際の優先順位が 異なっているためです (演算子の優先順位 を参照ください)。

例1 論理演算子についての説明

<?php

// --------------------
// foo() は決してコールされることはありません。これらの演算子は短絡評価を行うからです。

$a = (false && foo());
$b = (true  || foo());
$c = (false and foo());
$d = (true  or  foo());

// --------------------
// "||" の優先順位は "or" より高くなります

// $e に代入されるのは、(false || true) の評価結果です
// これは、次の式と同様です: ($e = (false || true))
$e = false || true;

// $f には false が代入され、true は無視されます
// これは、次の式と同様です: (($f = false) or true)
$f = false or true;

var_dump($e, $f);

// --------------------
// "&&" の優先順位は "and" より高くなります

// $g に代入されるのは、(true && false) の評価結果です
// これは、次の式と同様です: ($g = (true && false))
$g = true && false;

// $h には true が代入され、false は無視されます
// これは、次の式と同様です: (($h = true) and false)
$h = true and false;

var_dump($g, $h);
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
bool(false)
bool(false)
bool(true)

文字列演算子

文字列の演算子は 2 種類あります。最初のは結合演算子('.')で、右引数と 左引数を結合したものを返します。2 番目は、結合代入演算子('.=')で、 この演算子は右側の引数に左側の引数を追加します。詳細は、代入演算子 を 参照ください。

<?php
$a = "Hello ";
$b = $a . "World!"; // $b は、"Hello World!" となります。

$a = "Hello ";
$a .= "World!"; // $a は、"Hello World!" となります。
?>

文字列 と 文字列 関数も参照してください。

配列演算子

Array Operators
例 名前 結果
$a + $b 結合 $a および $b を結合する。
$a == $b 同等 $a および $b のキー/値のペアが等しい場合に TRUE。
$a === $b 同一 $a および $b のキー/値のペアが等しく、その並び順が等しく、 かつデータ型も等しい場合に TRUE。
$a != $b 等しくない $a が $b と等しくない場合に TRUE。
$a <> $b 等しくない $a が $b と等しくない場合に TRUE。
$a !== $b 同一でない $a が $b と同一でない場合に TRUE。

+ 演算子は、右側の配列を左側の配列に追加したものを返します。 両方の配列に存在するキーについては左側の配列の要素が優先され、 右側の配列にあった同じキーの要素は無視されます。

<?php
$a = array("a" => "apple", "b" => "banana");
$b = array("a" => "pear", "b" => "strawberry", "c" => "cherry");

$c = $a + $b; // Union of $a and $b
echo "Union of \$a and \$b: \n";
var_dump($c);

$c = $b + $a; // Union of $b and $a
echo "Union of \$b and \$a: \n";
var_dump($c);
?>
このスクリプトを実行すると、以下のように出力されます。 
Union of $a and $b:
array(3) {
  ["a"]=>
  string(5) "apple"
  ["b"]=>
  string(6) "banana"
  ["c"]=>
  string(6) "cherry"
}
Union of $b and $a:
array(3) {
  ["a"]=>
  string(4) "pear"
  ["b"]=>
  string(10) "strawberry"
  ["c"]=>
  string(6) "cherry"
}

同じキーと値を保持している場合に、配列が等しいとみなされます。

例1 配列の比較

<?php
$a = array("apple", "banana");
$b = array(1 => "banana", "0" => "apple");

var_dump($a == $b); // bool(true)
var_dump($a === $b); // bool(false)
?>

配列と 配列関数も参照してください。

型演算子

instanceof を使用して、 ある PHP 変数が特定の クラス のオブジェクトのインスタンスであるかどうかを調べます。

例1 クラスでの instanceof の使用法

<?php
class MyClass
{
}

class NotMyClass
{
}
$a = new MyClass;

var_dump($a instanceof MyClass);
var_dump($a instanceof NotMyClass);
?>

上の例の出力は以下となります。

bool(true)
bool(false)

instanceof は、ある変数が 特定の親クラスを継承したクラスのオブジェクトのインスタンスであるかどうかを調べることもできます。

例2 継承したクラスでの instanceof の使用法

<?php
class ParentClass
{
}

class MyClass extends ParentClass
{
}

$a = new MyClass;

var_dump($a instanceof MyClass);
var_dump($a instanceof ParentClass);
?>

上の例の出力は以下となります。

bool(true)
bool(true)

あるオブジェクトが特定のクラスのインスタンスで ない ことを調べるには、 論理 否定 演算子 を使用します。

例3 instanceof を使用して、オブジェクトがクラスのインスタンスで ない かどうかを調べる方法

<?php
class MyClass
{
}

$a = new MyClass;
var_dump(!($a instanceof stdClass));
?>

上の例の出力は以下となります。

bool(true)

最後に、instanceof は、ある変数が特定の インターフェイス を実装したクラスのオブジェクトのインスタンスであるかどうかも調べることができます。

例4 クラスでの instanceof の使用法

<?php
interface MyInterface
{
}

class MyClass implements MyInterface
{
}

$a = new MyClass;

var_dump($a instanceof MyClass);
var_dump($a instanceof MyInterface);
?>

上の例の出力は以下となります。

bool(true)
bool(true)

通常、instanceof ではリテラルのクラス名を使用しますが、 別のオブジェクトや文字列変数を使用することもできます。

例5 変数を用いた instanceof の使用法

<?php
interface MyInterface
{
}

class MyClass implements MyInterface
{
}

$a = new MyClass;
$b = new MyClass;
$c = 'MyClass';
$d = 'NotMyClass';

var_dump($a instanceof $b); // $b MyClass クラスのオブジェクトです
var_dump($a instanceof $c); // $c は文字列 'MyClass' です
var_dump($a instanceof $d); // $d は文字列 'NotMyClass' です
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(false)

注意すべき落とし穴があります。PHP 5.1.0 より前のバージョンでは、 instanceof は、クラス名が存在しない場合に __autoload() をコールしていました。 さらに、クラスが読み込めなかった場合に致命的なエラーが発生していました。 この問題の回避策としては、動的なクラス参照を使用するか、 クラス名を含む文字列変数を使用します。

例6 PHP 5.0 における、クラス名検索時の致命的エラーの回避策

<?php
$d = 'NotMyClass';
var_dump($a instanceof $d); // これで、致命的なエラーは発生しません
?>

上の例の出力は以下となります。

bool(false)

instanceof 演算子は PHP 5 から使用可能になりました。 それ以前には is_a() が使用されていましたが、 現在は is_a() は推奨されておらず、 instanceof の使用が推奨されています。 PHP 5.3.0 以降、is_a() は非推奨ではなくなったことに注意しましょう。

get_class() および is_a() も参照ください。

制御構造

目次

導入

すべての PHP スクリプトは、一連の文からなります。 文としては、代入、関数コール、ループ、条件文、そして何もしない文(空の文) さえ使用することができます。 文は、通常セミコロンで終了します。加えて、文は、中括弧によるグループ文で カプセル化することによりグループ化することが可能です。 グループ文は、同時に文にもなります。 本章では、様々な文の型について説明します。

if

(PHP 4, PHP 5)

if 構文は、PHP を含む全ての言語において最も重要な 機能の一つです。 この構文は、命令の条件実行を可能にします。 PHP では、C 言語に似た次のような if 構文が使用されます。 

if (式)
  文

式のセクションで 記述したように式は論理値で評価されます。 式が TRUE と評価された場合、 PHP は文を実行します。FALSE と評価された場合は、これを無視します。どのような値が FALSE と評価されるかについては論理値への変換 を参照してください。

以下の例は、$a が $b より大きい場合、aはbより大きい を表示します。

<?php
if ($a > $b)
  echo "aはbより大きい";
?>

条件分岐させたい文が一つ以上ある場合もしばしばあります。 もちろん、各々の文をif 文で括る必要はありません。 代わりに、複数の文をグループ化することができます。 例えば、このコードは、$a が $b よりも大きい場合に aはbよりも大きいを表示し、 $a の値を $b に 代入します。

<?php
if ($a > $b) {
  echo "aはbより大きい";
  $b = $a;
}
?>

if文は、他のif文の中で無限に入れ子にできます。 これは、プログラムの様々な部分の条件付実行について 完全な柔軟性を提供します。

else

(PHP 4, PHP 5)

ある条件が満たされている場合にある文を実行し、 その条件が満たされていない場合に別の文を実行したいと考えた ことが度々あるかと思います。 このためにelseがあります。 elseは、if文における式の値が FALSEの場合にある文を 実行するようにif文を拡張します。 例えば、次のコードは、$aが $bよりも大きい場合に aはbより大きいと表示し、 そうでない場合に、 aはbよりも大きくないと表示します。

<?php
if ($a > $b) {
  echo "aはbよりも大きい";
} else {
  echo "aはbよりも大きくない";
}
?>
else 文は、if式が FALSEと評価された場合のみ実行されます。 また、elseif式がある場合には、それも FALSEと評価された場合にのみ実行されます。 (elseif参照)

elseif/else if

(PHP 4, PHP 5)

elseifは、その名前から分かるように、if とelseの組み合わせです。elseifは、 elseのように、元のif式の値が FALSEの場合に別の文を実行するようにif 文を拡張します。 しかし、elseとは異なり、elseif式が TRUEの場合にのみ代わりの式を実行します。 例えば、次のコードは、aはbより大きい、 aはbに等しい、 aはbより小さいを出力します。

<?php
if ($a > $b) {
    echo "aはbより大きい";
} elseif ($a == $b) {
    echo "aはbと等しい";
} else {
    echo "aはbより小さい";
}
?>

複数の elseif を同じ if 文の中で使用することができます。 TRUE と評価された最初の elseif 式を実行します。PHP では、(単語二つで)'else if'と書くこともできます。 動作は(一単語の) 'elseif'と同じです。文法的な意味はやや異なっています (あなたが C 言語に詳しいとすると、C 言語のそれと同じ動作です)。 しかし、最終的な両者の動作は全く同じです。

elseif 文は、前にある全ての if 文と elseif の値が FALSE であり、 現在の elseif 式の値が TRUE である場合にのみ実行されます。

注意: 上の例のように波括弧を使用する限り、 elseif と else if はまったく同じだと考えてよいことに注意しましょう。コロンを使って if/elseif 条件を指定する場合は、 else if のように分割してはいけません。 分割すると、パースエラーとなってしまいます。

<?php

/* 間違った方法 */
if($a > $b):
    echo $a." is greater than ".$b;
else if($a == $b): // コンパイル不能
    echo "The above line causes a parse error.";
endif;


/* 正しい方法 */
if($a > $b):
    echo $a." is greater than ".$b;
elseif($a == $b): // 二つの単語を分割せず組み合わせていることに注目
    echo $a." equals ".$b;
else:
    echo $a." is neither greater than or equal to ".$b;
endif;

?>

制御構造に関する別の構文

(PHP 4, PHP 5)

PHPは、いくつかの制御構造、つまり、if、 while、for、 foreach、switch に関する別の構文を提供します。 各構造において開き波括弧をコロン(:)、閉じ波括弧をそれぞれ endif;,endwhile;, endfor;,endforeach;, endswitch;に変更するのが 別の構文の基本的な形式となります。

<?php if ($a == 5): ?>
Aは5に等しい
<?php endif; ?>

上の例では、HTML ブロック "Aは5に等しい" はこの構文で 書かれた if 文の内部で入れ子になっています。 この HTML ブロックは、$a が 5 の場合にのみ表示されます。

この方法は、else や elseif にも同様に適用することができます。 次の例は、この形式で if 文を elseif および else とともに使用しています。

<?php
if ($a == 5):
    echo "aは5に等しい";
    echo "...";
elseif ($a == 6):
    echo "aは6に等しい";
    echo "!!!";
else:
    echo "aは5でも6でもない";
endif;
?>

注意:

同じブロック内で別の構文を混ぜて使うことはできません。

while、 for、および if に、より多くの例があります。

while

(PHP 4, PHP 5)

whileループは、PHPで最も簡単なタイプのループです。 このループは、CのWHILEループと同様の動作をします。 whileループの基本形は次のようになります。 

while (式)
    文

while文の意味は簡単です。 while文は、式の値がTRUEである間、 入れ子の文を繰り返し実行することをPHPに指示します。 式の値は各反復処理の開始時にチェックされるので、ループ内の文の実行により この値が代わった場合でもループ実行は各ループを終るまで終わりません。 (PHPによるループ内の文の実行が1回分の反復に相当します) while式の値が初めからFALSEの 場合は、内部の文は一回も実行されません。

if文と同様に、波括弧で複数の文を囲うか、 以下に示す別の構文を用いることにより、同じwhile ループの中に複数の文をグループ化することができます。 

while (式):
    文
    ...
endwhile;

次の例は同じです。どちらも 1 から 10 までの数を出力します。

<?php
/* 例 1 */

$i = 1;
while ($i <= 10) {
    echo $i++;  /* 出力される値は、足される前の
                    $iの値です。
                    (後置加算) */
}

/* 例 2 */

$i = 1;
while ($i <= 10):
    echo $i;
    $i++;
endwhile;
?>

do-while

(PHP 4, PHP 5)

do-whileループは、論理式のチェックが各反復の 最初ではなく最後に行われること以外は、whileループと 全く同じです。通常のwhileループとの主な差は、 do-whileループは最低1回の実行を保証されていることです。 一方、通常のwhileループは、実行されないかもしれません (論理式は各反復の最初でチェックされるので、 最初から値がFALSEである場合はループの実行は すぐに終わります)。

do-while ループの構文は次の一つのみです。

<?php
$i = 0;
do {
    echo $i;
} while ($i > 0);
?>

上記のループは必ず一度だけ実行されます。その原因は、最初の反復の後、 論理値のチェックを行った際に値が FALSE となり ($i は 0 より大きくない)、ループの実行が終了するためです。

優れたCプログラマは、コードブロック中での実行中止が可能な do-whileループの別の使用法について熟知している かもしれません。 これは、do-while(0)でコードを括り、 break 文を使用する方法です。次のコードは、この方法の例を示しています。

<?php
do {
    if ($i < 5) {
        echo "i は十分大きくはありません。";
        break;
    }
    $i *= $factor;
    if ($i < $minimum_limit) {
        break;
    }
   echo "iはOKです。";

    /* i を処理します */

} while (0);
?>

この例をすぐに理解できなかったり、全く理解できなかったりしても問題ありません。 この '機能' を使用しなくても、強力なスクリプトを書くことができます。 PHP 5.3.0 以降では、この技のかわりに goto 演算子を使うこともできます。

for

(PHP 4, PHP 5)

for ループは、PHPで最も複雑なループです。 for は、Cのforループと同様に動作します。 forループの構文は、次のようになります。 

for (式1; 式2; 式3)
    文

最初の式(式1)は、ループ開始時に無条件に 評価(実行)されます。

各繰り返しの開始時に、式2が評価されます。 その式の値がTRUEが場合、ループは継続され、括弧 内の文が実行されます。値がFALSEの場合、ループの 実行は終了します。

各繰り返しの後、式3が評価(実行)されます。

各式は空にすることもできますし、複数の式をカンマで区切って指定することもできます。 式2 でカンマ区切りの式を使用すると、 すべての式を評価します。しかし、結果として取得するのは最後の式の結果となります。 式2 を空にすると、無限実行ループになります (PHP は、この状態を C 言語のように暗黙の内に TRUE とみなします)。 この機能は、初心者が想像するよりもずっと便利です。 for の式の結果ではなく条件付き break 文を使ってループを終了させたくなることもしばしばあります。

次の例について考えてみましょう。以下の例はすべて 1 から 10 までの数を表示します。

<?php
/* 例 1 */

for ($i = 1; $i <= 10; $i++) {
    echo $i;
}

/* 例 2 */

for ($i = 1; ; $i++) {
    if ($i > 10) {
        break;
    }
    echo $i;
}

/* 例 3 */

$i = 1;
for (; ; ) {
    if ($i > 10) {
        break;
    }
    echo $i;
    $i++;
}

/* 例 4 */

for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
?>

もちろん、最初の例(もしくは 4番目の例)が最善であると考えられます。 しかし、forループにおいて空の式を使用できると、 多くの場合、便利だということに気づかれるかと思います。

PHPは、forループ用に"コロン構文"もサポートします。 for loops. 

for (式1; 式2; 式3):
    文;
    ...
endfor;

多くのユーザーにとって、次の例のように配列をループ処理することはよくあるでしょう。

<?php
/*
* データが入った配列で、ループ処理中に
* その中身を書き換えたいと考えています
*/
$people = Array(
        Array('name' => 'Kalle', 'salt' => 856412),
        Array('name' => 'Pierre', 'salt' => 215863)
        );

for($i = 0; $i < sizeof($people); ++$i)
{
    $people[$i]['salt'] = rand(000000, 999999);
}
?>

この書き方には問題があります。 このコードは実行速度が遅くなることでしょう。 配列のサイズを毎回計算しているからです。 サイズが変わることはないのですから、これは簡単に最適化することができます。 配列のサイズを変数に格納して、ループ内では sizeof ではなくその変数の値を使えばいいのです。 以下に例を示します。

<?php
$people = Array(
        Array('name' => 'Kalle', 'salt' => 856412),
        Array('name' => 'Pierre', 'salt' => 215863)
        );

for($i = 0, $size = sizeof($people); $i < $size; ++$i)
{
    $people[$i]['salt'] = rand(000000, 999999);
}
?>

foreach

(PHP 4, PHP 5)

foreach は、配列を反復処理するための便利な方法です。 foreach が使えるのは配列とオブジェクトだけであり、 別のデータ型や初期化前の変数に対して使うとエラーになります。 この構造には二種類の構文があります。 

foreach (array_expression as $value)
    文
foreach (array_expression as $key => $value)
    文

最初の形式は、array_expressionで指定した配列に 関してループ処理を行います。各反復において現在の要素の値が $valueに代入され、内部配列ポインタが一つ前に 進められます。(よって、次の反復では次の要素を見ることになります。)

2番目の形式は、さらに各反復で現在の要素のキーを変数 $keyに代入します。

オブジェクトの反復処理をカスタマイズ することもできます。

注意:

foreachの実行開始時に内部配列ポインタは、 配列の先頭要素を指すように自動的にリセットされます。 このため、foreachループの前に reset()をコールする必要はありません。

foreach は内部の配列ポインタに依存するので、 ループ内で配列ポインタを変更すると予期せぬ振る舞いを引き起こします。

ループの中で配列の要素を直接変更したい場合は、 $value の前に & をつけます。こうすると、変数には リファレンス が代入されることになります。

<?php
$arr = array(1, 2, 3, 4);
foreach ($arr as &$value) {
    $value = $value * 2;
}
// $arr は array(2, 4, 6, 8) となります
unset($value); // 最後の要素への参照を解除します
?>

$value の参照は、ループ処理される配列が参照可能である場合 (すなわち、 変数である) のみ使用可能です。つまり、次のコードは動作しません。

<?php
foreach (array(1, 2, 3, 4) as &$value) {
    $value = $value * 2;
}
?>

警告

foreach ループを終えた後でも、 $value は配列の最後の要素を参照したままとなります。 unset() でその参照を解除しておくようにしましょう。

注意:

foreach は、'@' によりエラーメッセージ出力を抑 制する機能をサポートしていません。

既にご存知かと思いますが、以下の文は機能的に等価です。

<?php
$arr = array("one", "two", "three");
reset($arr);
while (list(, $value) = each($arr)) {
    echo "Value: $value<br />\n";
}

foreach ($arr as $value) {
    echo "Value: $value<br />\n";
}
?>

以下の文も機能的に等価です。

<?php
$arr = array("one", "two", "three");
reset($arr);
while (list($key, $value) = each($arr)) {
    echo "Key: $key; Value: $value<br />\n";
}

foreach ($arr as $key => $value) {
    echo "Key: $key; Value: $value<br />\n";
}
?>

使用法を示すためにその他の例を示します。

<?php
/* foreach の例 1: 値のみ */

$a = array(1, 2, 3, 17);

foreach ($a as $v) {
    echo "Current value of \$a: $v.\n";
}

/* foreachの例2: 値 (説明用に、手動でアクセスする際の表記を出力) */

$a = array(1, 2, 3, 17);

$i = 0; /* 説明用 */

foreach ($a as $v) {
    echo "\$a[$i] => $v.\n";
    $i++;
}

/* foreachの例3: キーと値 */

$a = array(
    "one" => 1,
    "two" => 2,
    "three" => 3,
    "seventeen" => 17
);

foreach ($a as $k => $v) {
    echo "\$a[$k] => $v.\n";
}

/* foreach の例4: 多次元配列 */
$a = array();
$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";

foreach ($a as $v1) {
    foreach ($v1 as $v2) {
        echo "$v2\n";
    }
}

/* foreach の例5: 動的配列 */

foreach (array(1, 2, 3, 4, 5) as $v) {
    echo "$v\n";
}
?>

break

(PHP 4, PHP 5)

breakは、現在実行中の for, foreach, while, do-while, switch 構造の実行を終了します。

break では、オプションの引数で ネストしたループ構造を抜ける数を指定することができます。

<?php
$arr = array('one', 'two', 'three', 'four', 'stop', 'five');
while (list(, $val) = each($arr)) {
    if ($val == 'stop') {
        break;    /* ここでは、'break 1;'と書くこともできます */
    }
    echo "$val<br />\n";
}

/* オプション引数を使用します */

$i = 0;
while (++$i) {
    switch ($i) {
    case 5:
        echo "At 5<br />\n";
        break 1;  /* switch 構造のみを抜けます */
    case 10:
        echo "At 10; quitting<br />\n";
        break 2;  /* switch と while を抜けます */
    default:
        break;
    }
}
?>

break の変更履歴
バージョン 説明
5.4.0 数値引数の部分に変数を渡すこと (例: $num = 2; break $num;) ができなくなりました。

continue

(PHP 4, PHP 5)

continue は、ループ構造において現在の繰り返しループ の残りの処理をスキップし、条件式を評価した後に 次の繰り返しの最初から実行を続けるために使用されます、

注意: PHP では、continue の動作に関しては switch 文がループ構造とみなされるということに注意しましょう。

continueでは、オプションの引数で 処理をスキップするループ構造のレベルの数を指定できます。

注意:

continue 0; および continue 1; は、 単に continue; を実行するのと同じです。

<?php
while (list($key, $value) = each($arr)) {
    if (!($key % 2)) { // キーが偶数の組をスキップします
        continue;
    }
    do_something_odd($value);
}

$i = 0;
while ($i++ < 5) {
    echo "Outer<br />\n";
    while (1) {
        echo "&nbsp;Middle<br />\n";
        while (1) {
            echo "&nbsp;&nbsp;Inner<br />\n";
            continue 3;
        }
        echo "This never gets output.<br />\n";
    }
    echo "Neither does this.<br />\n";
}
?>

continue の後のセミコロンを省略すると混乱を生じることがあります。 以下の例のようなことをしてはいけません。

<?php
for ($i = 0; $i < 5; ++$i) {
    if ($i == 2)
        continue
    print "$i\n";
}
?>

これは、以下のような結果になることを期待していたのでしょう。 

0
1
3
4

しかし、このスクリプトの出力は以下のようになります。 

2

continue print "$i\n"; は全体でひとつの式として評価されるので、 print がコールされるのは $i == 2 が true のときだけです (print の返り値が continue への数値引数として渡されます)。

continue の変更履歴
バージョン 説明
5.4.0 数値引数の部分に変数を渡すこと (例: $num = 2; continue $num;) ができなくなりました。

switch

(PHP 4, PHP 5)

switch文は、同じ式を用いてIF文を並べたのに似ています。 同じ変数を異なる値と比較し、値に応じて異なったコードを実行したいと 思うことがしばしばあるかと思います。 switch文は、まさにこのためにあるのです。

注意: 他の言語とは違って、 continue命令は switchにも適用され、breakと同じ動作をします。 ループの内部でswitchを使用しており、 外側のループの処理を続行させたい場合には、continue 2 を使用してください。

注意:

switch/case が行うのは、 緩やかな比較 であることに注意しましょう。

次の二つの例は、同じことを二つの異なった方法で書いたものです。 一つは、if文を、もう一つはswitch 文を使っています。

例1 switch構造

<?php
if ($i == 0) {
    echo "iは0に等しい";
} elseif ($i == 1) {
    echo "iは1に等しい";
} elseif ($i == 2) {
    echo "iは2に等しい";
}

switch ($i) {
    case 0:
        echo "iは0に等しい";
        break;
    case 1:
        echo "iは1に等しい";
        break;
    case 2:
        echo "iは2に等しい";
        break;
}
?>

例2 switch構造では文字列を使用できる

<?php
switch ($i) {
    case "apple":
        echo "i is apple";
        break;
    case "bar":
        echo "i is bar";
        break;
    case "cake":
        echo "i is cake";
        break;
}
?>

失敗を避けるためにswitch文がどのように実行されるのかを 理解することが重要です。 switch文は、行毎に実行されます。 (実際には、文毎に実行されます。)初めは、何も実行しません。 switch式の値と一致する値を有する case文が見つけられたときに初めてPHにより 命令の実行が行われます。 PHPはswitchブロックの終わりまたは最初の break文まで実行を続けます。 CASE文の終わりにbreak文を書かない場合は、PHPは 次のCASE文を実行しつづけます。例えば、

<?php
switch ($i) {
    case 0:
        echo "iは0に等しい";
    case 1:
        echo "iは1に等しい";
    case 2:
        echo "iは2に等しい";
}
?>

ここで、$iが0に等しい場合は、PHPは全ての echo 文を出力してしまいます! $iが1の場合、PHPは最後の二つの echo 文を出力します。 $iが2に等しい場合のみ、'期待した'動作をし、 'iは2に等しい'と表示します。 このため (ある種の状況下では、BREAKを付加することを避けたいと 思うかもしれませんが)、 break文を忘れないようにすることが重要です。

switch文では、条件は1度だけ評価され、 その結果が各case文と比較されます。 elseif文では、条件は、再度評価されます。 使用する条件が単純な比較処理よりも複雑な処理を行ったり、 重い繰り返し処理を行う場合、switchの方が より処理が速い可能性があります。

caseに付随する文は、空とすることが可能です。 この場合、次のcaseに付随する文に制御が移行します。

<?php
switch ($i) {
case 0:
case 1:
case 2:
    echo "iは3より小さいですが負ではありません";
    break;
case 3:
    echo "iは3です";
}
?>

default は、case 文の特別な場合です。これは他の全ての case にマッチしない場合に実行されます。例を以下に示します。

<?php
switch ($i) {
    case 0:
        echo "iは0に等しい";
        break;
    case 1:
        echo "iは1に等しい";
        break;
    case 2:
        echo "iは2に等しい";
        break;
    default:
       echo "iは0,1,2に等しくない";
}
?>

case式は、スカラー型に式を評価する 任意の式、つまり、整数、浮動小数点、文字列とすることができます。 配列又はオブジェクトは、単純な型にキャストされていない限り 使用することができません。

switch文の制御構造に関する別の構文がサポートされています。 詳細は、 制御構造に関する別の構文を参照ください。

<?php
switch ($i):
    case 0:
        echo "iは0に等しい";
        break;
    case 1:
        echo "iは1に等しい";
        break;
    case 2:
        echo "iは2に等しい";
        break;
    default:
        echo "iは0でも1でも2でもない";
endswitch;
?>

case の最後はコロンではなくセミコロンとすることもできます。たとえば次のようになります。

<?php
switch($beer)
{
    case 'ツボルグ';
    case 'カールスバーグ';
    case 'ハイネケン';
        echo 'いいっすねぇ';
    break;
    default;
        echo 'ほかのを選んでみませんか?';
    break;
}
?>

declare

(PHP 4, PHP 5)

declare 命令は、あるコードブロックの中に 実効命令をセットするために使用されます。declare の文法は他の制御構造と似ています。 

declare (命令)
    文

命令の箇所で、セットされた declareブロックの挙動を指定することが出来ます。 現在のところ、使用できる命令は ticks ( ticksに関しては以下を参照してください) と encoding (encoding に関しては以下を参照ください) です。

注意: encoding ディレクティブは PHP 5.3.0 で追加されました。

declareブロックの文 の実行のされ方や実行時にどのような作用が起こるかについては 命令に何が指定されたかに依存します。

declare構造はグローバルスコープしても使用され、 それはそれ以降のコード上の全てにおいて影響します (しかし、declare を含むファイルがインクルードされた場合は、 親ファイルにはその影響は及びません)。

<?php
// 以下は同じ意味です

// こうすることもできますし、
declare(ticks=1) {
    // ここにすべてのスクリプトを書きます
}

// こうすることもできます
declare(ticks=1);
// ここにすべてのスクリプトを書きます
?>

Ticks

tickとはdeclareブロックの実行中にパーサが N個の低レベル tick 可能命令を実行するごとに 発生するイベントのことです。Nの値は declareブロックの命令の箇所で ticks=Nのように 指定します。

すべての文が tick 可能なわけではありません。 たとえば条件式や引数式などは tick できません。

tickごとに発生させるイベントはregister_tick_function() を使用して指定します。詳細は以下の例を参照してください。1回のtickで 複数のイベントが起こり得ることに注意してください。

例1 Tick の使用例

<?php

declare(ticks=1);

// tick イベントごとにコールされる関数
function tick_handler()
{
    echo "tick_handler() called\n";
}

register_tick_function('tick_handler');

$a = 1;

if ($a > 0) {
    $a += 2;
    print($a);
}

?>

例2 Ticks の使用例

<?php

function tick_handler()
{
  echo "tick_handler() called\n";
}

$a = 1;
tick_handler();

if ($a > 0) {
    $a += 2;
    tick_handler();
    print($a);
    tick_handler();
}
tick_handler();

?>

register_tick_function() および unregister_tick_function() も参照ください。

Encoding

スクリプトのエンコーディングをスクリプトごとに指定するには encoding ディレクティブを使用します。

例3 スクリプトのエンコーディングの宣言

<?php
declare(encoding='ISO-8859-1');
// ここにコードを書きます
?>

警告

名前空間と組み合わせて使用する場合、使用できる形式は declare(encoding='...'); のみです。... にエンコーディングを指定します。declare(encoding='...') {} は、名前空間と組み合わせるとパースエラーとなります。

php を --enable-zend-multibyte つきでコンパイルしていない場合、 PHP 5.3 では encoding 宣言は無視されます。

PHP が --enable-zend-multibyte つきでコンパイルされているかどうかを知る方法は phpinfo() 以外に存在しないことに注意しましょう。

zend.script_encoding も参照ください。

return

(PHP 4, PHP 5)

関数内で呼び出されると、return文は即座に その関数の実行を停止し、引数を関数の値として返します。 returnはまた、eval()文や スクリプト自体の実行を終了させることが出来ます。

グローバルスコープで呼び出されると、現在実行中のスクリプトが終了 します。もしそのスクリプトが include もしくは require されたものである場合、制御は呼び出し元 のファイルに戻ります。また、そのスクリプトが include されたものである場合は、returnに与えられた引数 の値は include の戻り値となります。 returnがメインスクリプトで呼び出された場合は スクリプトが終了します。また、 設定ファイルの auto_prepend_file 又は auto_append_fileオプションで指定されたスクリプトの場合も 同様にそのスクリプトが終了します。

さらに詳しい情報に関しては 返り値を参照してください。

注意: return は関数ではなく言語構造であるため、 引数を括弧で囲う必要があるのはないことに注意しましょう。 括弧で囲わずそのままにしておくのが一般的です。 またそのほうが PHP にかかる負荷も低くなります。

注意: パラメータを省略した場合は括弧も省略する必要があります。この場合の返り値は NULL です。 return に括弧をつけてコールしながら何も引数を指定しないと、 パースエラーとなります。

注意: 変数をリファレンスで返す場合は、決して引数を 括弧で囲ってはいけません。そのようにすると正しく動作しません。 return ($a); とすると、変数を返すのではなく ($a) を評価した結果を返すことになります (この場合は、もちろん $a の値です)。

require

(PHP 4, PHP 5)

require は include とほぼ同じですが、失敗した場合に E_COMPILE_ERROR レベルの致命的なエラーも発生するという点が異なります。 つまり、スクリプトの処理がそこで止まってしまうということです。一方 include の場合は、警告 (E_WARNING) を発するもののスクリプトの処理は続行します。

どのように動作するかについては include のドキュメントを参照ください。

include

(PHP 4, PHP 5)

include 文は指定されたファイルを読み込み、評価します。

以下の記述内容は require にも当てはまります。

ファイルのインクルードは、指定されたパスから行います。パスを指定しない場合は、 include_path の設定を利用します。 ファイルが include_path に見つからないときは、include は呼び出し元スクリプトのディレクトリと現在の作業ディレクトリも探します。 include は、ファイルを見つけられない場合に warning を発行します。一方 require の場合は、同じ場合に fatal error を発行する点が異なります。

パスを指定した場合 — 絶対パス (Windows ならドライブレターあるいは \ で始まるパス、Unix/Linux 系なら / で始まるパス) あるいはカレントディレクトリからの相対パス (. あるいは .. で始まるパス) のどちらでも — は include_path は無視されます。たとえば ../ ではじまるファイル名を指定した場合は、 親ディレクトリからそのファイルを探します。

PHP でのファイルのインクルードやインクルードパスについての詳細は include_path のドキュメントを参照ください。

ファイルが読み込まれるとそのファイルに含まれるコードは、 includeもしくはrequireが実行された 行の変数スコープを継承します。 呼び出し側の行で利用可能である全ての変数は、読み込まれたファイル内で利用可能です。 しかし、読み込まれたファイル内で定義されている関数やクラスはすべて グローバルスコープとなります。

例1 基本的な include の例

vars.php
<?php

$color = 'green';
$fruit = 'apple';

?>

test.php
<?php

echo "A $color $fruit"; // A

include 'vars.php';

echo "A $color $fruit"; // A green apple

?>

呼び出し側のファイルの関数定義の中で読み込みが行われた場合は、 読み込まれるファイルに含まれる全てのコードは、 その関数内で定義されているものとして動作します。 従って変数のスコープもその関数のものが継承されます。 ただ マジック定数 は例外で、これは読み込みを行う前にパーサが評価します。

例2 関数内での読み込み

<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php は foo() のスコープを継承するため *
* $fruit はこの関数の外では無効となります。  *
* $color はglobalとして宣言されているため    *
* 有効です。                                 */

foo();                    // A green apple
echo "A $color $fruit";   // A green

?>

ファイルが読み込まれるときには、読み込まれるファイルの先頭で PHPモードを抜けてHTMLモードになり、最後に再びPHPモードに戻ります。 このため、読み込むファイル中のPHPコードとして実行する必要がある コードは、 有効なPHPの開始タグおよび終了タグで括る必要があります。

"URL fopenラッパー"が 有効になっている場合(デフォルト設定では有効です)、ローカルなパス名 の代わりにURL(HTTP経由)を用いて読み込むファイルを指定することが可能です。 URLで指定されたサーバーがファイルをPHPコードとして解釈することが 出来る場合には、HTTP GETを使用してURLリクエストに引数を指定することが 出来ます。これはファイルの読み込み云々やスコープの継承とは関係なく、 ただ単純にスクリプトがリモートのサーバーで実行されて結果がローカルの スクリプトに読み込まれる、というだけのことです。

警告

PHP 4.3.0 より前のバージョンの Windows 版 PHP は、現在この関数に関してリモートファイルアクセス機能を サポートしていません。これは、allow_url_fopen を 有効にした場合でも同様です。

例3 HTTP経由の include

<?php

/* この例は www.example.com が.phpはPHPスクリプトとして扱い、.txtは通常の *
 * ファイルとして扱うように設定されていると仮定しています。また、ここでの *
 * '動作します'という言葉の意味は、変数$fooと$barが読み込まれる側のファイ *
 * ルで使用可能である、ということです。                                   */

// 動作しません: www.example.com では file.txt はPHPコードとして解釈されません。
include 'http://www.example.com/file.txt?foo=1&bar=2';

// 動作しません: 'file.php?foo=1&bar=2' という名前のファイルをローカルファイル
// システム上から探し出そうとします。
include 'file.php?foo=1&bar=2';

// 動作します。
include 'http://www.example.com/file.php?foo=1&bar=2';

$foo = 1;
$bar = 2;
include 'file.txt';  // 動作する
include 'file.php';  // 動作する

?>

警告

セキュリティの警告

リモートファイルはリモートサーバー上で実行されます（ファイルの拡張子や リモートサーバーが PHP の実行を許可しているかどうかに依存します）が、 有効な PHP スクリプトである必要があります。なぜならそれはローカル サーバー上で処理されるからです。もしリモートサーバー上で処理された結果が ほしいだけならば、readfile() を使用するほうがよい でしょう。そうでなければ、リモートスクリプトが有効な期待通りのコードを 生成していることを確認するため、注意を払うことが必要になります。

リモートファイル, fopen(), file()も参照してください。

値の返し方: 読み込まれたファイル内では、ファイルの実行処理を終了し呼出側の スクリプトに戻るために return 文を実行することが可能です。 読み込まれたファイルから値を返すことも可能です。 通常の関数で行うのと同様にincludeコールの値を取得することができます。 しかし、読み込まれたリモートファイル(ローカルファイルの場合も同様)の出力が、 有効なPHPの開始／ 終了タグを有していない限り、リモートファイルを読み込む際に値を 取得することはできません。 必要な変数をこれらのタグの中で宣言することができ、これらの変数は ファイルが読み込まれた位置で使用可能となります。

include は特別な言語構造であるため、 引数の前後に括弧は不要です。 返り値を比較する際には注意してください。

例4 インクルードの戻り値を比較する

<?php
// won't work, evaluated as include(('vars.php') == 'OK'), i.e. include('')
if (include('vars.php') == 'OK') {
    echo 'OK';
}

// works
if ((include 'vars.php') == 'OK') {
    echo 'OK';
}
?>

例5 include と return 文

return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // 'PHP'と出力されます

$bar = include 'noreturn.php';

echo $bar; // 1が出力されます

?>

読み込みが成功すると$barの値は1となります。上の2つの例の違いに 注目してください。最初の例では読み込まれるファイル側で return を使用し、もう一方では使用していません。 ファイルが読み込めなかった場合、FALSE が返され、 E_WARNING が発生します。

読み込まれるファイルで定義された関数がある場合、 これらは、return の前後によらず メインファイルで使用できます。 このファイルが二度読み込まれた場合、PHP 5は関数が定義済みであるため 致命的なエラーを発生します。一方、PHP 4は return の後に定義された関数については、 エラーを発生しません。 ファイルが読み込み済みであるかどうかを調べ、 読み込まれるファイルの内容を条件分岐で返すかわりに include_once を使用することを推奨します。

PHP ファイルの内容を変数に "include する" もうひとつの方法は、 出力制御関数 を include とともに用いて 出力をキャプチャすることです。たとえば、

例6 出力バッファリングを用い、 PHP ファイルの内容を文字列として読み込む

<?php
$string = get_include_contents('somefile.php');

function get_include_contents($filename) {
    if (is_file($filename)) {
        ob_start();
        include $filename;
        return ob_get_clean();
    }
    return false;
}

?>

スクリプト中で自動的にファイルをインクルードするには、php.ini の auto_prepend_file および auto_append_file オプションも参照ください。

注意: これは、関数ではなく 言語構造のため、可変関数 を用いて コールすることはできません。

require, require_once, include_once, get_included_files(), readfile(), virtual() および include_path も参照ください。

require_once

(PHP 4, PHP 5)

require_once 文は require とほぼ同じ意味ですが、 ファイルがすでに読み込まれているかどうかを PHP がチェックするという点が異なります。 すでに読み込まれている場合はそのファイルを読み込みません。

_once の振る舞い、およびそれが _once なし版とどのように異なるのかについての情報は、 include_once のドキュメントを参照ください。

include_once

(PHP 4, PHP 5)

include_once 命令は、スクリプトの実行時に指定 したファイルを読み込み評価します。この動作は、 include 命令と似ていますが、ファイルからのコー ドが既に読み込まれている場合は、再度読み込まれないという重要な違い があります。その名が示す通り、ファイルは一度しか読み込まれません。

include_once は、スクリプトの実行時に同じファイ ルが複数回読み込まれ、評価される可能性がある場合に、関数の再定義や 変数値の再代入といった問題を回避するために一回だけ読み込ませるため に使用します。

この関数の動作についての情報は include のドキュメントを参照ください。

注意:

PHP 4 では、大文字小文字を区別しない OS (Windows など) では _once の動作が多少異なります。次に例を示します。

例1 PHP 4 における、大文字小文字を区別しない OS 上での include_once

<?php
include_once "a.php"; // a.phpを読み込みます
include_once "A.php"; // これもa.phpを読み込みます! (PHP 4 のみ)
?>
この挙動は PHP 5 で変更されました。たとえば Windows ではまず最初にパスが正規化され、 C:\PROGRA~1\A.php は C:\Program Files\a.php と同じ扱いとなります。 ファイルは一度だけ読み込まれるようになります。

goto

(PHP 5 >= 5.3.0)

goto 演算子を使用すると、 プログラム中の他の命令にジャンプすることができます。 ジャンプ先はラベルとコロンで表し、 goto の後にそのラベルを指定します。 これは、完全に制約のない goto というわけではありません。 対象となるラベルは同じファイル上の同じコンテキストになければなりません。 つまり、関数やメソッドの外に飛び出したり 関数やメソッドの中に突入したりすることはできないということです。 また、いかなるループや switch 構造の中にも突入することができません。 逆にループや switch 構造から抜け出すことはできます。一般的な用法としては、 goto を複数レベルの break として使うものがあります。

例1 goto の例

<?php
goto a;
echo 'Foo';
 
a:
echo 'Bar';
?>

上の例の出力は以下となります。

Bar

例2 ループでの goto の例

<?php
for($i=0,$j=50; $i<100; $i++) {
  while($j--) {
    if($j==17) goto end; 
  }  
}
echo "i = $i";
end:
echo 'j hit 17';
?>

上の例の出力は以下となります。

j hit 17

例3 これは動作しません

<?php
goto loop;
for($i=0,$j=50; $i<100; $i++) {
  while($j--) {
    loop:
  }
}
echo "$i = $i";
?>

上の例の出力は以下となります。

Fatal error: 'goto' into loop or switch statement is disallowed in
script on line 2

注意:

goto 演算子は PHP 5.3 以降で使用可能です。

What's the worse thing that could happen if you use goto?
この画像は » xkcd から提供いただいたものです。

関数

目次

ユーザー定義関数

関数は次のような構文で定義されます。

例1 関数の使用法を説明するための擬似コード

<?php
function foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
    echo "関数の例\n";
    return $retval;
}
?>

関数の中では、他の関数や クラス 定義 を含む PHP のあらゆる有効なコードを使用することができます。

関数名は、PHP の他のラベルと同じ規則に従います。関数名として有効な 形式は、まず文字かアンダースコアで始まり、その後に任意の数の文字・ 数字・あるいはアンダースコアが続くものです。正規表現で表すと、 [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]* となります。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

PHP では、関数は参照される前に定義されている必要はありません。 ただし以下の二つの例のように、条件付きで関数が 定義されるような場合を除きます。

次の二つの例のように、ある条件下でのみ関数が定義される場合には、 その関数定義は関数がコールされる前に 行われていなければなりません。

例2 条件つきの関数

<?php

$makefoo = true;

/* ここでは関数foo()はまだ定義されていないので
   コールすることはできません。
   しかし関数 bar()はコールできます。 */

bar();

if ($makefoo) {
  function foo()
  {
    echo "I don't exist until program execution reaches me.\n";
  }
}

/* ここでは $makefooがtrueと評価されているため 
   安全にfoo()をコールすることができます。 */

if ($makefoo) foo();

function bar() 
{
  echo "I exist immediately upon program start.\n";
}

?>

例3 関数の中の関数

<?php
function foo() 
{
  function bar() 
  {
    echo "I don't exist until foo() is called.\n";
  }
}

/* ここでは関数bar()はまだ定義されていないので
   コールすることはできません。 */

foo();

/* foo()の実行によって bar()が
   定義されるためここではbar()を
   コールすることができます。*/

bar();

?>

PHP では、関数やクラスはすべてグローバルスコープにあります - 関数の内部で定義したものであっても関数の外部からコールできますし、 その逆も可能です。

PHP は関数のオーバーロードをサポートしていません。 また、宣言された関数の定義を取り消したり再定義することも できません。

注意: 関数名は大文字小文字を区別しませんが、通常は 関数宣言時と同じ名前で関数をコールする方が好ましいです。

可変引数 および デフォルト引数 の機能をサポートしています。 func_num_args(), func_get_arg(), func_get_args() に関する関数リファレンスを 参照ください。

PHP では、関数を再帰的にコールすることが可能です。ただし、100 から 200 を超えるような再帰呼び出しは避けてください。そんなことをすると、 スタックが破壊され、スクリプトが異常終了してしまいます。

例4 再帰的な関数

<?php
function recursion($a)
{
    if ($a < 20) {
        echo "$a\n";
        recursion($a + 1);
    }
}
?>

関数の引数

引数のリストにより関数へ情報を渡すことができます。 このリストは、カンマで区切られた式のリストです。 引数の評価は、左から右の順番で行われます。

PHP は、値渡し(デフォルト)、 参照渡し、 デフォルト引数値 をサポートしています。また、 可変長引数リスト もサポートしてます。 func_num_args(), func_get_arg(), func_get_args() に関する関数リファレンスを 参照ください。

例1 Passing arrays to functions

<?php
function takes_array($input)
{
    echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
?>

参照渡しで引数を作成する

デフォルトで、関数の引数は値で渡されます。(このため、関数の内部で 引数の値を変更しても関数の外側では値は変化しません。)関数がその引 数を修正できるようにするには、その引数を参照渡しとする必要があり ます。

関数の引数を常に参照渡しとしたい場合には、関数定義において アンパサンド(&) を引数名の前に付加することができます。

例2 Passing function parameters by reference

<?php
function add_some_extra(&$string)
{
    $string .= 'and something extra.';
}
$str = 'This is a string, ';
add_some_extra($str);
echo $str;    // outputs 'This is a string, and something extra.'
?>

デフォルト引数値

関数は、スカラー引数に関して次のように C++ スタイルのデフォルト値を 定義することができます。

例3 関数におけるデフォルトパラメータの使用法

<?php
function makecoffee($type = "cappuccino")
{
    return "Making a cup of $type.\n";
}
echo makecoffee();
echo makecoffee(null);
echo makecoffee("espresso");
?>

上の例の出力は以下となります。

Making a cup of cappuccino.
Making a cup of .
Making a cup of espresso.

PHPでは、配列および特殊な型 NULL をデフォルト値とすることも可能です。 例えば、

例4 スカラー型以外をデフォルト値として使用する

<?php
function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
{
    $device = is_null($coffeeMaker) ? "hands" : $coffeeMaker;
    return "Making a cup of ".join(", ", $types)." with $device.\n";
}
echo makecoffee();
echo makecoffee(array("cappuccino", "lavazza"), "teapot");
?>

デフォルト値は、定数式である必要があり、 (例えば) 変数やクラスのメンバーであってはなりません。

引数のデフォルト値を使用する際には、デフォルト値を有する引数はデ フォルト値がない引数の右側に全てある必要があることに注意して下さ い。そうでない場合、意図したような動作が行われません。次の簡単な コードを見てみましょう。

例5 関数の引数のデフォルト値の 間違った使用法

<?php
function makeyogurt($type = "acidophilus", $flavour)
{
    return "Making a bowl of $type $flavour.\n";
}
 
echo makeyogurt("raspberry");   // 期待通りには動作しません。
?>

上の例の出力は以下となります。

Warning: Missing argument 2 in call to makeyogurt() in 
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Making a bowl of raspberry .

ここで、上の例を次のコードと比べてみましょう。

例6 関数の引数のデフォルト値の 正しい使用法

<?php
function makeyogurt($flavour, $type = "acidophilus")
{
    return "Making a bowl of $type $flavour.\n";
}
 
echo makeyogurt("raspberry");   // 期待通り動作します
?>

上の例の出力は以下となります。

Making a bowl of acidophilus raspberry.

注意: PHP 5以降、デフォルト引数値をリファレンス渡しにすることもできます。

可変長引数リスト

PHP は、可変長引数をユーザー定義関数でサポートしています。 可変長引数の使用法は非常に簡単で、 func_num_args(), func_get_arg(), func_get_args() 関数を使用します。

可変長引数に関して特別な構文は必要としません。 引数リストは従来と同様に関数定義で明示的に指定することができ、 動作も従来と変わりません。

返り値

オプションの return 文により値を返すことができます。 配列やオブジェクトを含むあらゆる型を返すことができます。 これにより、関数の実行を任意の箇所で終了し、その関数を呼び出した 箇所に制御を戻すことが出来ます。詳細に関しては return を参照してください。

注意:

return を省略した場合は NULL を返します。

例1 return の使用法

<?php
function square($num)
{
    return $num * $num;
}
echo square(4);   //  '16'を出力
?>

複数の値を返すことはできませんが、リストを返すことにより 同じ効果を得ることができます。

例2 複数の値を得るために配列を返す

<?php
function small_numbers()
{
    return array (0, 1, 2);
}
list ($zero, $one, $two) = small_numbers();
?>

関数からリファレンスを返すには、リファレンス演算子 & を関数宣 言部および変数への返り値を代入する際の両方で使用する必要があります。

例3 関数からリファレンスを返す

<?php
function &returns_reference()
{
    return $someref;
}

$newref =& returns_reference();
?>

リファレンスに関するさらに詳しい情報がリファレンスの説明にあります。

可変関数

PHP は可変関数(variable functions)の概念をサポートします。 これにより、変数名の後に括弧が付いている場合、その値が何であろうと PHPは、同名の関数を探し実行を試みます。 この機能は、コールバック、関数テーブル等を実装するために使用可能です。

可変関数は、echo, print, isset(), empty(), include, require のような言語構造と組み合わせて使用する ことはできません。これらの言語構造を可変変数として使うには 独自のラッパー関数を使う必要があります。

例1 可変関数の例

<?php
function foo()
{
    echo "In foo()<br />\n";
}

function bar($arg = '')
{
    echo "In bar(); argument was '$arg'.<br />\n";
}

// これは、echo のラッパー関数です。
function echoit($string)
{
    echo $string;
}

$func = 'foo';
$func();        // This calls foo()

$func = 'bar';
$func('test');  // This calls bar()

$func = 'echoit';
$func('test');  // This calls echoit()
?>

オブジェクトのメソッドを可変関数を使ってコールすることもできます。

例2 可変メソッドの例

<?php
class Foo
{
    function Variable()
    {
        $name = 'Bar';
        $this->$name(); // Bar() メソッドのコール
    }
    
    function Bar()
    {
        echo "This is Bar";
    }
}

$foo = new Foo();
$funcname = "Variable";
$foo->$funcname();  // $foo->Variable() をコールする

?>

静的メソッドをコールするときには、関数呼び出しのほうが静的プロパティ演算子よりも優先されます。

例3 静的プロパティを含む可変メソッドの例

<?php
class Foo
{
    static $variable = 'static property';
    static function Variable()
    {
        echo 'Method Variable called';
    }
}

echo Foo::$variable; // これは 'static property' を表示します。このスコープにおいて $variable が必要です。
$variable = "Variable";
Foo::$variable();  // これは $foo->Variable() をコールします。このスコープでの $variable の内容を読むからです。

?>

可変変数や function_exists()も参照してください。

内部（ビルトイン）関数

PHPは標準で多くの関数と言語構造を持っています。また他にも コンパイル済みの特定のPHPエクステンションを必要とする関数があります。 それらはもしコンパイルされていなければ"undefined function（未定義の関数）" として致命的エラーを発するでしょう。例えば、 imagecreatetruecolor()のような 画像関数を使用するには、 GDサポートを有効にしてPHPをコンパイルしておく必要があります。 また、mysql_connect()を使う場合もやはり MySQLサポートを有効にしてPHPが コンパイルされている必要があります。 stringや variable関数のように どのバージョンのPHPでも含まれているコアの関数もたくさんあります。 phpinfo()やget_loaded_extensions()を コールすることで使用しているPHPにロードされているエクステンションを 見ることができます。また、多くのエクステンションはデフォルトで有効に なっており、PHPのマニュアルはエクステンション毎に分けられていることにも 注意してください。PHPのセットアップについては 設定, インストール,そして個々のエクステンション の項をご覧ください。

関数のプロトタイプに関する解説はマニュアルの 関数の定義を読むにはを 参照してください。関数の戻り値や引数が直接与えられた場合に どのように動くかを認識することは重要です。 例えば、str_replace()は変更された文字列を 返すのに対し、usort()は与えられた引数そのものを 変更します。マニュアルの各項にはそれぞれの関数に関する情報があります。 関数の引数、振る舞いの変更、成功した場合失敗した場合の それぞれの戻り値、可用性に関する情報などです。 これらの重要な（時には微妙な）違いを知ることは、 正しいPHPコードを書くうえで極めて重要なことです。

注意: 関数へのパラメータとして関数が想定しているのとは異なるものを渡した場合、 例えば文字列を想定しているところに配列を渡した場合などの場合は 関数の返り値は未定義となります。たいていの場合は NULL を返すでしょう。しかしこれはあくまでも規約にすぎず、 これに依存することはできません。

function_exists(), the function reference, get_extension_funcs(), dl()も参照してください。

無名関数

無名関数はクロージャとも呼ばれ、 関数名を指定せずに関数を作成できるようにするものです。 コールバック パラメータとして使う際に便利ですが、用途はそれにとどまりません。

例1 無名関数の例

<?php
echo preg_replace_callback('~-([a-z])~', function ($match) {
    return strtoupper($match[1]);
}, 'hello-world');
// helloWorld と出力します
?>

クロージャは、変数の値として使用することもできます。 PHP は、そのような記述があると自動的に内部クラス Closure のインスタンスに変換します。 変数へのクロージャの代入は、他の代入と同じように記述し、 同じく最後にセミコロンをつけます。

例2 変数への無名関数の代入

<?php
$greet = function($name)
{
    printf("Hello %s\r\n", $name);
};

$greet('World');
$greet('PHP');
?>

クロージャは、変数を親のスコープから引き継ぐことができます。 引き継ぐ変数は、関数のヘッダで宣言しなければなりません。 親のスコープからの変数の引き継ぎは、グローバル変数を使うのとは 異なります。グローバル変数は、 関数が実行されるかどうかにかかわらずグローバルスコープに存在します。 クロージャの親スコープは、クロージャが宣言されている関数です (関数の呼び出し元のスコープである必要はありません)。 次の例を参照ください。

例3 クロージャのスコープ

<?php
// 基本的なショッピングカートで、追加した商品の一覧や各商品の
// 数量を表示します。カート内の商品の合計金額を計算するメソッド
// では、クロージャをコールバックとして使用します。
class Cart
{
    const PRICE_BUTTER  = 1.00;
    const PRICE_MILK    = 3.00;
    const PRICE_EGGS    = 6.95;

    protected $products = array();
    
    public function add($product, $quantity)
    {
        $this->products[$product] = $quantity;
    }
    
    public function getQuantity($product)
    {
        return isset($this->products[$product]) ? $this->products[$product] :
               FALSE;
    }
    
    public function getTotal($tax)
    {
        $total = 0.00;
        
        $callback =
            function ($quantity, $product) use ($tax, &$total)
            {
                $pricePerItem = constant(__CLASS__ . "::PRICE_" .
                    strtoupper($product));
                $total += ($pricePerItem * $quantity) * ($tax + 1.0);
            };
        
        array_walk($this->products, $callback);
        return round($total, 2);
    }
}

$my_cart = new Cart;

// カートに商品を追加します
$my_cart->add('butter', 1);
$my_cart->add('milk', 3);
$my_cart->add('eggs', 6);

// 合計に消費税 5% を付加した金額を表示します
print $my_cart->getTotal(0.05) . "\n";
// 結果は 54.29 です
?>

無名関数の実装には Closure クラスを使っています。

変更履歴

バージョン 説明
5.4.0 無名関数で $this を使えるようになりました。
5.3.0 無名関数が使えるようになりました。

注意

注意: クロージャ内から func_num_args()、 func_get_arg() および func_get_args() を使用することができます。

クラスとオブジェクト

目次

はじめに

PHP 5 以降、オブジェクトモデルが書き直されて、 より高い性能と高機能を実現するようになりました。 これは PHP 4 から大きく変わった点であり、PHP 5 には完全なオブジェクトモデルが搭載されています。

PHP 5 で採用された機能には 可視性、 abstract クラスやメソッド、 final クラスやメソッド、 新たな マジックメソッド、 インターフェイス、 クローン そして タイプヒンティング などがあります。

PHP では、オブジェクトを参照やハンドルと同様に扱います。つまり、 オブジェクトそのものではなくオブジェクトへの参照を変数に格納するようになります。 オブジェクトおよびリファレンス を参照ください。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

クラスの基礎

class

各クラスの定義は、classキーワードで始まり、クラス名が続きます。 そしてその後に波括弧のペアが続き、 その中にはクラスのプロパティとメソッドの定義を記述します。

クラス名には、PHP の予約語 以外でラベルとして有効なあらゆる名前を使用することができます。 有効なクラス名は、先頭が文字あるいはアンダースコアで始まり、 その後に任意の数の文字/数字/アンダースコアが続くものです。 正規表現で表すと、 [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]* のようになります。

クラスの中には、 定数 や 変数 ("プロパティ" といいます) そして関数 ("メソッド" といいます) を含めることができます。

例1 簡単なクラス定義

<?php
class SimpleClass
{
    // プロパティの宣言
    public $var = 'a default value';

    // メソッドの宣言
    public function displayVar() {
        echo $this->var;
    }
}
?>

メソッドがオブジェクトコンテキストからコールされる場合は、 疑似変数 $this が利用可能です。 $this は、呼び出し元オブジェクト (通常は、メソッドが属するオブジェクトですが、 メソッドが第二のオブジェクトのオブジェクトの コンテキストから スタティックに コールされる場合には、別のオブジェクトとなる場合もあります) への参照です。

例2 $this 疑似変数の例

<?php
class A
{
    function foo()
    {
        if (isset($this)) {
            echo '$this is defined (';
            echo get_class($this);
            echo ")\n";
        } else {
            echo "\$this is not defined.\n";
        }
    }
}

class B
{
    function bar()
    {
        // 注意: E_STRICT が有効な場合、次の行で警告が発生します
        A::foo();
    }
}

$a = new A();
$a->foo();

// 注意: E_STRICT が有効な場合、次の行で警告が発生します
A::foo();
$b = new B();
$b->bar();

// 注意: E_STRICT が有効な場合、次の行で警告が発生します
B::bar();
?>

上の例の出力は以下となります。

$this is defined (A)
$this is not defined.
$this is defined (B)
$this is not defined.

new

あるクラスのインスタンスを生成するには、new キーワードを使わなければなりません。エラー時に 例外をスローするような コンストラクタを定義していない限り、 オブジェクトが常に生成されます。 クラスは、そのインスタンスを作成する前に定義しなければなりません (これが必須となる場合もあります)。

クラス名を含む文字列を new で指定すると、 そのクラスのインスタンスを作成します。クラスが名前空間に属している場合は、 完全修飾名を指定しなければなりません。

例3 インスタンスを作成する

<?php
$instance = new SimpleClass();

// 変数を使うこともできます
$className = 'Foo';
$instance = new $className(); // Foo()
?>

クラスのコンテキストにおいては、 new self や new parent のようにして新しいオブジェクトを作成することができます。

作成済みのクラスのインスタンスを新たな変数に代入する場合、新しい変数は、 代入されたオブジェクトと同じインスタンスにアクセスします。 この動作は、インスタンスを関数に渡す場合も同様です。 作成済みのオブジェクトのコピーは、その クローンを作成 することにより作成可能です。

例4 オブジェクトの代入

<?php

$instance = new SimpleClass();

$assigned   =  $instance;
$reference  =& $instance;

$instance->var = '$assigned will have this value';

$instance = null; // $instance と $reference は null になります

var_dump($instance);
var_dump($reference);
var_dump($assigned);
?>

上の例の出力は以下となります。

NULL
NULL
object(SimpleClass)#1 (1) {
   ["var"]=>
     string(30) "$assigned will have this value"
}

PHP 5.3.0 以降では、オブジェクトのインスタンスを作成する別の方法が新たに導入されました。

例5 新しいオブジェクトの作成

<?php
class Test
{
    static public function getNew()
    {
        return new static;
    }
}

class Child extends Test
{}

$obj1 = new Test();
$obj2 = new $obj1;
var_dump($obj1 !== $obj2);

$obj3 = Test::getNew();
var_dump($obj3 instanceof Test);

$obj4 = Child::getNew();
var_dump($obj4 instanceof Child);
?>

上の例の出力は以下となります。

bool(true)
bool(true)
bool(true)

extends

クラスは、宣言部に extends キーワードを含めることで、他のクラスのメソッドと プロパティを継承することができます。多重継承を行うことはできず、クラスが継承できるベース クラスは一つだけです。

継承されたメソッドやプロパティをオーバーライドするには、 親クラスで定義されているのと同じ名前でそれを再宣言します。 しかし、親クラスでそのメソッドが final 定義されている場合はオーバーライドできません。 オーバーライドされた元のメソッドや静的プロパティにアクセスするには、 parent:: で参照します。

メソッドをオーバーライドするときには、パラメータのシグネチャも同じでなければなりません。 もし違っていれば、PHP は E_STRICT レベルのエラーとなります。ただしコンストラクタは例外で、 異なるパラメータでオーバーライドすることができます。

例6 簡単なクラスの継承

<?php
class ExtendClass extends SimpleClass
{
    // 親クラスのメソッドを再定義
    function displayVar()
    {
        echo "Extending class\n";
        parent::displayVar();
    }
}

$extended = new ExtendClass();
$extended->displayVar();
?>

上の例の出力は以下となります。

Extending class
a default value

プロパティ

クラスのメンバ変数のことを「プロパティ」といいます。 それ以外に「属性」「フィールド」などという呼びかたを見たことがあるかもしれません。 しかし、このマニュアルでは「プロパティ」と呼ぶことにします。 プロパティを定義するには public、protected あるいは private のいずれかのキーワードのあとに通常の変数の宣言を続けます。 宣言時に初期値を設定することもできますが、初期値は定数値でなければなりません。 つまり、コンパイル時に評価可能な値でなければならず、 実行時の情報がないと評価できない値であってはいけないということです。

public、protected そして private についての詳しい情報は アクセス権 を参照ください。

注意:

PHP 4 との互換性を考慮して、PHP 5 でも var を使ったプロパティの宣言が可能です。これは public や protected、 private と組み合わせて使うこともできます。 しかし、もはや var は必須ではありません。 PHP 5.0 から 5.1.3 までのバージョンでは、 var の使用は非推奨とされており、 E_STRICT 警告が発生していました。 しかし PHP 5.1.3 以降は非推奨ではなくなり、警告も出なくなっています。

public や protected、 private のかわりに var を使ってプロパティを宣言した場合、PHP 5 はそれを public と同等とみなします。

クラスメソッドからプロパティや定数、メソッドにアクセスするには $this->property (property はプロパティの名前) 形式を使います。静的なクラスメソッドの中から静的なプロパティにアクセスする場合は self::$property 形式となります。 詳細な情報は static キーワード を参照ください。

クラスメソッドがオブジェクトのコンテキストからコールされたときには、 擬似変数 $this が常に使えます。 $this は、呼び出し元のオブジェクト (通常はそのメソッドが属するオブジェクトですが、別のオブジェクトになる可能性もあります。 別のオブジェクトのコンテキストから 静的に コールされた場合などです) への参照となります。

例1 プロパティの宣言

<?php
class SimpleClass
{
   // 無効なプロパティ宣言
   public $var1 = 'hello ' . 'world';
   public $var2 = <<<EOD
hello world
EOD;
   public $var3 = 1+2;
   public $var4 = self::myStaticMethod();
   public $var5 = $myVar;

   // 有効なプロパティ宣言
   public $var6 = myConstant;
   public $var7 = array(true, false);

   // これは PHP 5.3.0 以降でのみ使える方式です
   public $var8 = <<<'EOD'
hello world
EOD;
}
?>

注意:

クラスやオブジェクトを操作するための便利な関数が用意されています。 クラス/オブジェクト関数 を参照ください。

ヒアドキュメント とは異なり、 nowdocs は任意の静的データコンテキストで使えます。プロパティの宣言時にも使用可能です。

例2 nowdoc を使ったプロパティの初期化

<?php
class foo {
   // PHP 5.3.0 以降
   public $bar = <<<'EOT'
bar
EOT;
}
?>

注意:

Nowdoc は PHP 5.3.0 以降で使用可能です。

オブジェクト定数

値が変更できない定数をクラス内に定義することができます。 定数は、通常の変数とは異なり、定義または使用する際に $ 記号を付けません。

定義する値は定数表現である必要があり、(例えば)変数・プロパティ・ 演算結果あるいは関数のコールなどであってはいけません。

インターフェイスに 定数 を持たせることもできます。 インターフェイスについてのドキュメント で例をごらんください。

PHP 5.3.0 以降では、変数を用いてクラスを参照することも可能です。 変数の値に (self や parent、 static といった) キーワードを指定することはできません。

例1 定数の定義と使用

<?php
class MyClass
{
    const constant = 'constant value';

    function showConstant() {
        echo  self::constant . "\n";
    }
}

echo MyClass::constant . "\n";

$classname = "MyClass";
echo $classname::constant . "\n"; // PHP 5.3.0 以降で対応

$class = new MyClass();
$class->showConstant();

echo $class::constant."\n"; // PHP 5.3.0 以降で対応
?>

例2 静的なデータの例

<?php
class foo {
    // PHP 5.3.0 以降で対応
    const bar = <<<'EOT'
bar
EOT;
}
?>

ヒアドキュメントとは異なり、nowdoc は静的データコンテキストでも使用することができます。

注意:

Nowdoc は PHP 5.3.0 以降で使用可能です。

クラスのオートローディング

オブジェクト指向アプリケーションを作成する開発者の多くは、 クラス定義毎に一つのPHPソースファイルを作成します。 最大の問題は、各スクリプトの先頭に、必要な読み込みを行う長いリストを 記述する必要があることです(各クラスについて一つ)。

PHP 5では、これはもう不要です。 未定義のクラス/インターフェイスを使用しようとした時に 自動的にコールされる __autoload() 関数を定義することができます。 この関数をコールすることにより、 スクリプトエンジンは、PHPがエラーで止まる前にクラスをロードする最後の チャンスを与えます。

ヒント

spl_autoload_register() を使えば、より柔軟にクラスのオートロードができます。 そのため、今や __autoload() を使うことはおすすめできません。 将来のバージョンではこの機能が非推奨となり、削除されるかもしれません。

注意:

5.3.0 より前のバージョンでは、__autoload 関数の内部でスローされた例外を catch ブロックでキャッチすることができず、致命的なエラーとなります。 5.3.0 以降では __autoload 関数の内部でスローされた例外を catch ブロックでキャッチできますが、ひとつだけ条件があります。 独自の例外クラスをスローした場合は、その例外クラスが利用可能でなければなりません。 __autoload 関数を再帰的に用いて、独自の例外クラスをオートロードします。

注意:

オートローディングは、PHP を CLI 対話モード で実行している場合は使用できません。

注意:

クラス名をたとえば call_user_func() などで使用する場合、 ../ のような危険な文字が含まれることもあり得ます。 このような関数にはユーザーの入力を渡さないことをおすすめします。 あるいは最低限 __autoload() の中で入力内容を検証するようにします。

例1 オートロードの例

この例は、 クラス MyClass1 および MyClass2 をそれぞれ MyClass1.php および MyClass2.php からロードします。

<?php
function __autoload($class_name) {
    include $class_name . '.php';
}

$obj  = new MyClass1();
$obj2 = new MyClass2();
?>

例2 オートロードの別の例

この例は、インターフェイス ITest をロードしようとします。

<?php

function __autoload($name) {
    var_dump($name);
}

class Foo implements ITest {
}

/*
string(5) "ITest"

Fatal error: Interface 'ITest' not found in ...
*/
?>

例3 5.3.0 以降での例外処理つきのオートロード

この例は、例外をスローして try/catch ブロックの動きを示します。

<?php
function __autoload($name) {
    echo "Want to load $name.\n";
    throw new Exception("Unable to load $name.");
}

try {
    $obj = new NonLoadableClass();
} catch (Exception $e) {
    echo $e->getMessage(), "\n";
}
?>

上の例の出力は以下となります。

Want to load NonLoadableClass.
Unable to load NonLoadableClass.

例4 5.3.0 以降での例外処理つきのオートロード - 独自の例外が見つからない場合

この例では、ロードできない独自の例外クラスをスローします。

<?php
function __autoload($name) {
    echo "Want to load $name.\n";
    throw new MissingException("Unable to load $name.");
}

try {
    $obj = new NonLoadableClass();
} catch (Exception $e) {
    echo $e->getMessage(), "\n";
}
?>

上の例の出力は以下となります。

Want to load NonLoadableClass.
Want to load MissingException.

Fatal error: Class 'MissingException' not found in testMissingException.php on line 4

参考

コンストラクタとデストラクタ

コンストラクタ

void __construct ([ mixed $args [, $... ]] )

PHP 5 では、開発者がクラスのコンストラクタメソッドを宣言することが できます。コンストラクタメソッドを有するクラスは、新たにオブジェクトが 生成される度にこのメソッドをコールします。これにより、 そのオブジェクトを使用する前に必要な初期化を行うことができます。

注意: 子クラスがコンストラクタを有している場合、親クラスのコンストラクタが 暗黙の内にコールされることはありません。 親クラスのコンストラクタを実行するには、子クラスのコンストラクタの 中で parent::__construct() をコールすることが 必要です。

例1 新しい統一されたコンストラクタを使用する

<?php
class BaseClass {
   function __construct() {
       print "In BaseClass constructor\n";
   }
}

class SubClass extends BaseClass {
   function __construct() {
       parent::__construct();
       print "In SubClass constructor\n";
   }
}

$obj = new BaseClass();
$obj = new SubClass();
?>

下位互換性を維持するため、PHP 5 が指定されたクラスの __construct() 関数をみつけられない場合には、 古い形式のコンストラクタ関数、つまり、そのクラスの名前と同じ関数が探されます。 実際、互換性の問題が発生する可能性があるのは、 そのクラスが __construct() という名前のメソッドを 有しており、それが異なる用途で使用されている場合です。

他のメソッドと異なり、親の __construct() と異なるパラメータで __construct() をオーバーライドしても PHP は E_STRICT エラーメッセージを出しません。

PHP 5.3.3 以降、名前空間つきのクラス名の最後の部分と同じ名前のメソッドは コンストラクタとみなされなくなりました。 名前空間を使っていないクラスは今までと変わりません。

例2 名前空間つきのクラスのコンストラクタ

<?php
namespace Foo;
class Bar {
    public function Bar() {
        // PHP 5.3.0-5.3.2 までは、これはコンストラクタとみなされました
        // PHP 5.3.3 以降は、これはコンストラクタにはなりません
    }
}
?>

デストラクタ

void __destruct ( void )

PHP 5 では、C++ のような他のオブジェクト指向言語に似た概念のデストラクタが 導入されました。デストラクタメソッドは、 特定のオブジェクトを参照するリファレンスがひとつもなくなったときにコールされます。 あるいは、スクリプトの終了時にも順不同でコールされます。

例3 デストラクタの例

<?php
class MyDestructableClass {
   function __construct() {
       print "In constructor\n";
       $this->name = "MyDestructableClass";
   }

   function __destruct() {
       print "Destroying " . $this->name . "\n";
   }
}

$obj = new MyDestructableClass();
?>

コンストラクタと同様、親クラスのデストラクタがエンジンにより暗黙のうちに コールされるということはありません。親クラスのデストラクタを実行するには、 デストラクタの中で明示的に parent::__destruct() をコールする必要があります。

exit() でスクリプトの実行を止めた場合にもデストラクタはコールされます。 デストラクタの内部で exit() をコールすると、 それ以降のシャットダウンルーチンを実行しません。

注意:

スクリプトのシャットダウン時にデストラクタがコールされた場合は、 HTTP ヘッダはすでに送信されています。スクリプトのシャットダウン時の作業ディレクトリは、 SAPI によっては (たとえば Apache など) 異なります。

注意:

デストラクタの中から (スクリプトの終了処理時に) 例外をスローしようとすると、致命的なエラーを引き起こします。

アクセス権

プロパティまたはメソッドのアクセス権 (visibility) は、 キーワード: public, protected または private を指定することにより定義できます。 public 宣言されたクラスのメンバーには、どこからでもアクセス可能です。 protected 宣言されたメンバーには、 そのクラス自身と継承したクラス、親クラスからのみアクセスできます。 private 宣言されたメンバーには、そのメンバーを定義したクラスからのみアクセスできます。

プロパティのアクセス権

クラスのプロパティは、public, private, または protected として定義しなくてはなりません。var を使って宣言した場合、 そのプロパティは public として定義されます。

例1 プロパティの宣言

<?php
/**
 * MyClass の定義
 */
class MyClass
{
    public $public = 'Public';
    protected $protected = 'Protected';
    private $private = 'Private';

    function printHello()
    {
        echo $this->public;
        echo $this->protected;
        echo $this->private;
    }
}

$obj = new MyClass();
echo $obj->public; // 動作します
echo $obj->protected; // Fatal エラー
echo $obj->private; // Fatal エラー
$obj->printHello(); // Public、Protected そして Private を表示します


/**
 * MyClass2 の定義
 */
class MyClass2 extends MyClass
{
    // public および protected メソッドは再定義できますが、
    // private はできません。
    protected $protected = 'Protected2';

    function printHello()
    {
        echo $this->public;
        echo $this->protected;
        echo $this->private;
    }
}

$obj2 = new MyClass2();
echo $obj2->public; // 動作します
echo $obj2->private; // 未定義です
echo $obj2->protected; // Fatal エラー
$obj2->printHello(); // Public、Protected2、Undefined を表示します

?>

注意: キーワード var で変数を宣言する PHP 4 の方法は、互換性を保つために今でもサポートされています (これは public と同じ扱いになります)。PHP 5.1.3 より前では、 これを使用すると E_STRICT 警告が発生します。

メソッドのアクセス権

クラスメソッドは、public, private, または protected として定義します。アクセス権を明示せずに宣言したメソッドは、 public となります。

例2 メソッドの宣言

<?php
/**
 * MyClass の定義
 */
class MyClass
{
    // public コンストラクタの宣言
    public function __construct() { }

    // public メソッドの宣言
    public function MyPublic() { }

    // protected メソッドの宣言
    protected function MyProtected() { }

    // private メソッドの宣言
    private function MyPrivate() { }

    // これは public となります
    function Foo()
    {
        $this->MyPublic();
        $this->MyProtected();
        $this->MyPrivate();
    }
}

$myclass = new MyClass;
$myclass->MyPublic(); // 動作します
$myclass->MyProtected(); // Fatal エラー
$myclass->MyPrivate(); // Fatal エラー
$myclass->Foo(); // Public、Protected および Private が動作します


/**
 * MyClass2 の定義
 */
class MyClass2 extends MyClass
{
    // これは public となります
    function Foo2()
    {
        $this->MyPublic();
        $this->MyProtected();
        $this->MyPrivate(); // Fatal エラー
    }
}

$myclass2 = new MyClass2;
$myclass2->MyPublic(); // 動作します
$myclass2->Foo2(); // Public および Protected は動作しますが、Private は動作しません

class Bar 
{
    public function test() {
        $this->testPrivate();
        $this->testPublic();
    }

    public function testPublic() {
        echo "Bar::testPublic\n";
    }
    
    private function testPrivate() {
        echo "Bar::testPrivate\n";
    }
}

class Foo extends Bar 
{
    public function testPublic() {
        echo "Foo::testPublic\n";
    }
    
    private function testPrivate() {
        echo "Foo::testPrivate\n";
    }
}

$myFoo = new foo();
$myFoo->test(); // Bar::testPrivate 
                // Foo::testPublic
?>

他のオブジェクトからのアクセス権

同じ型のオブジェクト間では、たとえ同一のインスタンスでなくても お互いの private メンバーや protected メンバーにアクセスすることができます。 これは、そのオブジェクトの内部ではオブジェクトの実装の詳細が既知であるからです。

例3 同じ型のオブジェクトの private メンバーへのアクセス

<?php
class Test
{
    private $foo;

    public function __construct($foo)
    {
        $this->foo = $foo;
    }

    private function bar()
    {
        echo 'Accessed the private method.';
    }

    public function baz(Test $other)
    {
        // private プロパティを変更することができます
        $other->foo = 'hello';
        var_dump($other->foo);

        // private メソッドをコールすることもできます
        $other->bar();
    }
}

$test = new Test('test');

$test->baz(new Test('other'));
?>

上の例の出力は以下となります。

string(5) "hello"
Accessed the private method.

オブジェクトの継承

プログラミング言語の原則としてよくみられるものに継承があります。 PHP はオブジェクトモデルにおいてこの継承を利用しています。 多くのクラスとオブジェクトとの連携に継承は関係しています。

例えば、クラスを拡張するとき、サブクラスは親クラスから public と、protected のメソッドをすべてを引き継ぎます。 (子の)クラスが親のメソッドを上書きしない限り、 親のメソッドの機能が保持されます。

これは、機能を定義して抽象化するのに便利です。 また、同じようなオブジェクトに機能を追加する際に、 共通機能を再実装する必要がなくなります。

注意:

オートローディングが有効になっていない限り、 クラスの定義は実際に使うより前になければなりません。 別のクラスを継承したクラスの場合は、 そのクラスより前に親クラスが宣言されていなければなりません。 この規則が適用されるのは、別のクラスやインターフェイスを継承したクラスです。

例1 継承の例

<?php

class foo
{
    public function printItem($string)
    {
        echo 'Foo: ' . $string . PHP_EOL;
    }
    
    public function printPHP()
    {
        echo 'PHP is great.' . PHP_EOL;
    }
}

class bar extends foo
{
    public function printItem($string)
    {
        echo 'Bar: ' . $string . PHP_EOL;
    }
}

$foo = new foo();
$bar = new bar();
$foo->printItem('baz'); // 出力: 'Foo: baz'
$foo->printPHP();       // 出力: 'PHP is great' 
$bar->printItem('baz'); // 出力: 'Bar: baz'
$bar->printPHP();       // 出力: 'PHP is great'

?>

スコープ定義演算子 (::)

スコープ定義演算子 (またの名を Paamayim Nekudotayim)、 平たく言うと「ダブルコロン」は、トークンのひとつです。 static, 定数 およびオーバーライドされたクラスのプロパティやメソッドにアクセスすることができます。

これらの要素をクラス定義の外から参照する際には、 クラスの名前を使用してください。

PHP 5.3.0 以降では、変数を用いてクラスを参照することも可能です。 変数の値に (self や parent、 static といった) キーワードを指定することはできません。

なぜダブルコロンに Paamayim Nekudotayim という名前をつけたのか、 ちょっと奇妙に感じられるかもしれません。 しかし、Zend Engine 0.5 (PHP 3のエンジン) を 書いている時に、Zend チームはこう呼ぶと決めたのです。 この奇妙な名前は、実はダブルコロンを意味するヘブライ語なのです!

例1 クラス定義の外からの ::

<?php
class MyClass {
    const CONST_VALUE = 'A constant value';
}

$classname = 'MyClass';
echo $classname::CONST_VALUE; // PHP 5.3.0 以降で対応

echo MyClass::CONST_VALUE;
?>

三つの特別なキーワード self と parentそして static がクラス定義の内部からプロパティまたはメソッドにアクセスする際に使用されます。

例2 クラス定義の中からの ::

<?php
class OtherClass extends MyClass
{
    public static $my_static = 'static var';

    public static function doubleColon() {
        echo parent::CONST_VALUE . "\n";
        echo self::$my_static . "\n";
    }
}

$classname = 'OtherClass';
echo $classname::doubleColon(); // PHP 5.3.0 以降で対応

OtherClass::doubleColon();
?>

拡張されたクラスが親クラスのメソッドの定義をオーバーライドする際、 PHPは親クラスのメソッドをコールしません。 親クラスのメソッドをコールするかしないかは、 拡張されたクラスに責任があります。 これは、コンストラクタおよびデストラクタ, オーバーロード, そして マジック メソッドの定義にも 適用されます。

例3 親クラスのメソッドをコールする

<?php
class MyClass
{
    protected function myFunc() {
        echo "MyClass::myFunc()\n";
    }
}

class OtherClass extends MyClass
{
    // 親の定義をオーバーライドします
    public function myFunc()
    {
        // それでも親の関数をコールできます
        parent::myFunc();
        echo "OtherClass::myFunc()\n";
    }
}

$class = new OtherClass();
$class->myFunc();
?>

静的コールのトリックに関するサンプル も参照ください。

static キーワード

クラスプロパティもしくはメソッドを static として宣言することで、 クラスのインスタンス化の必要なしにアクセスすることができます。 static なプロパティは、インスタンス化されたクラスオブジェクトから アクセスすることはできません (static なメソッドにはアクセスできます)。

PHP 4 との互換性を維持するため、 可視性の宣言が ない場合、そのプロパティまたはメソッドは、 publicとして宣言されていると みなされます。

static メソッドは、オブジェクトのインスタンスを生成せずに コールすることができます。疑似変数 $this は、 static として宣言されたメソッドの内部から利用することはできません。

static プロパティは、矢印演算子 -> によりオブジェクトからアクセス することはできません。

static でないメソッドを静的にコールすると、E_STRICT レベルの 警告が発生します。

他の PHP 静的変数と同様、 静的プロパティの初期化はリテラルあるいは定数でのみ可能です。 式で初期化することはできません。 つまり、静的プロパティを (たとえば) 整数値や配列で初期化することはできますが、 他の変数の値や関数の返り値、オブジェクトなどで初期化することはできません。

PHP 5.3.0 以降では、変数を用いてクラスを参照することも可能です。 変数の値に (self や parent、 static といった) キーワードを指定することはできません。

例1 static プロパティの例

<?php
class Foo
{
    public static $my_static = 'foo';

    public function staticValue() {
        return self::$my_static;
    }
}

class Bar extends Foo
{
    public function fooStatic() {
        return parent::$my_static;
    }
}


print Foo::$my_static . "\n";

$foo = new Foo();
print $foo->staticValue() . "\n";
print $foo->my_static . "\n";      // Undefined "Property" my_static

print $foo::$my_static . "\n";
$classname = 'Foo';
print $classname::$my_static . "\n"; // PHP 5.3.0 以降で対応

print Bar::$my_static . "\n";
$bar = new Bar();
print $bar->fooStatic() . "\n";
?>

例2 static メソッドの例

<?php
class Foo {
    public static function aStaticMethod() {
        // ...
    }
}

Foo::aStaticMethod();
$classname = 'Foo';
$classname::aStaticMethod(); // PHP 5.3.0 で対応
?>

クラスの抽象化

PHP 5 では、抽象クラスとメソッドが導入されました。 abstractとして定義されたクラスのインスタンスを生成することはできません。 １つ以上の抽象メソッドを含む全てのクラスもまた抽象クラスとなります。 abstractとして定義されたメソッドは、そのメソッドの外観を宣言するのみで、 実装を定義することはできません。

抽象クラスから継承する際、親クラスの宣言で abstract としてマークされた 全てのメソッドは、子クラスで定義されなければなりません。加えて、 これらのメソッドは同等 (あるいはより緩い制約) の 可視性 で定義される必要があります。例えば、抽象メソッドが protected として定義された場合、その関数の実装は protected または public のどちらかとして定義する必要があります。private にすることはできません。 さらに、メソッドのシグネチャも必ず一致していなくてはなりません。 すなわち、型ヒントや必須引数の数についても同じでなければならないということです。 PHP 5.4 以降では、これがコンストラクタについても適用されるようになりました。 それより前のバージョンでは、コンストラクタのシグネチャは違ってもかまいませんでした。

例1 抽象クラスの例

<?php
abstract class AbstractClass
{
    // 拡張クラスにこのメソッドの定義を強制する
    abstract protected function getValue();
    abstract protected function prefixValue($prefix);

    // Common method
    public function printOut() {
        print $this->getValue() . "\n";
    }
}

class ConcreteClass1 extends AbstractClass
{
    protected function getValue() {
        return "ConcreteClass1";
    }

    public function prefixValue($prefix) {
        return "{$prefix}ConcreteClass1";
    }
}

class ConcreteClass2 extends AbstractClass
{
    public function getValue() {
        return "ConcreteClass2";
    }

    public function prefixValue($prefix) {
        return "{$prefix}ConcreteClass2";
    }
}

$class1 = new ConcreteClass1;
$class1->printOut();
echo $class1->prefixValue('FOO_') ."\n";

$class2 = new ConcreteClass2;
$class2->printOut();
echo $class2->prefixValue('FOO_') ."\n";
?>

上の例の出力は以下となります。

ConcreteClass1
FOO_ConcreteClass1
ConcreteClass2
FOO_ConcreteClass2

'abstract'という名前のユーザー定義関数または関数を有さない コードは修正なしに動作します。

オブジェクト インターフェイス

オブジェクトインターフェイスにより、あるクラスが実装する必要があるメソッドの 種類を、これらのメソッドの実体を定義することなく、指定するコードを作成できる ようになります。

インターフェイスはキーワード interface により定義され、通常のクラスと 同様に定義することができますが、メソッドの実装は全く定義されません。

インターフェイス内で宣言される全てのメソッドはpublicである必要があります。 これは、インターフェイスの特性によります。

implements

インターフェイスを実装するには、implements 演算子を使用し、 このインターフェイスに含まれる全てのメソッドを実装する必要があります。 実装されていない場合、致命的エラーとなります。 各インターフェイスをカンマで区切って指定することで、 クラスは複数のインターフェイスを実装することができます。

注意:

ひとつのクラスの中で、同じ名前の関数を含む 2 つのインターフェイスを 実装することはできません。あいまいさを解決できなくなるためです。

注意:

クラスと同様、インターフェイスも extends 演算子で継承することができます。

注意:

インターフェイスを実装したクラスには、 そのインターフェイスで定義されているメソッドとまったく同じシグネチャを持つメソッドが必要です。 そうしなければ致命的なエラーが発生します。

定数

インターフェイスに定数を持たせることもできます。 インターフェイス定数は クラス定数 とまったく同じように動作します。しかし、 そのインターフェイスを継承したクラスやインターフェイスから上書きすることはできません。

例

例1 Interface の例

<?php

// インターフェイス 'iTemplate' を宣言する
interface iTemplate
{
    public function setVariable($name, $var);
    public function getHtml($template);
}

// インターフェイスを実装する。
// これは動作します。
class Template implements iTemplate
{
    private $vars = array();

    public function setVariable($name, $var)
    {
        $this->vars[$name] = $var;
    }

    public function getHtml($template)
    {
        foreach($this->vars as $name => $value) {
            $template = str_replace('{' . $name . '}', $value, $template);
        }

        return $template;
    }
}

// これは動作しません。
// Fatal error: Class BadTemplate contains 1 abstract methods
// and must therefore be declared abstract (iTemplate::getHtml)
class BadTemplate implements iTemplate
{
    private $vars = array();

    public function setVariable($name, $var)
    {
        $this->vars[$name] = $var;
    }
}
?>

例2 インターフェイスの継承

<?php
interface a
{
    public function foo();
}

interface b extends a
{
    public function baz(Baz $baz);
}

// これは動作します
class c implements b
{
    public function foo()
    {
    }

    public function baz(Baz $baz)
    {
    }
}

// これは動作せず、fatal error となります
class d implements b
{
    public function foo()
    {
    }

    public function baz(Foo $foo)
    {
    }
}
?>

例3 複数のインターフェイスの継承

<?php
interface a
{
    public function foo();
}

interface b
{
    public function bar();
}

interface c extends a, b
{
    public function baz();
}

class d implements c
{
    public function foo()
    {
    }

    public function bar()
    {
    }

    public function baz()
    {
    }
}
?>

例4 インターフェイスでの定数

<?php
interface a
{
    const b = 'Interface constant';
}

// Interface constant と表示します
echo a::b;


// しかし、これは動作しません。定数のオーバーライドが
// できないからです。
class b implements a
{
    const b = 'Class constant';
}
?>

インターフェイスとタイプヒンティングを組み合わせると、 特定のオブジェクトに特定のメソッドをうまく持たせることができます。 instanceof 演算子および タイプヒンティング を参照ください。

トレイト

PHP 5.4.0 以降では、コードを再利用するための「トレイト」という仕組みが導入されました。

トレイトは、PHP のような単一継承言語でコードを再利用するための仕組みのひとつです。 トレイトは、単一継承の制約を減らすために作られたもので、 いくつかのメソッド群を異なるクラス階層にある独立したクラスで再利用できるようにします。 トレイトとクラスを組み合わせた構文は複雑さを軽減させてくれ、 多重継承や Mixin に関連するありがちな問題を回避することもできます。

トレイトはクラスと似ていますが、トレイトは単にいくつかの機能をまとめるためだけのものです。 トレイト自身のインスタンスを作成することはできません。 昔ながらの継承に機能を加えて、振る舞いを水平方向で構成できるようになります。 つまり、継承しなくてもクラスのメンバーに追加できるようになります。

例1 トレイトの例

<?php
trait ezcReflectionReturnInfo {
    function getReturnType() { /*1*/ }
    function getReturnDescription() { /*2*/ }
}

class ezcReflectionMethod extends ReflectionMethod {
    use ezcReflectionReturnInfo;
    /* ... */
}

class ezcReflectionFunction extends ReflectionFunction {
    use ezcReflectionReturnInfo;
    /* ... */
}
?>

優先順位

基底クラスから継承したメンバーよりも、トレイトで追加したメンバーのほうが優先されます。 優先順位は現在のクラスのメンバーが最高で、その次がトレイトのメソッド、 そしてその次にくるのが継承したメソッドとなります。

例2 優先順位の例

基底クラスから継承したメソッドは、MyHelloWorld に SayWorld トレイトから追加されたメソッドで上書きされます。 この挙動は、MyHelloWorld クラスで定義したメソッドでも同じです。 優先順位は現在のクラスのメンバーが最高で、その次がトレイトのメソッド、 そしてその次にくるのが継承したメソッドとなります。

<?php
class Base {
    public function sayHello() {
        echo 'Hello ';
    }
}

trait SayWorld {
    public function sayHello() {
        parent::sayHello();
        echo 'World!';
    }
}

class MyHelloWorld extends Base {
    use SayWorld;
}

$o = new MyHelloWorld();
$o->sayHello();
?>

上の例の出力は以下となります。

Hello World!

例3 もうひとつの優先順位の例

<?php
trait HelloWorld {
    public function sayHello() {
        echo 'Hello World!';
    }
}

class TheWorldIsNotEnough {
    use HelloWorld;
    public function sayHello() {
        echo 'Hello Universe!';
    }
}

$o = new TheWorldIsNotEnough();
$o->sayHello();
?>

上の例の出力は以下となります。

Hello Universe!

複数のトレイト

複数のトレイトをひとつのクラスに追加するには、use 文でカンマ区切りで指定します。

例4 複数のトレイトの使用例

<?php
trait Hello {
    public function sayHello() {
        echo 'Hello ';
    }
}

trait World {
    public function sayWorld() {
        echo 'World';
    }
}

class MyHelloWorld {
    use Hello, World;
    public function sayExclamationMark() {
        echo '!';
    }
}

$o = new MyHelloWorld();
$o->sayHello();
$o->sayWorld();
$o->sayExclamationMark();
?>

上の例の出力は以下となります。

Hello World!

衝突の解決

同じ名前のメンバーを含む複数のトレイトを追加するときには、 衝突を明示的に解決しておかないと fatal エラーが発生します。

同一クラス内での複数のトレイト間の名前の衝突を解決するには、 insteadof 演算子を使って そのうちのひとつを選ばなければなりません。

この方法はひとつのメソッドだけしか使えませんが、 as 演算子を使うと、 衝突するメソッドのいずれかを別の名前で含めることができます。

例5 衝突の解決

この例では、Talker がトレイト A と B を使います。 A と B には同じ名前のメソッドがあるので、 smallTalk はトレイト B を使って bigTalk はトレイト A を使うように定義します。

Aliased_Talker は、as 演算子を使って B の bigTalk の実装に talk というエイリアスを指定して使います。

<?php
trait A {
    public function smallTalk() {
        echo 'a';
    }
    public function bigTalk() {
        echo 'A';
    }
}

trait B {
    public function smallTalk() {
        echo 'b';
    }
    public function bigTalk() {
        echo 'B';
    }
}

class Talker {
    use A, B {
        B::smallTalk insteadof A;
        A::bigTalk insteadof B;
    }
}

class Aliased_Talker {
    use A, B {
        B::smallTalk insteadof A;
        A::bigTalk insteadof B;
        B::bigTalk as talk;
    }
}
?>

メソッドの可視性の変更

as 構文を使うと、 クラス内でのメソッドの可視性も変更することができます。

例6 メソッドの可視性の変更

<?php
trait HelloWorld {
    public function sayHello() {
        echo 'Hello World!';
    }
}

// sayHello の可視性を変更します
class MyClass1 {
    use HelloWorld { sayHello as protected; }
}

// 可視性を変更したエイリアスメソッドを作ります
// sayHello 自体の可視性は変わりません
class MyClass2 {
    use HelloWorld { sayHello as private myPrivateHello; }
}
?>

トレイトを組み合わせたトレイト

クラスからトレイトを使えるのと同様に、トレイトからもトレイトを使えます。 トレイトの定義の中でトレイトを使うと、 定義したトレイトのメンバーの全体あるいは一部を組み合わせることができます。

例7 トレイトを組み合わせたトレイト

<?php
trait Hello {
    public function sayHello() {
        echo 'Hello ';
    }
}

trait World {
    public function sayWorld() {
        echo 'World!';
    }
}

trait HelloWorld {
    use Hello, World;
}

class MyHelloWorld {
    use HelloWorld;
}

$o = new MyHelloWorld();
$o->sayHello();
$o->sayWorld();
?>

上の例の出力は以下となります。

Hello World!

トレイトのメンバーの抽象化

トレイトでは、抽象メソッドを使ってクラスの要件を指定できます。

例8 抽象メソッドによる、要件の明示

<?php
trait Hello {
    public function sayHelloWorld() {
        echo 'Hello'.$this->getWorld();
    }
    abstract public function getWorld();
}

class MyHelloWorld {
    private $world;
    use Hello;
    public function getWorld() {
        return $this->world;
    }
    public function setWorld($val) {
        $this->world = $val;
    }
}
?>

トレイトの静的なメンバー

静的な変数をトレイトのメソッド内で参照できますが、 トレイトがそれを定義することはできません。 しかしトレイトでは、クラス用の静的メソッドを定義することはできます。

例9 静的な変数

<?php
trait Counter {
    public function inc() {
        static $c = 0;
        $c = $c + 1;
        echo "$c\n";
    }
}

class C1 {
    use Counter;
}

class C2 {
    use Counter;
}

$o = new C1(); $o->inc(); // 1 と表示
$p = new C2(); $p->inc(); // 1 と表示
?>

例10 静的なメソッド

<?php
trait StaticExample {
    public static function doSomething() {
        return 'Doing something';
    }
}

class Example {
    use StaticExample;
}

Example::doSomething();
?>

プロパティ

トレイトにはプロパティも定義できます。

例11 プロパティの定義

<?php
trait PropertiesTrait {
    public $x = 1;
}

class PropertiesExample {
    use PropertiesTrait;
}

$example = new PropertiesExample;
$example->x;
?>

トレイトでプロパティを定義したときは、クラスでは同じ名前のプロパティを定義できません。 定義しようとすると、エラーが発生します。クラス側での定義がトレイトでの定義と互換性がある (可視性も初期値も同じ) 場合は E_STRICT、 それ以外の場合は fatal error となります。

例12 衝突の解決

<?php
trait PropertiesTrait {
    public $same = true;
    public $different = false;
}

class PropertiesExample {
    use PropertiesTrait;
    public $same = true; // Strict Standards
    public $different = true; // Fatal error
}
?>

オーバーロード

PHP におけるオーバーロード機能は、 プロパティやメソッドを動的に "作成する" ための手法です。 これらの動的エンティティは、マジックメソッドを用いて処理されます。 マジックメソッドは、クラス内でさまざまなアクションに対して用意することができます。

オーバーロードメソッドが起動するのは、 宣言されていないプロパティやメソッドを操作しようとしたときです。 また、現在のスコープからは アクセス不能な プロパティやメソッドを操作しようとしたときにも起動します。 このセクションでは、これらの (宣言されていない、 あるいは現在のスコープからはアクセス不能な) プロパティやメソッドのことを "アクセス不能プロパティ" および "アクセス不能メソッド" と表記することにします。

オーバーロードメソッドは、すべて public で定義しなければなりません。

注意:

これらのマジックメソッドの引数は、 参照渡し とすることはできません。

注意:

PHP における "オーバーロード" の解釈は、他の多くのオブジェクト指向言語とは異なります。 一般的に「オーバーロード」とは、 「名前は同じだけれども引数の数や型が異なるメソッドを複数用意できる」 という機能のことを指します。

変更履歴

バージョン 説明
5.3.0 __callStatic() が追加されました。 public で、かつ static でない宣言を強制するような警告が追加されました。
5.1.0 __isset() と __unset() が追加されました。

プロパティのオーバーロード

public void __set ( string $name , mixed $value )
public mixed __get ( string $name )
public bool __isset ( string $name )
public void __unset ( string $name )

__set() は、 アクセス不能プロパティへデータを書き込む際に実行されます。

__get() は、 アクセス不能プロパティからデータを読み込む際に使用します。

__isset() は、 isset() あるいは empty() をアクセス不能プロパティに対して実行したときに起動します。

__unset() は、 unset() をアクセス不能プロパティに対して実行したときに起動します。

引数 $name は、 操作しようとしたプロパティの名前です。 __set() メソッドの引数 $value は、 $name に設定しようとした値となります。

プロパティのオーバーロードはオブジェクトのコンテキストでのみ動作します。 これらのマジックメソッドは、静的コンテキストでは起動しません。 したがって、これらのメソッドを static 宣言してはいけません。 PHP 5.3.0 以降、マジックオーバーロードメソッドを static 宣言すると警告が発生します。

注意:

__set() の返り値は無視されます。 これは、PHP が代入演算子を処理する方法によるものです。 同様に __get() は、 

 $a = $obj->b = 8;
のように代入と連結した場合には決してコールされません。

注意:

オーバーロードされたプロパティを、 isset() 以外の言語構造の中で使うことはできません。 つまり、オーバーロードされたプロパティに対して empty() がコールされたとしても、オーバーロードされたメソッドはコールされないということです。

この制約を回避するには、オーバーロードされたプロパティを そのスコープのローカル変数にコピーしてから empty() に渡さなければなりません。

例1 __get()、 __set()、__isset() および __unset() メソッドを使ったプロパティのオーバーロードの例

<?php
class PropertyTest
{
    /**  オーバーロードされるデータの場所  */
    private $data = array();

    /**  宣言されているプロパティにはオーバーロードは起動しません */
    public $declared = 1;

    /**  クラスの外部からアクセスした場合にのみこれがオーバーロードされます  */
    private $hidden = 2;

    public function __set($name, $value)
    {
        echo "Setting '$name' to '$value'\n";
        $this->data[$name] = $value;
    }

    public function __get($name)
    {
        echo "Getting '$name'\n";
        if (array_key_exists($name, $this->data)) {
            return $this->data[$name];
        }

        $trace = debug_backtrace();
        trigger_error(
            'Undefined property via __get(): ' . $name .
            ' in ' . $trace[0]['file'] .
            ' on line ' . $trace[0]['line'],
            E_USER_NOTICE);
        return null;
    }

    /**  PHP 5.1.0 以降 */
    public function __isset($name)
    {
        echo "Is '$name' set?\n";
        return isset($this->data[$name]);
    }

    /**  PHP 5.1.0 以降 */
    public function __unset($name)
    {
        echo "Unsetting '$name'\n";
        unset($this->data[$name]);
    }

    /**  マジックメソッドではありません。単なる例として示しています  */
    public function getHidden()
    {
        return $this->hidden;
    }
}


echo "<pre>\n";

$obj = new PropertyTest;

$obj->a = 1;
echo $obj->a . "\n\n";

var_dump(isset($obj->a));
unset($obj->a);
var_dump(isset($obj->a));
echo "\n";

echo $obj->declared . "\n\n";

echo "Let's experiment with the private property named 'hidden':\n";
echo "Privates are visible inside the class, so __get() not used...\n";
echo $obj->getHidden() . "\n";
echo "Privates not visible outside of class, so __get() is used...\n";
echo $obj->hidden . "\n";
?>

上の例の出力は以下となります。

Setting 'a' to '1'
Getting 'a'
1

Is 'a' set?
bool(true)
Unsetting 'a'
Is 'a' set?
bool(false)

1

Let's experiment with the private property named 'hidden':
Privates are visible inside the class, so __get() not used...
2
Privates not visible outside of class, so __get() is used...
Getting 'hidden'


Notice:  Undefined property via __get(): hidden in <file> on line 70 in <file> on line 29

メソッドのオーバーロード

public mixed __call ( string $name , array $arguments )
public static mixed __callStatic ( string $name , array $arguments )

__call() は、 アクセス不能メソッドをオブジェクトのコンテキストで実行したときに起動します。

__callStatic() は、 アクセス不能メソッドを静的コンテキストで実行したときに起動します。

引数 $name は、 コールしようとしたメソッドの名前です。 引数 $arguments は配列で、メソッド $name に渡そうとしたパラメータが格納されます。

例2 __call() および __callStatic() メソッドによる、メソッドのオーバーロードの例

<?php
class MethodTest
{
    public function __call($name, $arguments)
    {
        // 注意: $name は大文字小文字を区別します
        echo "Calling object method '$name' "
             . implode(', ', $arguments). "\n";
    }

    /**  PHP 5.3.0 以降 */
    public static function __callStatic($name, $arguments)
    {
        // 注意: $name は大文字小文字を区別します
        echo "Calling static method '$name' "
             . implode(', ', $arguments). "\n";
    }
}

$obj = new MethodTest;
$obj->runTest('in object context');

MethodTest::runTest('in static context');  // PHP 5.3.0 以降
?>

上の例の出力は以下となります。

Calling object method 'runTest' in object context
Calling static method 'runTest' in static context

オブジェクトの反復処理

PHP 5 は、たとえば foreach 命令などによる反復処理を可能とするよう オブジェクトを定義する手段を提供します。 デフォルトで、 全ての アクセス権限がある プロパティは、反復処理に使用することができます。

例1 Simple Object Iteration

<?php
class MyClass
{
    public $var1 = 'value 1';
    public $var2 = 'value 2';
    public $var3 = 'value 3';

    protected $protected = 'protected var';
    private   $private   = 'private var';

    function iterateVisible() {
       echo "MyClass::iterateVisible:\n";
       foreach($this as $key => $value) {
           print "$key => $value\n";
       }
    }
}

$class = new MyClass();

foreach($class as $key => $value) {
    print "$key => $value\n";
}
echo "\n";


$class->iterateVisible();

?>

上の例の出力は以下となります。

var1 => value 1
var2 => value 2
var3 => value 3

MyClass::iterateVisible:
var1 => value 1
var2 => value 2
var3 => value 3
protected => protected var
private => private var

出力からわかるように、 foreach による反復処理がすべての アクセス権がある プロパティについて行われています。

さらに、Iterator インターフェイス も実装できます。 これを実装すれば、オブジェクトの反復処理の方法や処理中に取得できる値を決めることができます。

例2 Iteratorを実装するオブジェクトの反復処理

<?php
class MyIterator implements Iterator
{
    private $var = array();

    public function __construct($array)
    {
        if (is_array($array)) {
            $this->var = $array;
        }
    }

    public function rewind()
    {
        echo "rewinding\n";
        reset($this->var);
    }
  
    public function current()
    {
        $var = current($this->var);
        echo "current: $var\n";
        return $var;
    }
  
    public function key() 
    {
        $var = key($this->var);
        echo "key: $var\n";
        return $var;
    }
  
    public function next() 
    {
        $var = next($this->var);
        echo "next: $var\n";
        return $var;
    }
  
    public function valid()
    {
        $key = key($this->var);
        $var = ($key !== NULL && $key !== FALSE);
        echo "valid: $var\n";
        return $var;
    }

}

$values = array(1,2,3);
$it = new MyIterator($values);

foreach ($it as $a => $b) {
    print "$a: $b\n";
}
?>

上の例の出力は以下となります。

rewinding
valid: 1
current: 1
key: 0
0: 1
next: 2
valid: 1
current: 2
key: 1
1: 2
next: 3
valid: 1
current: 3
key: 2
2: 3
next:
valid:

Iterator のすべてのメソッドを実装するかわりに、 IteratorAggregate インターフェイス を使うこともできます。 IteratorAggregate で実装を要するメソッドは IteratorAggregate::getIterator() だけで、 このメソッドは Iterator を実装したクラスのインスタンスを返す必要があります。

例3 IteratorAggregateを実装するオブジェクトの反復処理

<?php
class MyCollection implements IteratorAggregate
{
    private $items = array();
    private $count = 0;

    // Required definition of interface IteratorAggregate
    public function getIterator() {
        return new MyIterator($this->items);
    }

    public function add($value) {
        $this->items[$this->count++] = $value;
    }
}

$coll = new MyCollection();
$coll->add('value 1');
$coll->add('value 2');
$coll->add('value 3');

foreach ($coll as $key => $val) {
    echo "key/value: [$key -> $val]\n\n";
}
?>

上の例の出力は以下となります。

rewinding
current: value 1
valid: 1
current: value 1
key: 0
key/value: [0 -> value 1]

next: value 2
current: value 2
valid: 1
current: value 2
key: 1
key/value: [1 -> value 2]

next: value 3
current: value 3
valid: 1
current: value 3
key: 2
key/value: [2 -> value 3]

next:
current:
valid:

注意:

より詳細なイタレータの例については、 SPL 拡張モジュール を参照ください。

マジックメソッド

以下の関数名 __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __sleep(), __wakeup(), __toString(), __invoke(), __set_state() および __clone() は、PHP クラスにおける特殊関数の名前です。 これらの関数に関連する特別な機能を使用する場合を除き、 クラス内にこれらの名前を有する関数を作成してはいけません。

警告

PHP は、__ で始まる関数名を特殊関数として予約しています。 文書化された特殊な機能を必要とする場合を除き、 __ で始まる関数名を使用しないことが推奨されます。

__sleep() と __wakeup()

public array __sleep ( void )
void __wakeup ( void )

serialize() は、クラスに特殊な名前 __sleep() の関数があるかどうかを調べます。 もしあれば、シリアル化の前にその関数を実行します。 この関数で、オブジェクトをクリアすることができます。 またこの関数は、シリアル化するオブジェクトについて、 すべての変数の名前を配列で返すことが前提となっています。 このメソッドが何も返さなかった場合は、NULL がシリアル化され、E_NOTICE が発生します。

注意:

__sleep() で、親クラスの private プロパティの名前を返すことはできません。 そうしようとすると E_NOTICE レベルのエラーとなります。 この場合は、かわりに Serializable インターフェイスを使います。

典型的な __sleep() の使用法は、 途中のデータをコミットしたり、 似たようなタスクのクリアを行うといったものです。 また、オブジェクトが非常に大きく、かつ、完全に保存する必要がない場合、 この関数が有用です。

逆に、unserialize() は、 特殊な名前 __wakeup() を有する 関数の存在を調べます。 もし存在する場合、この関数は、オブジェクトが有する可能性が あるあらゆるリソースを再構築することができます。

意図される __wakeup() の使用法は、 シリアル化の際に失われたデータベース接続を再度確立したり、 その他の再初期化を行うことです。

例1 Sleep および wakeup

<?php
class Connection
{
    protected $link;
    private $server, $username, $password, $db;
    
    public function __construct($server, $username, $password, $db)
    {
        $this->server = $server;
        $this->username = $username;
        $this->password = $password;
        $this->db = $db;
        $this->connect();
    }
    
    private function connect()
    {
        $this->link = mysql_connect($this->server, $this->username, $this->password);
        mysql_select_db($this->db, $this->link);
    }
    
    public function __sleep()
    {
        return array('server', 'username', 'password', 'db');
    }
    
    public function __wakeup()
    {
        $this->connect();
    }
}
?>

__toString()

public string __toString ( void )

__toString() メソッドにより、 クラスが文字列に変換される際の動作を決めることができます。たとえば echo $obj; としたときに何を表示させるかといったことです。 このメソッドは文字列を返さなければなりません。それ以外の場合は E_RECOVERABLE_ERROR レベルの致命的なエラーが発生します。

例2 簡単な例

<?php
// 簡単なクラスを宣言
class TestClass
{
    public $foo;

    public function __construct($foo)
    {
        $this->foo = $foo;
    }

    public function __toString()
    {
        return $this->foo;
    }
}

$class = new TestClass('Hello');
echo $class;
?>

上の例の出力は以下となります。

Hello

注意が必要なのは、PHP 5.2.0 より前では、 __toString() メソッドは echo または print と直接結合された場合のみコールされていたということです。 PHP 5.2.0 以降では、これはすべての文字列コンテキスト (たとえば printf() における %s 修飾子) でコールされます。しかし、その他の型のコンテキスト (たとえば %d 修飾子) ではコールされません。 PHP 5.2.0 以降では、__toString() メソッドを持っていないオブジェクトを文字列に変換しようとすると E_RECOVERABLE_ERROR が発生します。

__invoke()

mixed __invoke ([ $... ] )

__invoke() メソッドは、 スクリプトがオブジェクトを関数としてコールしようとした際にコールされます。

注意:

この機能は PHP 5.3.0 以降で使用可能です。

例3 __invoke() の使用

<?php
class CallableClass
{
    public function __invoke($x)
    {
        var_dump($x);
    }
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>

上の例の出力は以下となります。

int(5)
bool(true)

__set_state()

static object __set_state ( array $properties )

この static メソッドは、 PHP 5.1.0 以降で var_export() によって エクスポートされたクラスのためにコールされます。

このメソッドの唯一のパラメータは、エクスポートされたプロパティを array('property' => value, ...) の形式で保持する配列です。

例4 __set_state() の使用法 (PHP 5.1.0 以降)

<?php

class A
{
    public $var1;
    public $var2;

    public static function __set_state($an_array) // PHP 5.1.0 以降
    {
        $obj = new A;
        $obj->var1 = $an_array['var1'];
        $obj->var2 = $an_array['var2'];
        return $obj;
    }
}

$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';

eval('$b = ' . var_export($a, true) . ';'); // $b = A::__set_state(array(
                                            //    'var1' => 5,
                                            //    'var2' => 'foo',
                                            // ));
var_dump($b);

?>

上の例の出力は以下となります。

object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}

finalキーワード

PHP 5 ではキーワードfinalが導入され、 finalを前に付けて定義されたメソッドは子クラスから上書きできません。 クラス自体がfinalと定義された場合には、このクラスを拡張することはできません。

例1 finalメソッドの例

<?php
class BaseClass {
   public function test() {
       echo "BaseClass::test() called\n";
   }
   
   final public function moreTesting() {
       echo "BaseClass::moreTesting() called\n";
   }
}

class ChildClass extends BaseClass {
   public function moreTesting() {
       echo "ChildClass::moreTesting() called\n";
   }
}
// Results in Fatal error: Cannot override final method BaseClass::moreTesting()
?>

例2 finalクラスの例

<?php
final class BaseClass {
   public function test() {
       echo "BaseClass::test() called\n";
   }

   // Here it doesn't matter if you specify the function as final or not
   final public function moreTesting() {
       echo "BaseClass::moreTesting() called\n";
   }
}

class ChildClass extends BaseClass {
}
// Results in Fatal error: Class ChildClass may not inherit from final class (BaseClass)
?>

注意: プロパティを final として宣言することはできません。 final として宣言できるのはクラスとメソッドのみです。

オブジェクトのクローン作成

オブジェクトのコピーを作成する際、そのプロパティも全て二重化することが、 常に望ましい動作であるわけではありません。 コピーコンストラクタが必要となる例として、 GTKウインドウを表すオブジェクトを有しており、 そのオブジェクトがGTKウインドウのリソースを保持している際、 コピーを作成する時に、同じプロパティを有するウインドウを作成し、 その新しいオブジェクトがその新しいウインドウのリソースを保持する ようにしたい場合が考えられます。 他の例としては、 オブジェクトがそのオブジェクトが使用する他のオブジェクトへのリファレンスを 保持しており、親オブジェクトをコピーする際に、そのコピーが独立したオブジェクトの コピーを有するように、そのオブジェクトのインスタンスを新たに作成したい場合が 考えられます。

オブジェクトのコピーは、clone キーワード (これは、そのオブジェクトの __clone() メソッドがある場合にこれをコールします)により作成されます。 オブジェクトの __clone() メソッドを直接コールすることはできません。 

$copy_of_object = clone $object;

オブジェクトのクローンが作成される際、PHP 5 は、そのオブジェクトのプロパティを 全てシャローコピーします。他の変数へのリファレンスを保持する全てのプロパティは、 リファレンスのままとなります。

void __clone ( void )

クローンの作成が完了すると、 __clone() メソッドが定義された場合、新規の作成されたオブジェクトの __clone() メソッドがコールされるため、この中で、プロパティに 必要な変更を行うことができます。

例1 オブジェクトのクローン作成

<?php
class SubObject
{
    static $instances = 0;
    public $instance;

    public function __construct() {
        $this->instance = ++self::$instances;
    }

    public function __clone() {
        $this->instance = ++self::$instances;
    }
}

class MyCloneable
{
    public $object1;
    public $object2;

    function __clone()
    {
        // this->object のコピーを作成します。こうしないと、
        // 同じオブジェクトを指すことになってしまいます。
        $this->object1 = clone $this->object1;
    }
}

$obj = new MyCloneable();

$obj->object1 = new SubObject();
$obj->object2 = new SubObject();

$obj2 = clone $obj;


print("元のオブジェクト\n");
print_r($obj);

print("クローンオブジェクト\n");
print_r($obj2);

?>

上の例の出力は以下となります。

元のオブジェクト
MyCloneable Object
(
    [object1] => SubObject Object
        (
            [instance] => 1
        )

    [object2] => SubObject Object
        (
            [instance] => 2
        )

)
クローンオブジェクト
MyCloneable Object
(
    [object1] => SubObject Object
        (
            [instance] => 3
        )

    [object2] => SubObject Object
        (
            [instance] => 2
        )

)

オブジェクトの比較

PHP 5では、オブジェクトの比較は、オブジェクト指向言語に期待される動作に対応し、 PHP 4よりも複雑になっています。(ただし、PHP 5はオブジェクト指向言語ではありません。)

比較演算子(==)を使用する際、 オブジェクト変数は、単純に比較されます。つまり、 二つのオブジェクトのインスタンスは、 同じ属性と値を有し、同じクラスのインスタンスである場合に、 等しいとされます。

一方、一致演算子(===)を使用する場合、 オブジェクト変数は、同じクラスの同じインスタンスを参照する場合のみ、 等しいとされます。

これらのルールを明確に示す例を以下に示します。

例1 PHP 5におけるオブジェクト比較の例

<?php
function bool2str($bool)
{
    if ($bool === false) {
        return 'FALSE';
    } else {
        return 'TRUE';
    }
}

function compareObjects(&$o1, &$o2)
{
    echo 'o1 == o2 : ' . bool2str($o1 == $o2) . "\n";
    echo 'o1 != o2 : ' . bool2str($o1 != $o2) . "\n";
    echo 'o1 === o2 : ' . bool2str($o1 === $o2) . "\n";
    echo 'o1 !== o2 : ' . bool2str($o1 !== $o2) . "\n";
}

class Flag
{
    public $flag;

    function Flag($flag = true) {
        $this->flag = $flag;
    }
}

class OtherFlag
{
    public $flag;

    function OtherFlag($flag = true) {
        $this->flag = $flag;
    }
}

$o = new Flag();
$p = new Flag();
$q = $o;
$r = new OtherFlag();

echo "同一クラスの2つのインスタンス\n";
compareObjects($o, $p);

echo "\n同じインスタンスへの2つのリファレンス\n";
compareObjects($o, $q);

echo "\n2つの異なるクラスのインスタンス\n";
compareObjects($o, $r);
?>

上の例の出力は以下となります。


同一クラスの2つのインスタンス
o1 == o2 : TRUE
o1 != o2 : FALSE
o1 === o2 : FALSE
o1 !== o2 : TRUE

同じインスタンスへの2つのリファレンス
o1 == o2 : TRUE
o1 != o2 : FALSE
o1 === o2 : TRUE
o1 !== o2 : FALSE

2つの異なるクラスのインスタンス
o1 == o2 : FALSE
o1 != o2 : TRUE
o1 === o2 : FALSE
o1 !== o2 : TRUE

注意:

拡張モジュール内では、自前で作成したオブジェクトの比較方法を独自に定義することができます。

タイプヒンティング

PHP 5では、タイプヒンティング(Type Hinting)が導入されました。 これにより、関数は、 (クラスの名前を関数プロトタイプの中に指定することにより) パラメータをオブジェクトもしくはインターフェイス、配列 (PHP 5.1 以降)、callable (PHP 5.4 以降) を必ず指定させることができるようになりました。 しかし、デフォルトのパラメータの値として NULL を使用した場合は、後から任意の値を引数に指定できるようになります。

タイプヒントでクラスやインターフェイスを指定した場合、 その子クラスや実装クラスも利用できます。

タイプヒントは int や string といったスカラー型には使えません。 また、トレイト も使えません。

例1 タイプヒンティングの例

<?php
// とあるクラス
class MyClass
{
    /**
     * テスト関数
     *
     * 第 1 引数は OtherClass 型のオブジェクトでなければならない
     */
    public function test(OtherClass $otherclass) {
        echo $otherclass->var;
    }


    /**
     * もう一つのテスト関数
     *
     * 第 1 引数は配列でなければならない
     */
    public function test_array(array $input_array) {
        print_r($input_array);
    }
    
    /**
     * 第 1 引数はイテレータでなければならない
     */
    public function test_interface(Traversable $iterator) {
        echo get_class($iterator);
    }
    
    /**
     * 第 1 引数は callable でなければならない
     */
    public function test_callable(callable $callback, $data) {
        call_user_func($callback, $data);
    }
}

// もう一つのサンプルクラス
class OtherClass {
    public $var = 'Hello World';
}
?>

タイプヒントの指定を満たさないとキャッチ可能な致命的エラーとなります。

<?php
// それぞれのクラスのインスタンス
$myclass = new MyClass;
$otherclass = new OtherClass;

// Fatal Error: Argument 1 must be an object of class OtherClass
$myclass->test('hello');

// Fatal Error: Argument 1 must be an instance of OtherClass
$foo = new stdClass;
$myclass->test($foo);

// Fatal Error: Argument 1 must not be null
$myclass->test(null);

// Works: Prints Hello World
$myclass->test($otherclass);

// Fatal Error: Argument 1 must be an array
$myclass->test_array('a string');

// 動作する: 配列の内容を表示する
$myclass->test_array(array('a', 'b', 'c'));

// 動作する: ArrayObject を表示する
$myclass->test_interface(new ArrayObject(array()));

// 動作する: int(1) を表示する
$myclass->test_callable('var_dump', 1);
?>

タイプヒンティングは、関数でも使用できます。

<?php
// とあるクラス
class MyClass {
    public $var = 'Hello World';
}

/**
 * テスト関数
 *
 * 第 1 引数は MyClass 型のオブジェクトでなければならない
 */
function myFunction(MyClass $foo) {
    echo $foo->var;
}

// 動作する
$myclass = new MyClass;
myFunction($myclass);
?>

タイプヒントには NULL 値を使用することもできます。

<?php

/* NULL 値も使えます */
function test(stdClass $obj = NULL) {

}

test(NULL);
test(new stdClass);

?>

遅延静的束縛 (Late Static Bindings)

PHP 5.3.0 以降、PHP に遅延静的束縛と呼ばれる機能が搭載されます。 これを使用すると、静的継承のコンテキストで呼び出し元のクラスを参照できるようになります。

より正確に言うと、静的遅延束縛は直近の "非転送コール" のクラス名を保存します。 静的メソッドの場合、これは明示的に指定されたクラス (通常は :: 演算子の左側に書かれたもの) となります。静的メソッド以外の場合は、そのオブジェクトのクラスとなります。 "転送コール" とは、self:: や parent::、static:: による静的なコール、 あるいはクラス階層の中での forward_static_call() によるコールのことです。 get_called_class() 関数を使うとコール元のクラス名を文字列で取得できます。 static:: はこのクラスのスコープとなります。

この "遅延静的束縛" という機能名は、内部動作を考慮してつけられたものです。 "遅延束縛 (Late binding)" の由来は、メソッドを定義しているクラス名を使用しても static:: の解決ができないことによります。 その代わりに、実行時情報をもとに解決するようになります。 "静的束縛 (static binding)" の由来は、 静的メソッドのコールに使用できることによります (ただし、静的メソッド以外でも使用可能です)。

self:: の制限

self:: あるいは __CLASS__ による現在のクラスへの静的参照は、 そのメソッドが属するクラス (つまり、 そのメソッドが定義されているクラス) に解決されます。

例1 self:: の使用例

<?php
class A {
    public static function who() {
        echo __CLASS__;
    }
    public static function test() {
        self::who();
    }
}

class B extends A {
    public static function who() {
        echo __CLASS__;
    }
}

B::test();
?>

上の例の出力は以下となります。

A

遅延静的束縛の使用法

遅延静的束縛は、この制限を解決するためのキーワードを導入し、 実行時に最初にコールされたクラスを参照するようにしています。 このキーワードを使用すると、先ほどの例における test() から B を参照できるようになります。 このキーワードは新たに追加したものではなく、すでに予約済みである static を使用しています。

例2 static:: のシンプルな使用法

<?php
class A {
    public static function who() {
        echo __CLASS__;
    }
    public static function test() {
        static::who(); // これで、遅延静的束縛が行われます
    }
}

class B extends A {
    public static function who() {
        echo __CLASS__;
    }
}

B::test();
?>

上の例の出力は以下となります。

B

注意:

静的でないコンテキストでは、呼び出されるクラスはそのオブジェクトのクラスと同じになります。 $this-> は private メソッドを同じスコープからコールしようとするので、 static:: を使うと異なる結果となります。もうひとつの相違点は、 static:: は静的なプロパティしか参照できないということです。

例3 非静的コンテキストにおける static:: の使用法

<?php
class A {
    private function foo() {
        echo "success!\n";
    }
    public function test() {
        $this->foo();
        static::foo();
    }
}

class B extends A {
   /* foo() が B にコピーされるので、メソッドのスコープは A のままとなり、
    * コールは成功します */
}

class C extends A {
    private function foo() {
        /* もとのメソッドが置き換えられるので、新しいメソッドのスコープは C となります */
    }
}

$b = new B();
$b->test();
$c = new C();
$c->test();   //fails
?>

上の例の出力は以下となります。

success!
success!
success!


Fatal error:  Call to private method C::foo() from context 'A' in /tmp/test.php on line 9

注意:

遅延静的束縛の解決は、静的コールが代替なしに完全に解決された時点で終了します。 一方、parent:: や self:: といったキーワードを使用する静的コールは、コール元の情報を転送します。

例4 転送するコールと転送しないコール

<?php
class A {
    public static function foo() {
        static::who();
    }

    public static function who() {
        echo __CLASS__."\n";
    }
}

class B extends A {
    public static function test() {
        A::foo();
        parent::foo();
        self::foo();
    }

    public static function who() {
        echo __CLASS__."\n";
    }
}
class C extends B {
    public static function who() {
        echo __CLASS__."\n";
    }
}

C::test();
?>

上の例の出力は以下となります。

A
C
C

オブジェクトと参照

PHP 5 でのオブジェクト指向プログラミングのポイントとしてよく言われるのは 「オブジェクトはデフォルトでは参照渡しとなります」ということです。 しかし、正確には少し異なります。 この節では、いくつかの例を用いてその誤解をといていきます。

PHP の参照は一種のエイリアスで、ふたつの異なる変数に同じ値を書き込めるものです。 PHP 5 以降、オブジェクト変数の値にオブジェクト自身は含まれなくなりました。 含まれるのはオブジェクトの ID のみで、 これを用いて実際のオブジェクトにアクセスできるようになっています。 オブジェクトが引数として渡されたり返り値となったり あるいは別の変数に代入されたりした場合、 それはエイリアスではありません。ID のコピーを保持し、 同じオブジェクトを指すようになるのです。

例1 参照とオブジェクト

<?php
class A {
    public $foo = 1;
}  

$a = new A;
$b = $a;     // $a と $b は同じ ID を持つコピーです
             // ($a) = ($b) = <id>
$b->foo = 2;
echo $a->foo."\n";


$c = new A;
$d = &$c;    // $c と $d は参照です
             // ($c,$d) = <id>

$d->foo = 2;
echo $c->foo."\n";


$e = new A;

function foo($obj) {
    // ($obj) = ($e) = <id>
    $obj->foo = 2;
}

foo($e);
echo $e->foo."\n";

?>

上の例の出力は以下となります。

2
2
2

オブジェクトのシリアライズ

オブジェクトのシリアライズ - セッション内でのオブジェクト

serialize() は、 PHP で保存できるあらゆる値をバイトストリームで表した文字列を返します。 unserialize() を使うと、 この文字列から元の変数の値を取り出すことができます。 オブジェクトをシリアライズすると、オブジェクト内の変数もすべて保存されます。 オブジェクト内のメソッドは保存されません。 クラス名のみが保存されます。

オブジェクトを unserialize() するには、 そのオブジェクトのクラスが定義されている必要があります。 A クラスのオブジェクトをシリアライズしたのなら、 その文字列にはクラス A とその中のすべての変数の値が含まれています。 別のファイルでそれを復元してクラス A のオブジェクトを取り出すには、 まずそのファイル内にクラス A の定義が存在しなければなりません。 これを実現するには、たとえばクラス A の定義を別ファイルに書き出してそれを include したり spl_autoload_register() 関数を使ったりします。

<?php
// classa.inc:
  
  class A {
      public $one = 1;
    
      public function show_one() {
          echo $this->one;
      }
  }
  
// page1.php:

  include("classa.inc");
  
  $a = new A;
  $s = serialize($a);
  // $s を、page2.php からみつけられるどこかに書き出します
  file_put_contents('store', $s);

// page2.php:
  
  // シリアライズした文字列を復元するには、これが必要です
  include("classa.inc");

  $s = file_get_contents('store');
  $a = unserialize($s);

  // これで、$a オブジェクトの show_one() が使えるようになりました
  $a->show_one();
?>

セッションを使っているアプリケーションで session_register() を使ってオブジェクトを登録した場合は、 PHP のページの終了時にオブジェクトが自動的にシリアライズされます。 そして、次のページが始まるときに自動的にそれが復元されるのです。 これによって、いちどセッションに登録したオブジェクトは アプリケーションのどのページでも使えるようになります。 しかし session_register() 関数は PHP 5.4.0 で削除されます。

アプリケーション内でオブジェクトをシリアライズして再利用する場合のお勧めは、 そのクラスの定義をアプリケーション全体で include することです。 クラスの定義が存在しなければオブジェクトの復元に失敗してしまいます。 その場合、PHP は __PHP_Incomplete_Class_Name クラスのオブジェクトを返します。このオブジェクトにはメソッドは一切なく、 使い道がなくなってしまいます。

つまり、もし上の例の $a を session_register("a") でセッションに格納するなら、 page1.php と page2.php だけではなく すべてのページで classa.inc を include しなければなりません。

変更履歴

PHP 5 の OOP モデルの変更履歴をここに記録します。 個々の機能の説明や注意点については、クラスとオブジェクトに関するドキュメントを参照ください。

バージョン 説明
5.4.0 変更: 抽象クラスでコンストラクタのシグネチャを定義している場合は、 そのシグネチャに従うことが必須となりました。
5.3.3 変更: 名前空間 つきのクラス名の最後の部分と同じ名前のメソッドは、コンストラクタ とはみなされなくなりました。 名前空間を使っていないクラスは今までと変わりません。
5.3.0 変更: プロトタイプでデフォルト値を指定したメソッドをもつインターフェイスを 実装したクラスを作るときに、実装側でのデフォルト値を インターフェイスのデフォルト値と一致させなくてもよくなりました。
5.3.0 変更: 変数を使ってクラスを参照することができるようになりました (例: echo $classname::constant;)。 この変数の値に、キーワード (self や parent、static など) を使うことはできません。
5.3.0 変更: オーバーロード メソッドが static 宣言されている場合に E_WARNING レベルのエラーが発生するようになりました。 また、public 宣言することが必須となりました。
5.3.0 変更: 5.3.0 より前のバージョンでは、 __autoload() 関数の中で発生した例外を catch ブロックで捕捉することができず、 致命的なエラーとなっていました。このバージョンからは __autoload 関数内で発生した例外を catch ブロックで捕捉できるようになりましたが、ひとつ条件があります。 独自の例外クラスをスローする場合は、その例外クラスが使用可能でなければなりません。 __autoload 関数は、再帰的に呼び出されて独自の例外クラスを読み込もうとする可能性があります。
5.3.0 追加: __callStatic メソッド。
5.3.0 追加: ヒアドキュメント および nowdoc の、クラス定数やプロパティの定義での使用。 注意: ヒアドキュメントの値は、ダブルクォートで囲んだ文字列と同じ規則に従わなければなりません (その中で変数を使えないなど)。
5.3.0 追加: 遅延静的束縛。
5.3.0 追加: __invoke() メソッド。
5.2.0 変更: __toString() メソッドがコールされるのは echo や print と直接組み合わせて使った場合のみでした。このバージョンからは、任意の文字列コンテキスト (printf() で %s 修飾子を使った場合など) でコールされるようになりました。ただし、他の型のコンテキスト (%d 修飾子を使った場合など) は除きます。 PHP 5.2.0 以降は、__toString メソッドを持たないオブジェクトを文字列に変換しようとすると E_RECOVERABLE_ERROR レベルのエラーが発生します。
5.1.3 変更: PHP 5 の初期のバージョンでは var を使うことが非推奨とされており、E_STRICT レベルのエラーが発生していました。 このバージョンからは非推奨ではなくなり、エラーが発生しなくなりました。
5.1.0 変更: __set_state() メソッドが、 var_export() でエクスポートしたクラスに対してもコールされるようになりました。
5.1.0 追加: __isset() メソッドおよび __unset() メソッド。

名前空間

目次

名前空間の概要

(PHP 5 >= 5.3.0)

名前空間とは何でしょう? 広義の「名前空間」とは、項目をカプセル化するもののことです。 これは多くの場面で見られる抽象概念です。 たとえば、たいていの OS はディレクトリでファイルをグループ化します。 この場合、ディレクトリがその中のファイルの名前空間として機能しています。 具体的に言うと、foo.txt というファイルは /home/greg と /home/other の両方に存在することが可能ですが、それらふたつの foo.txt を同じディレクトリに配置することはできません。 さらに、/home/greg ディレクトリの外から foo.txt にアクセスするには、ディレクトリ名をファイル名の前につけて /home/greg/foo.txt としなければなりません。 プログラミングの世界における名前空間も、この延長線上にあります。

PHP の世界では、名前空間は次のふたつの問題を解決するための手段として用意されています。 ライブラリやアプリケーションの作者が、 クラスや関数といった再利用可能なコード部品を作ろうとするときにこれらの問題にぶちあたることになります。

  1. あなたが作成したコードと PHP の組み込みのクラス/関数/定数 あるいはサードパーティのクラス/関数/定数の名前が衝突する
  2. 最初の問題を解決するためには、Extra_Long_Names のような長い名前をつけなければならない

PHP の名前空間は、関連するクラスやインターフェイス、関数、そして定数をひとまとめにして扱うものです。 PHP の名前空間構文の例を見てみましょう。

例1 名前空間構文の例

<?php
namespace my\name; // "名前空間の定義" を参照ください

class MyClass {}
function myfunction() {}
const MYCONST = 1;

$a = new MyClass;
$c = new \my\name\MyClass; // "グローバル空間" を参照ください

$a = strlen('hi'); // "名前空間の使用法: グローバル関数/定数への
                   // 移行" を参照ください

$d = namespace\MYCONST; // "namespace 演算子および __NAMESPACE__ 定数"
                        // を参照ください
$d = __NAMESPACE__ . '\MYCONST';
echo constant($d); // "名前空間および動的言語機能" を参照ください
?>

注意:

名前空間の名前として PHP や php は使えません。これらで始まる名前 (PHP\Classes など) も同様です。 これらの名前は言語の内部で使うために予約されており、ユーザーのコードで使うことはできません。

名前空間の定義

(PHP 5 >= 5.3.0)

PHP のコードならなんでも名前空間に含めることができますが、 実際に名前空間の影響を受けるのはクラスとインターフェイス、関数、そして定数の 4 種類だけです。

名前空間を宣言するには、キーワード namespace を使用します。名前空間を含むファイルでは、他のコードより前にファイルの先頭で名前空間を宣言しなければなりません。 ただし declare キーワードは例外です。

例1 名前空間の宣言

<?php
namespace MyProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }

?>
名前空間の宣言より前に書くことが許されているコードは declare 文のみです。ソースファイルのエンコーディングを定義するために使用します。 さらに、PHP コード以外であっても名前空間の宣言の前に記述することはできません (スペースも同様です)。

例2 名前空間の宣言

<html>
<?php
namespace MyProject; // fatal error - namespace must be the first statement in the script
?>

さらに、他の PHP の制御構造とは異なり、同一の名前空間を複数のファイルで定義することができます。 これにより、ひとつの名前空間の内容をファイルシステム上で分割することができます。

サブ名前空間の宣言

(PHP 5 >= 5.3.0)

ディレクトリやファイルと同様、PHP の名前空間においても名前空間の階層構造を指定することができます。 このようにして名前空間を定義します。

例1 階層つきの名前空間の宣言

<?php
namespace MyProject\Sub\Level;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }

?>
上の例は、定数 MyProject\Sub\Level\CONNECT_OK とクラス MyProject\Sub\Level\Connection、 そして関数 MyProject\Sub\Level\connect を作成します。

同一ファイル内での複数の名前空間の定義

(PHP 5 >= 5.3.0)

複数の名前空間を同一ファイル内で宣言することもあります。 この場合の構文は次の 2 通りです。

例1 シンプルな組み合わせ方式による複数の名前空間の宣言

<?php
namespace MyProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }

namespace AnotherProject;

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
?>

この構文は、複数の名前空間をひとつのファイルに含める場合の方法としてはお勧めしません。 かわりに、次の波括弧構文を使うことを推奨します。

例2 波括弧構文による複数の名前空間の宣言

<?php
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace AnotherProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}
?>

ただ、複数の名前空間をひとつのファイルに記述するようなコーディングはできるだけ避けるべきです。 主な使い道としては、複数の PHP スクリプトをひとつのファイルにまとめるときくらいでしょう。

名前空間に属さないグローバルなコードを名前空間つきのコードと組み合わせるときには、 波括弧構文しか使用できません。グローバルなコードは、名前空間の名前を指定しない namespace 文で囲みます。たとえば次のようになります。

例3 複数の名前空間および名前空間に属さないコードの宣言

<?php
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace { // グローバルコード
session_start();
$a = MyProject\connect();
echo MyProject\Connection::start();
}
?>

namespace の波括弧の外側に書くことができる PHP コードは、最初の declare 文だけです。

例4 複数の名前空間および名前空間に属さないコードの宣言

<?php
declare(encoding='UTF-8');
namespace MyProject {

const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */  }
}

namespace { // global code
session_start();
$a = MyProject\connect();
echo MyProject\Connection::start();
}
?>

名前空間の使用法: 基本編

(PHP 5 >= 5.3.0)

名前空間の使い方についてあれこれ言う前に、まずは PHP がどのようにしてコード中の要素の名前空間を知るのかを理解しておくことが重要です。 PHP の名前空間は、ファイルシステムにたとえて考えることができます。 たとえば、ファイルシステム内のファイルにアクセスするには次の 3 つの方法があります。

  1. foo.txt のような相対ファイル名を使う。これは currentdirectory/foo.txt と解釈されます。ここで、 currentdirectory は現在いるディレクトリを表します。したがって、カレントディレクトリが /home/foo であった場合はこれは /home/foo/foo.txt となります。
  2. subdirectory/foo.txt のような相対パス名を使う。これは currentdirectory/subdirectory/foo.txt と解釈されます。
  3. /main/foo.txt のような絶対パス名を使う。これは /main/foo.txt と解釈されます。
PHP の名前空間内の要素についても同じ理屈があてはまります。 たとえば、クラス名を参照するには次の 3 つの方法があります。
  1. $a = new foo(); あるいは foo::staticmethod(); のような非修飾名 あるいはプレフィックスなしのクラス名。 現在の名前空間が currentnamespace である場合、これは currentnamespace\foo と解釈されます。 名前空間に属さないグローバルなコードにおいては、これは foo と解釈されます。 注意: 修飾されていない関数や定数は、名前空間内にその関数や定数がなければ グローバルな関数あるいは変数とみなされます。詳細は 名前空間の使用法: グローバルな関数/定数への移行 を参照ください。
  2. $a = new subnamespace\foo(); あるいは subnamespace\foo::staticmethod(); のような修飾名 あるいはプレフィックスつきクラス名。 現在の名前空間が currentnamespace である場合、これは currentnamespace\subnamespace\foo と解釈されます。 名前空間に属さないグローバルなコードにおいては、これは subnamespace\foo と解釈されます。
  3. $a = new \currentnamespace\foo(); あるいは \currentnamespace\foo::staticmethod(); のような完全修飾名 あるいはグローバルプレフィックス演算子つきのクラス名。 これは、常にコードで記述されたとおりの名前である currentnamespace\foo と解釈されます。

これら 3 つの構文を実際のコードで使う例を次に示します。

file1.php

<?php
namespace Foo\Bar\subnamespace;

const FOO = 1;
function foo() {}
class foo
{
    static function staticmethod() {}
}
?>

file2.php

<?php
namespace Foo\Bar;
include 'file1.php';

const FOO = 2;
function foo() {}
class foo
{
    static function staticmethod() {}
}

/* 非修飾名 */
foo(); // Foo\Bar\foo 関数と解釈されます
foo::staticmethod(); // Foo\Bar\foo クラスの staticmethod メソッドと解釈されます
echo FOO; // 定数 Foo\Bar\FOO と解釈されます

/* 修飾名 */
subnamespace\foo(); // Foo\Bar\subnamespace\foo 関数と解釈されます
subnamespace\foo::staticmethod(); // Foo\Bar\subnamespace\foo クラスの
                                  // staticmethod メソッドと解釈されます
echo subnamespace\FOO; // 定数 Foo\Bar\subnamespace\FOO と解釈されます
                                  
/* 完全修飾名 */
\Foo\Bar\foo(); // Foo\Bar\foo 関数と解釈されます
\Foo\Bar\foo::staticmethod(); // Foo\Bar\foo クラスの staticmethod メソッドと解釈されます
echo \Foo\Bar\FOO; // 定数 Foo\Bar\FOO と解釈されます
?>

グローバルなクラス、関数あるいは定数にアクセスするには、完全修飾名を使用して \strlen()、\Exception あるいは \INI_ALL などとすることができます。

例1 グローバルなクラス、関数および定数への名前空間内からのアクセス

<?php
namespace Foo;

function strlen() {}
const INI_ALL = 3;
class Exception {}

$a = \strlen('hi'); // グローバル関数 strlen をコールします
$b = \INI_ALL; // グローバル定数 INI_ALL にアクセスします
$c = new \Exception('error'); // グローバルクラス Exception のインスタンスを作成します
?>

名前空間と動的言語機能

(PHP 5 >= 5.3.0)

PHP における名前空間の実装は、PHP 自身が動的プログラミング言語であるという性質に影響を受けています。 したがって、次の例のようなコードを名前空間を使って書き直すには

例1 要素への動的なアクセス

example1.php:

<?php
class classname
{
    function __construct()
    {
        echo __METHOD__,"\n";
    }
}
function funcname()
{
    echo __FUNCTION__,"\n";
}
const constname = "global";

$a = 'classname';
$obj = new $a; // classname::__construct と表示します
$b = 'funcname';
$b(); // funcname と表示します
echo constant('constname'), "\n"; // global と表示します
?>
完全修飾名 (クラス名に名前空間プレフィックスをつけたもの) を使う必要があります。 動的なクラス名、関数名あるいは定数名においては修飾名と完全修飾名に差はないので、 先頭のバックスラッシュはなくてもかまいません。

例2 名前空間つき要素への動的なアクセス

<?php
namespace namespacename;
class classname
{
    function __construct()
    {
        echo __METHOD__,"\n";
    }
}
function funcname()
{
    echo __FUNCTION__,"\n";
}
const constname = "namespaced";

include 'example1.php';

$a = 'classname';
$obj = new $a; // classname::__construct と表示します
$b = 'funcname';
$b(); // funcname と表示します
echo constant('constname'), "\n"; // global と表示します

/* ダブルクォートを使う場合は "\\namespacename\\classname" としなければなりません */
$a = '\namespacename\classname';
$obj = new $a; // namespacename\classname::__construct と表示します
$a = 'namespacename\classname';
$obj = new $a; // これも namespacename\classname::__construct と表示します
$b = 'namespacename\funcname';
$b(); // namespacename\funcname と表示します
$b = '\namespacename\funcname';
$b(); // これも namespacename\funcname と表示します
echo constant('\namespacename\constname'), "\n"; // namespaced と表示します
echo constant('namespacename\constname'), "\n"; // これも namespaced と表示します
?>

文字列中の名前空間名のエスケープに関する注意 を読んでおくことを忘れないようにしましょう。

namespace キーワードおよび __NAMESPACE__ 定数

(PHP 5 >= 5.3.0)

PHP には、現在の名前空間内の要素へのアクセスを抽象化するための方法が 2 通りあります。 マジック定数 __NAMESPACE__ および namespace キーワードがそれです。

__NAMESPACE__ の値は文字列で、現在の名前空間の名前が格納されます。 名前空間に属さないグローバルなコードでは、この中身は空文字列となります。

例1 名前空間内のコードでの __NAMESPACE__ の例

<?php
namespace MyProject;

echo '"', __NAMESPACE__, '"'; // "MyProject" と出力します
?>

例2 グローバルなコードでの __NAMESPACE__ の例

<?php

echo '"', __NAMESPACE__, '"'; // "" と出力します
?>
__NAMESPACE__ 定数は、動的に名前を作成する場合に便利です。 たとえば次のようになります。

例3 __NAMESPACE__ による動的な名前の作成

<?php
namespace MyProject;

function get($classname)
{
    $a = __NAMESPACE__ . '\\' . $classname;
    return new $a;
}
?>

namespace キーワードを使用すると、 現在の名前空間あるいはサブ名前空間内の要素を明示的に指定することができます。 これは、クラスにおける self 演算子と同じ意味合いのものです。

例4 名前空間内での namespace 演算子

<?php
namespace MyProject;

use blah\blah as mine; // "名前空間の使用法: インポート/エイリアス" を参照ください

blah\mine(); // MyProject\blah\mine() 関数をコールします
namespace\blah\mine(); // MyProject\blah\mine() 関数をコールします

namespace\func(); // MyProject\func() 関数をコールします
namespace\sub\func(); // MyProject\sub\func() 関数をコールします
namespace\cname::method(); // MyProject\cname クラスの静的メソッド "method" をコールします
$a = new namespace\sub\cname(); // MyProject\sub\cname クラスのオブジェクトのインスタンスを作成します
$b = namespace\CONSTANT; // 定数 MyProject\CONSTANT の値を $b に代入します
?>

例5 グローバルコードでの namespace 演算子

<?php

namespace\func(); // func() 関数をコールします
namespace\sub\func(); // sub\func() 関数をコールします
namespace\cname::method(); // cname クラスの静的メソッド "method" をコールします
$a = new namespace\sub\cname(); // sub\cname クラスのオブジェクトのインスタンスを作成します
$b = namespace\CONSTANT; // 定数 CONSTANT の値を $b に代入します
?>

名前空間の使用法: エイリアス/インポート

(PHP 5 >= 5.3.0)

外部の完全修飾名をエイリアスで参照したりインポートしたりする機能は、 名前空間において非常に重要なものです。 これは、Unix 系のファイルシステムでファイルやディレクトリへのシンボリックリンクを作成することに似ています。

PHP の名前空間では、3 通りの方法でエイリアスやインポートをサポートしています。 クラス名のエイリアスを作成する方法、インターフェイス名のエイリアスを作成する方法、 そして名前空間名のエイリアスを作成する方法です。 関数や定数のインポートはサポートしていないことに注意しましょう。

PHP でのエイリアス作成には use 演算子を使用します。 ここに、3 種類すべてのインポート方法の例を示します。

例1 use 演算子によるインポート/エイリアス

<?php
namespace foo;
use My\Full\Classname as Another;

// これは use My\Full\NSname as NSname と同じです
use My\Full\NSname;

// グローバルクラスをインポートします
use ArrayObject;

$obj = new namespace\Another; // foo\Another クラスのオブジェクトのインスタンスを作成します
$obj = new Another; // My\Full\Classname クラスのオブジェクトのインスタンスを作成します
NSname\subns\func(); // My\Full\NSname\subns\func 関数をコールします
$a = new ArrayObject(array(1)); // ArrayObject クラスのオブジェクトのインスタンスを作成します
// "use ArrayObject" がなければ、foo\ArrayObject クラスのオブジェクトのインスタンスを作成することになります
?>
名前空間つきの名前 (完全修飾形式の名前空間は区切り文字を含んだ Foo\Bar のようなもので、グローバルな場合は区切り文字を含まない FooBar のようになります) では先頭のバックスラッシュは不要で、推奨されないことに注意しましょう。 インポートする名前は完全修飾形式でなければならず、 現在の名前空間からの相対指定で処理されることはないからです。

PHP では、複数の use 文を同一行に置くための便利なショートカットもサポートしています。

例2 use 演算子によるインポート/エイリアスで、複数の use 文を組み合わせる例

<?php
use My\Full\Classname as Another, My\Full\NSname;

$obj = new Another; // My\Full\Classname クラスのオブジェクトのインスタンスを作成します
NSname\subns\func(); // My\Full\NSname\subns\func 関数をコールします
?>

インポートはコンパイル時に行われるので、動的なクラス名、関数名や定数名には影響を及ぼしません。

例3 インポートと動的名

<?php
use My\Full\Classname as Another, My\Full\NSname;

$obj = new Another; // My\Full\Classname クラスのオブジェクトのインスタンスを作成します
$a = 'Another';
$obj = new $a;      // Another クラスのオブジェクトのインスタンスを作成します
?>

さらにインポートの影響が及ぶのは非修飾名および修飾名のみです。 完全修飾名は絶対的なものであり、インポートの影響を受けることはありません。

例4 インポートと完全修飾名

<?php
use My\Full\Classname as Another, My\Full\NSname;

$obj = new Another; // My\Full\Classname クラスのオブジェクトのインスタンスを作成します
$obj = new \Another; // Another クラスのオブジェクトのインスタンスを作成します
$obj = new Another\thing; // My\Full\Classname\thing クラスのオブジェクトのインスタンスを作成します
$obj = new \Another\thing; // Another\thing クラスのオブジェクトのインスタンスを作成します
?>

インポート時のスコープ規則

use キーワードの宣言は、ファイル内の一番外側のスコープ (グローバルスコープ) あるいは名前空間宣言の中で行わなければなりません。 これは、インポートが実行時ではなくコンパイル時に行われるためです。 ブロック内のスコープではインポートできません。 次の例は、use キーワードの間違った使い方を示すものです。

例5 間違ったインポートの例

<?php
namespace Languages;

class Greenlandic
{
    use Languages\Danish;

    ...
}
?>

注意:

インポート規則はファイル単位のものです。つまり、インクルードされたファイルは インクロード元の親ファイルのインポート規則を 引き継ぎません。

グローバル空間

(PHP 5 >= 5.3.0)

名前空間の定義がない場合、すべてのクラスや関数の定義はグローバル空間に配置されます。 これは、名前空間に対応する前の PHP がサポートしていた空間です。 名前の先頭に \ をつけると、 名前空間の内部からであってもグローバル空間の名前を指定することができます。

例1 グローバル空間を指定する方法

<?php
namespace A\B\C;

/* この関数は A\B\C\fopen です */
function fopen() { 
     /* ... */
     $f = \fopen(...); // グローバルな fopen をコールします
     return $f;
} 
?>

名前空間の使用法: グローバル関数/定数への移行

(PHP 5 >= 5.3.0)

名前空間内で、PHP が未定義のクラス名や関数、定数に出会った場合、 それぞれに応じて異なる優先順位で解決を行います。 クラス名は、常に現在の名前空間での名前として解釈されます。 したがって、内部クラスあるいは名前空間に属さないクラスにアクセスするには 次のように完全修飾名で指定しなければなりません。

例1 名前空間内からのグローバルクラスへのアクセス

<?php
namespace A\B\C;
class Exception extends \Exception {}

$a = new Exception('hi'); // $a は A\B\C\Exception クラスのオブジェクトです
$b = new \Exception('hi'); // $b は Exception クラスのオブジェクトです

$c = new ArrayObject; // fatal error, class A\B\C\ArrayObject not found
?>

関数や定数の場合、名前空間内にその関数や定数が見つからなければ PHP はグローバル関数/定数を探します。

例2 名前空間内からのグローバル関数/定数への移行

<?php
namespace A\B\C;

const E_ERROR = 45;
function strlen($str)
{
    return \strlen($str) - 1;
}

echo E_ERROR, "\n"; // "45" と表示します
echo INI_ALL, "\n"; // "7" と表示します - グローバルの INI_ALL に移行しました

echo strlen('hi'), "\n"; // "1" と表示します
if (is_array('hi')) { // "is not array" と表示します
    echo "is array\n";
} else {
    echo "is not array\n";
}
?>

名前解決のルール

(PHP 5 >= 5.3.0)

名前解決のルールを説明するにあたって、いくつかの重要な定義を示しておきます。

名前空間名の定義
非修飾名

これは名前空間区切り文字を含まない識別子で、Foo のようなものです。

修飾名

これは名前空間区切り文字を含む識別子で、Foo\Bar のようなものです。

完全修飾名

これは名前空間区切り文字を含む識別子のうち先頭が名前空間区切り文字で始まるもので、 \Foo\Bar のようなものです。namespace\Foo も完全修飾名です。

名前解決は、これらの解決ルールによって行われます。

  1. 完全修飾された関数、クラス、定数へのコールはコンパイル時に解決されます。 たとえば、new \A\B は A\B クラスと解釈されます。
  2. 非修飾名および (完全修飾でない) 修飾名の変換は、現在のインポートルールに基づいてコンパイル時に行われます。 たとえば、名前空間 A\B\C が C という名前でインポートされている場合、 C\D\e() へのコールは A\B\C\D\e() と変換されます。
  3. 名前空間内で、インポートルールによる変換が行われなかった修飾名は 現在の名前空間が先頭に付加されます。たとえば、 C\D\e() へのコールが名前空間 A\B 内で行われた場合、それは A\B\C\D\e() に変換されます。
  4. 非修飾クラス名の変換は、現在のインポートルールに基づいてコンパイル時に行われます (インポートされた短い名前がフルネームに置き換わります)。たとえば、 名前空間 A\B\C が C という名前でインポートされている場合、 new C() は new A\B\C() と変換されます。
  5. 名前空間内 (ここでは A\B としましょう) で、非修飾な関数へのコールは実行時に解決されます。 関数 foo() のコールは、次のように解決されます。
    1. まず現在の名前空間から関数 A\B\foo() を探します。
    2. 次に グローバル 関数 foo() を探します。
  6. 名前空間内 (ここでは A\B としましょう) で、 非修飾あるいは (完全修飾でない) 修飾なクラスへのコールは実行時に解決されます。 new C() や new D\E() がどのように解決されるかを示します。 new C() の場合は、
    1. まず現在の名前空間からクラス A\B\C を探します。
    2. A\B\C を autoload します。
    new D\E() の場合は、
    1. 現在の名前空間を先頭につけた A\B\D\E を探します。
    2. A\B\D\E を autoload します。
    グローバル名前空間内のグローバルクラスを参照するには、完全修飾形式の new \C() を使わなければなりません。

例1 名前解決の例

<?php
namespace A;
use B\D, C\E as F;

// 関数のコール

foo();      // まず名前空間 "A" で定義されている "foo" のコールを試み、
            // 次にグローバル関数 "foo" をコールします

\foo();     // グローバルスコープで定義されている関数 "foo" をコールします

my\foo();   // 名前空間 "A\my" で定義されている関数 "foo" をコールします

F();        // まず名前空間 "A" で定義されている "F" のコールを試み、
            // 次にグローバル関数 "F" をコールします

// クラスの参照

new B();    // 名前空間 "A" で定義されているクラス "B" のオブジェクトを作成します
            // 見つからない場合は、クラス "A\B" の autoload を試みます

new D();    // インポートルールを使用し、名前空間 "B" で定義されているクラス "D" のオブジェクトを作成します
            // 見つからない場合は、クラス "B\D" の autoload を試みます

new F();    // インポートルールを使用し、名前空間 "C" で定義されているクラス "E" のオブジェクトを作成します
            // 見つからない場合は、クラス "C\E" の autoload を試みます

new \B();   // グローバルスコープで定義されているクラス "B" のオブジェクトを作成します
            // 見つからない場合は、クラス "B" の autoload を試みます

new \D();   // グローバルスコープで定義されているクラス "D" のオブジェクトを作成します
            // 見つからない場合は、クラス "D" の autoload を試みます

new \F();   // グローバルスコープで定義されているクラス "F" のオブジェクトを作成します
            // 見つからない場合は、クラス "F" の autoload を試みます

// 別の名前空間から使用する静的メソッド/関数

B\foo();    // 名前空間 "A\B" の関数 "foo" をコールします

B::foo();   // 名前空間 "A" で定義されているクラス "B" のメソッド "foo" をコールします
            // クラス "A\B" が見つからない場合はクラス "A\B" の autoload を試みます

D::foo();   // インポートルールを使用し、名前空間 "B" で定義されているクラス "D" のメソッド "foo" をコールします
            // クラス "B\D" が見つからない場合はクラス "B\D" の autoload を試みます

\B\foo();   // 名前空間 "B" の関数 "foo" をコールします

\B::foo();  // グローバルスコープのクラス "B" のメソッド "foo" をコールします
            // クラス "B" が見つからない場合はクラス "B" の autoload を試みます

// 現在の名前空間から使用する静的メソッド/関数

A\B::foo();   // 名前空間 "A\A" のクラス "B" のメソッド "foo" をコールします
              // クラス "A\A\B" が見つからない場合はクラス "A\A\B" の autoload を試みます

\A\B::foo();  // 名前空間 "A" のクラス "B" のメソッド "foo" をコールします
              // クラス "A\B" が見つからない場合はクラス "A\B" の autoload を試みます
?>

FAQ: 名前空間について知っておくべきこと

(PHP 5 >= 5.3.0)

この FAQ は 2 つに別れています。一般的な質問と、 深く理解するために有用な実装に関する質問です。

まずは一般的な質問。

  1. 名前空間を使わない場合、 何か注意すべきことはありますか?
  2. 名前空間内での内部クラスあるいはグローバルクラスの使用法は?
  3. 同じ名前空間にあるクラス、関数あるいは定数を使用する方法は?
  4. \my\name や \name のような名前はどのように解決される?
  5. my\name のような名前はどのように解決される?
  6. 修飾されていない name のようなクラス名はどのように解決される?
  7. 修飾されていない name のような関数名/定数名はどのように解決される?

また、名前空間の実装を理解するために有用な実装の詳細は次のとおりです。

  1. インポートした名前が同一ファイルで定義されているクラスと衝突しない
  2. 名前空間のネストはできない
  3. 関数や定数は use 文でインポートできない
  4. 動的な名前空間名 (クォートした名前) ではバックスラッシュのエスケープが必要
  5. バックスラッシュを含む未定義な定数を参照すると、致命的なエラーが発生する
  6. 特別な定数 NULL, TRUE, FALSE, ZEND_THREAD_SAFE そして ZEND_DEBUG_BUILD は上書きできない

名前空間を使わない場合、何か注意すべきことはありますか?

いいえ。これまで書いてきたコード、今後書く名前空間を含まないコードのいずれについても、 名前空間が何らかの影響を及ぼすことはありません。 お望みなら名前空間を使わないコードを書くこともできます。

例1 名前空間の外部にあるグローバルクラスへのアクセス

<?php
$a = new \stdClass;
?>

これは、機能的に次と同等です。

例2 名前空間の外部にあるグローバルクラスへのアクセス

<?php
$a = new stdClass;
?>

名前空間内での内部クラスあるいはグローバルクラスの使用法は?

例3 名前空間内からの内部クラスへのアクセス

<?php
namespace foo;
$a = new \stdClass;

function test(\ArrayObject $typehintexample = null) {}

$a = \DirectoryIterator::CURRENT_AS_FILEINFO;

// 内部クラス/グローバルクラスの継承
class MyException extends \Exception {}
?>

同じ名前空間にあるクラス、関数あるいは定数を使用する方法は?

例4 名前空間内のクラス、関数あるいは定数へのアクセス

<?php
namespace foo;

class MyClass {}

// 現在の名前空間のクラスをタイプヒントに使用する方法
function test(MyClass $typehintexample = null) {}
// 現在の名前空間のクラスをタイプヒントに使用するもうひとつの方法
function test(\foo\MyClass $typehintexample = null) {}

// 現在の名前空間のクラスの継承
class Extended extends MyClass {}

// グローバル関数へのアクセス
$a = \globalfunc();

// グローバル定数へのアクセス
$b = \INI_ALL;
?>

\my\name や \name のような名前はどのように解決される?

\ から始まる名前は常に見た目のままに解釈されます。 つまり \my\name は my\name であり、 \Exception は Exception となります。

例5 完全修飾名

<?php
namespace foo;
$a = new \my\name(); // "my\name" クラスのインスタンスを作成します
echo \strlen('hi'); // "strlen" 関数をコールします
$a = \INI_ALL; // $a に定数 "INI_ALL" の値を設定します
?>

my\name のような名前はどのように解決される?

名前にバックスラッシュを含むが先頭はバックスラッシュでない名前、たとえば my\name のような名前は 2 通りの方法で解釈されます。

別の名前に my というエイリアスを指定する import 文がある場合は、そのエイリアスが my\name の my 部分に適用されます。

それ以外の場合は、現在の名前空間が my\name の先頭に付け加えられます。

例6 修飾名

<?php
namespace foo;
use blah\blah as foo;

$a = new my\name(); // "foo\my\name" クラスのインスタンスを作成します
foo\bar::name(); // "blah\blah\bar" の静的メソッド "name" をコールします
my\bar(); // "foo\my\bar" 関数をコールします
$a = my\BAR; // $a に定数 "foo\my\BAR" の値を設定します
?>

修飾されていない name のようなクラス名はどのように解決される?

バックスラッシュを含まない name のようなクラス名は 2 通りの方法で解釈されます。

別の名前に name というエイリアスを指定する import 文がある場合は、そのエイリアスが適用されます。

それ以外の場合は、現在の名前空間が name の先頭に付け加えられます。

例7 非修飾クラス名

<?php
namespace foo;
use blah\blah as foo;

$a = new name(); // "foo\name" クラスのインスタンスを作成します
foo::name(); // "blah\blah" クラスの静的メソッド "name" をコールします
?>

修飾されていない name のような関数名/定数名はどのように解決される?

バックスラッシュを含まない name のような関数名/定数名は 2 通りの方法で解釈されます。

まず、現在の名前空間が name の先頭に付け加えられます。

現在の名前空間に name という関数あるいは定数がない場合は、 グローバル関数あるいは定数に name があればそれを使用します。

例8 非修飾関数/定数名

<?php
namespace foo;
use blah\blah as foo;

const FOO = 1;

function my() {}
function foo() {}
function sort(&$a)
{
    sort($a);
    $a = array_flip($a);
    return $a;
}

my(); // "foo\my" をコールします
$a = strlen('hi'); // "foo\strlen" が存在しないので、グローバル関数 "strlen" をコールします
$arr = array(1,3,2);
$b = sort($arr); // "foo\sort" 関数をコールします
$c = foo(); // calls function "foo\foo" - import is not applied

$a = FOO; // sets $a to value of constant "foo\FOO" - import is not applied
$b = INI_ALL; // sets $b to value of global constant "INI_ALL"
?>

インポートした名前が同一ファイルで定義されているクラスと衝突しない

次のようなスクリプトの組み合わせは、正当なものです。

file1.php

<?php
namespace my\stuff;
class MyClass {}
?>

another.php

<?php
namespace another;
class thing {}
?>

file2.php

<?php
namespace my\stuff;
include 'file1.php';
include 'another.php';

use another\thing as MyClass;
$a = new MyClass; // 名前空間 another のクラス "thing" のインスタンスを作成します。
?>

MyClass クラスが名前空間 my\stuff にあるとはいえ、名前の衝突はありません。 MyClass の定義は別のファイルにあるからです。 しかし、次の例は名前の衝突による致命的なエラーとなります。 MyClass の定義が同じファイル上の use 文で行われているからです。

<?php
namespace my\stuff;
use another\thing as MyClass;
class MyClass {} // fatal error: MyClass conflicts with import statement
$a = new MyClass;
?>

名前空間のネストはできない

PHP では名前空間のネストはできません。

<?php
namespace my\stuff {
    namespace nested {
        class foo {}
    }
}
?>
しかし、それっぽいことをするのは簡単です。次のようにすればいいのです。
<?php
namespace my\stuff\nested {
    class foo {}
}
?>

関数や定数は use 文でインポートできない

use 文の影響を受けるのは名前空間とクラス名のみです。 長い名前の定数や関数を短い名前にするには、それらが含まれる名前空間をインポートします。

<?php
namespace mine;
use ultra\long\ns\name;

$a = name\CONSTANT;
name\func();
?>

動的な名前空間名 (クォートした名前) ではバックスラッシュのエスケープが必要

バックスラッシュは文字列のエスケープ文字として使われることに注意しましょう。 文字列の中で使う際にはバックスラッシュを二重に書く必要があります。 そうしないと、予期せぬ結果を引き起こしてしまいます。

例9 ダブルクォートで囲んだ文字列内で名前空間名を扱う際の危険

<?php
$a = new "dangerous\name"; // ダブルクォートの中では \n が改行文字になってしまいます!
$obj = new $a;

$a = new 'not\at\all\dangerous'; // こっちは大丈夫です
$obj = new $a;
?>
シングルクォートで囲んだ文字列内では、 バックスラッシュによるエスケープシーケンスをより安全に使うことができます。 しかし、文字列内では常にバックスラッシュをエスケープする習慣をつけておくことをお勧めします。

バックスラッシュを含む未定義な定数を参照すると、致命的なエラーが発生する

未定義の定数のうち FOO のような修飾されていないものは、 PHP が FOO を定数の値と解釈したという notice が発生します。 修飾あるいは完全修飾形式の定数、つまりバックスラッシュを含む定数の場合、 それが未定義なら致命的なエラーが発生します。

例10 未定義の定数

<?php
namespace bar;
$a = FOO; // notice - undefined constants "FOO" assumed "FOO";
$a = \FOO; // fatal error, undefined namespace constant FOO
$a = Bar\FOO; // fatal error, undefined namespace constant bar\Bar\FOO
$a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
?>

特別な定数 NULL, TRUE, FALSE, ZEND_THREAD_SAFE そして ZEND_DEBUG_BUILD は上書きできない

名前空間内で特別な組み込み定数を定義しようとすると、致命的なエラーが発生します。

例11 未定義の定数

<?php
namespace bar;
const NULL = 0; // 致命的なエラー
const true = 'stupid'; // これも、致命的なエラー
// etc.
?>

例外(exceptions)

目次

PHP 5 は、他のプログラミング言語に似た例外モデルを有しています。 PHP 内で例外が投げられ ("throw" され)、それが 捕捉され ("catch" され) ます。発生した例外を 捕捉するには、コードを try ブロックで囲みます。 各 try ブロックには、対応する catch ブロックが存在する必要があります。異なる型の例外を捕捉するために 複数の catch フロックを使用することができます。 通常の実行時 (try ブロック内で例外が投げられなかった 場合、あるいは投げられた例外に対応する catch ブロックが存在しなかった場合) は、catch ブロック内は処理されず、それ以降から処理が続けられます。 catch ブロックの中から例外を投げる (あるいは投げなおす) こともできます。

例外が投げられた場合、その命令に続くコードは実行されず、 PHP は最初にマッチする catch ブロックを探します。 例外が捕捉されない場合、PHP は "Uncaught Exception ..." というメッセージとともに 致命的なエラー(fatal error)を発行します。 ただし、set_exception_handler() でハンドラが 定義されている場合を除きます。

スローされるオブジェクトは、Exception クラスあるいは Exception のサブクラスのインスタンスでなければなりません。 それ以外のオブジェクトをスローしようとすると PHP の Fatal Error が発生します。

注意:

PHP の内部関数の多くは エラー報告 を使っており、例外を使っているのは新しい オブジェクト指向 の拡張モジュールのみです。 しかし、ErrorException を使えば簡単にエラーを例外に変換することができます。

ヒント

Standard PHP Library (SPL) には組み込みの例外が数多く用意されています。

例1 例外を投げるには

<?php
function inverse($x) {
    if (!$x) {
        throw new Exception('ゼロによる除算。');
    }
    else return 1/$x;
}

try {
    echo inverse(5) . "\n";
    echo inverse(0) . "\n";
} catch (Exception $e) {
    echo '捕捉した例外: ',  $e->getMessage(), "\n";
}

// 実行は継続される
echo 'Hello World';
?>

上の例の出力は以下となります。

0.2
捕捉した例外: ゼロによる除算。
Hello World

例2 ネストした例外

<?php

class MyException extends Exception { }

class Test {
    public function testing() {
        try {
            try {
                throw new MyException('foo!');
            } catch (MyException $e) {
                /* 改めてスロー */
                throw $e;
            }
        } catch (Exception $e) {
            var_dump($e->getMessage());
        }
    }
}

$foo = new Test;
$foo->testing();

?>

上の例の出力は以下となります。

string(4) "foo!"

例外を拡張する

組み込みの Exception クラスを拡張することで、例外クラスをユーザーが 定義することが可能です。以下のメンバーおよびプロパティは、 組み込みの Exception クラスから派生した子クラスの中でアクセス可能です。

例1 例外クラスを構築する

<?php
class Exception
{
    protected $message = 'Unknown exception';   // exception message
    private   $string;                          // __toString cache
    protected $code = 0;                        // user defined exception code
    protected $file;                            // source filename of exception
    protected $line;                            // source line of exception
    private   $trace;                           // backtrace
    private   $previous;                        // previous exception if nested exception

    public function __construct($message = null, $code = 0, Exception $previous = null);

    final private function __clone();           // Inhibits cloning of exceptions.

    final public  function getMessage();        // message of exception
    final public  function getCode();           // code of exception
    final public  function getFile();           // source filename
    final public  function getLine();           // source line
    final public  function getTrace();          // an array of the backtrace()
    final public  function getPrevious();       // previous exception
    final public  function getTraceAsString();  // formatted string of trace

    /* Overrideable */
    public function __toString();               // formatted string for display
}
?>

クラスが、組み込みの Exception クラスを拡張し、 コンストラクタを再定義した場合、 全ての利用可能なデータが正しく代入されることを保証するために parent::__construct() もコールすることが強く推奨されます。 __toString() メソッドは、 オブジェクトが文字列として表された際に独自の出力を行うために 上書きすることができます。

注意:

例外を複製することはできません。Exception を clone しようとすると 致命的な E_ERROR エラーが発生します。

例2 例外クラスの拡張 (PHP 5.3.0+)

<?php
/**
 * カスタム例外クラスを定義する
 */
class MyException extends Exception
{
    // 例外を再定義し、メッセージをオプションではなくする
    public function __construct($message, $code = 0, Exception $previous = null) {
        // なんらかのコード
    
        // 全てを正しく確実に代入する
        parent::__construct($message, $code, $previous);
    }

    // オブジェクトの文字列表現を独自に定義する
    public function __toString() {
        return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
    }

    public function customFunction() {
        echo "A Custom function for this type of exception\n";
    }
}


/**
 * 例外をテストするためのクラスを作成
 */
class TestException
{
    public $var;

    const THROW_NONE    = 0;
    const THROW_CUSTOM  = 1;
    const THROW_DEFAULT = 2;

    function __construct($avalue = self::THROW_NONE) {

        switch ($avalue) {
            case self::THROW_CUSTOM:
                // カスタム例外を投げる
                throw new MyException('1 is an invalid parameter', 5);
                break;

            case self::THROW_DEFAULT:
                // デフォルト例外を投げる
                throw new Exception('2 is not allowed as a parameter', 6);
                break;

            default: 
                // 例外なし。オブジェクトが生成される
                $this->var = $avalue;
                break;
        }
    }
}


// 例1
try {
    $o = new TestException(TestException::THROW_CUSTOM);
} catch (MyException $e) {      // Will be caught
    echo "Caught my exception\n", $e;
    $e->customFunction();
} catch (Exception $e) {        // Skipped
    echo "Caught Default Exception\n", $e;
}

// 実行を継続する
var_dump($o); // Null
echo "\n\n";


// 例2
try {
    $o = new TestException(TestException::THROW_DEFAULT);
} catch (MyException $e) {      // この型にはマッチしない
    echo "Caught my exception\n", $e;
    $e->customFunction();
} catch (Exception $e) {        // キャッチされる
    echo "Caught Default Exception\n", $e;
}

// 実行を継続する
var_dump($o); // Null
echo "\n\n";


// 例3
try {
    $o = new TestException(TestException::THROW_CUSTOM);
} catch (Exception $e) {        // キャッチされる
    echo "Default Exception caught\n", $e;
}

// 実行を継続する
var_dump($o); // Null
echo "\n\n";


// 例4
try {
    $o = new TestException();
} catch (Exception $e) {        // スキップされる、例外なし
    echo "Default Exception caught\n", $e;
}

// 実行を継続する
var_dump($o); // TestException
echo "\n\n";
?>

注意:

PHP 5 の PHP 5.3.0 より前のバージョンでは例外のネストに対応していません。 もしこのサンプルを動かしたい場合は、MyException クラスを次のコードで置き換えましょう。

<?php
/**
 * カスタム例外クラスを定義する
 */
class MyException extends Exception
{
    // 例外を再定義し、メッセージをオプションではなくする
    public function __construct($message, $code = 0) {
        // なんらかのコード
    
        // 全てを正しく確実に代入する
        parent::__construct($message, $code);
    }

    // オブジェクトの文字列表現を独自に定義する
    public function __toString() {
        return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
    }

    public function customFunction() {
        echo "A custom function for this type of exception\n";
    }
}
?>

リファレンスの説明

目次

リファレンスとは?

PHP において、リファレンスとは同じ変数の内容を異なった名前で コールすることを意味します。これは C のポインタとは異なります。 リファレンスを使ってポインタの演算をすることはできませんし、 リファレンスは実メモリのアドレスでもありません。詳細は リファレンスが行わないこと を参照ください。 そうではなく、リファレンスはシンボルテーブルのエイリアスです。 PHP では、変数名と変数の内容は異なっており、 このため、同じ内容は異なった複数の名前を有する事が可能であることに 注意してください。最も良く似ているのは、Unix のファイル名とファイルの 関係です。この場合、変数名はディレクトリエントリ、変数の内容は ファイル自体に対応します。リファレンスは、Unix ファイルシステムの ハードリンクのようなものであると考えられます。

リファレンスが行うことは何ですか?

リファレンスを使う基本操作には三通りあります。 リファレンスの代入、 リファレンス渡し、 そして リファレンスを返すことです。 この節では、これらの操作に関する基本的な解説をします。 そして、詳細な説明へのリンクを示します。

リファレンスの代入

まず最初の操作です。PHP のリファレンスを使うと、 ふたつの変数が同じ内容を指すようにできます。 次の例を考えてみましょう。

<?php
$a =& $b;
?>
この場合、$a と $b は同じ内容を指します。

注意:

ここで、$a と $b は完全に 同じで、$a が $b を 指しているわけではなく、その逆でもありません。$a と $b は同じ場所を指しているのです。

注意:

未定義の変数のリファレンスに対して代入したり 渡したり返したりすると、そこで変数が作成されます。

例1 未定義の変数のリファレンスの使用

<?php
function foo(&$var) { }

foo($a); // $a が作成され、null が代入されます

$b = array();
foo($b['b']);
var_dump(array_key_exists('b', $b)); // bool(true)

$c = new StdClass;
foo($c->d);
var_dump(property_exists($c, 'd')); // bool(true)
?>

リファレンスを返す関数や new 演算子でも 同じ構文が使用可能です (PHP 4.0.4 以降 PHP 5.0.0 未満まで)。

<?php
$foo =& find_var($bar);
?>
PHP 5 以降、new は自動的にリファレンスを返すようになりました。そのため、この場面で =& を使用することは非推奨となりました。 PHP 5.3 以降では E_DEPRECATED、それより前のバージョンでは E_STRICT レベルのメッセージが表示されます (技術的な話をすると、PHP 5 以降では、リソース型のようなオブジェクト変数は 実際のデータへの単なるポインタとなりました。つまり、 オブジェクトのリファレンスはこれまでのような意味での "リファレンス" つまりエイリアスとは異なります。 詳細な情報は オブジェクトと参照 にあります)。

警告

関数の内部で global 宣言された変数にリファレンスを 代入すると、そのリファレンスは関数の内部でのみ参照可能となります。 これを避けるには、$GLOBALS 配列を使用します。

例2 関数内でのグローバル変数の参照

<?php
$var1 = "Example variable";
$var2 = "";

function global_references($use_globals)
{
    global $var1, $var2;
    if (!$use_globals) {
        $var2 =& $var1; // 関数の内部でのみ参照可能
    } else {
        $GLOBALS["var2"] =& $var1; // 関数の外部でも参照可能
    }
}

global_references(false);
echo "var2 の値は '$var2'\n"; // var2 の値は ''
global_references(true);
echo "var2 の値は '$var2'\n"; // var2 の値は 'Example variable'
?>
global $var; は、$var =& $GLOBALS['var']; の短縮版だと考えてください。 これにより、他のリファレンスを $var に代入し、 ローカル変数のリファレンスのみを変更します。

注意:

foreach ステートメントの内部でリファレンス変数に値を代入すると、リファレンスも変更されます。

例3 リファレンスと foreach ステートメント

<?php
$ref = 0;
$row =& $ref;
foreach (array(1, 2, 3) as $row) {
    // 何かを実行します
}
echo $ref; // 3 - 配列の最後の要素
?>

厳密にリファレンスでの代入をしなくても、 array() で作成した式は、配列の要素の先頭に & を追加したのと同じような動作をします。たとえば、次のようになります。

<?php
$a = 1;
$b = array(2, 3);
$arr = array(&$a, &$b[0], &$b[1]);
$arr[0]++; $arr[1]++; $arr[2]++;
/* $a == 2, $b == array(3, 4); */
?>

しかし、配列の内部のリファレンスは危険もあるということに気をつけましょう。 通常の (リファレンスではない) 代入の右辺にリファレンスを使っても 左辺はリファレンスには変わりませんが、配列の内部のリファレンスは通常の代入のままとなります。 これは、関数をコールする際に配列をリファレンスで渡すときも同じです。 たとえば、次のようになります。

<?php
/* スカラー変数への代入 */
$a = 1;
$b =& $a;
$c = $b;
$c = 7; // $c はリファレンスではないので $a や $b の値は変わりません

/* 配列変数への代入 */
$arr = array(1);
$a =& $arr[0]; // $a および $arr[0] は同じリファレンスセットになります
$arr2 = $arr; // これは、リファレンス代入ではありません!
$arr2[0]++;
/* $a == 2, $arr == array(2) */
/* $arr の内容は、たとえリファレンスでなくても変わります! */
?>
言い換えると、配列内のリファレンスの挙動はその要素ごとに決まるということです。 個々の要素のリファレンスに関する動きは、 配列コンテナがリファレンスであるかどうかとは独立しています。

リファレンス渡し

リファレンスの第 2 の使用法は、変数のリファレンス渡しです。この場合、 関数でローカル変数が作成され、コール側の変数が、それと同じ内容への リファレンスとなります。例を示します。

<?php
function foo(&$var) 
{
  $var++;
}

$a=5;
foo($a);
?>
この結果、$a は 6 となります。これは、関数 foo の中では、変数 $var は $a と同じ内容を指しているためです。 より詳細な説明は、 リファレンス渡し を参照ください。

リファレンスによる返り値

リファレンスの第 3 の使用法は、 リファレンスによる返り値 です。

リファレンスが行わないこと

これまでに説明したように、リファレンスはポインタではありません。このため、 次の例は期待通りに動作しません。

<?php
function foo(&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar); 
?>

ここでの動作としては、関数 foo の $var はコール側の $bar と関連付けられますが、$GLOBALS["baz"] に再結合されるといったものになります。$bar は関数 foo で利用できないため、 リファレンス以外にはコール側の変数スコープにある $bar を何かに結合する手段はありません （この変数は $var として表されていますが、 $var はその変数の内容のみを有しており、 コール側のシンボルテーブルで名前と変数を結合したものではありません）。 関数内で指定した変数を参照するには、リファレンス返し が使用可能です。

リファレンス渡し

リファレンスにより関数に変数を渡すことが可能です。この場合、関数内で その引数を修正可能になります。構文は次のようになります。

<?php
function foo(&$var)
{
    $var++;
}

$a=5;
foo($a);
// $a はここでは 6 です
?>

注意: 関数コールの際には、リファレンス記号がないことに注意してください。 関数定義にのみリファレンス記号があります。リファレンスで正しく引数を 渡すには、関数定義のみで十分です。以前のバージョンの PHP では foo(&$a); のような形式で & を利用すると "Call-time pass-by-reference" という警告が発生していましたが、 PHP 5.3.0 以降では警告は発生しません。

次のものはリファレンスで渡すことが可能です。

  • 変数、すなわち、foo($a)
  • new 命令、すなわち、foo(new foobar())

  • 関数から返されるリファレンスは、次のようになります。

    <?php
    function foo(&$var)
    {
            $var++;
    }
    function &    bar()
    {
            $a = 5;
        return     $a;
    }
    foo(bar());
    ?>
    リファレンスによる 返り値 に関する説明も参照ください。

他の式は、結果が未定義となるため、リファレンスで渡すべきではありません。 例えば、リファレンスで渡す次の例は、無効です。

<?php
function foo(&$var)
{
    $var++;
}
function bar() // & がないことに注意
{
    $a = 5;
    return $a;
}
foo(bar()); // PHP 5.0.5 以降、致命的なエラーが発生する

foo($a = 5); // 式、変数ではない
foo(5); // 致命的なエラーが発生する
?>
以上の説明は、PHP 4.0.4 以降用です。

リファレンスを返す

リファレンスを返すことは、結合する変数を見付けるために関数を使用し たい場合に便利です。パフォーマンスを向上させるためだけの目的で この機能を用いることはやめてください。 そのようなことをしなくても、PHP エンジンが自動的に最適化を行います。 リファレンスを返すのは、そうすべき妥当な理由がある場合に限られます! リファレンスを返す場合、次の構文を使用して下さい。

<?php
class foo {
    public $value = 42;

    public function &getValue() {
        return $this->value;
    }
}

$obj = new foo;
$myValue = &$obj->getValue(); // $myValue は $obj->value へのリファレンス、つまり 42 となります
$obj->value = 2;
echo $myValue;                // $obj->value の新しい値である 2 を表示します
?>
この例では、関数 getValue により返された オブジェクトのプロパティが、設定されます。リファレンス構文を 使用しない場合のようにコピーとなるわけではありません。

注意: パラメータを渡す場合と異なり、ここでは、通常のようにコピーでは なくリファレンスで返り値を指定し、リファレンス結合を指定するために 両方の場所で & を使用する必要があります。 $myValue について行われたのは、通常の代入ではありません。

注意: 以下のような形式で関数からリファレンスを返そうとした場合、 return ($this->value); これは、あなたが望んでいるように 式 の結果を返してくれることはありません。 可能なことは、値へのリファレンスを返すことができるということだけで、 それ以外の何者でもありません。 PHP 4.4.0 および PHP 5.1.0 以降では、式の結果や new 演算子の結果をそのまま返そうとした場合に E_NOTICE エラーが発生します。

返されたリファレンスを使うには、リファレンスを代入しなければなりません。

<?php
function &collector() {
  static $collection = array();
  return $collection;
}
$collection = &collector();
$collection[] = 'foo';
?>
返されたリファレンスを、リファレンスを要求する別の関数に渡すには、 この構文を使います。
<?php
function &collector() {
  static $collection = array();
  return $collection;
}
array_push(collector(), 'foo');
?>

注意: array_push(&collector(), 'foo'); は 動かないことに注意しましょう。fatal エラーとなります。

リファレンスの解除

リファレンスを解除することは、ちょうど変数名と変数の内容の結合を 解除することに相当します。これは、変数の内容が破棄されることを 意味しません。例えば、

<?php
$a = 1;
$b =& $a;
unset($a);
?>
は、$b を削除せず、$a のみを 削除します。

ここでも、Unix の unlink コールと類似したものと 考えると便利です。

リファレンスの適用範囲

PHP の多くの構文構造は、リファレンス機構を利用して実装されています。 このため、前記のリファレンス結合に関する事項はこれらの構造についても 適用されます。リファレンス渡しおよびリファレンスの返り値のような いくつかの構造について前節で記述されています。リファレンスを使用する 他の構造には次のものがあります。

global リファレンス

変数を global $var として宣言した場合、実際には グローバル変数へのリファレンスを作成したことになります。この意味は、 次の例と同じです。

<?php
$var =& $GLOBALS["var"];
?>

これは、例えば、$var を削除してもグローバル変数は 削除されないことを意味します。

$this

オブジェクトのメソッドでは、$this は 常にコール側のオブジェクトへのリファレンスです。

定義済の変数

PHP には定義済みの定数が多く用意されており、すべてのスクリプトで使用することができます。 外部から来る変数 や組み込みの環境変数、直近のエラーメッセージや最後に取得したヘッダなどのあらゆる内容が取得できます。

関連情報については、FAQ の "register_globals の影響は?" を参照ください。

スーパーグローバル

スーパーグローバル — すべてのスコープで使用できる組み込みの変数

説明

PHP の定義済み変数の中には "スーパーグローバル" というものがあります。 これは、スクリプト全体を通してすべてのスコープで使用可能な変数のことです。 関数やメソッドの内部からアクセスする際にも global $variable; などとする必要はありません。

スーパーグローバルには次のようなものがあります。

変更履歴

バージョン 説明
4.1.0 スーパーグローバルが PHP に導入されました。

注意

注意: 使用できる変数

デフォルトでは、すべてのスーパーグローバルが使用可能です。 ただし、それに影響を与える設定項目もあります。詳細は variables_order のドキュメントを参照ください。

注意: register_globals の扱い

非推奨の register_globals ディレクティブが on に設定されている場合は、 内部の変数もスクリプトのグローバルスコープで使用できるようになります。 たとえば $_POST['foo'] は $foo という名前でも使えるようになるということです。

関連情報については、FAQ の "register_globals の影響は?" を参照ください。

注意: 可変変数

スーパーグローバルは、関数やクラスメソッドの中の 可変変数 として使用することはできません。

$GLOBALS

(PHP 4, PHP 5)

$GLOBALS — グローバルスコープで使用可能なすべての変数への参照

説明

スクリプトのグローバルスコープに現在定義されているすべての変数への参照を含む連想配列です。 変数名が配列のキーとなります。

例

例1 $GLOBALS の例

<?php
function test() {
    $foo = "local variable";

    echo '$foo in global scope: ' . $GLOBALS["foo"] . "\n";
    echo '$foo in current scope: ' . $foo . "\n";
}

$foo = "Example content";
test();
?>

上の例の出力は、 たとえば以下のようになります。

$foo in global scope: Example content
$foo in current scope: local variable

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意: 変数の可用性

他のスーパーグローバル とは異なり、$GLOBALS は PHP で常に使用可能です。

$_SERVER

$HTTP_SERVER_VARS [非推奨]

(PHP 4 >= 4.1.0, PHP 5)

$_SERVER -- $HTTP_SERVER_VARS [非推奨] — サーバー情報および実行時の環境情報

説明

$_SERVER は、ヘッダ、パス、スクリプトの位置のような 情報を有する配列です。この配列のエントリは、Web サーバーにより 生成されます。全ての Web サーバーがこれら全てを提供する保障はありません。 サーバーは、これらのいくつかを省略したり、この一覧にない他のものを 定義する可能性があります。これらの変数の多くは、 » CGI/1.1 specification で定義されています。したがって、これらについては定義されていることを 期待することができます。

$HTTP_SERVER_VARS の最初の情報は同じですが、 これはスーパーグローバルではありません (HTTP_SERVER_VARS と $_SERVER は異なる変数であり、 PHP は異なる変数として処理を行うことに注意してください)。

インデックス

以下の各要素のいくつかは $_SERVER に現れない可能性があります。PHP をコマンドラインで実行している場合には、 使用できるものは僅かであることに注意してください。

'PHP_SELF'
現在実行しているスクリプトのファイル名です。 ドキュメントルートから取得されます。 例えば、http://example.com/test.php/foo.bar というアドレス上にあるスクリプトでは $_SERVER['PHP_SELF'] は /test.php/foo.bar となります。 __FILE__ 定数 には、カレント(すなわち読み込まれた)ファイルのパスとファイル名が含まれます。 PHP がコマンドラインから実行される場合、PHP 4.3.0 以降、 この変数にはスクリプト名が含まれます。これより前のバージョンでは、 この変数は使用できません。
'argv'
スクリプトに渡された引数の配列です。スクリプトがコマンドラインから 実行された場合、C 言語スタイルでコマンドライン引数に アクセスすることができます。GET メソッドを通してコールされた場合には 検索引数が格納されます。
'argc'
スクリプトに渡されたコマンドライン引数の数 (コマンドラインから実行した場合) です。
'GATEWAY_INTERFACE'
サーバーが使用している CGI のバージョンです。 例 'CGI/1.1'
'SERVER_ADDR'
現在のスクリプトが実行されているサーバーの IP アドレスです。
'SERVER_NAME'
現在のスクリプトが実行されているサーバーのホスト名です。 スクリプトがバーチャルホスト上で実行されている場合は そのバーチャルホスト名となります。
'SERVER_SOFTWARE'
レスポンスヘッダ上に書かれている、 サーバーの認識文字列です。
'SERVER_PROTOCOL'
ページがリクエストされた際のプロトコル名とバージョンです。 例.'HTTP/1.0'
'REQUEST_METHOD'
ページにアクセスする際に使用されたリクエストのメソッド名です。 'GET', 'HEAD', 'POST', 'PUT' など。

注意:

リクエストのメソッドが HEAD だった場合、 PHP スクリプトはヘッダを送信した後（言い換えれば、 出力バッファリングを行わずに全出力を処理した後）に終了します。

'REQUEST_TIME'
リクエストの開始時のタイムスタンプ。PHP 5.1.0 以降で利用可能。
'REQUEST_TIME_FLOAT'
リクエストの開始時のタイムスタンプ (マイクロ秒までの精度)。 PHP 5.4.0 以降で利用可能。
'QUERY_STRING'
ページがアクセスされた際にもし検索引数があればそれが格納されます。
'DOCUMENT_ROOT'
現在実行されているスクリプトが存在するドキュメントルート ディレクトリです。サーバーのコンフィグレーションファイルで 定義されています。
'HTTP_ACCEPT'
現在のリクエストの Accept: ヘッダがもしあれば その内容。
'HTTP_ACCEPT_CHARSET'
現在のリクエストの Accept-Charset: ヘッダが もしあればその内容。例: 'iso-8859-1,*,utf-8'
'HTTP_ACCEPT_ENCODING'
現在のリクエストに Accept-Encoding: ヘッダが もしあればその内容。例: 'gzip'
'HTTP_ACCEPT_LANGUAGE'
現在のリクエストに Accept-Language: ヘッダが もしあればその内容。例: 'en'
'HTTP_CONNECTION'
現在のリクエストに Connection: ヘッダが もしあればその内容。例: 'Keep-Alive'
'HTTP_HOST'
現在のリクエストに Host: ヘッダが もしあればその内容。
'HTTP_REFERER'
現在のページに遷移する前にユーザーエージェントが参照していた ページのアドレス（もしあれば）。これはユーザーエージェントに よってセットされます。全てのユーザーエージェントが これをセットしているわけではなく、また、HTTP_REFERER を変更する機能を持つものもああります。 要するに、信頼するべきものではありません。
'HTTP_USER_AGENT'
現在のリクエストに User-Agent: ヘッダが もしあればその内容。ページにアクセスしてきているユーザーエージェント のしるしの文字列です。典型的な例は、 Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)。たとえば、 get_browser() でこの値を使って ページの出力をそのブラウザにあわせたものにすることも できるでしょう。
'HTTPS'
スクリプトが HTTPS プロトコルを通じて実行されている場合に 空でない値が設定されます。

注意: ISAPI を IIS で使用している場合は、HTTPS プロトコルを通さないでリクエストが行われたときの値は off となることに注意しましょう。

'REMOTE_ADDR'
現在ページをみているユーザーの IP アドレス。
'REMOTE_HOST'
現在のページにアクセスしているホスト名。DNS の逆引き検索は ユーザーの REMOTE_ADDR に基づいています。

注意: Web サーバーがこの値を生成できるように設定されている必要があります。 例えば Apache の場合 HostnameLookups On が httpd.conf に設定されていなければこの値は生成されません。 gethostbyaddr() もご覧ください。

'REMOTE_PORT'
ユーザーのマシンから Web サーバーへの通信に使用されているポート番号
'REMOTE_USER'
認証されたユーザー。
'REDIRECT_REMOTE_USER'
リクエストが内部でリダイレクトされた場合の認証されたユーザー。
'SCRIPT_FILENAME'

現在実行されているスクリプトの絶対パス

注意:

file.php あるいは ../file.php のような相対パスを指定して CLI でスクリプトが実行されている場合、 $_SERVER['SCRIPT_FILENAME'] には ユーザーが指定した相対パスが含まれます。

'SERVER_ADMIN'
Web サーバーの設定ファイルの SERVER_ADMIN (Apache の場合)ディレクティブ にセットされている値。スクリプトがバーチャルホスト上で 実行されている場合、バーチャルホストに対して値が定義されます。
'SERVER_PORT'
Web サーバーの通信ポートとして使用されているポート番号。デフォルトでは '80' ですが、例えば SSL を使用している場合は セキュア HTTP ポートとして設定されている値に変わります。
'SERVER_SIGNATURE'
サーバー上で生成されたページに追加される、 サーバーのバージョン名とバーチャルホスト名の文字列。 Web サーバーの設定で有効になっていることが必要です。
'PATH_TRANSLATED'
バーチャルからリアルへのマッピングがなされた後の、 現在のスクリプトのファイルシステム上（ドキュメントルートではなく） でのパス。

注意: PHP 4.3.2 以降、PATH_TRANSLATED は、 Apache 2 SAPI において暗黙のうちに設定されなく なりました。一方、Apache 1 では、この値が Apache により設定されない場合、 SCRIPT_FILENAME と同じ値に設定されます。 この変更は、PATH_TRANSLATED は PATH_INFO が定義されている場合のみ 存在するべきであるという CGI の規約を満たすために 行われました。 Apache 2 ユーザーは、PATH_INFO を定義するために httpd.conf の中で AcceptPathInfo = On を使用することが可能です。

'SCRIPT_NAME'
現在のスクリプトのパス。 スクリプト自身のページを指定するのに有用です。 __FILE__ 定数には、カレント(すなわち読み込まれた)ファイルのパスとファイル名が 含まれます。
'REQUEST_URI'
ページにアクセスするために指定された URI。例えば、 '/index.html'
'PHP_AUTH_DIGEST'
HTTP ダイジェスト認証を 行っている場合、クライアントから送られた 'Authorization' ヘッダの 内容が設定されます（適切な認証処理を行うために利用します）。
'PHP_AUTH_USER'
HTTP 認証しているときにそのユーザー名がセットされます。
'PHP_AUTH_PW'
HTTP 認証しているときにそのユーザーの パスワードがセットされます。
'AUTH_TYPE'
HTTP 認証しているときにその認証形式がセットされます。
'PATH_INFO'
実際のスクリプトファイル名とクエリ文字列の間にある、クライアントが提供するパス名情報。 たとえば、現在のスクリプトに http://www.example.com/php/path_info.php/some/stuff?foo=bar という URL でアクセスしていた場合の $_SERVER['PATH_INFO'] は /some/stuff となります。
'ORIG_PATH_INFO'
PHP で処理される前の 'PATH_INFO' の原本。

変更履歴

バージョン 説明
4.1.0 $_SERVER が導入され、 $HTTP_SERVER_VARS は非推奨となりました。

例

例1 $_SERVER の例

<?php
echo $_SERVER['SERVER_NAME'];
?>

上の例の出力は、 たとえば以下のようになります。

www.example.com

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

$_GET

$HTTP_GET_VARS [非推奨]

(PHP 4 >= 4.1.0, PHP 5)

$_GET -- $HTTP_GET_VARS [非推奨] — HTTP GET 変数

説明

URL パラメータで現在のスクリプトに渡された変数の連想配列です。

$HTTP_GET_VARS は同じ情報を持っていますが、 これはスーパーグローバルではありません (HTTP_GET_VARS と $_GET は違う変数であり、PHPはそれぞれ別に扱います)。

変更履歴

バージョン 説明
4.1.0 $_GET が導入され、 $HTTP_GET_VARS は非推奨となりました。

例

例1 $_GET の例

<?php
echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
?>

ユーザーが http://example.com/?name=Hannes と入力したとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意:

GET 変数は urldecode() 関数を介して渡されます。

$_POST

$HTTP_POST_VARS [非推奨]

(PHP 4 >= 4.1.0, PHP 5)

$_POST -- $HTTP_POST_VARS [非推奨] — HTTP POST 変数

説明

HTTP POST メソッドで現在のスクリプトに渡された変数の連想配列です。

$HTTP_POST_VARS は同じ情報を持っていますが、 これはスーパーグローバルではありません (HTTP_POST_VARS と $_POST は違う変数であり、PHPはそれぞれ別に扱います)。

変更履歴

バージョン 説明
4.1.0 $_POST が導入され、 $HTTP_POST_VARS は非推奨となりました。

例

例1 $_POST の例

<?php
echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
?>

ユーザーが name=Hannes と POST したとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

$_FILES

$HTTP_POST_FILES [非推奨]

(PHP 4 >= 4.1.0, PHP 5)

$_FILES -- $HTTP_POST_FILES [非推奨] — HTTP ファイルアップロード変数

説明

HTTP POST メソッドで現在のスクリプトにアップロードされた項目の連想配列です。

$HTTP_POST_FILES は同じ情報を持っていますが、 これはスーパーグローバルではありません ($HTTP_POST_FILES と $_FILES は異なる変数であり、PHP はこれらを異なる変数として扱うことに注意してください)。

変更履歴

バージョン 説明
4.1.0 $_FILES が導入され、 $HTTP_POST_FILES は非推奨となりました。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

$_REQUEST

(PHP 4 >= 4.1.0, PHP 5)

$_REQUEST — HTTP リクエスト変数

説明

$_GET、 $_POST そして $_COOKIE の内容をまとめた連想配列です。

変更履歴

バージョン 説明
5.3.0 request_order が導入されました。 このディレクティブは $_REQUEST の内容に影響を及ぼします。
4.3.0 $_FILES の情報が $_REQUEST から削除されました。
4.1.0 $_REQUEST が導入されました。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

注意:

コマンドライン で実行する場合、ここには argv や argc の内容は含まれません。これらの内容は $_SERVER 配列に格納されます。

注意:

$_REQUEST 内の変数の内容は、 GET や POST そして COOKIE といった仕組みでスクリプトに渡されます。 これらはリモートユーザーが変更可能なので、信頼できるとは限りません。 この配列内に含まれる変数の値や順序は、 PHP の設定ディレクティブ variables_order で決まります。

参考

$_SESSION

$HTTP_SESSION_VARS [非推奨]

(PHP 4 >= 4.1.0, PHP 5)

$_SESSION -- $HTTP_SESSION_VARS [非推奨] — セッション変数

説明

現在のスクリプトで使用できるセッション変数を含む連想配列です。 セッション変数の使用法についての詳細は、 セッション関数 のドキュメントを参照ください。

$HTTP_SESSION_VARS は同じ情報を格納していますが、 これはスーパーグローバルではありません ($HTTP_SESSION_VARS と $_SESSION は異なる変数であり、PHP はこれらを異なる変数として扱うことに注意してください)。

変更履歴

バージョン 説明
4.1.0 $_SESSION が導入され、 $HTTP_SESSION_VARS は非推奨となりました。

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

  • session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する

$_ENV

$HTTP_ENV_VARS [非推奨]

(PHP 4 >= 4.1.0, PHP 5)

$_ENV -- $HTTP_ENV_VARS [非推奨] — 環境変数

説明

環境変数として現在のスクリプトに渡された変数の連想配列です。

これらの変数は PHP パーサが実行されている環境から PHP のグローバル名前空間に取り込まれます。 その多くは、PHP が実行されているシェルに由来するものであり、 システムが違えばシェルも違ってくるため、確定的なリストを 得ることは不可能です。定義されている環境変数のリストについては 使用しているシェルのドキュメントをご覧ください。

CGI 変数を含むその他の環境変数も、 PHP がサーバーモジュールとして実行されているか CGI プロセッサとして 実行されているかに関わらずここに含まれます。

$HTTP_ENV_VARS は同じ情報を持っていますが、 これはスーパーグローバルではありません ($HTTP_ENV_VARS と $_ENV は違う変数であり、PHP はそれぞれ別に扱います)。

変更履歴

バージョン 説明
4.1.0 $_ENV が導入され、 $HTTP_ENV_VARS は非推奨となりました。

例

例1 $_ENV の例

<?php
echo 'My username is ' .$_ENV["USER"] . '!';
?>

"bjori" がこのスクリプトを実行したとします。

上の例の出力は、 たとえば以下のようになります。

My username is bjori!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

参考

$_COOKIE

$HTTP_COOKIE_VARS [非推奨]

(PHP 4 >= 4.1.0, PHP 5)

$_COOKIE -- $HTTP_COOKIE_VARS [非推奨] — HTTP クッキー

説明

現在のスクリプトに HTTP クッキーから渡された変数の連想配列です。

$HTTP_COOKIE_VARS は同じ情報を持っていますが、 これはスーパーグローバルではありません ($HTTP_COOKIE_VARS と $_COOKIE は違う変数であり、PHP はそれぞれ別に扱います)。

変更履歴

バージョン 説明
4.1.0 $_COOKIE が導入され、 $HTTP_COOKIE_VARS は非推奨となりました。

例

例1 $_COOKIE の例

<?php
echo 'Hello ' . htmlspecialchars($_COOKIE["name"]) . '!';
?>

"name" というクッキーが事前に設定されているものとします。

上の例の出力は、 たとえば以下のようになります。

Hello Hannes!

注意

注意:

これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

$php_errormsg

(PHP 4, PHP 5)

$php_errormsg — 直近のエラーメッセージ

説明

$php_errormsg は、PHP によって発せられた 最後のエラーメッセージのテキストを格納する変数です。 エラーが発生したスコープ内、かつ track_errors 設定オプションが オン (デフォルトはオフ) にセットされている場合にのみ有効です。

注意: この変数は、track_errors が php.ini で有効になっている場合にのみ使用可能です。

警告

ユーザー定義のエラーハンドラ (set_error_handler()) が設定されている場合は、$php_errormsg はエラーハンドラが FALSE を返した場合にのみ設定されます。

例

例1 $php_errormsg の例

<?php
@strpos();
echo $php_errormsg;
?>

上の例の出力は、 たとえば以下のようになります。

Wrong parameter count for strpos()

$HTTP_RAW_POST_DATA

(PHP 4, PHP 5)

$HTTP_RAW_POST_DATA — 生の POST データ

説明

$HTTP_RAW_POST_DATA には生の POST データが格納されます。 always_populate_raw_post_data も参照ください。

$http_response_header

(PHP 4 >= 4.0.4, PHP 5)

$http_response_header — HTTP レスポンスヘッダ

説明

$http_response_header 配列は get_headers() 関数と似ています。 HTTP ラッパー を使用する際に、$http_response_header に HTTP レスポンスヘッダが格納されます。 $http_response_header は ローカルスコープ で作成されます。

例

例1 $http_response_header の例

<?php
function get_contents() {
  file_get_contents("http://example.com");
  var_dump($http_response_header);
}
get_contents();
var_dump($http_response_header);
?>

上の例の出力は、 たとえば以下のようになります。

array(9) {
  [0]=>
  string(15) "HTTP/1.1 200 OK"
  [1]=>
  string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
  [2]=>
  string(29) "Server: Apache/2.2.3 (CentOS)"
  [3]=>
  string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
  [4]=>
  string(27) "ETag: "280100-1b6-80bfd280""
  [5]=>
  string(20) "Accept-Ranges: bytes"
  [6]=>
  string(19) "Content-Length: 438"
  [7]=>
  string(17) "Connection: close"
  [8]=>
  string(38) "Content-Type: text/html; charset=UTF-8"
}
NULL

$argc

(PHP 4, PHP 5)

$argc — スクリプトに渡された引数の数

説明

コマンドラインから実行したときに、 現在のスクリプトに渡された引数の数が含まれます。

注意: スクリプトのファイル名は、常にスクリプトへの引数として渡されます。 したがって、$argc の最小値は 1 です。

注意: この変数は、register_argc_argv が無効になっている場合には使えません。

例

例1 $argc の例

<?php
var_dump($argc);
?>

このサンプルを php script.php arg1 arg2 arg3 と実行します。

上の例の出力は、 たとえば以下のようになります。

int(4)

$argv

(PHP 4, PHP 5)

$argv — スクリプトに渡された引数の配列

説明

コマンドラインから実行したときに、 現在のスクリプトに渡されたすべての引数の配列が含まれます。

注意: 最初の引数 $argv[0] は常に、スクリプトの実行に使う名前となります。

注意: この変数は、register_argc_argv が無効になっている場合には使えません。

例

例1 $argv の例

<?php
var_dump($argv);
?>

このサンプルを php script.php arg1 arg2 arg3 と実行します。

上の例の出力は、 たとえば以下のようになります。

array(4) {
  [0]=>
  string(10) "script.php"
  [1]=>
  string(4) "arg1"
  [2]=>
  string(4) "arg2"
  [3]=>
  string(4) "arg3"
}

参考

  • getopt() - コマンドライン引数のリストからオプションを取得する

目次

定義済みの例外

目次

SPL の例外 も参照ください。

Exception

(PHP 5 >= 5.1.0)

導入

Exception は、すべての例外の基底クラスです。

クラス概要

Exception {
/* プロパティ */
protected string $message ;
protected int $code ;
protected string $file ;
protected int $line ;
/* メソッド */
public __construct ([ string $message = "" [, int $code = 0 [, Exception $previous = NULL ]]] )
final public string getMessage ( void )
final public Exception getPrevious ( void )
final public mixed getCode ( void )
final public string getFile ( void )
final public int getLine ( void )
final public array getTrace ( void )
final public string getTraceAsString ( void )
public string __toString ( void )
final private void __clone ( void )
}

プロパティ

message

例外メッセージ

code

例外コード

file

例外が作られたファイル名

line

例外が作られた行

Exception::__construct

(PHP 5 >= 5.1.0)

Exception::__construct — 例外を作成する

説明

public Exception::__construct() ([ string $message = "" [, int $code = 0 [, Exception $previous = NULL ]]] )

例外を作成します。

パラメータ

message

スローする例外メッセージ。

code

例外コード。

previous

以前に使われた例外。例外の連結に使用します。

変更履歴

バージョン 説明
5.3.0 previous パラメータが追加されました。

注意

注意:

message は、バイナリセーフ ではありません。

Exception::getMessage

(PHP 5 >= 5.1.0)

Exception::getMessage — 例外メッセージを取得する

説明

final public string Exception::getMessage ( void )

例外メッセージを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外メッセージ文字列を返します。

例

例1 Exception::getMessage() の例

<?php
try {
    throw new Exception("Some error message");
} catch(Exception $e) {
    echo $e->getMessage();
}
?>

上の例の出力は、 たとえば以下のようになります。

Some error message

Exception::getPrevious

(PHP 5 >= 5.3.0)

Exception::getPrevious — 前の例外を返す

説明

final public Exception Exception::getPrevious ( void )

前に発生した例外 ( Exception::__construct() の 3 番目の引数) を返します。

パラメータ

この関数にはパラメータはありません。

返り値

前に発生した Exception、あるいはそれが存在しない場合は NULL を返します。

例

例1 Exception::getPrevious() の例

例外トレースをループし、表示します。

<?php
class MyCustomException extends Exception {}

function doStuff() {
    try {
        throw new InvalidArgumentException("You are doing it wrong!", 112);
    } catch(Exception $e) {
        throw new MyCustomException("Something happend", 911, $e);
    }
}


try {
    doStuff();
} catch(Exception $e) {
    do {
        printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
    } while($e = $e->getPrevious());
}
?>

上の例の出力は、 たとえば以下のようになります。

/home/bjori/ex.php:8 Something happend (911) [MyCustomException]
/home/bjori/ex.php:6 You are doing it wrong! (112) [InvalidArgumentException]

Exception::getCode

(PHP 5 >= 5.1.0)

Exception::getCode — 例外コードを取得する

説明

final public mixed Exception::getCode ( void )

例外コードを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外コードを整数値で返します。しかし、 Exception クラスを継承したクラスでは、違う型を返すこともあります (たとえば PDOException は文字列を返します)。

例

例1 Exception::getCode() の例

<?php
try {
    throw new Exception("Some error message", 30);
} catch(Exception $e) {
    echo "The exception code is: " . $e->getCode();
}
?>

上の例の出力は、 たとえば以下のようになります。

The exception code is: 30

Exception::getFile

(PHP 5 >= 5.1.0)

Exception::getFile — 例外が発生したファイルを取得する

説明

final public string Exception::getFile ( void )

例外が作られたファイルの名前を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

例外が作られたファイルの名前を返します。

例

例1 Exception::getFile() の例

<?php
try {
    throw new Exception;
} catch(Exception $e) {
    echo $e->getFile();
}
?>

上の例の出力は、 たとえば以下のようになります。

/home/bjori/tmp/ex.php

Exception::getLine

(PHP 5 >= 5.1.0)

Exception::getLine — 例外が発生した行を取得する

説明

final public int Exception::getLine ( void )

例外が作られた行番号を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

例外が作られた行番号を返します。

例

例1 Exception::getLine() の例

<?php
try {
    throw new Exception("Some error message");
} catch(Exception $e) {
    echo "The exception was created on line: " . $e->getLine();
}
?>

上の例の出力は、 たとえば以下のようになります。

The exception was created on line: 3

Exception::getTrace

(PHP 5 >= 5.1.0)

Exception::getTrace — スタックトレースを取得する

説明

final public array Exception::getTrace ( void )

例外のスタックトレースを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外のスタックトレースを配列で返します。

例

例1 Exception::getTrace() の例

<?php
function test() {
 throw new Exception;
}

try {
 test();
} catch(Exception $e) {
 var_dump($e->getTrace());
}
?>

上の例の出力は、 たとえば以下のようになります。

array(1) {
  [0]=>
  array(4) {
    ["file"]=>
    string(22) "/home/bjori/tmp/ex.php"
    ["line"]=>
    int(7)
    ["function"]=>
    string(4) "test"
    ["args"]=>
    array(0) {
    }
  }
}

Exception::getTraceAsString

(PHP 5 >= 5.1.0)

Exception::getTraceAsString — スタックトレースを文字列で取得する

説明

final public string Exception::getTraceAsString ( void )

例外のスタックトレースを文字列で返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外のスタックトレースを文字列で返します。

例

例1 Exception::getTraceAsString() の例

<?php
function test() {
    throw new Exception;
}

try {
    test();
} catch(Exception $e) {
    echo $e->getTraceAsString();
}
?>

上の例の出力は、 たとえば以下のようになります。

#0 /home/bjori/tmp/ex.php(7): test()
#1 {main}

Exception::__toString

(PHP 5 >= 5.1.0)

Exception::__toString — 例外の文字列表現

説明

public string Exception::__toString ( void )

例外を文字列で表現したものを返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外を文字列で表現したものを返します。

例

例1 Exception::__toString() の例

<?php
try {
    throw new Exception("Some error message");
} catch(Exception $e) {
    echo $e;
}
?>

上の例の出力は、 たとえば以下のようになります。

exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}

Exception::__clone

(PHP 5 >= 5.1.0)

Exception::__clone — 例外をコピーする

説明

final private void Exception::__clone ( void )

例外のコピーを作成しようとします。結果としてこれは Fatal エラーとなります。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

エラー / 例外

例外はクローン不可能です。

目次

ErrorException

(PHP 5 >= 5.1.0)

導入

エラー例外です。

クラス概要

ErrorException extends Exception {
/* プロパティ */
protected int $severity ;
/* メソッド */
public __construct ([ string $message = "" [, int $code = 0 [, int $severity = 1 [, string $filename = __FILE__ [, int $lineno = __LINE__ [, Exception $previous = NULL ]]]]]] )
final public int getSeverity ( void )
/* 継承したメソッド */
final public string Exception::getMessage ( void )
final public Exception Exception::getPrevious ( void )
final public mixed Exception::getCode ( void )
final public string Exception::getFile ( void )
final public int Exception::getLine ( void )
final public array Exception::getTrace ( void )
final public string Exception::getTraceAsString ( void )
public string Exception::__toString ( void )
final private void Exception::__clone ( void )
}

プロパティ

severity

例外の深刻度

例

例1 set_error_handler() を使用した、エラーメッセージから ErrorException への変換

<?php
function exception_error_handler($errno, $errstr, $errfile, $errline ) {
    throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
}
set_error_handler("exception_error_handler");

/* 例外を発生させます */
strpos();
?>

上の例の出力は、 たとえば以下のようになります。

Fatal error: Uncaught exception 'ErrorException' with message 'Wrong parameter count for strpos()' in /home/bjori/tmp/ex.php:8
Stack trace:
#0 [internal function]: exception_error_handler(2, 'Wrong parameter...', '/home/bjori/php...', 8, Array)
#1 /home/bjori/php/cleandocs/test.php(8): strpos()
#2 {main}
  thrown in /home/bjori/tmp/ex.php on line 8

ErrorException::__construct

(PHP 5 >= 5.1.0)

ErrorException::__construct — 例外を作成する

説明

public ErrorException::__construct() ([ string $message = "" [, int $code = 0 [, int $severity = 1 [, string $filename = __FILE__ [, int $lineno = __LINE__ [, Exception $previous = NULL ]]]]]] )

例外を作成します。

パラメータ

message

スローする例外メッセージ。

code

例外コード。

severity

例外の深刻度。

filename

例外がスローされたファイル名。

lineno

例外がスローされた行番号。

previous

ひとつ前の例外。例外の連結に使います。

ErrorException::getSeverity

(PHP 5 >= 5.1.0)

ErrorException::getSeverity — 例外の深刻度を取得する

説明

final public int ErrorException::getSeverity ( void )

例外の深刻度を返します。

パラメータ

この関数にはパラメータはありません。

返り値

例外の深刻度レベルを返します。

例

例1 ErrorException::getSeverity() の例

<?php
try {
    throw new ErrorException("Exception message", 0, 75);
} catch(ErrorException $e) {
    echo "This exception severity is: " . $e->getSeverity();
}
?>

上の例の出力は、 たとえば以下のようになります。

This exception severity is: 75

目次

定義済みのインターフェイス

目次

SPL インターフェイス も参照ください。

Traversable インターフェイス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

そのクラスの中身が foreach を使用してたどれるかどうかを検出するインターフェイスです。

これは抽象インターフェイスであり、単体で実装することはできません。 IteratorAggregate あるいは Iterator を実装しなければなりません。

注意:

このインターフェイスを実装した内部クラス (組み込みクラス) は foreach で使用することができます。 IteratorAggregate や Iterator を実装する必要はありません。

注意:

これは内部エンジンのインターフェイスであり、PHP スクリプトないで実装することはできません。 そのかわりに IteratorAggregate あるいは Iterator を使用しなければなりません。

インターフェイス概要

Traversable {
}

このインターフェイスにはメソッドがありません。 traverse 可能なすべてのクラス用の基底インターフェイスとしてのみ存在しています。

Iterator インターフェイス

(PHP 5 >= 5.0.0)

導入

外部のイテレータあるいはオブジェクト自身から反復処理を行うためのインターフェイスです。

インターフェイス概要

Iterator extends Traversable {
/* メソッド */
abstract public mixed current ( void )
abstract public scalar key ( void )
abstract public void next ( void )
abstract public void rewind ( void )
abstract public boolean valid ( void )
}

定義済みのイテレータ

PHP には多くのイテレータがあらかじめ用意されており、日々の作業に使えます。その一覧は SPL イテレータ を参照ください。

例

例1 基本的な使用法

この例は、イテレータで foreach を使用したときに order メソッドがコールされる様子を示すものです。

<?php
class myIterator implements Iterator {
    private $position = 0;
    private $array = array(
        "firstelement",
        "secondelement",
        "lastelement",
    );  

    public function __construct() {
        $this->position = 0;
    }

    function rewind() {
        var_dump(__METHOD__);
        $this->position = 0;
    }

    function current() {
        var_dump(__METHOD__);
        return $this->array[$this->position];
    }

    function key() {
        var_dump(__METHOD__);
        return $this->position;
    }

    function next() {
        var_dump(__METHOD__);
        ++$this->position;
    }

    function valid() {
        var_dump(__METHOD__);
        return isset($this->array[$this->position]);
    }
}

$it = new myIterator;

foreach($it as $key => $value) {
    var_dump($key, $value);
    echo "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

string(18) "myIterator::rewind"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(0)
string(12) "firstelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(1)
string(13) "secondelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"
string(19) "myIterator::current"
string(15) "myIterator::key"
int(2)
string(11) "lastelement"

string(16) "myIterator::next"
string(17) "myIterator::valid"

Iterator::current

(PHP 5 >= 5.0.0)

Iterator::current — 現在の要素を返す

説明

abstract public mixed Iterator::current ( void )

現在の要素を返します。

パラメータ

この関数にはパラメータはありません。

返り値

あらゆる型を返すことが可能です。

Iterator::key

(PHP 5 >= 5.0.0)

Iterator::key — 現在の要素のキーを返す

説明

abstract public scalar Iterator::key ( void )

現在の要素のキーを返します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合にスカラー型、失敗した場合に NULL を返します。

エラー / 例外

失敗した場合に E_NOTICE を発行します。

Iterator::next

(PHP 5 >= 5.0.0)

Iterator::next — 次の要素に進む

説明

abstract public void Iterator::next ( void )

現在位置を次の要素に移動します。

注意:

このメソッドは、各 foreach ループの 後 にコールされます。

パラメータ

この関数にはパラメータはありません。

返り値

返り値は無視されます。

Iterator::rewind

(PHP 5 >= 5.0.0)

Iterator::rewind — イテレータの最初の要素に巻き戻す

説明

abstract public void Iterator::rewind ( void )

イテレータの最初の要素に巻き戻します。

注意:

これは、foreach ループの開始時に 最初 にコールされるメソッドです。 foreach ループの 後 には実行 されません。

パラメータ

この関数にはパラメータはありません。

返り値

返り値は無視されます。

Iterator::valid

(PHP 5 >= 5.0.0)

Iterator::valid — 現在位置が有効かどうかを調べる

説明

abstract public boolean Iterator::valid ( void )

このメソッドは Iterator::rewind() および Iterator::next() の後にコールされ、 現在の位置が有効化どうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

返り値は boolean にキャストして評価されます。 成功した場合に TRUE を、失敗した場合に FALSE を返します。

目次

IteratorAggregate インターフェイス

(PHP 5 >= 5.0.0)

導入

外部イテレータを作成するためのインターフェイスです。

インターフェイス概要

IteratorAggregate extends Traversable {
/* メソッド */
abstract public Traversable getIterator ( void )
}

例1 基本的な例

<?php
class myData implements IteratorAggregate {
    public $property1 = "Public property one";
    public $property2 = "Public property two";
    public $property3 = "Public property three";

    public function __construct() {
        $this->property4 = "last property";
    }

    public function getIterator() {
        return new ArrayIterator($this);
    }
}

$obj = new myData;

foreach($obj as $key => $value) {
    var_dump($key, $value);
    echo "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

string(9) "property1"
string(19) "Public property one"

string(9) "property2"
string(19) "Public property two"

string(9) "property3"
string(21) "Public property three"

string(9) "property4"
string(13) "last property"

IteratorAggregate::getIterator

(PHP 5 >= 5.0.0)

IteratorAggregate::getIterator — 外部イテレータを取得する

説明

abstract public Traversable IteratorAggregate::getIterator ( void )

外部イテレータを返します。

パラメータ

この関数にはパラメータはありません。

返り値

Iterator あるいは Traversable を実装したオブジェクトのインスタンスを返します。

エラー / 例外

失敗した場合は Exception をスローします。

目次

ArrayAccess インターフェイス

(PHP 5 >= 5.0.0)

導入

配列としてオブジェクトにアクセスするための機能のインターフェイスです。

インターフェイス概要

ArrayAccess {
/* メソッド */
abstract public boolean offsetExists ( mixed $offset )
abstract public mixed offsetGet ( mixed $offset )
abstract public void offsetSet ( mixed $offset , mixed $value )
abstract public void offsetUnset ( mixed $offset )
}

例1 基本的な使用法

<?php
class obj implements arrayaccess {
    private $container = array();
    public function __construct() {
        $this->container = array(
            "one"   => 1,
            "two"   => 2,
            "three" => 3,
        );
    }
    public function offsetSet($offset, $value) {
        if (is_null($offset)) {
            $this->container[] = $value;
        } else {
            $this->container[$offset] = $value;
        }
    }
    public function offsetExists($offset) {
        return isset($this->container[$offset]);
    }
    public function offsetUnset($offset) {
        unset($this->container[$offset]);
    }
    public function offsetGet($offset) {
        return isset($this->container[$offset]) ? $this->container[$offset] : null;
    }
}

$obj = new obj;

var_dump(isset($obj["two"]));
var_dump($obj["two"]);
unset($obj["two"]);
var_dump(isset($obj["two"]));
$obj["two"] = "A value";
var_dump($obj["two"]);
$obj[] = 'Append 1';
$obj[] = 'Append 2';
$obj[] = 'Append 3';
print_r($obj);
?>

上の例の出力は、 たとえば以下のようになります。

bool(true)
int(2)
bool(false)
string(7) "A value"
obj Object
(
    [container:obj:private] => Array
        (
            [one] => 1
            [three] => 3
            [two] => A value
            [0] => Append 1
            [1] => Append 2
            [2] => Append 3
        )

)

ArrayAccess::offsetExists

(PHP 5 >= 5.0.0)

ArrayAccess::offsetExists — オフセットが存在するかどうか

説明

abstract public boolean ArrayAccess::offsetExists ( mixed $offset )

オフセットが存在するかどうかを返します。

このメソッドが実行されるのは、ArrayAccess を実装したオブジェクト上で isset() あるいは empty() を使用した場合です。

注意:

empty() を使用すると ArrayAccess::offsetGet() がコールされ、ArrayAccess::offsetExists() が TRUE を返すかどうかで空かどうかを判断します。

パラメータ

offset

調べたいオフセット。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

注意:

非 boolean 値が返された場合は boolean にキャストして返します。

例

例1 ArrayAccess::offsetExists() の例

<?php
class obj implements arrayaccess {
    public function offsetSet($offset, $value) {
        var_dump(__METHOD__);
    }
    public function offsetExists($var) {
        var_dump(__METHOD__);
        if ($var == "foobar") {
            return true;
        }
        return false;
    }
    public function offsetUnset($var) {
        var_dump(__METHOD__);
    }
    public function offsetGet($var) {
        var_dump(__METHOD__);
        return "value";
    }
}

$obj = new obj;

echo "Runs obj::offsetExists()\n";
var_dump(isset($obj["foobar"]));

echo "\nRuns obj::offsetExists() and obj::offsetGet()\n";
var_dump(empty($obj["foobar"]));

echo "\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
var_dump(empty($obj["foobaz"]));
?>

上の例の出力は、 たとえば以下のようになります。

Runs obj::offsetExists()
string(17) "obj::offsetExists"
bool(true)

Runs obj::offsetExists() and obj::offsetGet()
string(17) "obj::offsetExists"
string(14) "obj::offsetGet"
bool(false)

Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get
string(17) "obj::offsetExists"
bool(true)

ArrayAccess::offsetGet

(PHP 5 >= 5.0.0)

ArrayAccess::offsetGet — オフセットを取得する

説明

abstract public mixed ArrayAccess::offsetGet ( mixed $offset )

指定したオフセットの値を返します。

このメソッドは、オフセットが empty() かどうかを調べる際に実行されます。

パラメータ

offset

取得したいオフセット。

注意

注意:

PHP 5.3.4 以降ではプロトタイプのチェックが緩和され、 このメソッドの実装で参照を返せるようになりました。 これにより、ArrayAccess オブジェクトのオーバーロードされた配列に対する間接的な変更ができるようになりました。

直接的な変更とは、$obj[6] = 7 のように配列のその次元の値を完全に置き換える変更のことです。 一方、間接的な変更とは、$obj[6][7] = 7 のようにその次元の一部分のみを変更したり $var =& $obj[6] のように他の変数に参照を代入したりする変更のことです。 ++ によるインクリメントや -- によるデクリメントもまた、ある意味では間接的な変更を要するものです。

直接的な変更の際には ArrayAccess::offsetSet() がコールされますが、間接的な変更の際には ArrayAccess::offsetGet() がコールされます。この場合は ArrayAccess::offsetGet() の実装が参照を返せるようにしておく必要があります。 そうしなければ E_NOTICE メッセージが発生します。

返り値

すべての型の値を返すことができます。

参考

ArrayAccess::offsetSet

(PHP 5 >= 5.0.0)

ArrayAccess::offsetSet — オフセットを設定する

説明

abstract public void ArrayAccess::offsetSet ( mixed $offset , mixed $value )

指定したオフセットに値を代入します。

パラメータ

offset

値を代入したいオフセット。

value

設定したい値。

返り値

値を返しません。

注意

注意:

下記の例のように、もし他の値が利用できなければ、 offset パラメータは NULL に設定されます。

<?php
$arrayaccess[] = "first value";
$arrayaccess[] = "second value";
print_r($arrayaccess);
?>

上の例の出力は以下となります。

Array
(
    [0] => first value
    [1] => second value
)

注意:

この関数は、参照による代入の場合にはコールされません。また、 ArrayAccess でオーバーロードした配列の次元への間接的な変更 (間接的な変更とは、その次元を直接変更するのではなく 下位の次元やプロパティを変更したり、配列の次元を別の変数に参照で代入したりすることです) の場合にもコールされません。これらの場合は、かわりに ArrayAccess::offsetGet() がコールされます。 この操作が成功するのはメソッドが参照を返せるようになっているときだけで、 参照を返せるようになるのは PHP 5.3.4 以降を使っている場合のみです。

ArrayAccess::offsetUnset

(PHP 5 >= 5.0.0)

ArrayAccess::offsetUnset — オフセットの設定を解除する

説明

abstract public void ArrayAccess::offsetUnset ( mixed $offset )

オフセットの設定を解除します。

注意:

このメソッドは、 (unset) による型キャストの際にはコール されません。

パラメータ

offset

設定解除したいオフセット。

返り値

値を返しません。

目次

Serializable インターフェイス

(PHP 5 >= 5.1.0)

導入

独自のシリアライズ用のインターフェイスです。

このインターフェイスを実装したクラスは __sleep() や __wakeup() をサポートしなくなります。 シリアライズが必要な場合には、自動的に serialize メソッドがコールされます。 このメソッドは __destruct() を実行しません。また、 メソッド内で明示的に書かない限りは一切の副作用を及ぼしません。 アンシリアライズされるときにはそのクラスが自動的に検知し、__construct() メソッドのかわりに適切な unserialize() メソッドがコールされます。 標準のコンストラクタを実行させたい場合は、unserialize() メソッドの中でそれをコールします。

インターフェイス概要

Serializable {
/* メソッド */
abstract public string serialize ( void )
abstract public void unserialize ( string $serialized )
}

例1 基本的な使用法

<?php
class obj implements Serializable {
    private $data;
    public function __construct() {
        $this->data = "My private data";
    }
    public function serialize() {
        return serialize($this->data);
    }
    public function unserialize($data) {
        $this->data = unserialize($data);
    }
    public function getData() {
        return $this->data;
    }
}

$obj = new obj;
$ser = serialize($obj);

var_dump($ser);

$newobj = unserialize($ser);

var_dump($newobj->getData());
?>

上の例の出力は、 たとえば以下のようになります。

string(38) "C:3:"obj":23:{s:15:"My private data";}"
string(15) "My private data"

Serializable::serialize

(PHP 5 >= 5.1.0)

Serializable::serialize — オブジェクトの文字列表現

説明

abstract public string Serializable::serialize ( void )

オブジェクトを文字列であらわしたものを返します。

注意:

このメソッドは、オブジェクトの デストラクタ として働きます。 このメソッドの後に __destruct() メソッドがコールされることは ありません。 method.

パラメータ

この関数にはパラメータはありません。

返り値

オブジェクトの文字列表現、あるいは NULL を返します。

エラー / 例外

Throws Exception when returning other types then strings and NULL

参考

Serializable::unserialize

(PHP 5 >= 5.1.0)

Serializable::unserialize — オブジェクトを作成する

説明

abstract public void Serializable::unserialize ( string $serialized )

オブジェクトのアンシリアライズ時にコールされます。

注意:

このメソッドは、オブジェクトの コンストラクタ として働きます。 このメソッドの後に __construct() メソッドがコールされることは ありません。

パラメータ

serialized

オブジェクトの文字列表現。

返り値

このメソッドの返り値は無視されます。

参考

目次

Closure クラス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

無名関数 を表すために使うクラスです。

無名関数は PHP 5.3 で実装された機能で、この型のオブジェクトを生成します。 かつてこれは、内部実装がたまたまそうなっているだけという扱いでした。 しかし今では、この事実を前提として考慮してもかまいません。 PHP 5.4 以降ではこのクラスにメソッドが用意され、 生成した無名関数をさらにコントロールできるようになります。

ここであげたメソッド以外にも、このクラスには __invoke メソッドが存在します。 これは、マジックコール を実装した他のクラスとの一貫性を保つためのものであり、 関数をコールするときにこのメソッドは使われません。

クラス概要

Closure {
/* メソッド */
__construct ( void )
public static Closure bind ( Closure $closure , object $newthis [, mixed $newscope = 'static' ] )
public Closure bindTo ( object $newthis [, mixed $newscope = 'static' ] )
}

Closure::__construct

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

Closure::__construct — インスタンス作成を無効化したコンストラクタ

説明

Closure::__construct ( void )

このメソッドは、 Closure クラスのインスタンスを作れないようにするために存在します。 このクラスのオブジェクトを作るには、 無名関数 のページに書かれている手順を使います。

パラメータ

この関数にはパラメータはありません。

返り値

このメソッドは値を返しません。単に (E_RECOVERABLE_ERROR 型の) エラーが発生するだけです。

参考

Closure::bind

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

Closure::bind — バインドされたオブジェクトとクラスのスコープでクロージャを複製する

説明

public static Closure Closure::bind ( Closure $closure , object $newthis [, mixed $newscope = 'static' ] )

このメソッドは、静的メソッド版の Closure::bindTo() です。 詳細な説明は Closure::bindTo() のドキュメントを参照ください。

パラメータ

closure

バインドする無名関数。

newthis

指定した無名関数をバインドするオブジェクト。クロージャのバインドを解除するには NULL を指定します。

newscope

クロージャを関連づけるクラススコープ、あるいは 'static' で現在のスコープを維持します。 オブジェクトを渡した場合は、そのオブジェクトの型をその代わりに使います。 これは、バインドしたオブジェクトの protected メソッドや private メソッドの可視性を決めます。

返り値

新しい Closure オブジェクトを返します。 失敗した場合に FALSE を返します

例

例1 Closure::bind() の例

<?php
class A {
    private static $sfoo = 1;
    private $ifoo = 2;
}
$cl1 = static function() {
    return A::$sfoo;
};
$cl2 = function() {
    return $this->ifoo;
};

$bcl1 = Closure::bind($cl1, null, 'A');
$bcl2 = Closure::bind($cl2, new A(), 'A');
echo $bcl1(), "\n";
echo $bcl2(), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1
2

参考

Closure::bindTo

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

Closure::bindTo — 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

説明

public Closure Closure::bindTo ( object $newthis [, mixed $newscope = 'static' ] )

自身と同じ本体とバインド変数を持つ新しい 無名関数 を作って返します。しかし、バインドするオブジェクトは変わって新しいクラスのスコープとなります。

“バインドするオブジェクト” によって、$this が関数本体で持つ値が決まり、“クラスのスコープ” は、無名関数からどのクラスの private メンバーや protected メンバーにアクセスできるのかが決まります。 すなわち、無名関数から見えるメンバーは、 その無名関数が newscope クラスのメソッドであった場合と同じものになります。

静的なクロージャは何もオブジェクトをバインドできません (newthis の値は NULL でなければなりません) が、 それでもこの関数を使ってクラスのスコープを変えることができます。

この関数が静的でないクロージャに関して保証するのは、 バインドされたインスタンスを持っていればスコープ内にあるということです。 また、その逆も成り立ちます。そのため、静的でないクロージャにスコープとして NULL インスタンスを渡すとそれは静的となり、静的でなくスコープにもないクロージャに NULL でないインスタンスを渡すと、特定されていない何らかのクラスのスコープに入ります。

注意:

単に無名関数を複製したいだけの場合は、 cloning を使うこともできます。

パラメータ

newthis

指定した無名関数をバインドするオブジェクト。クロージャのバインドを解除するには NULL を指定します。

newscope

クロージャを関連づけるクラススコープ、あるいは 'static' で現在のスコープを維持します。 オブジェクトを渡した場合は、そのオブジェクトの型をその代わりに使います。 これは、バインドしたオブジェクトの protected メソッドや private メソッドの可視性を決めます。

返り値

新しい Closure オブジェクトを返します。 失敗した場合に FALSE を返します

例

例1 Closure::bindTo() の例

<?php

class A {
    function __construct($val) {
        $this->val = $val;
    }
    function getClosure() {
        // このオブジェクトとスコープにバインドしたクロージャを返します。
        return function() { return $this->val; };
    }
}

$ob1 = new A(1);
$ob2 = new A(2);

$cl = $ob1->getClosure();
echo $cl(), "\n";
$cl = $cl->bindTo($ob2);
echo $cl(), "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1
2

参考

目次

  • Closure::__construct — インスタンス作成を無効化したコンストラクタ
  • Closure::bind — バインドされたオブジェクトとクラスのスコープでクロージャを複製する
  • Closure::bindTo — 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

コンテキストオプションとパラメータ

PHP にはさまざまなコンテキストオプションやパラメータがあり、 すべてのファイルシステムラッパーおよびストリームラッパーで使用することができます。 コンテキストの作成は stream_context_create() で行います。オプションの設定は stream_context_set_option() で、そしてパラメータの設定は stream_context_set_params() で行います。

ソケットコンテキストオプション

ソケットコンテキストオプション — ソケットコンテキストオプション一覧

説明

ここでは、ソケット越しに動作するラッパー すなわち tcp、http あるいは ftp でサポートされるオプションを扱います。

オプション

bindto

PHP がネットワークにアクセスする際の IP アドレス (IPv4 あるいは IPv6 のどちらか）やポート番号を指定する際に使用されます。 その書式は ip:port（IP やポート番号に 0 を指定すると、それをシステムに自動的に設定させる ことができます) です。

注意:

FTP の通常の操作では 2 つのソケット接続を使用するので、 このオプションでポート番号を指定することができません。

backlog

ソケットのリスンキューから出て行く接続の数を制限します。

注意:

stream_socket_server() でのみ有効です。

変更履歴

バージョン 説明
5.1.0 bindto が追加されました。
5.3.3 backlog が追加されました。

例

例1 基本的な bindto の使用例

<?php
// IP アドレス '192.168.0.100' でインターネットに接続する
$opts = array(
    'socket' => array(
        'bindto' => '192.168.0.100:0',
    ),
);


// IP アドレス '192.168.0.100' とポート番号 '7000' でインターネットに接続する
$opts = array(
    'socket' => array(
        'bindto' => '192.168.0.100:7000',
    ),
);


// ポート番号 '7000' でインターネットに接続する
$opts = array(
    'socket' => array(
        'bindto' => '0:7000',
    ),
);


// コンテキストを作成し…
$context = stream_context_create($opts);

// …そしてデータを取得するためにそれを使用する
echo file_get_contents('http://www.example.com', false, $context);

?>

HTTP コンテキストオプション

HTTP コンテキストオプション — HTTP コンテキストオプションの一覧

説明

http:// および https:// トランスポート用のコンテキストオプションです。

オプション

method string

リモートサーバーでサポートされる GET、 POST あるいはその他の HTTP メソッド。

デフォルトは GET です。

header string

リクエストに付加されるヘッダ。ここで指定した値が (User-agent:、Host:、 および Authentication: などの) 他の値を上書きすることもあります。

user_agent string

User-Agent: ヘッダとして送信する値。上で説明した header オプションで user-agent が 定義されていない場合のみ使用されます。

デフォルトでは、php.ini の user_agent の設定内容を使用します。

content string

ヘッダの後に送信する追加データ。通常、POST または PUT リクエストの際に使用されます。

proxy string

プロキシサーバーを示す URI (例: tcp://proxy.example.com:5100)。

request_fulluri boolean

TRUE を指定すると、リクエストを生成する際に完全な URI (GET http://www.example.com/path/to/file.html HTTP/1.0) が用いられます。これは標準のリクエストフォーマットではありませんが、 このようなフォーマットを要求するプロキシサーバーも存在します。

デフォルトは FALSE です。

follow_location integer

Location: .. のリダイレクトをたどります。

デフォルトは TRUE です。

max_redirects integer

リダイレクトをたどる最大数。値が 1 以下の場合は リダイレクトをたどらないことを意味します。

デフォルトは 20 です。

protocol_version float

HTTP プロトコルのバージョン。

デフォルトは 1.0 です。

注意:

5.3.0 より前のバージョンの PHP では chunked transfer decoding を実装していません。 この値を 1.1 に設定するなら、 1.1 準拠にするのは自分の責任となります。

timeout float

読み込みタイムアウト秒数を float (例 10.5) で指定します。

デフォルトでは php.ini 設定 default_socket_timeout の値を使用します。

ignore_errors boolean

ステータスコードが失敗を意味する場合でもコンテンツを取得します。

デフォルトは FALSE です。

変更履歴

バージョン 説明
5.3.4 follow_location が追加されました。
5.3.0 protocol_version に 1.1 を設定した場合に、 chuned transfer decoding をサポートするようになりました。
5.2.10 ignore_errors が追加されました。
5.2.10 header に数値添字の配列を使用できるようになりました。
5.2.1 timeout が追加されました。
5.1.0 HTTP プロキシを使用した HTTPS のプロキシが追加されました。
5.1.0 max_redirects が追加されました。
5.1.0 protocol_version が追加されました。

例

例1 ページの取得と POST データの送信

<?php

$postdata = http_build_query(
    array(
        'var1' => 'some content',
        'var2' => 'doh'
    )
);

$opts = array('http' =>
    array(
        'method'  => 'POST',
        'header'  => 'Content-type: application/x-www-form-urlencoded',
        'content' => $postdata
    )
);

$context = stream_context_create($opts);

$result = file_get_contents('http://example.com/submit.php', false, $context);

?>

例2 リダイレクトを無視し、ヘッダとコンテンツの取得

<?php

$url = "http://www.example.org/header.php";

$opts = array('http' =>
    array(
        'method' => 'GET',
        'max_redirects' => '0',
        'ignore_errors' => '1'
    )
);

$context = stream_context_create($opts);
$stream = fopen($url, 'r', false, $context);

// ヘッダ情報およびストリームのメタデータ
var_dump(stream_get_meta_data($stream));

// $url の実際のデータ
var_dump(stream_get_contents($stream));
fclose($stream);
?>

注意

注意: 基盤となるソケットストリームのコンテキストオプション
これ以外のコンテキストオプションが 基盤となるトランスポート でサポートされています。 http:// ストリームの場合は、tcp:// のコンテキストオプションを参照ください。 https:// ストリームの場合は、ssl:// のコンテキストオプションを参照ください。

注意: HTTP ステータスライン
このストリームラッパーがリダイレクトをたどると、 stream_get_meta_data() が返す wrapper_data のインデックス 0 の内容が必ずしもそのコンテンツの HTTP ステータスラインであるとは限らなくなります。 

array (
  'wrapper_data' =>
  array (
    0 => 'HTTP/1.0 301 Moved Permantenly',
    1 => 'Cache-Control: no-cache',
    2 => 'Connection: close',
    3 => 'Location: http://example.com/foo.jpg',
    4 => 'HTTP/1.1 200 OK',
    ...
最初のリクエストが 301 (permanent redirect) を返したので、ストリームラッパーが自動的にリダイレクト先をたどり、レスポンス 200 (インデックス = 4) を取得しました。

FTP コンテキストオプション

FTP コンテキストオプション — FTP コンテキストオプションの一覧

説明

ftp:// および ftps:// トランスポート用のコンテキストオプションです。

オプション

overwrite boolean

リモートサーバー上の既存のファイルに対する上書きを許可する。 書き込みモード（アップロード）時のみ有効。

デフォルトは FALSE です。

resume_pos integer

転送を開始するファイル内の位置。 読み込みモード（ダウンロード）時のみ有効。

デフォルトは 0 (ファイルの先頭) です。

proxy string

FTP リクエストを、http プロキシサーバー経由で行う。 ファイルの読み込み操作にのみ適用される。 例: tcp://squid.example.com:8000

変更履歴

バージョン 説明
5.1.0 proxy が追加されました。
5.0.0 overwrite および resume_pos が追加されました。

注意

注意: 基盤となるソケットストリームのコンテキストオプション
これ以外のコンテキストオプションが 基盤となるトランスポート でサポートされています。 ftp:// ストリームの場合は、tcp:// のコンテキストオプションを参照ください。 ftps:// ストリームの場合は、ssl:// のコンテキストオプションを参照ください。

SSL コンテキストオプション

SSL コンテキストオプション — SSL コンテキストオプションの一覧

説明

ssl:// および tls:// トランスポート用のコンテキストオプションです。

オプション

verify_peer boolean

SSL サーバー証明書の検証を要求するかどうか。

デフォルトは FALSE です。

allow_self_signed boolean

自己証明の証明書を許可するかどうか。 verify_peer が必要です。

デフォルトは FALSE です。

cafile string

ローカルファイルシステム上の証明書ファイルの場所。 verify_peer オプションでリモートサーバーとの 認証の際に使用する。

capath string

cafile が指定されていなかったりその場所にファイルが 見つからなかったりした場合、capath が指す ディレクトリを検索して認証ファイルを探します。capath は認証ファイルのディレクトリを正確に指している必要があります。

local_cert string

ファイルシステム上のローカル証明書ファイルのパス。 あなたの証明書とプライベートキーを含み、PEM エンコードされた ファイルである必要があります。オプションで、発行者の 認証チェーンを含めることも可能です。

passphrase string

local_cert ファイルをエンコードした際の パスフレーズ。

CN_match string

予期している一般名 (CN)。PHP は限定されたワイルドカード検索を 行います。もし一般名がこれにマッチしなかった場合、接続の試行は 失敗します。

verify_depth integer

証明書のチェインが深すぎる場合に終了するかどうか。

デフォルトでは検証を行いません。

ciphers string

使用可能な暗号化方式の一覧を設定します。設定できるフォーマットは » ciphers(1) の説明を参照ください。

デフォルトは DEFAULT です。

capture_peer_cert boolean

TRUE に設定すると、peer_certificate コンテキストオプションがピア証明書を含んで作成されます。

capture_peer_cert_chain boolean

TRUE に設定すると、peer_certificate_chain コンテキストオプションが証明書チェインを含んで作成されます。

SNI_enabled boolean

TRUE に設定すると、サーバー名の表示 (SNI) が有効になります。 これを有効にすると、同じ IP アドレスで複数の証明書を使えるようになります。

SNI_server_name string

設定すると、この値がサーバー名として用いられるようになります。 設定されていない場合は、ストリームをオープンしたときに使ったホスト名からサーバー名を推測します。

変更履歴

バージョン 説明
5.3.2 SNI_enabled および SNI_server_name が追加されました。
5.0.0 capture_peer_cert、 capture_peer_chain および ciphers が追加されました。

注意

注意: ssl:// は https:// および ftps:// のラッパーの 基盤となるものなので、ssl:// に適用可能なオプションは https:// および ftps:// にも 適用可能です。

注意: SNI (Server Name Indication) を使うには、PHP のコンパイル時に OpenSSL 0.9.8j 以降を使わなければなりません。SNI をサポートしているかどうかは OPENSSL_TLSEXT_SERVER_NAME で判定します。

CURL コンテキストオプション

CURL コンテキストオプション — CURL コンテキストオプションの一覧

説明

CURL コンテキストオプションは、 CURL 拡張モジュールのコンパイル時に --with-curlwrappers オプションを指定すると使用可能となります。

オプション

method string

GET、POST あるいはその他リモートサーバーがサポートする HTTP メソッド。

デフォルトは GET です。

header string

リクエスト時に送信する追加のヘッダ。このオプションの値は (User-agent: や Host:、 Authentication: といった) 他の値を上書きします。

user_agent string

User-Agent: ヘッダで送信する値。

デフォルトでは、php.ini の user_agent の設定内容を使用します。

content string

ヘッダの後に送信する追加データ。このオプションは GET あるいは HEAD リクエストでは使用しません。

proxy string

プロキシサーバーのアドレスを表す URI (tcp://proxy.example.com:5100 など)。

max_redirects integer

リダイレクトを追いかける最大数。1 以下を指定した場合は、リダイレクトを追跡しません。

デフォルトは 20 です。

curl_verify_ssl_host boolean

ホストを検証する。

デフォルトは FALSE です。

注意:

このオプションは、http および ftp の両方のプロトコルラッパーで使用可能です。

curl_verify_ssl_peer boolean

SSL 証明書の検証を要求する。

デフォルトは FALSE です。

注意:

このオプションは、http および ftp の両方のプロトコルラッパーで使用可能です。

例

例1 ページの取得と POST データの送信

<?php

$postdata = http_build_query(
    array(
        'var1' => 'some content',
        'var2' => 'doh'
    )
);

$opts = array('http' =>
    array(
        'method'  => 'POST',
        'header'  => 'Content-type: application/x-www-form-urlencoded',
        'content' => $postdata
    )
);

$context = stream_context_create($opts);

$result = file_get_contents('http://example.com/submit.php', false, $context);

?>

Phar コンテキストオプション

Phar コンテキストオプション — Phar コンテキストオプション一覧

説明

phar:// ラッパーのコンテキストオプションです。

オプション

compress int

Phar 圧縮定数 のいずれか。

metadata mixed

Phar メタデータ。Phar::setMetadata() を参照ください。

コンテキストパラメータ

コンテキストパラメータ — コンテキストパラメータの一覧

説明

これらの パラメータ を コンテキスト に設定するには stream_context_set_params() 関数を使用します。

パラメータ

notification callable

イベントがストリーム上で発生したときにコールされる callable。

詳細は stream_notification_callback() を参照ください。

目次

サポートするプロトコル/ラッパー

PHP には多くの組み込みラッパーが用意されています。さまざまな URL 風のプロトコルによって、 fopen() や copy()、 file_exists() そして filesize() といったファイルシステム関数で使用することができます。 これらのラッパーだけでなく、 stream_wrapper_register() 関数でラッパーを自作することもできます。

注意: ラッパーを指定する際の URL 構文としてサポートしているのは scheme://... 形式のみです。 scheme:/ や scheme: といった形式には対応していません。

file://

file:// — ローカルファイルシステムへのアクセス

説明

PHP で使用されるデフォルトのラッパーは Filesystem で、 これはローカルファイルシステムを表します。 相対パス(/, \, \\,または Windows のドライブ文字で始まらないパス)が指定された場合、 指定されたパスは、現在の作業ディレクトリに対して適用されます。 多くの場合、これは、スクリプトがあるディレクトリです。ただし、カレントディレクトリが 変更されている場合を除きます。 CLI SAPI を使用した場合、このデフォルトはスクリプトがコールされたディレクトリとなります。

fopen() や file_get_contents() のようないくつかの関数については、相対パスと同時に include_path も検索されます。

オプション

  • /path/to/file.ext
  • relative/path/to/file.ext
  • fileInCwd.ext
  • C:/path/to/winfile.ext
  • C:\path\to\winfile.ext
  • \\smbserver\share\path\to\winfile.ext
  • file:///path/to/file.ext

オプション

ラッパーの概要
属性 サポートの有無
allow_url_fopen で制約される No
読み込み許可 Yes
書き込み許可 Yes
追加許可 Yes
同時読み書き許可 Yes
stat() のサポート Yes
unlink() のサポート Yes
rename() のサポート Yes
mkdir() のサポート Yes
rmdir() のサポート Yes

変更履歴

バージョン 説明
5.0.0 file:// が追加されました。

http://

https://

http:// -- https:// — HTTP(s) URL へのアクセス

説明

HTTP 1.0 により HTTP GET メソッドを用いてファイル/リソースに読み込みのみの アクセスが可能です。仮想ホストにホスト名でアクセスするために、 Host: ヘッダが送信されます。 php.ini ファイルまたはストリームコンテキストによって user_agent 文字列を設定している場合、 それはリクエストの中にも含まれます。

ストリームにより、リソースの body にアクセスすることが できます。ヘッダは、$http_response_header 変数に保存されます。

(全てのリダイレクトが処理された後に)ドキュメント取得元のリソースの URL を知ることが 重要な場合、ストリームから返された一連のレスポンスヘッダを処理する必要があります。

from ディレクティブが設定されており、かつそれが コンテキストオプションとパラメータ で上書きされていない場合は、その値が From: ヘッダとなります。

オプション

  • http://example.com
  • http://example.com/file.php?var1=val1&var2=val2
  • http://user:password@example.com
  • https://example.com
  • https://example.com/file.php?var1=val1&var2=val2
  • https://user:password@example.com

オプション

ラッパーの概要
属性 サポートの可否
allow_url_fopen で制約される Yes
読み込み可 Yes
書き込み可 No
追記可能 No
同時読み書き可 N/A
stat() をサポート No
unlink() をサポート No
rename() をサポート No
mkdir() をサポート No
rmdir() をサポート No

変更履歴

バージョン 説明
4.3.7 バグのある IIS サーバーを検出し、"SSL: Fatal Protocol Error" エラーを回避するようになりました。
4.3.0 https:// が追加されました。
4.0.5 リダイレクトをサポートするようになりました。

例

例1 リダイレクト後の URL の検出

<?php
$url = 'http://www.example.com/redirecting_page.php';

$fp = fopen($url, 'r');

$meta_data = stream_get_meta_data($fp);
foreach ($meta_data['wrapper_data'] as $response) {

    /* リダイレクトされているか? */
    if (strtolower(substr($response, 0, 10)) == 'location: ') {

        /* $url をリダイレクト先に書き換える */
        $url = substr($response, 10);
    }

}

?>

例2 HTTP リクエストで独自のヘッダを送信する

カスタムヘッダを送信するには コンテキストオプション を使います。それ以外にも、こんなハックも使えます。 これは INI 設定項目 user_agent を処理する際の副作用によるものです。 user_agent に何らかの正常な文字列 (たとえばデフォルト設定の PHP/version など) を指定し、さらに続けて キャリッジリターン(\r) / ラインフィード(\n) を置いた後に任意のヘッダを記述します。

<?php
ini_set('user_agent', "PHP\r\nX-MyCustomHeader: Foo");

$fp = fopen('http://www.example.com/index.php', 'r');
?>

送信されるリクエストは次のようになります。

GET /index.php HTTP/1.0
Host: www.example.com
User-Agent: PHP
X-MyCustomHeader: Foo

注意

注意: HTTPS がサポートされるのは、openssl 拡張モジュールが有効な場合のみです。

HTTP 接続は読み込みのみ可で、HTTP リソースにデータを書き込んだり ファイルをコピーしたりすることはできません。

たとえば POST および PUT リクエストを送信することも、 HTTP コンテキスト を使えば可能です。

参考

ftp://

ftps://

ftp:// -- ftps:// — FTP(s) URL へのアクセス

説明

FTP 経由でのファイルの読み込みと新しいファイルの作成を許可します。 サーバーがパッシブモードの FTP をサポートしていない場合、接続は失敗します。

読み込み用または書き込み用のどちらかでファイルをオープンすることが 可能ですが、それらを両方同時に指定することはできません。FTP サーバー上の 既存のファイルを書き込み用にオープンしようとした場合、もし コンテキストオプション overwrite が指定されていなければ 接続は失敗します。既存のファイルを FTP 越しに上書きしたい場合は、 コンテキストオプション overwrite を指定したうえで 書き込み用にファイルをオープンします。別の方法としては、 FTP 拡張モジュール を使用することも可能です。

from ディレクティブを php.ini で設定した場合、この値が anonymous FTP のパスワードとして送信されます。

オプション

  • ftp://example.com/pub/file.txt
  • ftp://user:password@example.com/pub/file.txt
  • ftps://example.com/pub/file.txt
  • ftps://user:password@example.com/pub/file.txt

オプション

ラッパーの概要
属性 PHP 4 PHP 5
allow_url_fopen で制約される Yes Yes
読み込み許可 Yes Yes
書き込み許可 Yes（新規ファイルのみ） Yes（新規ファイル あるいは 既存のファイルで overwrite を指定）
追加許可 No Yes
同時読み書き許可 No No
stat() のサポート No PHP 5.0.0 では filesize()、 filetype()、file_exists()、 is_file() および is_dir() のみ。 PHP 5.1.0 で filemtime()。
unlink() のサポート No Yes
rename() のサポート No Yes
mkdir() のサポート No Yes
rmdir() のサポート No Yes

変更履歴

バージョン 説明
4.3.0 ftps:// が追加されました。

注意

注意:

FTPS がサポートされるのは、openssl 拡張モジュールが有効な場合のみです。

もしサーバーが SSL をサポートして いなければ、通常の（暗号化されない）FTP を使用します。

注意: 追記
PHP 5.0.0 では、ftp:// URL ラッパー経由での ファイルの追記が可能となりました。それ以前のバージョンでは ftp:// 経由でのファイルの追記は失敗していました。

php://

php:// — さまざまな入出力ストリームへのアクセス

説明

PHP ではさまざまな入出力ストリームを提供しています。 これらを使うと、PHP 自身の入出力ストリームへのアクセスや 標準入出力と標準エラー出力のファイル記述子へのアクセス、 メモリやディスクを使ったテンポラリファイルストリームへのアクセスができ、 フィルタを使って他のファイルリソースの読み書きに手を加えることもできます。

php://stdin, php://stdout および php://stderr

php://stdin、php://stdout および php://stderr は、PHP プロセスの 対応する入出力ストリームへの直接アクセスを許可します。 これらのストリームは複製されたファイル記述子を参照します。そのため、 php://stdin をオープンしたあとでそれを閉じたとしても、 識別子のコピーが閉じられるだけです。STDIN で参照される実際のストリームは何も影響を受けません。 PHP 5.2.1 より前のバージョンでは、これに関連する挙動にバグがあります。 これらのラッパーを使うのではなく、定数 STDIN, STDOUT および STDERR を使用することを推奨します。

php://stdin は読み込み専用で、 php://stdout および php://stderr は書き込み専用です。

php://input

php://input は読み込み専用のストリームで、 リクエストの body 部から生のデータを読み込むことができます。 POST リクエストの場合は $HTTP_RAW_POST_DATA よりも php://input を使うのが望ましいでしょう。php.ini ディレクティブの設定に依存しないからです。 さらに、$HTTP_RAW_POST_DATA がデフォルトで設定されない場合は、 always_populate_raw_post_data を有効にするよりも $HTTP_RAW_POST_DATA を使うほうがメモリの消費量が少なくなるでしょう。 php://input は、 enctype="multipart/form-data" に対しては使用できません。

注意: php://input でオープンしたストリームは、は一度しか読み込めません。 また、このストリームは seek 操作をサポートしていません。 しかし、SAPI の実装によっては、別の php://input ストリームをオープンして読み込みを再開できる可能性もあります。 これは、リクエストの body 部のデータが保存されている場合にのみ可能となります。 通常、POST リクエストの場合はそのようになりますが、 PUT や PROPFIND といった他のメソッドの場合は保存されません。

php://output

php://output は書き込み専用のストリームで、 print および echo と同じ方法での出力バッファへの書き込みを許可します。

php://fd

php://fd は、指定したファイル記述子に直接アクセスすることができます。 たとえば php://fd/3 は、ファイル記述子 3 を指します。

php://memory および php://temp

php://memory および php://temp は読み書き可能なストリームで、一時データをファイルのように保存できるラッパーです。 両者の唯一の違いは、 php://memory が常にデータをメモリに格納するのに対して php://temp は定義済みの上限 (デフォルトは 2 MB) に達するとテンポラリファイルを使うという点です。 このテンポラリファイルの場所は、 sys_get_temp_dir() 関数と同じ方法で決めます。

php://temp のメモリ制限を制御するには /maxmemory:NN を追加します。この NN はメモリに保持するデータの最大量で、単位はバイトです。 このサイズを超えるとテンポラリファイルを使います。

php://filter

php://filter は、フィルタアプリケーションが ストリームをオープンすることを許可するために設計されたメタラッパーです。 これは、readfile()、file() および file_get_contents() のようなオールインワンの ファイル関数とともに使用すると有用です。これらの関数には、コンテンツが 読み込まれる前にストリームにフィルタを適用する手段がありません。

php://filter の対象は、 次のようなパラメータをパスの一部として受け取ります。 これらのパラメータの詳細は、使用例を参照ください。

php://filter のパラメータ
名前 説明
resource=<フィルタの対象となるストリーム> このパラメータは必須です。フィルタリングしたいストリームを指定します。
read=<読み込みチェーンに適用するフィルタのリスト> このパラメータは任意です。ひとつあるいは複数のフィルタ名を、 パイプ文字 (|) で区切って指定します。
write=<書き込みチェーンに適用するフィルタのリスト> このパラメータは任意です。ひとつあるいは複数のフィルタ名を、 パイプ文字 (|) で区切って指定します。
<両方のチェーンに適用するフィルタのリスト> read= や write= がついていないすべてのフィルタは、読み込みと書き込みのチェーンの両方に適切に適用されます。

オプション

ラッパーの概要（php://filter については、 フィルタされる側のラッパーの概要を参照します）
属性 サポートの有無
allow_url_fopen で制約される No
allow_url_include で制約される php://input、 php://stdin、 php://memory および php://temp のみ。
読み込み許可 php://stdin、 php://input、 php://fd、 php://memory および php://temp のみ。
書き込み許可 php://stdout、 php://stderr、 php://output、 php://fd、 php://memory および php://temp のみ。
追加許可 php://stdout、 php://stderr、 php://output、 php://fd、 php://memory および php://temp のみ (書き込みと同じ)。
同時読み書き許可 php://fd、 php://memory および php://temp のみ。
stat() のサポート php://memory および php://temp のみ。
unlink() のサポート No
rename() のサポート No
mkdir() のサポート No
rmdir() のサポート No
stream_select() のサポート php://stdin、 php://stdout、 php://stderr、 php://fd、および php://temp のみ。

変更履歴

バージョン 説明
5.3.6 php://fd が追加されました。
5.1.0 php://memory および php://temp が追加されました。
5.0.0 php://filter が追加されました。

例

例1 php://temp/maxmemory

このオプションパラメータは、php://temp がテンポラリファイルを使うようになるまでのメモリの制限を設定します。

<?php
// 制限を 5 MB にします。
$fiveMBs = 5 * 1024 * 1024;
$fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

fputs($fp, "hello\n");

// 書き込んだ内容を読み込みます。
rewind($fp);
echo stream_get_contents($fp);
?>

例2 php://filter/resource=<フィルタの対象となるストリーム>

このパラメータは、 php://filter 指定の最後に存在し、フィルタリング したいストリームを指している必要があります。

<?php
/* これは単純に以下と同じです。
   readfile("http://www.example.com");
   なぜなら、実際のところ何のフィルタ処理も行われないからです。 */

readfile("php://filter/resource=http://www.example.com");
?>

例3 php://filter/read=<読み込みチェーンに適用するフィルタのリスト>

このパラメータは 1 つ以上のフィルタ名を パラメータとしてとり、それらはパイプ文字 | で区切られます。

<?php
/* これは、www.example.com のすべての内容を
   大文字に変換して出力します。 */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");

/* これは上の例と同じですが、それに加えて
   ROT13 エンコード処理を行います。 */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>

例4 php://filter/write=<書き込みチェーンに適用するフィルタのリスト>

このパラメータは 1 つ以上のフィルタ名を パラメータとしてとり、それらはパイプ文字 | で区切られます。

<?php
/* これは、文字列 "Hello World"
   に対して rot13 フィルタを適用し、カレントディレクトリの
   example.txt に書き込みます。 */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>

zlib://

bzip2://

zip://

zlib:// -- bzip2:// -- zip:// — 圧縮ストリーム

説明

zlib: PHP 4.0.4 - PHP 4.2.3 (fopencookie をサポートするシステムのみ)

compress.zlib:// および compress.bzip2:// PHP 4.3.0以降

zlib: は gzopen() と同様に 動作しますが、このストリームは fread() および 他のファイルシステム関数と組み合わせて使用することができるところが 異なります。この機能ではファイル名に ':' 文字が含まれる曖昧さが あるため、PHP 4.3.0 以降では古い機能となっています。代わりに compress.zlib:// を使用してください。

compress.zlib:// および compress.bzip2:// は、それぞれ gzopen() および bzopen() と等価で、 fopencookie をサポートしないシステムの上でも動作します。

ZIP 拡張モジュール は zip: ラッパーを登録します。

オプション

  • zlib:
  • compress.zlib://
  • compress.bzip2://

オプション

ラッパーの概要
属性 サポートの有無
allow_url_fopen で制約される No
読み込み許可 Yes
書き込み許可 Yes (zip:// を除く)
追加許可 Yes (zip:// を除く)
同時読み書き許可 No
stat() のサポート No, 圧縮されたファイルの状態を知るには、通常の file:// ラッパーを使用します。
unlink() のサポート No, 圧縮されたファイルを unlink するには、通常の file:// ラッパーを使用します。
rename() のサポート No
mkdir() のサポート No
rmdir() のサポート No

data://

data:// — データ (RFC 2397)

説明

data: (» RFC 2397) ストリームラッパーは、 PHP 5.2.0 以降で使用可能です。

オプション

  • data://text/plain;base64,

オプション

ラッパーの概要
属性 サポートの有無
allow_url_fopen で制約される No
allow_url_include で制約される Yes
読み込み許可 Yes
書き込み許可 No
追加許可 No
同時読み書き許可 No
stat() のサポート No
unlink() のサポート No
rename() のサポート No
mkdir() のサポート No
rmdir() のサポート No

例

例1 data:// の内容の表示

<?php
// "I love PHP" と表示します
echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
?>

例2 media type の取得

<?php
$fp   = fopen('data://text/plain;base64,', 'r');
$meta = stream_get_meta_data($fp);

// "text/plain" と表示します
echo $meta['mediatype'];
?>

glob://

glob:// — パターンにマッチするパス名の検索

説明

glob: ストリームラッパーは PHP 5.3.0 以降で使用可能です。

オプション

  • glob://

オプション

ラッパーの概要
属性 サポートの有無
allow_url_fopen で制約される No
allow_url_include で制約される No
読み込み許可 No
書き込み許可 No
追加許可 No
同時読み書き許可 No
stat() のサポート No
unlink() のサポート No
rename() のサポート No
mkdir() のサポート No
rmdir() のサポート No

例

例1 基本的な使用法

<?php
// ext/spl/examples/ ディレクトリのすべての *.php ファイルについて、
// そのファイル名とサイズを表示します
$it = new DirectoryIterator("glob://ext/spl/examples/*.php");
foreach($it as $f) {
    printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
}
?> 
tree.php: 1.0K
findregex.php: 0.6K
findfile.php: 0.7K
dba_dump.php: 0.9K
nocvsdir.php: 1.1K
phar_from_dir.php: 1.0K
ini_groups.php: 0.9K
directorytree.php: 0.9K
dba_array.php: 1.1K
class_tree.php: 1.8K

phar://

phar:// — PHP アーカイブ

説明

phar:// ストリームラッパーは PHP 5.3.0 以降で使用可能です。 詳細は Phar ストリームラッパー を参照ください。

オプション

  • phar://

オプション

ラッパーの概要
属性 サポートの有無
allow_url_fopen で制約される No
allow_url_include で制約される No
読み込み許可 Yes
書き込み許可 Yes
追加許可 No
同時読み書き許可 Yes
stat() のサポート Yes
unlink() のサポート Yes
rename() のサポート Yes
mkdir() のサポート Yes
rmdir() のサポート Yes

ssh2://

ssh2:// — Secure Shell 2

説明

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// PHP 4.3.0 以降（PECL）

注意: このラッパーはデフォルトでは有効になっていません
ssh2.*:// ラッパーを使用するには、 » PECL から » SSH2 拡張モジュールを インストールする必要があります。

ssh2 ラッパーでは、URL のホスト部分に接続リソースを渡すことで既にオープン している接続を再利用することが可能です。

オプション

  • ssh2.shell://user:pass@example.com:22/xterm
  • ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd
  • ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14
  • ssh2.sftp://user:pass@example.com:22/path/to/filename

オプション

ラッパーの概要
属性 ssh2.shell ssh2.exec ssh2.tunnel ssh2.sftp ssh2.scp
allow_url_fopen で制約される Yes Yes Yes Yes Yes
読み込み許可 Yes Yes Yes Yes Yes
書き込み許可 Yes Yes Yes Yes No
追加許可 No No No Yes（サーバーがサポートしている場合） No
同時読み書き許可 Yes Yes Yes Yes No
stat() のサポート No No No Yes No
unlink() のサポート No No No Yes No
rename() のサポート No No No Yes No
mkdir() のサポート No No No Yes No
rmdir() のサポート No No No Yes No

コンテキストオプション
名前 使用法 デフォルト
session 再利用する接続済みの ssh2 リソース  
sftp 再利用する割り当て済みの sftp リソース  
methods Key exchange, hostkey, cipher, compression, および MAC methods  
callbacks    
username 接続するユーザー名  
password パスワード認証に使用するパスワード  
pubkey_file 認証に使用する公開鍵ファイル  
privkey_file 認証に使用する秘密鍵ファイル  
env 設定する環境変数の連想配列  
term pty を割り当てる際の端末エミュレート方式  
term_width pty を割り当てる際の端末の幅  
term_height pty を割り当てる際の端末の高さ  
term_units term_width および term_height の単位 SSH2_TERM_UNIT_CHARS

例

例1 アクティブな接続からストリームをオープンする

<?php
$session = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                            '/home/username/.ssh/id_rsa', 'secret');
$stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
?>

rar://

rar:// — RAR

説明

このラッパーが受け取るのは、RAR アーカイブへの URL エンコードされたパス (絶対パスあるいは相対パス)、そしてオプションでアスタリスク (*)、番号記号 (#)、 アーカイブ内のエントリ名です。エントリ名を指定する場合は番号記号が必須となります。 エントリ名の先頭のスラッシュは必須ではありません。

このラッパーは、ファイルだけでなくディレクトリも開くことができます。 ディレクトリを開く際にアスタリスクを使うと、 返されるディレクトリエントリ名はエンコードされていない状態となります。 アスタリスクを指定しなかった場合は URL エンコードしたものを返します。 これは、RecursiveDirectoryIterator などの組み込み機能で このラッパーをファイル名の代わりに正しく使えるようにするためです。

番号記号とエントリ名の部分が含まれていない場合は、アーカイブのルートを表示します。 これは通常のディレクトリとは異なり、 返されるストリームには更新時刻などの情報が含まれません。 ルートディレクトリは、アーカイブの個別のエントリとして存在するわけではないからです。 このラッパーを RecursiveDirectoryIterator で使う場合、 ルートにアクセスするには URL に番号記号を含めなければなりません。 そうすれば、子要素の URL も正しく作られます。

注意: このラッパーはデフォルトでは有効になっていません
rar:// ラッパーを使用するには、 » PECL から » rar 拡張モジュールを インストールする必要があります。

rar:// は、PECL rar 3.0.0 以降で使用可能です。

オプション

  • rar://<url encoded archive name>[*][#[<url encoded entry name>]]

オプション

ラッパーの概要
属性 サポートの有無
allow_url_fopen で制約される No
allow_url_include で制約される No
読み込み許可 Yes
書き込み許可 No
追加許可 No
同時読み書き許可 No
stat() のサポート Yes
unlink() のサポート No
rename() のサポート No
mkdir() のサポート No
rmdir() のサポート No

コンテキストオプション
名前 使用法 デフォルト
open_password アーカイブのヘッダを暗号化するときに使うパスワード。 WinRAR では、ヘッダの暗号が設定されている場合はすべてのファイルを同じパスワードで暗号化します。 そのため、ヘッダが暗号化されているアーカイブでは file_password は無視されます。  
file_password ファイルを暗号化するときに使うパスワード。 ヘッダが暗号化されている場合はこの設定は無視され、かわりに open_password の値を使います。 ふたつのオプションがある理由は、 ヘッダとファイルを別々のパスワードで暗号化する可能性に対応するためです。 アーカイブのヘッダが暗号化されていない場合は open_password は無視され、 このオプションを使わなければならないことに注意しましょう。  
volume_callback 存在しないボリュームのパスを決めるために使うコールバック。詳細は RarArchive::open() を参照ください。  

例

例1 RAR アーカイブの走査

<?php

class MyRecDirIt extends RecursiveDirectoryIterator {
    function current() {
        return rawurldecode($this->getSubPathName()) .
            (is_dir(parent::current())?" [DIR]":"");
    }
}

$f = "rar://" . rawurlencode(dirname(__FILE__)) .
    DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';

$it = new RecursiveTreeIterator(new MyRecDirIt($f));

foreach ($it as $s) {
    echo $s, "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

|-allow_everyone_ni [DIR]
|-file1.txt
|-file2_אּ.txt
|-with_streams.txt
\-אּ [DIR]
  |-אּ\%2Fempty%2E [DIR]
  | \-אּ\%2Fempty%2E\file7.txt
  |-אּ\empty [DIR]
  |-אּ\file3.txt
  |-אּ\file4_אּ.txt
  \-אּ\אּ_2 [DIR]
    |-אּ\אּ_2\file5.txt
    \-אּ\אּ_2\file6_אּ.txt

例2 暗号化されたファイルのオープン (ヘッダの暗号化)

<?php
$stream = fopen("rar://" .
    rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
    'encrypted_headers.rar' . '#encfile1.txt', "r", false,
    stream_context_create(
        array(
            'rar' =>
                array(
                    'open_password' => 'samplepassword'
                )
            )
        )
    );
var_dump(stream_get_contents($stream));
/* 作成日や最終更新日は WinRAR では選択式になっています。
 * そのため、多くのファイルには含まれていません */
var_dump(fstat($stream));
?>

上の例の出力は、 たとえば以下のようになります。

string(26) "Encrypted file 1 contents."
Array
(
    [0] => 0
    [1] => 0
    [2] => 33206
    [3] => 1
    [4] => 0
    [5] => 0
    [6] => 0
    [7] => 26
    [8] => 0
    [9] => 1259550052
    [10] => 0
    [11] => -1
    [12] => -1
    [dev] => 0
    [ino] => 0
    [mode] => 33206
    [nlink] => 1
    [uid] => 0
    [gid] => 0
    [rdev] => 0
    [size] => 26
    [atime] => 0
    [mtime] => 1259550052
    [ctime] => 0
    [blksize] => -1
    [blocks] => -1
)

ogg://

ogg:// — オーディオストリーム

説明

ogg:// ラッパー経由で読み込みモードでオープンされた ファイルは、OGG/Vorbis コーデックでエンコードされた圧縮音声ファイルとして 扱われます。同様に、ogg:// ラッパー経由で書き込みモード あるいは追記モードでオープンされたファイルは、圧縮音声データとして 書き込まれます。読み込みモードでオープンした OGG/Vorbis ファイルに対して stream_get_meta_data() を適用した場合、以下のような さまざまな情報を返します。 vendor タグ、comments、 多くの channels、サンプリングレート rate 、 および以下のパラメータで指定されるエンコーディングレート。 bitrate_lower、bitrate_upper、 bitrate_nominal、bitrate_window

ogg:// PHP 4.3.0 and up (PECL)

注意: このラッパーはデフォルトでは有効になっていません
ogg:// ラッパーを使用するには、 » PECL から » OGG/Vorbis 拡張モジュールを インストールする必要があります。

オプション

  • ogg://soundfile.ogg
  • ogg:///path/to/soundfile.ogg
  • ogg://http://www.example.com/path/to/soundstream.ogg

オプション

ラッパーの概要
属性 サポートの有無
allow_url_fopen で制約される No
読み込み許可 Yes
書き込み許可 Yes
追加許可 Yes
同時読み書き許可 No
stat() のサポート No
unlink() のサポート No
rename() のサポート No
mkdir() のサポート No
rmdir() のサポート No

コンテキストオプション
名前 使用法 デフォルト モード
pcm_mode 読み込みの際に適用する PCM エンコーディング。以下のうちのひとつ。 OGGVORBIS_PCM_U8、OGGVORBIS_PCM_S8、 OGGVORBIS_PCM_U16_BE、OGGVORBIS_PCM_S16_BE、 OGGVORBIS_PCM_U16_LE、および OGGVORBIS_PCM_S16_LE （8 ビットか 16 ビットか、符号付きか符号なしか、ビッグエンディアンかリトルエンディアンか）。 OGGVORBIS_PCM_S16_LE Read
rate 入力データのサンプリングレート。Hz 単位。 44100 Write/Append
bitrate 整数値の場合、エンコードの際の固定ビットレート（16000 から 131072）。 浮動小数点値の場合、使用する可変ビットレート（-1.0 から 1.0）。 128000 Write/Append
channels エンコードする音声チャネル数。一般には 1（モノラル）あるいは 2（ステレオ）。 最大 16 まで。 2 Write/Append
comments エンコード時にトラックヘッダに入れる文字列の配列。   Write/Append

例

expect://

expect:// — 対話的プロセスストリーム

説明

expect:// ラッパーでオープンしたストリームを使用すると、 プロセスの標準入力・標準出力・標準エラー出力への PTY 経由でのアクセスが 可能となります。

注意: このラッパーはデフォルトでは有効となっていません。
expect:// ラッパーを使用するには、 » PECL にある » Expect 拡張モジュールを インストールする必要があります。

expect:// PHP 4.3.0 以降 (PECL)

オプション

  • expect://command

オプション

ラッパーの概要
属性 サポートの有無
allow_url_fopen で制約される No
読み込み許可 Yes
書き込み許可 Yes
追加許可 Yes
同時読み書き許可 No
stat() のサポート No
unlink() のサポート No
rename() のサポート No
mkdir() のサポート No
rmdir() のサポート No

例

目次

  • file:// — ローカルファイルシステムへのアクセス
  • http:// — HTTP(s) URL へのアクセス
  • ftp:// — FTP(s) URL へのアクセス
  • php:// — さまざまな入出力ストリームへのアクセス
  • zlib:// — 圧縮ストリーム
  • data:// — データ (RFC 2397)
  • glob:// — パターンにマッチするパス名の検索
  • phar:// — PHP アーカイブ
  • ssh2:// — Secure Shell 2
  • rar:// — RAR
  • ogg:// — オーディオストリーム
  • expect:// — 対話的プロセスストリーム

セキュリティ

はじめに

PHP は強力な言語そしてインタプリタであり、モジュールとして Web サー バーに組み込んだ場合でも、独立した CGI バイナリ として実行される場合でも、ファイルをアクセスしたり、コマンドを実行 したり、サーバーへのネットワーク接続を開くことができます。デフォル トでは、これらの機能を実行した場合、Webサーバー上でセキュリティ上の 問題を生じる可能性があります。PHP は、特に CGI プログラムを書く場合、 Perl や C より安全な言語となるように設計されています。コンパイル時 または実行時の設定オプションを正しく選び、適切なコードを書くことに より、必要な自由度とセキュリティの組み合わせを確実に提供することが できます。

PHP の使用法に多くの異なった手段があるように、PHP の動作を制御する 多くの設定オプションがあります。オプションの選択肢が広いため、PHP を様々な用途に使用することができます。しかし、このことは、これらの オプションとサーバー設定の組み合わせによっては、安全でない設定とな ることを意味します。

PHPの設定の自由度はそのコードの柔軟さにほぼ匹敵します。PHPは、シェ ルユーザーコマンドを全て実行可能な完全なサーバーアプリケーションや 厳しく制御された環境で低リスクの簡単なサーバーサイドインクルードを 使用できるようなアプリケーションを構築する場合に使用することが可能 です。そうした環境の構築方法、セキュリティのレベルはPHPの開発者に大 きく依存しています。

本章は、安全に使用可能な異なった設定と条件の組み合わせについての説 明から始めます。続いて、複数のセキュリティレベルのコーディングにお ける複数の考慮事項について説明し、最後にいくつかの一般的なセキュリ ティ上のアドバイスを行います。

一般的な考慮事項

完全に安全なシステムは理想の産物でしかないため、セキュリティ業界で しばしば使用される手法は、リスクと利便性のバランスのとれた手法です。 変数がユーザーから投稿される度に(網膜スキャンと指紋のような)2種類の 生体認証が必要だとしたら、極端に高いレベルの説明義務を生じます。ま た、かなり複雑なフォームを埋めるために30分もかかるとすれば、ユーザー がセキュリティをバイパスする手段を探す気分にさせる傾向があります。

最善のセキュリティは、通常、ユーザーによる業務の達成を防たげずに要求 を十分に達成できる程度にさしでがましくないものです。むしろ、いくつ かのセキュリティ攻撃は、単純にこの種の多げさに構築され、時間を浪費 しがちなセキュリティ機構を狙うものです。

記憶するに値する言葉として次のようなものがあります。「システムは鎖 の最も弱い輪と同程度に優れている」全てのトランザクションが時間、場 所、トランザクションの型等に基づき大量に記録されているが、ユーザーは 一つのクッキーのみにより認証されている場合、ユーザーとそのトランザク ションログの結び付きの確実性はかなり弱くなります。

テストの際に、最も簡単なページに関してでさえ、全ての可能性をテスト することは不可能であるということを頭に入れておいてください。期待する 入力は、不機嫌な社員、経験のあるクラッカー、キーボードの上を歩く家 の猫による入力とは全く無関係でしょう。これが、想定外のデータが入力 される可能性がある場所を見分けるために論理的な視点からコードを見て、 その後、修正、減少、または詳細に調べるというのが、最善であるという 理由です。

インターネットにはあなたのコードを壊したり、システムを破壊したり、 不適切な内容を投稿したり、その他あなたの一日を不快にするようなこと により自分の名を馳せたいと思う人がたくさんいます。サイトの規模の大 小によらず、単にオンラインであり、接続できるサーバーを有しているだけ で攻撃目標となりえます。多くのクラック用プログラムはサイトの大きさ を考慮せず、犠牲者を探しつつ大きなIPブロックで網を張っています。 その犠牲者の一人にならないようにしてください。

CGI バイナリとしてインストール

目次

受ける可能性がある攻撃

PHP を CGI バイナリとして使用するのは、PHP を モジュールとして(Apache のような)サーバーソフトウエアに組み込み たくない何らかの理由がある場合や安全な chroot と setuid 環境をス クリプトに提供する他の CGI ラッパーと組み合わせて PHP を使用する 場合の設定オプションです。セットアップ時には、通常、PHP 実行バイ ナリを Web サーバーの cgi-bin ディレクトリにインストールします。 CERT 勧告 » CA-96.11は、いかなるイ ンタプリタを cgi-bin に置くことにも反対しています。 PHP バイナリをスタンドアロンのインタプリタとして使用することが できる場合でも、PHP は、セットアップにより生じる可能性がある 次のような攻撃を防ぐように設計されています。

  • システムファイルへのアクセス: http://my.host/cgi-bin/php?/etc/passwd URL において疑問符 (?) の後のクエリー情報は、CGI インターフェー スにより、インタプリタにコマンドライン引数として渡されます。通 常、インタプリタは、コマンドライン上の最初の引数に指定されたファ イルを開き、実行します。 CGI バイナリとして実行された場合、PHP は、コマンドライン引数の 解釈を拒否します。
  • サーバー上の Web ドキュメントへのアクセス: http://my.host/cgi-bin/php/secret/doc.html URL の PHP バイナリ名の後のパス情報の部分、つまり/secret/doc.html は、 CGI プログラムによりオープンされて実行される ファイルの名前を指定するために従来より使用されています。 http://my.host/secret/script.php のようなドキュメントへの要求を PHP インタプリタにリダイレクト するために、通常、何らかの Web サーバー設定用命令(Apache では Action) が使用されます。この設定により、Web サーバーは、まずディレクトリ /secret へのアクセス権をチェックし、 リダイレクト要求 http://my.host/cgi-bin/php/secret/script.php を生成します。残念なことに、リクエストが最初からこの形式で与え られた場合、Web サーバーによるアクセスチェックは、 /secret/script.php ファイル ではなく、/cgi-bin/php ファイル に対して行われます。この手法により、/cgi-bin/php にアクセス可能なユーザーは、 Web サーバー上の全ての保護されたドキュメントにアクセスできてし まいます。 PHP では、サーバードキュメントツリーにアクセス制限付きのディレ クトリがある場合、設定ディレクティブ cgi.force_redirect、 doc_root および user_dir をこの攻撃を防止す るために使用することができます。 これらを組み合わせたいくつか の手法について以下に詳細な説明を示します。

ケース 1: 配布制限がないファイルのみを配布

サーバー上にパスワードまたは IP アドレスを元にしたアクセス制限に よる制約を課すコンテンツがない場合、この設定オプションを使用す る必要はありません。使用する Web サーバーがリダイレクトを許可しな い場合やサーバーがリダイレクト要求を安全に処理しつつPHP バイナリ と通信できる手段を有していない場合、オプション --enable-force-cgi-redirectを configure スクリプトに指定することができます。この場合でも、直接 的な方法 http://my.host/cgi-bin/php/dir/script.php でもなくリダイレクション http://my.host/dir/script.phpでもない他の やり方で PHP スクリプトを呼び出せるようになっていないかどうか確認 する必要があります。

リダイレクションは、例えば Apache では命令 AddHandler および Action で設定することができます。(以下を参照してください。)

ケース 2: cgi.force_redirect を使用

設定ディレクティブ cgi.force_redirect は、 http://my.host/cgi-bin/php/secretdir/script.php のように URL から直接 PHP を呼び出すことを禁止します。 代わりに、 Web サーバーのリダイレクションにより処理された場合は、 PHP はこのモードでのみ処理を行います。 4.2.0 より古いバージョンの PHP では、コンパイル時のオプション --enable-force-cgi-redirect を使えば同じことができます。

通常、Apache 用設定でのリダイレクションは、 次の命令を使用して行います。

Action php-script /cgi-bin/php
AddHandler php-script .php

このオプションは、Apache Web サーバーでのみテストされており、リク エストのリダイレクト時に Apache が標準ではないCGI 環境変数 REDIRECT_STATUS をセットすることを前提にしています。 リクエストが直接のものであるか間接のものであるかを示す手段をWeb サーバーが全くサポートしていない場合は、このオプションを使用する ことはできません。この場合、ここで記した CGI 版を実行する他の方法 の内の一つを使用する必要があります。

ケース 3: doc_root または user_dir を設定

Web サーバー上のドキュメントディレクトリに スクリプトや実行ファイルのようなアクティブな内容を読み込むのは、 往々にして危険な行為であるとみなされることがあります。 何らかの設定ミスによりスクリプトが実行されず、通常の HTML ドキュメント として表示されてしまう場合には、知的著作物またはパスワードのような セキュリティ情報が漏洩する可能性があります。 このため、多くのシステム管理者は、スクリプトを PHP CGI を通じてのみ アクセス可能な他のディレクトリ構造にセットアップしたいと思うこと でしょう。 この場合、常にインタープリタに処理されるため、上記のように表示されること はありません。

前節で記したようなリクエストがリダイレクトされたものでないことを 確かめる方法が利用可能でない場合、 スクリプト用の doc_root を Web ドキュメント用ルートとは別に セットアップする必要があります。

設定用命令 doc_root により 設定ファイル ファイル中で PHP スクリプト用ドキュメントルートを設定することができます。 または、環境変数 PHP_DOCUMENT_ROOT でも設定する ことができます。 これを設定した場合、CGI 版の PHP は、 常に開くファイルの名前をこの doc_root リクエストのパス情報を用いて作成し、 (以下の user_dir を除き、)確実に このディレクトリの外側でスクリプトが実行されないようにします。

ここで利用可能な別のオプションは、 user_dir です。user_dir が設定されていない場合、 開かれるファイル名を制御するのは、doc_root のみです。 http://my.host/~user/doc.php のような URL は、ユーザーホームディレクトリ以下のファイルを開かず、 doc_root 以下の ~user/doc.php というファイルを開くことになります。 (ディレクトリ名がチルダ [~] で始まっている ということになります)

user_dir が例えば、public_phpに 設定されていた場合、 http://my.host/~user/doc.php の ようなリクエストは、そのユーザー user のホームディレクトリにある public_php 以下の doc.php という名前のファイルをオープンしま す。ユーザーのホームディレクトリが、 /home/user である場合、 実行されるファイルは、 /home/user/public_php/doc.php となります。

user_dir の展開は、 doc_root の設定によらず行われます。 このため、ドキュメントルートおよびユーザーディレクトリへの アクセスを別々に制御することができます。

ケース 4: Webツリーの外にPHPパーサを置く

非常に安全性の高いオプションとしてPHP パーサのバイナリをファイル 用 Web ツリーの外側、例えば /usr/local/binに置くことが考えられます。こ のオプションの唯一の欠点は、PHP タグを有する全てのファイルの先頭 行に次のような一行を加える必要があることです。 

#!/usr/local/bin/php
また、ファイルを実行可能にしておく必要があります。この場合、実行 時にシェルエスケープ機能 #! を使用する Perl や sh や他のスクリプト言語で書かれた CGI スクリプトを処理するのと全 く同様に処理を行います。

この設定で PATH_INFO および PATH_TRANSLATED 情報を正しく処理するためには、 PHP パーサを設定オプション --enable-discard-path を付けてコンパイルする必要があります。

Apache モジュールとしてインストール

PHP が Apache モジュールとして使用された場合、PHP は、Apache ユー ザーの許可属性(通常はユーザー "nobody" の許可属性)を継承します。 これは、セキュリティと認証に数々の影響を与えます。例えば、データベー スと接続するためにPHPを使用している場合、データベースが組込みのア クセス制御機能を有していない限り、そのデータベースを "nobody"ユー ザからアクセス可能とする必要が生じます。これは、悪意のあるスクリプ トが、ユーザー名とパスワードなしにデータベースにアクセスし、修正する ことができることを意味します。Webスパイダがデータベース管理用Webペー ジを回って、データベースを全て削除することも可能です。Apache認証に よりこの攻撃に対して防衛することが可能であり、また、LDAPや .htaccessファイル等を使用して固有のアクセスモデルを設計し、PHPスク リプトの一部としてそのコードを読み込むことも可能です。

しばしば、PHPユーザー(この場合はApacheユーザー)が非常に小さなリスクを 有する場所に一度セキュリティが確立されると、PHPはユーザーディレクト リにウイルスファイルを書き込んだりすることができなくなります。もし くは、データベースにアクセスしたり変更したりといったことが出来なく なります。この場合、良いファイルおよび悪いファイルの書き込み、また は、良いデータベーストランザクションと悪いデータベーストランザクシ ョンに関して等しく安全性が確保されていると言えます。

この観点からしばしば行われるセキュリティ上の失敗としてApacheにルー ト権限を与えたり、他の何らかの手段でApacheの権限を昇格させるという ものがあります。

Apacheユーザーの権限をルートに昇格させることは非常に危険であり、シ ステム全体を危険にさらす可能性があります。よって、sudoやchrootの実 行、ルート権限で実行を行う他の手段は、セキュリティに精通した人以外 は、考慮するべきではありません。

いくつかのより簡単な解決策があります。open_basedir を使用することによ り、PHPに使用を許可するディレクトリを制御したり制限したりすること が可能です。また、全てのWebベースの作業をユーザーファイル、システム ファイル以外のファイルに制限するために、Apache専用エリアを設定する ことも可能です。

ファイルシステムのセキュリティ

目次

PHP は、ファイルおよびディレクトリ毎に権限を設定する多くのサーバーシ ステム上に組み込まれたセキュリティを提供します。これにより、ファイ ルシステム内のファイルを読み込み可能に制御することが可能になります。 全てのファイルは世界中から読み込み可能であり、このファイルシステム にアクセスした全てのユーザーから読み込まれても安全であることを確認す る必要があります。

PHPは、ファイルシステムにユーザーレベルのアクセスを許可するように設 計されているため、PHPスクリプトから/etc/password のようなシステム ファイルを読み込み可能としたり、イーサネット接続を修正したり、巨大 なプリンタジョブを出力したりすることができます。これから明らかにわ かることですが、読み書きするファイルを適切に設定する必要があります。

各自のホームディレクトリにあるファイルを削除する次のスクリプトを見 てみましょう。これは、ファイル管理用にWebインターフェイスを使用す る場合に通常生じるような設定を仮定しています。この場合、Apacheユー ザはそのユーザーのホームディレクトリにあるファイルを削除可能です。

例1 甘い変数の確認から生じるリスク

<?php
// ユーザーのホームディレクトリからファイルを削除する
$username = $_POST['user_submitted_name'];
$userfile = $_POST['user_submitted_filename'];
$homedir  = "/home/$username";

unlink("$homedir/$userfile");

echo "ファイルは削除されました!";
?>
username および filename はユーザーフォームから投稿可能であるため、別の username および filename を投稿して 削除すべきではない削除することが可能となります。この場合、 他の何らかの形式の認証を使用するべきです。投稿された変数が、 "../etc/" と "passwd " であった場合について考えてみましょう。簡単 なコードを以下に示します。

例2 ... ファイルシステムへの攻撃

<?php
// 外部からPHPユーザーがアクセス可能なハードドライブを削除します。PHPが
// ルートのアクセス権限を有している場合、
$username = $_POST['user_submitted_name']; // "../etc"
$userfile = $_POST['user_submitted_filename']; // "passwd"
$homedir  = "/home/$username"; // "/home/../etc"

unlink("$homedir/$userfile"); // "/home/../etc/passwd"

echo "ファイルは削除されました!";
?>
こうした問題を防止するために必要な重要なチェック手段として以下の2 種類のものがあります。
  • PHP Webユーザーバイナリに制限された権限のみを許可する。
  • 投稿された全ての変数を確認する。
以下に改良されたスクリプトを示します。

例3 より安全なファイル名の確認

<?php
// PHPユーザーがアクセス可能なハードドライブからファイルを削除する。
$username = $_SERVER['REMOTE_USER']; // 認証機構を使用する
$userfile = basename($_POST['user_submitted_filename']);
$homedir  = "/home/$username";

$filepath = "$homedir/$userfile";

if (file_exists($filepath) && unlink($filepath)) {
    $logstring = "$filepath を削除しました\n";
} else {
    $logstring = "$filepath の削除に失敗しました\n";
}
$fp = fopen("/home/logging/filedelete.log", "a");
fwrite($fp, $logstring);
fclose($fp);

echo htmlentities($logstring, ENT_QUOTES);

?>
しかし、これでも、傷口を塞いだことにはなりません。 ユーザーが自分用のユーザーログインを作成することをあなたの認証システムが 許可しており、ユーザーが"../etc/"へのログインを選択した場合、システム はまたも公開されてしまいます。このため、よりカスタマイズされたチェッ クを行なう方がよいでしょう。

例4 より安全なファイル名の確認

<?php
$username     = $_SERVER['REMOTE_USER']; // 認証機構を使用する
$userfile     = $_POST['user_submitted_filename'];
$homedir      = "/home/$username";

$filepath     = "$homedir/$userfile";

if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
    die("Bad username/filename");
}

//etc...
?>

オペレーティングシステムにより、注意するべきファイルは大きく変化し ます。これらには、デバイスエントリ(/dev/ または COM1)、設定ファイ ル(/etc/ ファイルおよび .ini ファイル)、よく知られたファイル保存領 域 (/home/、 My Documents)等が含まれます。このため、明示的に許可す るもの以外の全てを禁止する方針とする方が通常はより簡単です。

Null バイト関連の問題

PHP はファイルシステム関連の操作に C 言語の関数を使用しているので、 null バイトの処理を予期せぬかたちで行うことがあります。 C 言語では null バイトは文字列の終端を表すので、 null バイトを含む文字列があった場合に null バイト以降の内容は文字列として処理されません。 以下に、この問題に関する脆弱性を含むコード例を示します。

例1 null バイトに対して脆弱なスクリプト

<?php
$file = $_GET['file']; // ここで "../../etc/passwd\0" が渡されたとします
if (file_exists('/home/wwwrun/'.$file.'.php')) {
    // file_exists は true を返します。これは、ファイル /home/wwwrun/../../etc/passwd が存在するからです
    include '/home/wwwrun/'.$file.'.php';
    // ファイル /etc/passwd がインクルードされてしまいます
}
?>

したがって、ファイルシステム操作で使用する「汚染された」文字列は、 つねに適切に検証しなければなりません。 先ほどの例を改良したものを示します。

例2 入力を適切に検証する例

<?php
$file = $_GET['file']; 

// 値として与えられる可能性のある、有効な値の一覧を作成します
switch ($file) {
    case 'main':
    case 'foo':
    case 'bar':
        include '/home/wwwrun/include/'.$file.'.php';
        break;
    default:
        include '/home/wwwrun/include/main.php';
}
?>

データベースのセキュリティ

目次

今日、ダイナミックなコンテンツを提供するウェブアプリケーションに おいてはデータベースは欠く事のできなコンポーネントとなっています。 そういったデータベースには重要な、そして秘密にすべき情報が格納 されることになるので、それらをいかにして保護するかについて十分に 考慮する必要があります。

情報を取り出したり格納するためにはデータベースに接続する必要があります。 そして適切なクエリを送信し、結果を受け取り、切断します。クエリに 使用される言語はStructured Query Language (SQL)が一般的です。アタッカー がどのようにSQLに 干渉するかについて参照してください。

皆さんがお気づきの様に、PHPそれ自体は貴方のデータベースを保護することは ありません。以下のセクションはPHPスクリプトからどのようにデータベースに アクセスし操作すればいいのか、とういことに関する非常に基本的な導入です。

このシンプルなルールを覚えて置いてください：それは「多重防衛」です。 より多くの箇所で、より多くの保護を行うことにより、アタッカーが攻撃に 成功して機密情報が漏洩する可能性は減っていきます。データベースと アプリケーションを正しくデザインすることで貴方の心配を取り除くことが できます。

データベースのデザイン

他人が用意した既存のものを使用するのでない限り、最初に行うのはデータベースの作成です。 データベースが作成されると、そのデータベースのオーナーは作成コマンドを 実行したユーザーになります。通常、オーナー(とスーパーユーザー)のみが そのデータベースに対して操作を行うことが出来ます。他のユーザーがデータベースを 使用するには適切な権利が与えられている必要があります。

アプリケーションはデータベースにオーナー、もしくはスーパーユーザーとして 接続しては絶対にいけません。なぜならこれらのユーザーは 例えばスキーマの変更(テーブルの削除等)や全コンテンツの削除、といった あらゆるクエリーを実行することが出来るからです。

貴方が作成するアプリケーションがデータベースに対して行う操作の各方面ごとに、 操作対象となるオブジェクトに対して、出来る限り少ない権限を持った複数の ユーザーを作成した方が良いでしょう。ユーザーに対しては、最低限必要な権限のみを 与え、関係の無いデータへのアクセスを許可しないようにします。これは、 万が一侵入者がそのユーザーの権限を以ってデータベースにアクセスした際に、 アプリケーションと関係の無いデータにまでアクセスされることを防ぐためです。

全てのビジネスロジックをウェブアプリケーション(つまり貴方のスクリプト) で実装することは推奨されません。代わりに、ビュー、トリガー、ルールといった データベースの機能を活用した方が良いでしょう。システムが更新され、 新しい機能がデータベースへのアクセスすることになった場合、個々のデータベース クライアントごとに再度同様のロジックを実装しなければならなくなります。 さらに、トリガーは透過的に、そして自動的にフィールドを扱うことが出来るので、 デバッグ時や、トランザクションのロールバック時に役立ちます。

データベースへの接続

更なるセキュリティのために、クライアント/サーバー間の通信においてSSLを用いた 暗号化を行った方が良いでしょう。もしくはsshを使用することも出来ます。 どちらかの手段を講じた後、トラフィックをモニタリングしてみれば ここから何らかの情報を得ることが困難だという事が分かると思います。

ストレージの暗号化

SSL/SSHによってクライアント/サーバー間で通信されるデータは保護されますが、 データベースに保存されたデータは保護されません。SSLはあくまで通信上の プロトコルなのです。

一旦アタッカーがデータベースへ(ウェブサーバーを通さずに)アクセスできてしまうと、 そこに格納されているデータ自体が暗号化されていない限り、自由に閲覧され、 使用されてしまいます。データを暗号化することによって、この脅威を減らすことが できますが、この機能をサポートしているデータベースは僅かです。

この問題への最も簡単な対応策は、まず自分専用の暗号化パッケージを作成し、 それをあなたのPHPスクリプトから使用することです。PHPのMcrypt, Mhash といった幾つかの拡張モジュールは、様々な暗号化アルゴリズムをサポート しているので役に立つでしょう。データ格納時に暗号化を行い、取得時に 復号化します。この方法についてはリファレンスを参照してください。

もし完全にデータを隠したい場合や、元のデータ自体は必要ない場合(つまり 表示されない場合)は、ハッシュも考慮に入れたほうが良いでしょう。 ハッシュの良く知られた使用方法は、パスワードをそのまま格納せずに、 その暗号学的ハッシュ値を格納する方法です。crypt() も参照してください。

例1 ハッシュされたパスワードフィールドを使う

// ハッシュされたパスワードを格納する
$query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
            pg_escape_string($username), crypt($password, '$2a$07$usesomesillystringforsalt$'));
$result = pg_query($connection, $query);

// パスワードが正しいかどうか問い合わせる
$query = sprintf("SELECT 1 FROM users WHERE name='%s' AND pwd='%s';",
            pg_escape_string($username), crypt($password, '$2a$07$usesomesillystringforsalt$'));
$result = pg_query($connection, $query);

if (pg_num_rows($result) > 0) {
    echo 'Welcome, $username!';
} else {
    echo "$username の認証が失敗しました。";
}

SQLインジェクション

多くの開発者はSQLクエリがどのように改竄されるかということを余り 気にかけておらず、またSQLクエリは信用できるものと考えているようです。 実際にはSQLクエリはアクセス制限を回避することが可能で、従って 通常の認証や権限のチェックを無視することができます。時には、 OSレベルのコマンドを実行できてしまうこともあります。

ダイレクトSQLコマンドインジェクション(SQLコマンドの直接実行)という手法は、 攻撃者がSQLコマンドを生成もしくは既存のコマンドを変更することで 隠蔽すべきデータを公開したり、重要なデータを書き換えたり、データベース ホストで危険なシステムレベルのコマンドを実行したりするものの事です。 この手法は、ユーザーからの入力をスタティックなパラメータと組み合わせて SQLクエリを生成するアプリケーションにおいて使用されます。以下の例は 不幸なことに実際の事例に基づいたものです。

入力のチェックを怠っており、スーパーユーザーもしくはデータベース作成権限を 持つユーザー以外のユーザーでデータベースに接続していない ために、攻撃者はデータベースにスーパーユーザーを作成することが出来ます。

例1 表示するデータを分割し ... そしてスーパーユーザーを作成します。 (PostgreSQLの例)

$offset = $argv[0]; // 入力チェックが行われていません！
$query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
$result = pg_query($conn, $query);
通常のユーザーは、$offsetがURLに埋め込まれている '次へ'または'前へ'リンクをクリックします。スクリプトは、受け取った $offsetが数字であることを期待します。しかしながら、 攻撃者はurlencode()された以下のようなURLを追加 することで攻撃を試みます。 
0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
    select 'crack', usesysid, 't','t','crack'
    from pg_shadow where usename='postgres';
--
このようなことが行われると、スクリプトは攻撃者にスーパーユーザー権限での アクセスを提供してしまいます。0;が正しいオフセット 指していると同時に、クエリをそこで終端させていることに気をつけてください。

注意:

SQLパーサにクエリの残りの部分を無視させるために開発者によく使わ れる技法として、SQLのコメント記号である--があ ります。

パスワードを取得する恐るべき手段に、サイトの検索結果のページを欺く というものがあります。攻撃する者が必要とするものは、投稿された変数 の中でSQL命令で使用される際に正しく扱われていないものがあるかどう かを確かめるだけです。これらのフィルタは、通常、 SELECT文のWHERE, ORDER BY, LIMIT及びOFFSET句をカスタマイズするた めに前に置かれる形で設定されます。使用するデータベースが UNION構造をサポートしている場合、 攻撃者は元のクエリに任意のテーブルからパスワードのリストを取得する クエリを追加しようとするかもしれません。 暗号化されたパスワードフィールドを使用することが強く推奨されます。

例2 記事...そして(全てのデータベースサーバーの)いくつかのパスワード のリストを表示する

$query  = "SELECT id, name, inserted, size FROM products
                  WHERE size = '$size'
                  ORDER BY $order LIMIT $limit, $offset;";
$result = odbc_exec($conn, $query);
クエリの静的な部分は、以下のように全てのパスワードを外部にもらす別の SELECT文と組み合わせることができます。 
'
union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
--
('及び--を使用する) このクエリが$queryで使用される変数の１つに代入 された場合、この悪意のあるクエリが実行されることになります。

SQL UPDATE もデータベースを攻撃するために使用されます。これらのク エリも切捨てたり新しいクエリを元のクエリに追加することによる攻撃 を受けます。しかし、攻撃者はSET句を使用する可 能性があります。この場合、クエリを成功させるためにいくつかのスキー マ情報を保有する必要があります。これは、フォームの変数名や総当た り法により調べることができます。パスワードまたはユーザー名を保存す るフィールド用の命名記法はそう多くはありません。

例3 パスワードのリセットから ... (全てのデータベースサーバーで)より多 くの権限を得るまで

$query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
しかし、悪意のあるユーザーは、管理者のパスワードを変更するために 値 ' or uid like'%admin%'; -- を $uid に代入するか、または、より多くの権限を得 るために、単純に$pwd に(後ろに空白を付けて) "hehehe', admin='yes', trusted=100 "と設定する 可能性があります。この場合、このクエリは以下のように改謬されてし まいます。
// $uid == ' or uid like'%admin%'; --
$query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%'; --";

// $pwd == "hehehe', admin='yes', trusted=100 "
$query = "UPDATE usertable SET pwd='hehehe', admin='yes', trusted=100 WHERE ...;"

恐ろしい例として、いくつかのデータベースホストのオペレーティン グシステムレベルのコマンドがアクセス可能となる方法を示します。

例4 データベースホストのオペレーティングシステムを攻撃する (MSSQLサーバー)

$query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
$result = mssql_query($query);
攻撃者が、値 a%' exec master..xp_cmdshell 'net user test testpass /ADD' -- を$prodに投稿した場合、 $query は以下のようになります。
$query  = "SELECT * FROM products
                    WHERE id LIKE '%a%'
                    exec master..xp_cmdshell 'net user test testpass /ADD'--";
$result = mssql_query($query);
MSSQLサーバー−は、新規ユーザーをローカルアカウント用データベースに追 加するコマンドを含むSQL命令をバッチ実行します。 このアプリケーションがsaで実行され、 MSSQLSERVERサービスが充分な権限で実行されている場合、攻撃者は このマシンにアクセスする権限を有することになります。

注意:

上記のいくつかの例は、データベースサーバーの種類に依存しています。 これは、他の製品に対して同様な攻撃ができないことを意味するもので はありません。使用しているデータベースが他の手段で攻撃可能である 可能性もあります。

SQL インジェクションで発生する問題の例
この画像は » xkcd から提供いただいたものです。

回避策

攻撃者がデータベースの構造に関して最低限の知識を持っていないと攻撃は成功しないということは明らかですが、 その手の情報はたいてい、簡単に入手できます。 たとえば、オープンソースやその他一般に公開されているソフトウェアパッケージをデフォルトの設定で使っていれば、 データベースの情報は完全に公開されているので誰でも知ることができます。 クローズドソースのコードであってもこの手の情報は漏れることがあります。 たとえ何らかの難読化処理が行われていたとしても。 さらに、自作のコードだとしても、 画面に表示されるエラーメッセージなどから情報が漏れることがあります。 それ以外にも、ありがちなテーブル名やカラム名などは攻撃の対象となります。 たとえば、ログインフォームで使っているテーブル名が 'users' で、その中に 'id'、'username'、'password' といったカラムがある場合などです。

これらの攻撃は、セキュリティを考慮して書かれていないコードを攻撃 する方法です。特にクライアント側から入力されるあらゆる種類の入力 を決して信用しないでください。これは、selectボックスやhidden input フィールド、Cookieの場合も同様です。最初の例は、このような欠点の ないクエリが破滅をもたらしうることを示すものです。

  • データベースにスーパーユーザーまたはデータベースの所有者として 接続しないでください。 非常に制限された権限を有するカスタマイズ されたユーザーを常に使用してください。
  • 指定された入力が期待するデータ型であることを確認してください。 PHPは、多くの種類の入力検証用関数を有しており、 変数関連の関数や 文字型関数にある簡単な関数 (例: それぞれ、is_numeric(), ctype_digit()) や、 Perl互換の正規表現のサポートま であります。

  • アプリケーションが、数値入力を期待している場合、データを is_numeric()で検証するか、 settype()により暗黙の型変換を行うか、 sprintf()により数値表現を使用することを検討 してみてください。

    例5 ページング用のクエリを構築するためのより安全な方法

    settype($order, 'integer');
    $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";

    // フォーマット文字列の%dに注意してください。%sを使用しても意味がありません。
    $query = sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;",
                     $offset);

  • データベースに渡される数値以外のユーザー入力を データベース固有の文字列エスケープ関数 (mysql_real_escape_string(), sqlite_escape_string() など) でクオートしてください。 データベース固有の文字列エスケープ機能が利用できない場合、 addslashes() および str_replace()関数が利用できるでしょう。 (データベースの型に依存) 最初の例を参照 してください。前期の例が示すように、クエリの静的な部分をクオート するだけでは充分ではなく、簡単にクラックされてしまう可能性があ ります。
  • データベース固有の情報、特にスキーマに関する情報は出力してはい きません。エラー出力およ びエラー処理およびログ関数 も参照ください。
  • ユーザーがテーブルまたはビューに直接アクセスできないように、 データアクセスを抽象化することを目的としてストアドプロシージャ 及び事前に定義したカーソルを使用することもできますが、このソリュー ションには、副作用があります。

これらのケースにおいて、スクリプトまたはサポートされている場合は データベース自体でクエリのログをとることが有益です。 明らかにログは破壊的な行為を防止することはできませんが、攻撃され たアプリケーションを追跡する際には有効です。ログ自体は有益ではあ りませんが、含まれている情報は有益です。通常、より詳細なログをと る方が良いでしょう。

エラーのレポート

PHPのセキュリティに関して、2種類のエラー出力があります。一つは、セ キュリティ向上に役立つものであり、もう一つは、セキュリティ上有害な ものです。

標準的な攻撃手法の中に不完全なデータをシステムに送信し、返されるエ ラーの種類と内容を調べることにより、システムを調べるというものがあ ります。これにより、システムのクラッカーがありうる弱点を調査するた めにそのサーバーに関する情報を調べることが可能になります。 例えば、ある攻撃者が事前のフォーム投稿の際にあるページに関して収集 した情報を持っている場合、変数を上書きしたり、修正したりしようとす るかもしれません。

例1 カスタムHTMLページにより変数を攻撃する

<form method="POST" action="attacktarget?username=badfoo&password=badfoo">
<input type="hidden" name="username" value="badfoo">
<input type="hidden" name="password" value="badfoo">
</form>

通常返されるPHPのエラーは、エラーを生じた関数やファイル、エラーを 発生したPHPファイル、エラーを発生した行番号のような情報が含まれて おり、スクリプトをデバッグする開発者に非常に有用です。これらが調べ ることができる情報の全てです。デバッグ目的でPHPの開発者が show_source(), highlight_string(), highlight_file() を使用することはまれではありま せん。しかし、実用サイトでは、これは秘密の変数、未確認の構文、その 他の危険な情報を公開することになってしまいます。特に危険なのは、 組み込みのデバッグハンドラを有する既知のソースからのコードを実行して いるか、一般的なデバッグ技法を使用している場合です。攻撃者が、使用し ている一般的な技法を特定できた場合、次のようにあるページに様々な一般 的なデバッグ用文字列を送信することによりしらみつぶしに攻撃しようとす るかもしれません。

例2 一般的なデバッグ変数を探す

<form method="post" action="attacktarget?errors=Y&amp;showerrors=1&amp;debug=1">
<input type="hidden" name="errors" value="Y">
<input type="hidden" name="showerrors" value="1">
<input type="hidden" name="debug" value="1">
</form>

エラー処理の方法の方法のいかんによらず、エラーを調べる機能は、攻撃 者により多くの情報を与えることにつながります。

例えば、多くの一般的なエラー形式では、システムはPHPを実行している ことを示します。攻撃者が .html ページを調べ、(システムの既知の弱点 を探すために)誤ったデータを送信することによりバックエンドを調べた いと思った場合、システムをPHPと共に構築されていることを知ることが 可能となる可能性があります。

関数エラーは、システムが特定のデータベースエンジンが実行しているこ と、または、Webページのプログラム内容や設計に関する鍵を示すことが あります。これにより、データベースポートをオープンしたり、Webペー ジに固有のバグや弱点を調べるといったより詳細な調査を行うことが可能 となります。例えば、異なった不正なデータを送信することにより、攻撃 者は、(エラー行番号から)そのスクリプトの異なる場所を調べることと同 時にそのスクリプトの認証の順番を定義することが可能です。

ファイルシステムまたは一般的なPHPエラーは、Webサーバーが有する許可属 性やWebサーバーのファイル構造を示すことがあります。エラーコードを書 く開発者は、元は秘密の情報を容易に公開することにより、この問題を悪 化させる可能性があります。

この問題に対しては3種類の対策があります。最初の対策は、全ての関数 をよく調べ、大部分のエラーの修正を試みることです。2番目は、実行す るコードのエラーリポートを完全に無効にすることです。3番目は、 PHPのカスタムエラー処理関数を使用して独自のエラーハンドラを作成す ることです。システムのセキュリティポリシーに基づき、これらの3種類 の対策が適用可能かどうかを判定します。

この問題を事前に防止する手段の一つは、PHPに組み込まれている error_reporting()機能を使用することです。これにより、 コードを安全にするための手がかりが得られ、危険と思われる変数が使用 されている部分をみつけることが可能です。実使用の前に E_ALL を指定してコードをテストすることにより、変数が他の手段で汚染されたり、修正さ れたりする可能性がある部分を簡単に見つけることが可能です。 実使用の準備ができた際には、あなたのコードをプローブから保護するために error_reporting() を 0 に設定するか、php.ini のオプション display_errors をオフに設定する、 のいずれかでエラーリポートを完全に無効にすべきです。 もし後者を選択した場合、加えて error_log ini ディレクティブを使用する、あるいは log_errors をオンにしてログファイルのパスを定義すべきです。

例3 E_ALLで危険な変数を見つける

<?php
if ($username) {  // 使用前に初期化または確認されていない変数
    $good_login = 1;
}
if ($good_login == 1) { // 上のテストが失敗した場合、使用前に初期化または確認されていない
    readfile ("/highly/sensitive/data/index.html");
}
?>

グローバル変数の登録機能の使用法

警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

PHPの変更点で最も議論の対象となったのは、おそらく、PHP » 4.2.0において PHPのディレクティブ register_globalsが デフォルトでONからOFFに変更された時でしょう。 当時、このディレクティブに依存することが一般的であり、多くの人は、 このパラメータの存在すら知らず、PHPの動作そのものであるというよう に考えていました。このページは、このディレクティブにより安全でな いコードを書く可能性があるということをこのページで説明しますが、 このディレクティブそのものが安全でないわけではなく、これを誤って使 用することが安全でないということを念頭においていてください。

register_globalsをonとした場合、この機能により、HTMLフォームから投 稿される変数と同時に、あらゆる種類の変数がスクリプトに注入される ことになります。これは、PHPにおいては変数の初期化が不 要であるということにも関係し、安全でないコードを書くことが極めて容 易になるということを意味します。困難な変更でしたが、PHPコミュニティ は、このディレクティブをデフォルトで無効とすることを決定しました。 onとした場合、どこから来たのかが不明であり、出処を仮定するしかない 変数を使用することになります。スクリプト自体で定義される内部変数は、 ユーザーにより送信されたリクエストデータと混ざってしまいますが、 register_globals を無効とすることでこれを回避することができます。 以下にregister_globalsの誤った使用例を示しましょう。

例1 register_globals = on の誤った使用例

<?php
// ユーザーが認証された場合のみ $authorized = true を定義する
if (authenticated_user()) {
    $authorized = true;
}

// 最初に$authorizedをfalseとして初期化していないため、
// 以下のコードにより、GET auth.php?authorized=1 のように
// register_globals機能により定義される可能性があります。
// このため、誰でも認証されたようにみせることができます!
if ($authorized) {
    include "/highly/sensitive/data.php";
}
?>

register_globals = onとした場合、上記のロジックは破綻する可能性が あります。offの場合、$authorizedはリクエストに より設定することはできず、正しく動作します。しかし、一般に良いプロ グラミング法は、変数を最初に初期化することです。例えば、上の例で $authorized = falseを先頭に置いておくことができ ます。これにより、ユーザーはデフォルトで認証されない状態となるため、 register_globalsのon/offによらず上記のコードは動作します。

別の例は、 セッションに関するも のです。register_globals = onとした場合、以下の例で $usernameを使用することもできますが、 (URLにより)GETのような他の手段によっても $username を設定することができることに留意する 必要があります。

例2 register_globals on またはoffの場合のセッションの使用例

<?php
// $usernameの出処は不明だが、$_SESSIONがセッションデータであることは
// 既知です。
if (isset($_SESSION['username'])) {

    echo "Hello <b>{$_SESSION['username']}</b>";

} else {

    echo "Hello <b>Guest</b><br />";
    echo "Would you like to login?";

}
?>

偽造が試みられた時に警告するために予防的な計測を行うことも可能です。 ある変数の出処を前もって正確に知っている場合、 投稿されたデータが適切な投稿元からのものであるかを調べることができ ます。これは、データが偽造されたものでないことを保証するわけではあ りませんが、攻撃者による偽造の成立を限定的なものにすることができま す。リクエストデータの出処を気にかけない場合、 $_REQUEST を使用することができます。 この変数には、GET、POST、COOKIEが合わさって含まれています。 本マニュアルの 外部から来る変数 のセクションを参照してください。

例3 簡単に変数汚染を検出する

<?php
if (isset($_COOKIE['MAGIC_COOKIE'])) {

    // MAGIC_COOKIE comes from a cookie.
    // Be sure to validate the cookie data!

} elseif (isset($_GET['MAGIC_COOKIE']) || isset($_POST['MAGIC_COOKIE'])) {

   mail("admin@example.com", "Possible breakin attempt", $_SERVER['REMOTE_ADDR']);
   echo "Security violation, admin has been alerted.";
   exit;

} else {

   // MAGIC_COOKIE isn't set through this REQUEST

}
?>

もちろん、register_globalsをoffにするだけでは、使用するコードが安 全であることを意味しません。投稿された全てのデータ毎に 他の手段で検証することも必要です。ユーザーデータを常に検証し、 使用する変数を初期化してください! 初期化されていない変数を調べるには、 error_reporting()で E_NOTICEレベルのエラーを有効にするように してください。

register_globalsをOnまたはOffのエミュレートに関数情報に ついては、FAQを 参照してください。

注意: スーパーグローバル: 使用可能なバージョンに関する注意

PHP 4.1.0 以降、 $_GET, $_POST, $_SERVER 等のスーパーグローバル配列が使用可能となっています。 詳細な情報については、マニュアルの superglobals のセクションを参照してください。

ユーザーが投稿したデータ

多くの PHP のプログラムで最も脆弱な部分は、言語自体に起因するものではなく、 単にセキュリティを考慮して書かれていないコードの問題です。そのため、 指定したコードの部分の意味を常に時間をかけて吟味し、 予想外の変数が投稿された場合に有り得る損害を確かめる必要があります。

例1 危険な変数の使用

<?php
// ユーザーのホームディレクトリからファイルを削除します... または他の誰
// かのディレクトリかも?
unlink ($evil_var);

// 彼らのアクセスのログを書き込む.. または違うかも?
fputs ($fp, $evil_var);

// 何かちょっとしたことを実行.. または rm -rf *?
system ($evil_var);
exec ($evil_var);

?>
常に注意してコードをテストし、Webブラウザから投稿された全ての変数 について次のような点を確認してください。
  • このスクリプトは、意図したファイルのみを受け付けるか?
  • 例外的なまたは意図したもの以外のデータにより実行することが可能 か?
  • このスクリプトは意図した以外の方法で使用することが可能か?
  • このスクリプトは、悪い意味で他のスクリプトと組み合わせて使用す ることが可能か?
  • トランザクションは適切に記録されているか?
スクリプトを書いた後ではなく、書いている時にこれらの質問を適宜行う ことにより、セキュリティ改善のために不幸にして書き直しが必要になる ということを避けることができます。こうした考慮をまず行うことにより、 システムのセキュリティを保証できるわけではありませんが、改善の一助 にはなりえます。

register_globals,magic_quotes, または他の便利な設定は、有効性、発 信元、指定した変数の値について混乱を生じる可能性があるため、設定を オフにしたいと思うかもしれません。error_reporting(E_ALL) モードで PHPを動作させた場合、確認または初期化する前に使用された変数に関し て警告を発生させることも可能です。(これにより、処理時に通常とは異 なるデータを防止することが可能です)

マジッククオート

目次

警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

マジッククオートは、PHPスクリプトに入力されるデータを 自動的にエスケープする機能です。 コードでは、マジッククオートをオフにして 実行する際必要な時にデータをエスケープすることが望まれます。

マジッククオートとは

警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

オンの場合、全ての' (シングルクオート), " (ダブルクオート), \ (バックスラッシュ)およびNULL 文字がバックスラッシュで自動的にエスケープされます。 これは、addslashes() の機能と同じです。

3種類のマジッククオートディレクティブを以下に示します。

  • magic_quotes_gpc HTTPリクエストデータ(GET, POST, そして COOKIE)に作用します。 実行時に設定することはできません。 PHPのデフォルトは、onです。 get_magic_quotes_gpc()も参照してください。
  • magic_quotes_runtime 有効な場合、データベースやテキストファイルを含む 外部ソースからデータを返す関数の多くは、 バックスラッシュをクオートでエスケープします。 実行時に設定することができ、PHPでのデフォルトは offです。 set_magic_quotes_runtime()および get_magic_quotes_runtime()も参照してください。
  • magic_quotes_sybase 有効な場合、シングルクオートはバックスラッシュではなくシングルクオートで エスケープされます。 onの場合、 magic_quotes_gpc の指定を完全に上書きします。 これら両方のディレクティブを有効にすると、シングルクオートは ''とエスケープされます。 ダブルクオートやNULLはそのままとなり、エスケープされません。 この値を取得するには、 ini_get()も参照してください。

なぜマジッククオートを使用していたのか

警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

  • もはやマジッククオートを使う理由はありません。 PHP ではサポートされなくなるからです。以前は確かに存在し、 特に意識せずによりよい (安全な) コードを書けるという意味で 一部の初心者の助けとなっていました。 しかし、この挙動を前提としたコードを見かけたときは マジッククオートをオンにするよりコードそのものを書き換えるほうがいいでしょう。 ではいったい、なぜこんな機能が存在していたのか? 単純に、SQL インジェクション を防ぐためというだけの理由です。 いまどきの開発者はセキュリティに対する意識が向上しており、 マジッククオートなどという機能に頼るよりも データベース自体のエスケープ機能やプリペアドステートメントを使った方がよいことに気づいています。

なぜマジッククオートを使用しないのか

警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

  • 移植性 これがonであることを仮定すると、移植性に影響します。 この確認のためにget_magic_quotes_gpc()を 使用し、適切なコーディングを行ってください。
  • 性能 エスケープされたデータが全てデータベースに挿入されるわけではないので、 このように全てのデータをエスケープすることは性能を低下させます。 単に(addslashes()のような)エスケープを行う関数を 実行時にコールする方がより効率的です。 php.ini-developmentはこれらのディレクティブを デフォルトで有効にしていますが、 php.ini-productionはこれを無効にしています。 この推奨は主に性能面によるものです。
  • 不便 全てのデータをエスケープする必要はないため、しばしば、 エスケープするべきではないデータまでエスケープされてしまう問題に 悩まされることになります。例えば、フォームからメールを送信する際、 emailの中に多くの \' が含まれることになります。 これを修正するために、 stripslashes()を大量に使用することが必要と なる可能性があります。

マジッククオートを無効にする

magic_quotes_gpc ディレクティブはシステムレベルでのみ無効にすることができ、 実行時に行うことはできません。 つまり、ini_set() では指定できません。

例1 マジッククオートをサーバー側で無効にする

このディレクティブをphp.iniで Off にする 例を示します。 より詳細については、 設定を変更する方法というタイトルのマニュアルのセクションを 参照してください。 

; Magic quotes
;

; Magic quotes for incoming GET/POST/Cookie data.
magic_quotes_gpc = Off

; Magic quotes for runtime-generated data, e.g. data from SQL, from exec(), etc.
magic_quotes_runtime = Off

; Use Sybase-style magic quotes (escape ' with '' instead of \').
magic_quotes_sybase = Off

サーバーの設定を変更できない場合には、 .htaccessも使用できます。 例えば、 

php_flag magic_quotes_gpc Off

サーバーレベルの設定を変更できない場合に対応するといったように、 移植性の高いコード(あらゆる環境で動作するコード)を書く要望に 対して、以下に、 magic_quotes_gpcを実行時に無効にする例を示します。 この方法は非効率であるため、どこかでディレクティブを適切に 設定する方が良いでしょう。

例2 マジッククオートを実行時に無効にする

<?php
if (get_magic_quotes_gpc()) {
    $process = array(&$_GET, &$_POST, &$_COOKIE, &$_REQUEST);
    while (list($key, $val) = each($process)) {
        foreach ($val as $k => $v) {
            unset($process[$key][$k]);
            if (is_array($v)) {
                $process[$key][stripslashes($k)] = $v;
                $process[] = &$process[$key][stripslashes($k)];
            } else {
                $process[$key][stripslashes($k)] = stripslashes($v);
            }
        }
    }
    unset($process);
}
?>

PHPの隠蔽

一般に隠蔽という手段はセキュリティとしては弱いものだと言われています。 しかしこうした手法が望ましい場合もあります。

PHP を隠すための簡単な技法がいくつかあり、 システムの弱点を見つけようとする攻撃を遅延させることができる可能性があります。 php.ini ファイルで expose_php を off と設定すれば、 攻撃者が利用可能な情報を減らすことができます。

他の手段は、ApacheのようなWebサーバーで PHPに異なるファイル形式をパースさせるように設定することです。 これは、.htaccessディレクティブまたは Apacheの設定ファイル自体で指定します。 これにより、紛らわしいファイル拡張子を使用可能です。

例1 PHPを他の言語として隠す

# PHPコードを他のコード型のようにする
AddType application/x-httpd-php .asp .py .pl
または、次のように完全に隠すことも可能です。

例2 PHP拡張子用に未知の型を使用する

# Make PHP code look like unknown types
AddType application/x-httpd-php .bop .foo .133t
または、HTMLコードとして隠すことも可能です。この場合、全てのHTMLファ イルがPHPエンジンを通じてパースされることになるため、若干の性能上の 問題があります。

例3 PHP拡張子としてHTML型を使用する

# 全てのPHPコードをHTMLのように作成する
AddType application/x-httpd-php .htm .html
効率的にこれを使用するには、全てのPHPファイルの名前を上の拡張子に変更 する必要があります。これは、あいまいさに基づく形式のセキュリティですが、 欠点の少ない簡単な防衛策です。

最新版を維持する

PHP は、他の大規模なシステムと同様に、セキュリティを確保しつつ 改良されています。新バージョンにはしばしば大規模あるいは小規模な 変更が含まれています。その内容は、セキュリティの機能追加であったり セキュリティ上の問題・設定の不備・その他システム全体のセキュリティや 安定性にかかわる問題の修正であったりします。

他のシステムレベルのスクリプト言語やプログラムと同様に、最善の アプローチは、頻繁に更新し、最新のバージョンとその変更を 注視し続けることです。

機能

PHP による HTTP 認証

header() 関数を使うと、 "Authentication Required" メッセージをクライアントブラウザに送ることができます。 これにより、クライアントブラウザではユーザー名とパスワードの入力要求 ウインドウがポップアップ表示されます。一度、ユーザーがユーザー名と パスワードを入力すると、PHP スクリプトを含むその URL は、次回以降、 定義済みの変数 PHP_AUTH_USER と、 PHP_AUTH_PW と、 PHP_AUTH_TYPE にそれぞれユーザー名、 パスワード、認証型が代入された状態で呼ばれます。 定義済みの変数は、配列 $_SERVER および $HTTP_SERVER_VARS でアクセス可能です。 "Basic" 認証および "Digest" 認証 (PHP 5.1.0 以降) の両者がサポートされています。詳細は、 header()を参照ください。

注意: PHP バージョンに関する注意

$_SERVER のような スーパーグローバルは、 PHP » 4.1.0 以降で利用可能となりました。

ページ上でクライアント認証を強制するスクリプトの例を以下に示します。

例1 Basic HTTP 認証の例

<?php
if (!isset($_SERVER['PHP_AUTH_USER'])) {
    header("WWW-Authenticate: Basic realm=\"My Realm\"");
    header("HTTP/1.0 401 Unauthorized");
    echo "ユーザーがキャンセルボタンを押した時に送信されるテキスト\n";
    exit;
} else {
    echo "<p>こんにちは、{$_SERVER['PHP_AUTH_USER']} さん。</p>";
    echo "<p>あなたは、{$_SERVER['PHP_AUTH_PW']} をパスワードとして入力しました。</p>";
}
?>

例2 Digest HTTP 認証の例

この例は、シンプルな Digest HTTP 認証スクリプトをどの様に実装するか を示しています。 その他情報については、» RFC 2617 を読んでください。

<?php
$realm = 'Restricted area';

//user => password
$users = array('admin' => 'mypass', 'guest' => 'guest');


if (empty($_SERVER['PHP_AUTH_DIGEST'])) {
    header('HTTP/1.1 401 Unauthorized');
    header('WWW-Authenticate: Digest realm="'.$realm.
           '",qop="auth",nonce="'.uniqid().'",opaque="'.md5($realm).'"');

    die('ユーザーがキャンセルボタンを押した時に送信されるテキスト');
}


// PHP_AUTH_DIGEST 変数を精査する
if (!($data = http_digest_parse($_SERVER['PHP_AUTH_DIGEST'])) ||
    !isset($users[$data['username']]))
    die('誤った証明書です!');


// 有効なレスポンスを生成する
$A1 = md5($data['username'] . ':' . $realm . ':' . $users[$data['username']]);
$A2 = md5($_SERVER['REQUEST_METHOD'].':'.$data['uri']);
$valid_response = md5($A1.':'.$data['nonce'].':'.$data['nc'].':'.$data['cnonce'].':'.$data['qop'].':'.$A2);

if ($data['response'] != $valid_response)
    die('誤った証明書です!');

// OK, 有効なユーザー名とパスワードだ
echo 'あなたは次のユーザーとしてログインしています: ' . $data['username'];

// http auth ヘッダをパースする関数
function http_digest_parse($txt)
{
    // データが失われている場合への対応
    $needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1);
    $data = array();
    $keys = implode('|', array_keys($needed_parts));

    preg_match_all('@(' . $keys . ')=(?:([\'"])([^\2]+?)\2|([^\s,]+))@', $txt, $matches, PREG_SET_ORDER);

    foreach ($matches as $m) {
        $data[$m[1]] = $m[3] ? $m[3] : $m[4];
        unset($needed_parts[$m[1]]);
    }

    return $needed_parts ? false : $data;
}
?>

注意: 互換性に関する注意

HTTPヘッダ行をコーディングする際には注意を要します。全てのクライアントへの 互換性を最大限に保証するために、キーワード "Basic" には、 大文字の"B"を使用して書くべきです。realm文字列は(一重引用符ではなく) 二重引用符で括る必要があります。また、HTTP/1.0 401 ヘッダ行のコード 401 の前には、 1つだけ空白を置く必要があります。 認証パラメータは、上のダイジェスト認証の例にあるように カンマ区切りで指定しなければなりません。

単に PHP_AUTH_USERおよびPHP_AUTH_PW を出力するのではなく、ユーザー名とパスワードの有効性をチェックしたいと 思うかもしれません。 その場合、クエリーをデータベースに送るか、ある dbm ファイル中の ユーザーを調べるといったことをすることになるでしょう。

バグのある Internet Explorer ブラウザには注意してください。このブラ ウザは、ヘッダの順序に関してとてもうるさいようです。今のところ、 HTTP/1.0 401 ヘッダの前に WWW-Authenticate ヘッダを送るのが効果があるようです。

PHP 4.3.0 以降、誰かが従来の外部機構による認証を行ってきたページの パスワードを暴くようなスクリプトを書くことを防ぐために、 特定のページに関して外部認証が可能でかつ セーフモード が有効の場合、 PHP_AUTH 変数はセットされません。 この場合、外部認証されたユーザーかどうかを確認するために REMOTE_USER 変数、すなわち、 $_SERVER['REMOTE_USER'] を使用することができます。

注意: 設定上の注意

PHP は、外部認証が動作しているかどうかの判定を AuthType ディレクティブの有無で行います。

しかし、上記の機能も、認証を要求されないURLを管理する人が同じサーバー にある認証を要するURLからパスワードを盗むことを防ぐわけではありませ ん。

サーバーからレスポンスコード 401 を受けた際に、Netscape Navigatorおよび Internet Explorer は共にローカルブラウザのウインドウ上の認証キャッシュを 消去します。この機能により、簡単にユーザーを"ログアウト"させ、強制的に ユーザー名とパスワードを再入力させることができます。この機能は、 "タイムアウト" 付きのログインや、"ログアウト" ボタンに適用されています。

例3 新規に名前 / パスワードを入力させる HTTP 認証の例

<?php
function authenticate() {
    header('WWW-Authenticate: Basic realm="Test Authentication System"');
    header('HTTP/1.0 401 Unauthorized');
    echo "このリソースにアクセスする際には有効なログインIDとパスワードを入力する必要があります。\n";
    exit;
}

if (!isset($_SERVER['PHP_AUTH_USER']) ||
    ($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
    authenticate();
} else {
    echo "<p>Welcome: " . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "<br />";
    echo "Old: " . htmlspecialchars($_REQUEST['OldAuth']);
    echo "<form action='' method='post'>\n";
    echo "<input type='hidden' name='SeenBefore' value='1'>\n";
    echo "<input type='hidden' name='OldAuth' value=\"" . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "\" />\n";
    echo "<input type='submit' value='Re Authenticate'>\n";
    echo "</form></p>\n";
}
?>

この動作は、HTTP Basic 認証の標準に基づいていません。よって、この機能に 依存しないように注意する必要があります。Lynx によるテストの結果、 Lynx は、認証証明書を 401 サーバー応答によりクリアしないことが明らかに なっています。このため、back を押してから forward を再度押すことにより 証明書の要件が変更されない限りリソースをオープンすることができます。 しかし、ユーザーは '_' キーを押すことにより認証情報をクリアすることが可能です。

PHP4.3.3 までは、Microsoft の IIS サーバーと CGI 版の PHP の組み合わせでは、 この機能は、IIS の制約により使用することができなかったことにも 注意してください。PHP 4.3.3 以降においてこの機能を使用するには、 IIS の設定の "ディレクトリセキュリティ" の "編集" ボタンを押して "匿名アクセス" のみをオンにしてください。 その他のフィールドはオフのままにしてください。

他の制限としては、IIS モジュール (ISAPI) と PHP 4 を使用している場合に、 PHP_AUTH_* 変数が使用できないことがあります。 しかし、代わりにHTTP_AUTHORIZATION を使うことができます。 例えば、次のようなコードを考慮してください。list($user, $pw) = explode(':', base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));

注意: IIS に関する注意:
IIS上 で HTTP 認証を使用する場合、PHP の cgi.rfc2616_headers ディレクティブは0 (デフォルト値) にセットされて いなければなりません。

注意:

セーフモード が有効の場合、 WWW-Authenticateヘッダの realm部にスクリプトの uid が追加されます。

クッキー(Cookies)

PHP は、HTTP クッキー(Cookie)を完全にサポートします。 クッキーは、リモートブラウザに文字列データを保存したり、 再訪するユーザーを特定したりする機構です。 setcookie() か setrawcookie() を使用してクッキーをセットすることができます。 クッキーは HTTP ヘッダの一部なので、 setcookie() はブラウザに何らかの出力を行う前にコールする必要があります。 この制約は、header() に課されているものと同じです。 また、 出力バッファ関数を使用して、 設定するクッキーや送信するヘッダの内容が決まるまで スクリプトからの出力を遅らせることが出来ます。

もし variables_order が "C" を含んでいる場合、クライアントから送られた全てのクッキーは 自動的に $_COOKIE という（常にグローバルな）配列に格納されます。 多数の値を一つのクッキーに割り付けたい場合は、[] をクッキー名に加えてください。

register_globals の設定に よっては、クッキーから通常の PHP 変数を作成することも可能です。 しかし、この設定に依存することは推奨されません。なぜなら、セキュリティの 観点からこの機能はオフにされていることが多いからです。 それ以前のバージョンでも、track_vars がセットされていれば $HTTP_COOKIE_VARS にクッキーの内容が格納されます。 (この設定は PHP 4.0.3 以降は常にオンになっています)

ちょっとした注意やブラウザのバグといった詳細に関しては、 setcookie() と setrawcookie() を参照してください。

セッション

PHPのセッションサポートは、連続するアクセスを通じて特定のデータを保持する 手段を構成します。この機能により、よりカスタマイズされたアプリケーション の構築が可能となり、Webサイトをより魅力的なものにすることができます。 詳細な情報は、 セッションに関するリファレンス のセクションにあります。

XFormsの処理

» XForms は、従来のWebフォームから 派生したもので、広範なプラットフォームやブラウザそしてPDFドキュメントのような 従来のメディア以外のものにすら使用することができます。

xformsのまず第一の違いは、クライアントへフォームを送信する方法です。 » HTML作成者のためのXForms には、XFormsの作成方法の詳細な解説がありますが、この手引きの趣旨に沿って、 ここでは簡単な例のみ示すことにします。

例1 簡単なXForms検索フォーム

<h:html xmlns:h="http://www.w3.org/1999/xhtml"
        xmlns="http://www.w3.org/2002/xforms">
<h:head>
 <h:title>Search</h:title>
 <model>
  <submission action="http://example.com/search"
              method="post" id="s"/>
 </model>
</h:head>
<h:body>
 <h:p>
  <input ref="q"><label>Find</label></input>
  <submit submission="s"><label>Go</label></submit>
 </h:p>
</h:body>
</h:html>

上のフォームは、(qという名前の),テキスト入力ボックス と投稿ボタンを表示します。投稿ボタンがクリックされた時、このフォームは actionが参照するページに送信されます。

ここからが、Webアプリケーションの視点から異なって見え始めるところです。 通常のHTMLフォームでは、データは、 application/x-www-form-urlencoded で送信されますが、XFormsでは、この情報は XML 形式のデータで送信されます。

XFormsで処理することを選択した場合には、おそらくデータを XML 形式で取得したいはずで、この場合、$HTTP_RAW_POST_DATA により、 ブラウザが生成した XML ドキュメントにアクセスすることができます。このデータは、使用する XSLT エンジンやドキュメントパーサに渡すことができます。

データ形式には関心がなく、データを従来の データ形式には関心がなく、データを従来の $_POST変数に ロードしたいだけの場合、 method 属性を urlencoded-post に変更することにより、 クライアントブラウザに application/x-www-form-urlencoded としてデータを送信するよう指示することができます。

例2 XFormにより$_POSTを送信する

<h:html xmlns:h="http://www.w3.org/1999/xhtml"
        xmlns="http://www.w3.org/2002/xforms">
<h:head>
 <h:title>Search</h:title>
 <model>
  <submission action="http://example.com/search"
              method="urlencoded-post" id="s"/>
 </model>
</h:head>
<h:body>
 <h:p>
  <input ref="q"><label>Find</label></input>
  <submit submission="s"><label>Go</label></submit>
 </h:p>
</h:body>
</h:html>

注意: 本稿執筆時点で、多くのブラウザはXFormsをサポートしていません。 上の例が失敗する場合、ブラウザのバージョンを確認してください。

ファイルアップロードの処理

目次

POST メソッドによるアップロード

この機能により、テキスト、バイナリファイルの両方をアップロードできるように なります。 PHP の認証機構およびファイル操作関数を用いて、アップロードを許可する ユーザーとアップロード後にそのファイルを使用して行う動作を完全に制御する ことが可能です。

PHP は、全ての RFC-1867 対応ブラウザからファイルのアップロードを 受けることができます。

注意: 関係する設定に関する注記

php.iniの file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size, max_input_time ディレクティブも参照ください。

PHP は Netscape Composer および W3C の Amaya クライアントにより使用される PUT メソッドによるファイルアップロードもサポートしています。詳細は、PUT メソッドのサポート を参照ください。

例1 ファイルアップロード用のフォーム

ファイルアップロード画面は、次のような特別なフォームを作成すること により、作成することができます。 

<!-- データのエンコード方式である enctype は、必ず以下のようにしなければなりません -->
<form enctype="multipart/form-data" action="__URL__" method="POST">
    <!-- MAX_FILE_SIZE は、必ず "file" input フィールドより前になければなりません -->
    <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
    <!-- input 要素の名前が $_FILES 配列での名前となります -->
    このファイルをアップロード: <input name="userfile" type="file" />
    <input type="submit" value="ファイルを送信" />
</form>

上の例の __URL__ は、PHP ファイルを指すよう置換される 必要があります。

hidden フィールドMAX_FILE_SIZE は、 input フィールド file の前に置く必要があります。 この値は、PHP で取得可能なファイルの最大サイズを規定します。この値はバイト数で指定します。 MAX_FILE_SIZE は常に指定しておくべきです。 巨大なファイルを転送しようとして長時間待ち続け、 結局ファイルが大きすぎて転送できなかったなどといった羽目に陥るのを防げるからです。 注意: ブラウザ側でこの最大値を出し抜くのは簡単なことなので、この機能を信頼して、 これより大きなサイズのファイルがブロックされることを前提にしてはいけません。 しかし、PHP 側の最大サイズの設定を欺くことはできません。

注意:

アップロード用のフォームが enctype="multipart/form-data" 属性を有しているかを 確認してください。さもないと、ファイルのアップロードは動作しません。

オートグローバル $_FILES は、PHP 4.1.0 以降に存在します ($HTTP_POST_FILES は、これ以前のバージョンに存在します)。 これらの配列には、全てアップロードされたファイルの情報が 含まれています。

$_FILES の内容は次のようになります。ここでは、上の例のスクリプトで使われたように、 アップロードファイルの名前として userfile を 使用することを仮定していることに注意してください。 実際にはどんな名前にすることもできます。

$_FILES['userfile']['name']

クライアントマシンの元のファイル名。

$_FILES['userfile']['type']

ファイルの MIME 型。ただし、ブラウザがこの情報を提供する場合。 例えば、"image/gif" のようになります。 この MIME 型は PHP 側ではチェックされません。そのため、 この値は信用できません。

$_FILES['userfile']['size']

アップロードされたファイルのバイト単位のサイズ。

$_FILES['userfile']['tmp_name']

アップロードされたファイルがサーバー上で保存されているテンポラ リファイルの名前。

$_FILES['userfile']['error']

このファイルアップロードに関する エラーコード ['error']は、PHP 4.2.0 で追加されました。

php.ini の upload_tmp_dir ディレクティブで 他の場所を指定しない限り、ファイルはサーバーにおけるデフォルトの テンポラリディレクトリに保存されます。サーバーのデフォルトディレクトリは、 PHP を実行する環境において環境変数 TMPDIR を設定する ことにより変更することができます。しかし、PHP スクリプトの内部から putenv() 関数により設定しても上手くいきません。 この環境変数は、アップロードされたファイルに他の処理を行う際にも 同様に使用することが可能です。

例2 ファイルのアップロードを検証する

詳細については、is_uploaded_file() および move_uploaded_file() の関数のエントリも 参照ください。以下はフォームからファイルをアップロードするプロセスの例です。

<?php
// 4.1.0より前のPHPでは$FILESの代わりに$HTTP_POST_FILESを使用する必要
// があります。

$uploaddir = '/var/www/uploads/';
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

echo '<pre>';
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
    echo "File is valid, and was successfully uploaded.\n";
} else {
    echo "Possible file upload attack!\n";
}

echo 'Here is some more debugging info:';
print_r($_FILES);

print "</pre>";

?>

アップロードされたファイルを受け取る PHP スクリプトは、アップロード されたファイルを用いて何をするべきかを決めるために必要なロジックを 全て実装する必要があります。例えば、変数 $_FILES['userfile']['size'] を使用して、小さすぎたり 大きすぎたりするファイルを捨てることができます。指定した型以外の ファイルを全て捨てるために変数 $_FILES['userfile']['type'] を用いることができますが、 これはあくまでいくつかのチェックの中のひとつとしてのみ実行するように してください。なぜなら、この値を設定するのはあくまでもクライアントであり、 PHP 側では何もチェックしていないからです。 PHP 4.2.0 以降、 $_FILES['userfile']['error'] を使用することができ、 エラーコード に基づき、ロジックを構成することができます。 何らかの方法により、テンポラリディレクトリからファイルを削除したり 他の場所に移動したりする必要があります。

フォームでアップロードされるファイルが選択されていない場合、PHP は $_FILES['userfile']['size'] として 0 を返し、 $_FILES['userfile']['tmp_name'] には値を 設定しません。

移動または名前の変更が行われていない場合、リクエストの終了時に そのファイルはテンポラリディレクトリから削除されます。

例3 ファイルの配列をアップロードする

PHP はファイルについても HTML フォームで配列を使用すること をサポートしています。 

<form action="" method="post" enctype="multipart/form-data">
<p>Pictures:
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="submit" value="Send" />
</p>
</form>
<?php
foreach ($_FILES["pictures"]["error"] as $key => $error) {
    if ($error == UPLOAD_ERR_OK) {
        $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
        $name = $_FILES["pictures"]["name"][$key];
        move_uploaded_file($tmp_name, "data/$name");
    }
}
?>

ファイルアップロードのプログレスバーは、セッションのアップロードの進捗 で実装することができます。

エラーメッセージの説明

PHP 4.2.0 以降、PHP はファイル配列とともに適当なエラーコードを返します。 エラーコードは、PHP によるファイルアップロードの間に生成され、 ファイル配列の['error'] 要素で アクセス可能です。言い換えると、エラーは、 $_FILES['userfile']['error'] でアクセス可能でしょう。

UPLOAD_ERR_OK

値: 0; エラーはなく、ファイルアップロードは成功しています。

UPLOAD_ERR_INI_SIZE

値: 1; アップロードされたファイルは、php.ini の upload_max_filesize ディレクティブの値を超えています。

UPLOAD_ERR_FORM_SIZE

値: 2; アップロードされたファイルは、HTML フォームで指定された MAX_FILE_SIZE を超えています。

UPLOAD_ERR_PARTIAL

値: 3; アップロードされたファイルは一部のみしかアップロードされていません。

UPLOAD_ERR_NO_FILE

値: 4; ファイルはアップロードされませんでした。

UPLOAD_ERR_NO_TMP_DIR

値: 6; テンポラリフォルダがありません。PHP 4.3.10 と PHP 5.0.3 で導入されました。

UPLOAD_ERR_CANT_WRITE

値: 7; ディスクへの書き込みに失敗しました。PHP 5.1.0 で導入されました。

UPLOAD_ERR_EXTENSION

値: 8; PHP の拡張モジュールがファイルのアップロードを中止しました。 どの拡張モジュールがファイルアップロードを中止させたのかを突き止めることはできません。 読み込まれている拡張モジュールの一覧を phpinfo() で取得すれば参考になるでしょう。 PHP 5.2.0 で導入されました。

注意:

これらは PHP 4.3.0 で PHP 定数となりました。

陥りやすい落とし穴

MAX_FILE_SIZE の値に、php.ini の upload_max_filesize で指定されたファイルサイズより大きなファイルサイズを指定する ことはできません。デフォルトは、2 メガバイトです。

メモリ制限が有効な場合、memory_limit の値をより大きく 設定することが必要となる可能性があります。 memory_limit に充分大きな 値を設定するようにしてください。

max_execution_time に設定した値が小さすぎた場合、スクリプトの実行時間がこの値を越える 可能性を生じます。 max_execution_time に充分大きな値を設定するように してください。

注意: max_execution_time はスクリプト自身の実行時間にのみ影響します。 スクリプトの実行範囲の外側で発生する動作にかかる時間、つまり、 system() を使ったシステムコールや、 sleep() 関数、データベースに対するクエリー、 ファイルアップロードプロセス、などに費やされた時間はスクリプトの 総実行時間に含まれません。

警告

max_input_time は、スクリプトで入力を受け付けることができる最大秒数を設定します。 この秒数には、ファイルアップロードの時間も含まれます。 大きなファイルや複数のファイルをアップロードしたり接続に時間を要したりする場合は、 デフォルト値の 60 seconds を増やしましょう。

post_max_size の設定値が 小さすぎた場合、大きなファイルをアップロードすることができなくなります。 post_max_size に充分大きな値を設定するように してください。

PHP 5.2.12 以降、 max_file_uploads は一回のリクエストあたりでアップロードできるファイルの数の制限値となります。 この制限を超える数のファイルをアップロードしようとすると、制限に達した時点で $_FILES は処理を停止します。たとえば max_file_uploads が 10 の場合には、$_FILES には 10 件までの要素しか入らないということです。

処理するファイルを検証しない場合、ユーザーが他のディレクトリにある 非公開情報にアクセスできる可能性を生じます。

CERN httpd は、クライアントから得た content-type MIME ヘッダにおいて最初が空白文字で始まるものを切り捨てるようですので注意してください。 このような動作をする限り、CERN httpdは、 ファイルアップロード機能をサポートしないでしょう。

大量のディレクトリ一覧のスタイルのせいで、 風変わりな名前（空白を含んでいるとか）のファイルを適切に扱えることは 保証できません。

通常の input フィールドとファイルアップロードフィールドを (input の name に foo[] を利用するなどして) 同一のフォーム変数で扱うことはできません。

複数ファイルのアップロード

input で異なった name を 使用することにより、複数のファイルをアップロードすることができます。

複数のファイルを一度にアップロードし、自動的にまとめられた情報を 配列で取得することが可能です。これを行うには、HTML フォームで 複数選択可能なセレクトやチェックボックスを指定する際と同様、 配列を用いた投稿用の構文を使用する必要があります。

例1 複数ファイルのアップロード

<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Send these files:<br />
  <input name="userfile[]" type="file" /><br />
  <input name="userfile[]" type="file" /><br />
  <input type="submit" value="Send files" />
</form>

上記のフォームで投稿された場合、配列 $_FILES['userfile'], $_FILES['userfile']['name'], $_FILES['userfile']['size'] (4.1.0 より前のバージョンの PHP の場合は $HTTP_POST_FILES)が設定されま す。 register_globals が on の場合、 アップロードファイルに関してグローバル変数も設定されます。 これらの各々は、投稿されたファイルに 関する適当な値を有する数値を添字とする配列となります。

例えば、ファイル名が /home/test/review.html および /home/test/xwp.out のファイルが 投稿されたとしましょう。この場合、 $_FILES['userfile']['name'][0] の値が review.html となり、 $_FILES['userfile']['name'][1] の値が xwp.out となります。 同様に、$_FILES['userfile']['size'][0] の値が review.html のファイルサイズといったように なります。

$_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0], $_FILES['userfile']['type'][0] も設定されます。

警告

PHP 5.2.12 以降、 max_file_uploads は一回のリクエストあたりでアップロードできるファイルの数の制限値となります。 フォームからの一回のリクエストで、 これを超える数のファイルをアップロードしてしまわないようにしましょう。

PUT メソッドのサポート

PHP は、クライアントがサーバーにファイルを保存するための HTTP PUT メソッドのサポートを提供します。 PUT リクエストは POST リクエストによるファイルアップロードよりもシンプルであり、 次のような形になります。 

PUT /path/filename.html HTTP/1.1

これは、通常、リモートクライアントが /path/filename.html が指す内容を Web ツリーに保存したいことを意味します。 Apache または PHP に おいて全ての人が Web ツリー上の任意のファイルを自動的に上書きできる ようにするというのは明らかに良い発想ではありません。よって、このような リクエストを処理する際には、まずそのリクエストを処理する特定の PHP スクリプトが必要なことを web サーバーに通知する必要があります。 Apache においては、Script ディレクティブにより これを行うことができます。これは、Apache 設定ファイルのほぼ任意の 場所に置くことができます。一般的なのは、<Directory> ブロックまたは <VirtualHost> ブロックの中です。次のように指定します。 

Script PUT /put.php

これにより、この行を指定したコンテキストにマッチする URI を有する すべての PUT リクエストが put.php スクリプトに送られるよう Apache に 指定します。 もちろん、拡張子 .php により PHP が実行されるよう設定され、 PHP がアクティブであることが必要です。 このスクリプトに対するすべての PUT リクエストの対象リソースは、 スクリプト自身とします。アップロードされるファイルのファイル名ではありません。

PHP では、put.php の中で以下のようなことを行います。 これは、アップロードされたファイルをサーバー上のファイル myputfile.ext にコピーします。 ファイルコピーを行う前には、 何らかの確認やユーザー認証を行いたくなるかもしれません。

例1 HTTP PUT されたファイルの保存

<?php
/* PUT されたデータは標準入力からやってきます */
$putdata = fopen("php://input", "r");

/* 書き込みモードでファイルをオープンします */
$fp = fopen("myputfile.ext", "w");

/* データを 1 KB 単位で読み込み、
   ファイルに書き込みます */
while ($data = fread($putdata, 1024))
  fwrite($fp, $data);

/* ストリームを閉じます */
fclose($fp);
fclose($putdata);
?>

リモートファイルの使用

php.iniでallow_url_fopenを有効にした場合、 ファイル名をパラメータとする関数の多くで HTTP および FTP のURL を使用することができます。加えて、 include、 include_once、 require および require_once 命令でURLを使用することができます (PHP 5.2.0 以降では、これらで使用するためには allow_url_include を有効にする必要があります)。 PHPがサポートしているプロトコルに関する詳細は サポートするプロトコル/ラッパーを参照してください。

注意:

PHP 4.0.3以前のバージョンにおいては、URLラッパーを使用するために、 configureオプション --enable-url-fopen-wrapper を使用してPHPをconfigureを行なう必要があります。

注意:

PHP 4.3未満のWindows版PHPは次の関数については リモートファイルアクセスをサポートしてません: include, include_once, require, require_once, そしてGD および Image 関数拡張によるimagecreatefromXXX関数。

例えば、リモートWebサーバーにファイルをオープンし、データを出力、デー タベースクエリーに使用するか、単にWebサイトのスタイルに合わせて出力 を行うことが可能です。

例1 リモートページのタイトルを得る

<?php
$file = fopen ("http://www.example.com/", "r");
if (!$file) {
    echo "<p>Unable to open remote file.\n";
    exit;
}
while (!feof ($file)) {
    $line = fgets ($file, 1024);
    /* タイトルとタグが同じ行にある場合のみ動作します。 */
    if (preg_match ("@\<title\>(.*)\</title\>@i", $line, $out)) {
        $title = $out[1];
        break;
    }
}
fclose($file);
?>

(正しいアクセス権限を有するユーザーとして接続した場合には) FTPサーバーにファイルを書き込むこともできます。 この方法では、新規ファイルを作成することのみができます。 既存のファイルを上書きしようとした場合には、 fopen()の処理は失敗します。

'anonymous' 以外のユーザーで接続を行う場合、URL の中で 'ftp://user:password@ftp.example.com/path/to/file' のようにユーザー名 (そして多分パスワードも) 指定する必要があります (Basic 認証を要求された際に HTTP 経由でファイルをアクセスする場合と同じ種類の構文を使用することができます)。

例2 リモートサーバーにデータを保存する

<?php
$file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
if (!$file) {
    echo "<p>Unable to open remote file for writing.\n";
    exit;
}
/* データをここに書きます。 */
fputs ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
fclose ($file);
?>

注意:

上の例からリモートログに書きこむためにこの手法を使用することを考えるかも しれません。 しかし残念ながら、リモート上のファイルが既に存在する状態では fopen()をコールすることができないため、 それはできません。 分散ロギングのようなことを行うには、 syslog() の使用を考えてみてください。

接続処理

PHP 内部で、接続ステータスが保持されます。 これは、次の 3 つの状態をとりえます。

  • 0 - NORMAL
  • 1 - ABORTED
  • 2 - TIMEOUT

通常 PHP が実行されている場合、NORMAL 状態がアクティブになります。 リモートクライアントが接続を切った場合、ABORTED 状態フラグが有効になります。 通常、リモートクライアントの接続断は、STOP ボタンを押すことにより発生します。 PHP 側の時間制限 (set_time_limit() 参照) にかかった場合、 TIMEOUT 状態フラグが有効になります。

スクリプトを終了させるためにクライアントとの接続を切断するかどうかを 決めることが出来ます。 時々、出力がどのリモートブラウザにも受信されない場合でも、 常にスクリプトの実行完了まで実行する方が便利であることがあります。 しかし、デフォルトの動作はリモートクライアントとの接続が断となった際にスクリプト の実行は破棄されます。 この動作は、php.ini ディレクティブ ignore_user_abort にて 設定できます。 同様に同じ意味を有する Apache httpd.conf ディレクティブ php_value ignore_user_abort または ignore_user_abort() 関数にて設定することも可能です。 PHP にユーザーによる破棄を無視するように設定していない場合、 ユーザーが破棄した場合、スクリプトの実行は終了します。 一つの例外は、register_shutdown_function() を用いて シャットダウン関数を定義した場合です。 シャットダウン関数を定義した場合、リモートユーザーが STOP ボタンを押した後、 次にスクリプトが何か出力を行おうとした場合、PHP は接続が破棄されたことを検知し、 シャットダウン関数がコールされます。 このシャットダウン関数は、スクリプトが正常に終了した 際にもコールされます。 このため、クライアントが接続を切断した場合に別の動作をさせたい場合に は、connection_aborted() 関数を使用することが 可能です。 この関数は、接続が破棄された場合に、TRUE を返します。

スクリプトは、組み込みのスクリプトタイマーによっても終了することが できます。デフォルトのタイムアウトは、30 秒です。 これは、php.iniディレクティブ max_execution_time または同義の Apache httpd.conf ディレクティブ php_value max_execution_time を set_time_limit() 関数と同様に用いることにより 変更することが可能です。タイマーが切れた時、スクリプトは中断されます。 上記のクライアントが接続を切るケースのように シャットダウン関数が登録されている場合、この関数がコールされます。 このシャットダウン関数の中では、 connection_status() 関数のコールにより タイムアウトがシャットダウン関数のコールを生じさせるかどうかを 確認することができます。 この関数は、タイムアウトによりシャットダウン関数がコールされた 場合に 2 を返します。

もう一つ注意すべき点は、状態 ABORTED および TIMEOUT は同時にアクティブにできるということです。 これは、PHP をユーザーによる中断を無視するよう設定した場合に 可能です。 PHP は、ユーザーが接続を破棄しているが、スクリプトは 実行しつづけるということがある可能性があることに注意する 必要があります。 時間制限にかかって中断される場合、もしあればシャットダウン関数が コールされます。 ここで、connection_status() は 3 を返します。

持続的データベース接続

持続的接続は、スクリプトの実行終了時にも閉じられないリンクです。 持続的接続が要求された時、PHPは(前もってオープンされたままになって いる)同じ持続的接続が既にオープンされていないかどうかを確認します。 そして、存在する場合には、それを使用します。存在しない場合には、そ のリンクを作成します。'同じ'接続とは、同じホスト、同じユーザー名、 同じパスワード(利用可能な場合)でオープンされた接続のことを意味しま す。

Webサーバーの動作及び負荷の分散に関して熟知していない人は、持続的接 続において何が行われないかに関してミスを犯す可能性があります。特に、 持続的接続は、同じリンクで'ユーザーセッション'をオープンする機能 やトランザクションを効率的に確立する機能やその他のあらゆる機能を提 供しません。つまり、言いたいことを極めて簡単に述べると、持続的接続 は非持続的接続で使用できない いかなる 機能も提 供しません。

なぜ?

これは、Webサーバーの動作により行われるべきものです。Webページを生 成するためにPHPを利用するWebサーバーには、3種類の方法があります。

最初は、CGI "ラッパー"としてPHPを使用する方法です。このように実行し た場合、PHPインタプリタのインスタンスは、Webサーバーに(PHPページに 関する)ページがリクエストされる度に生成され、破棄されます。リクエス ト毎に破棄されるために、(SQLデータベースサーバーへのリンクのような) 必要な全てのリソースは破棄される際にクローズされます。この場合、持 続的接続を使用することから得るものは何もありません。持続的接続は持 続しないのです。

2番目は、最も一般的ですが、PHPをマルチプロセスWebサーバー(現在は Apacheのみが含まれます)のモジュールとして実行する方法です。マルチプ ロセスサーバーは、通常、実際にWebページを送信する複数のプロセス(子) を管理するプロセス(親)を有しています。リクエストがクライアントから 来ると、親プロセスは、他のクライアントにすでに送信を行っていないク ライアントの一つに渡します。このため、同じクライアントが2番目のリク エストをサーバーに送信した際に最初のではなく他の子プロセスにより送 信が行われる可能性があります。 持続的接続がオープンされているとき、SQL サービスにリクエストを行う それぞれのページは SQL サーバーへの確立された接続を再利用することが できます。

最後の方法は、PHPをマルチスレッドWebサーバーのプラグインとして使用する 方法です。現在、PHP 4 は、ISAPI, WSAPI, NSAPI を(Windows上で)サポー トしており、Netscape FastTrack、Microsoftの Internet Information Server (IIS)、O'Reillyの WebSite Proのようなマルチスレッド型サーバー のプラグインとしてPHPを使用することが可能です。この場合の動作は前記 のマルチプロセス型モデルと同様です。

持続的接続が機能を全く付加しないとしたら、優れている点はなんでしょう?

答えはかなり簡単です。効率です。持続的接続は、SQLサーバーへ接続する オーバーヘッドが大きい場合には有効です。このオーバーヘッドが実際に 大きいがどうかは様々な要因に依存します。例えば、データベースの種類、 Webサーバーが動作するのと同じコンピューターで動作しているか、SQLサー バーを動作させているマシンの負荷、等となります。肝心なのは、接続の オーバーヘッドが高い場合、持続的接続は著しいということです。持続的 接続は、SQLサーバーへの接続を要求するページをリクエスト毎に処理する 代わりに子プロセスが動作中の間一回しかサーバーへの接続を行わないよ うにします。このことは、持続的接続をオープンしたプロセス毎にサーバー への持続的接続をオープンするということになります。例えば、20の異なっ た子プロセスがSQLサーバーへの持続的接続を行うスクリプトを実行した場 合、各子プロセス毎にSQLサーバーへの20の異なった接続が行われます。

しかし、気をつけなければならないことが一つあります。それはデータ ベースへの接続数を制限して使用している場合に、持続的な子プロセスの 接続数がその数を超えると問題が発生し得ることです。もしデータベース の同時接続数の制限が16だとして、サーバーに多くのアクセスがあったため 17個の子プロセスが接続しようとするとそのうちの一つは接続に失敗しま す。もしスクリプトにコネクションをシャットダウンしないようなバグ( 例えば無限ループ)があると16程度の同時接続しか許容しないデータベース はすぐにダメになってしまいます。使用しているデータベースが、中断さ れた、もしくは使用されていないコネクションをどのように扱うかを確認 してみてください。

警告

持続的接続を使用する際にはまだいくつか心に留めておく必要がある注意 点があります。一つは持続的接続でテーブルをロックする場合にスクリプト が何らかの理由でロックを外し損ねると、それ以降に実行されるスクリプト がその接続を使用すると永久にブロックしつづけてしまい、ウェブサーバーか データベースサーバーを再起動しなければならなくなるということです。もう 一つはトランザクションを使用している場合に、トランザクションブロック が終了する前にスクリプトが終了してしまうと、そのブロックは次に同じ接 続を使用して実行されるスクリプトに引き継がれる、ということです。 どちらの場合でも register_shutdown_function()を使用してテーブルの ロックを解除したりトランザクションをロールバックする簡単なクリーン アップ関数を登録することができます。しかしそれよりも良い方法は、テー ブルロックやトランザクションを使用するスクリプトでは持続的接続を使用 せず、問題を完全に避けて通ることです(他の箇所で使用する分には問題あ りません)。

重要なことをまとめます。持続的接続は、標準的な接続に1対1の割りつけ を行うように設計されています。このことは、常に 持続的接続を非持続的接続で置きかえ、かつ動作を変更しないということ ができることを意味します。持続的接続は、スクリプトの効率を変える かもしれません(おそらく変えます)が、動作は変更しません!

fbsql_pconnect(), ibase_pconnect(), ifx_pconnect(), ingres_pconnect(), msql_pconnect(), mssql_pconnect(), mysql_pconnect(), ociplogon(), odbc_pconnect(), oci_pconnect(), pfsockopen(), pg_pconnect(), sybase_pconnect()も参照してください。

セーフモード

目次

PHP のセーフモードは、共有サーバーでのセキュリティの問題を解決するための試みです。 この問題を PHP のレベルで解決しようとするのはアーキテクチャ上正しくありません。 しかし、Web サーバーや OS レベルでの代替策はあまり現実的ではないため、 多くのユーザー、特に ISP ではセーフモードが現在使用されています。

警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

セーフモードの変更履歴
バージョン 説明
5.4.0 PHP から削除され、E_CORE_ERROR レベルのエラーが発生するようになりました。
5.3.0 非推奨となり、E_DEPRECATED エラーが発生するようになりました。

セキュリティとセーフモード

セキュリティとセーフモード設定ディレクティブ
名前 デフォルト 変更可能 変更履歴
safe_mode "0" PHP_INI_SYSTEM PHP 5.4.0 で削除されました。
safe_mode_gid "0" PHP_INI_SYSTEM PHP 4.1.0 から利用可能。PHP 5.4.0 で削除されました。
safe_mode_include_dir NULL PHP_INI_SYSTEM PHP 4.1.0 から利用可能。PHP 5.4.0 で削除されました。
safe_mode_exec_dir "" PHP_INI_SYSTEM PHP 5.4.0 で削除されました。
safe_mode_allowed_env_vars "PHP_" PHP_INI_SYSTEM PHP 5.4.0 で削除されました。
safe_mode_protected_env_vars "LD_LIBRARY_PATH" PHP_INI_SYSTEM PHP 5.4.0 で削除されました。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

セーフモードの設定ディレクティブの簡単な説明を以下に示します。

safe_mode boolean

セーフモードを有効にするか否か。 PHP が --enable-safe-mode でコンパイルされている場合のデフォルトは On、そうでないときのデフォルトは Off です。

警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

safe_mode_gid boolean

デフォルトでは、セーフモードはオープンしようとするファイルの UIDの比較チェックを行います。GIDの比較にすることでこのチェックを 緩やかなものにしたい場合、safe_mode_gidをオンにしてください。 ファイルにアクセスする際にUID (FALSE)を使用するか GID (TRUE)を使用するか制御できます。

safe_mode_include_dir string

このディレクトリ（そのサブディレクトリも含む）の配下のファイルが インクルードされる場合、UID/GID のチェックはバイパスされます。（ディレクトリは include_pathの配下であるか あるいはフルパスで記述される必要があります）

PHP 4.2.0以降、このディレクティブは include_pathと同様に コロン(Windowsではセミコロン)で分けた形式で複数のパスを書くことができます。 ここで指定される制限は実はプレフィックスでありディレクトリ名ではありません。 つまり、"safe_mode_include_dir = /dir/incl" と書くと "/dir/include" と "/dir/incls" の両方へのアクセスが許可されます（もしディレクトリが存在すれば）。 指定したディレクトリのみを許可したい場合には、最後にスラッシュを追加してください。 例："safe_mode_include_dir = /dir/incl/" PHP 4.2.3 と PHP 4.3.3 以降では、ディレクティブの値が空の場合、 異なる UID/GID を持つファイルを インクルードすることはできません。 以前のバージョンでは、全てのファイルをインクルード可能でした。
safe_mode_exec_dir string

PHPがセーフモードで動作する場合、system()や その他のプログラム実行関数を、 このディレクトリ以外で起動することは拒否されます。 Windowsを含む全ての環境において ディレクトリのセパレータとして/を使用する必要があります。

safe_mode_allowed_env_vars string

ある種の環境変数の設定はセキュリティ上の潜在的な欠陥となりえます。 このディレクティブにはプレフィックスをカンマで区切って書くことができます。 セーフモードでは、ここに書かれたプレフィックスで始まる環境変数だけを ユーザーが変更できるようになります。デフォルトでは、ユーザーは PHP_ で始まる名前の環境変数 (PHP_FOO=BAR など) だけをセットすることができます。

注意:

このディレクティブが空の場合、PHPは全ての環境変数について ユーザーが変更することを許可してしまいます。

safe_mode_protected_env_vars string

putenv()を使ってエンドユーザーが変更するのを 防ぎたい環境変数をカンマ区切りで記述します。ここで設定された環境変数は もしもsafe_mode_allowed_env_varsでは許可されているものであっても 保護されます。

open_basedir, disable_functions, disable_classes, register_globals, display_errors, log_errorsも参照してください。

セーフモードがonの場合、PHPは、 現在のスクリプトの所有者がファイル関数により処理されているファイルまたはディレクトリ の所有者に一致するかどうかを調べます。例えば、 

-rw-rw-r--    1 rasmus   rasmus       33 Jul  1 19:20 script.php
-rw-r--r--    1 root     root       1116 May 26 18:01 /etc/passwd
script.php を実行すると、
<?php
 readfile('/etc/passwd');
?>
セーフモードが有効な場合、以下のようなエラーが出力されます。 
Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not
allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2

UID checking. しかし、多くの環境において、厳密なUIDチェックは 適切ではなく、より緩やかなGIDチェックで十分です。 これはsafe_mode_gidスイッチで サポートされます。これをOnにすると制限の緩い GIDチェックに、Off（デフォルト） にするとUIDチェックになります。

safe_modeの代わりに、 open_basedirディレクトリを セットすると、全てのファイル操作は特定のディレクトリ配下のみに制限されます。 例えば(Apacheのhttpd.confの例): 

<Directory /docroot>
  php_admin_value open_basedir /docroot
</Directory>
open_basedirでセットしたのと 同じ script.php を実行すると、以下のような結果になります: 
Warning: open_basedir restriction in effect. File is in wrong directory in
/docroot/script.php on line 2

特定の関数を無効にすることもできます。 disable_functionsディレクティブは php.ini以外では使用できないことに注意してください。 つまり、httpd.conf上のバーチャルホスト毎あるいはディレクトリ毎に 関数を無効にすることはできない、ということになります。 もしphp.iniファイルに以下を追加した場合: 

disable_functions = readfile,system
以下のような結果になります: 
Warning: readfile() has been disabled for security reasons in
/docroot/script.php on line 2

警告

もちろん、これらの PHP の制限はバイナリを実行した場合は有効になりません。

セーフモードにより制限を受けるか無効となる関数

safe-modeにより制限される 関数のリストを示します。ただし、まだ、不完全で、不正確である可能性 があります。

セーフモードで制限される関数
関数 制限
dbmopen() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
dbase_open() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
filepro() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
filepro_rowcount() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
filepro_retrieve() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
ifx_*() sql_safe_mode restrictions, (!= safe mode)
ingres_*() sql_safe_mode restrictions, (!= safe mode)
mysql_*() sql_safe_mode restrictions, (!= safe mode)
pg_lo_import() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
posix_mkfifo() 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。
putenv() iniディレクティブのsafe_mode_protected_env_vars および safe_mode_allowed_env_varsに依存します。 putenv()のドキュメントも参照ください。
move_uploaded_file() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
chdir() 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。
dl() この関数は、PHP が safe-mode で動作している場合は無効となります。
backtick operator この関数は、PHP が safe-mode で動作している場合は無効となります。
shell_exec() (functional equivalent of backticks) この関数は、PHP が safe-mode で動作している場合は無効となります。
exec() safe_mode_exec_dir の中でのみ実行可能です。現実的な理由により、現在、実行パスに ..を含めることは許可されていません。 escapeshellcmd()はこの関数の引数にたいして 実行できます。
system() safe_mode_exec_dir の中でのみ実行可能です。現実的な理由により、現在、実行パスに ..を含めることは許可されていません。 escapeshellcmd()はこの関数の引数にたいして 実行できます。
passthru() safe_mode_exec_dir の中でのみ実行可能です。現実的な理由により、現在、実行パスに ..を含めることは許可されていません。 escapeshellcmd()はこの関数の引数にたいして 実行できます。
popen() safe_mode_exec_dir の中でのみ実行可能です。現実的な理由により、現在、実行パスに ..を含めることは許可されていません。 escapeshellcmd()はこの関数の引数にたいして 実行できます。
fopen() 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。
mkdir() 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。
rmdir() 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。
rename() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。
unlink() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。
copy() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。 ( sourceおよび targetにおいて)
chgrp() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
chown() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。
chmod() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 加えて、SUID, SGID, スティキービットを設定する ことはできません
touch() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。
symlink() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。 (注意: ターゲットのみが 確認されます)
link() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。 (注意: ターゲットのみが 確認されます)
apache_request_headers() セーフモードでは、authorization で始まるヘッダ(大文字小文字は 区別されません)は返されません。
header() セーフモードでは、WWW-Authenticate (HTTP認証)ヘッダをセットする場合に realmパートに スクリプトのUIDがセットされます。
PHP_AUTH variables セーフモードでは、PHP_AUTH_USER, PHP_AUTH_PW, AUTH_TYPEは $_SERVERに含まれません。 にも関わらず、USERにREMOTE_USERを使うことは未だ可能です。 （PHP4.3.0以降でのみ影響）
highlight_file(), show_source() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。 (注: PHP 4.2.1以降でのみ影響する)
parse_ini_file() 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。 (注: PHP 4.2.1以降でのみ影響する)
set_time_limit() PHPがセーフモードで実行されている場合は影響を受けません。
max_execution_time PHPがセーフモードで実行されている場合は影響を受けません。
mail() セーフモードでは、5番目のパラメータが無効となります。(注意: PHP 4.2.3以降のみ適用)
session_start() デフォルトの files session.save_handler を使う場合は、スクリプトのオーナーが session.save_path ディレクトリのオーナーと同じでなければなりません。
すべてのファイルシステム関数およびストリーム関数 処理を行うファイル/ディレクトリが実行するスクリプトと 同じUIDを有しているかどうかを確認します。 処理を行うディレクトリが実行するスクリプトと同じ UID を有しているかどうかを確認します。 (php.ini オプション safe_mode_include_dir を参照ください)。

PHP をコマンドラインから使用する

目次

導入

PHP は、CLI SAPI を PHP 4.3.0 以降でサポートしています。この SAPI の主な目的は、シェルアプリケーションを PHP で開発することです。CLI SAPI とその他の SAPI の間にはちょっとした違いがあり、 それを本章で説明します。CLI と CGI は多くの共通点がありますが、別の SAPI であるということも覚えておきましょう。

CLI SAPI は、 --enable-cli でデフォルトで有効となっています。 ./configure の際に --disable-cli オプションを指定して無効にすることもできます。

CLI/CGI バイナリの名前、位置、そして存在するかどうかは PHP がどのようにインストールされているかによって異なります。デフォルトで make を実行したときには、CGI と CLI が両方ビルドされて、それぞれ PHP ソースディレクトリの sapi/cgi/php-cgi と sapi/cli/php にできあがります。 両方とも php という名前であることに注意しましょう。 make install のときにどうなるかは、configure 行に依存します。 configure で例えば apxs のような SAPI モジュールが選択された場合、または --disable-cgi が指定された場合、 make install によって CLI が {PREFIX}/bin/php にコピーされます。さもなければ CGI がそこにコピーされます。 つまり、たとえば configure で --with-apxs を指定すると、make install での CLI のコピー先は {PREFIX}/bin/php となります。 既にインストールされている CGI バイナリを上書きしたい場合には、 make install の後に make install-cli を実行してください。あるいは configure で --disable-cgi を指定することもできます。

注意:

--enable-cli と --enable-cgi の両方がデフォルトで有効になっています。そのため、configure で --enable-cli を指定したからといって、make install で {PREFIX}/bin/php にコピーされるのが必ずしも CLI になるとは限りません。

PHP 5 以降、Windows 版の CLI はメインフォルダ内で php.exe という名前で配布されます。CGI バージョンは、php-cgi.exe として配布されます。さらに PHP 5 では、configure で --enable-cli-win32 を指定すると、新しく php-win.exe というファイルが配布されます。 これは CLI バージョンとほぼ同じですが、何も出力しないため、コンソールを必要としません。

注意: 自分の SAPI は何か?

シェルで php -v をタイプすると、 php が CGI なのか CLI なのかわかります。 php_sapi_name() と定数 PHP_SAPI も参照してください。

注意:

Unix の man ページは、 シェル環境から man php とすれば見ることができます。

他の SAPI との違い

CLI SAPI を他の SAPI と比べた時の 大きな違いを以下に示します。

  • CGI SAPI と異なり、ヘッダが出力されません。

    CGI SAPI は HTTP ヘッダの出力を抑制する機能を 提供していますが、等価な機能は CLI SAPI ではサポートされていません。

    デフォルトでは CLI は静寂モードで起動されます。古い CGI スクリプトと互換性を 保って使えるように -q および --no-header スイッチが残されています。

    作業ディレクトリをスクリプトの場所に変更しません (-C および --no-chdir スイッチは 互換性のために残されています)。

    エラーメッセージはプレーンテキスト (HTML フォーマットはしない) で表示されます。

  • 以下に示すいくつかの php.ini ディレクティブは、CLI SAPI により上書きされます。これは、シェル環境では意味がないためです。

    上書きされる php.ini のディレクティブ
    ディレクティブ CLI SAPI のデフォルト値 コメント
    html_errors FALSE エラーメッセージに含まれる HTML タグは シェル上では意味がなく、可読性をかなり低下させるため、この ディレクティブはデフォルトで FALSE となっています。
    implicit_flush TRUE print, echo および 関連するものによる全ての出力は、直ちに出力され、バッファに キャッシュされないことが望ましいと言えます。この場合でも、 標準出力を保留または操作したい場合には、 出力バッファリング を使用することが可能です。
    max_execution_time 0 (無制限) シェル環境では、PHP を際限なく使用できる ようにするために、最大実行時間の制限は無しに設定されています。 Web 用アプリケーションは数秒単位で実行されるよう作られて いますが、シェルアプリケーションの実行時間は、これよりかなり 長くなる傾向があります。
    register_argc_argv TRUE

    この設定が TRUE なので、CLI SAPI では常に argc (アプリケーションに渡した引数の数) および argv (実際の引数の配列) を使うことができます。

    CLI SAPI を使用するときに PHP の $argc 変数と $argv 変数が登録され、適切な値がセットされます。 あるいは $_SERVER や $_SERVER['argv'] を使うこともできます。

    output_buffering FALSE

    php.ini で FALSE とハードコードされていても、 出力バッファリング 関数は使用可能です。

    max_input_time FALSE

    PHP CLI は GET、POST あるいはファイルのアップロードをサポートしません。

    注意:

    これらのディレクティブは、設定ファイル php.ini またはカスタム 設定ファイル(指定した場合のみ)で他の値に初期化できません。 この制限は、これらのデフォルト値が全ての設定ファイルをパースした後に 適用されるためです。しかし、これらの値は実行時に変更することが 可能です (上記のディレクティブの全てについてこれが当てはまるわけでは ありません。例えば、register_argc_argv)。

    注意:

    コマンドラインのスクリプトでは ignore_user_abort を設定することを推奨します。詳細は ignore_user_abort() を参照ください。

  • シェル環境での利便性を考慮して、 I/O ストリーム 用に多くの定数が定義されています。

  • CLI SAPI は、カレントディレクトリをスクリプトのディレクトリに変更 しません!

    例1 CGI SAPI との違いを示す例

    <?php
    // test.php という名前のシンプルなテストアプリケーション
    echo getcwd(), "\n";
    ?>

    CGI 版を使った場合、出力は以下のようになります。 

    $ pwd
/tmp

$ php -q another_directory/test.php
/tmp/another_directory

    これは、PHP がカレントディレクトリを スクリプトのディレクトリに変更することを明らかに示しています。

    CLI SAPI を使った場合はこのようになります。 

    $ pwd
/tmp

$ php -f another_directory/test.php
/tmp

    これにより、PHP でシェルツールを書く際の柔軟性をより大きくすることができます。

    注意:

    CGI SAPI は、この CLI SAPI の動作をコマンドライン実行時のスイッチ -C によりサポートしています。

コマンドラインオプション

PHP バイナリにより提供されるコマンドラインオプションの一覧は、 -h スイッチを指定して PHP を実行することにより いつでも調べることができます。 

Usage: php [options] [-f] <file> [--] [args...]
   php [options] -r <code> [--] [args...]
   php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
   php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
   php [options] -- [args...]
   php [options] -a

  -a               Run interactively
  -c <path>|<file> Look for php.ini file in this directory
  -n               No php.ini file will be used
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -f <file>        Parse and execute <file>.
  -h               This help
  -i               PHP information
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -r <code>        Run PHP <code> without using script tags <?..?>
  -B <begin_code>  Run PHP <begin_code> before processing input lines
  -R <code>        Run PHP <code> for every input line
  -F <file>        Parse and execute <file> for every input line
  -E <end_code>    Run PHP <end_code> after processing all input lines
  -H               Hide any passed arguments from external tools.
  -S <addr>:<port> Run with built-in web server.
  -t <docroot>     Specify document root <docroot> for built-in web server.
  -s               Output HTML syntax highlighted source.
  -v               Version number
  -w               Output source with stripped comments and whitespace.
  -z <file>        Load Zend extension <file>.

  args...          Arguments passed to script. Use -- args when first argument
                   starts with - or script is read from stdin

  --ini            Show configuration file names

  --rf <name>      Show information about function <name>.
  --rc <name>      Show information about class <name>.
  --re <name>      Show information about extension <name>.
  --rz <name>      Show information about Zend extension <name>.
  --ri <name>      Show configuration for extension <name>.

コマンドラインオプション
オプション 長い形式のオプション 説明
-a --interactive

PHP を対話的に実行します。詳細な情報は、対話シェル を参照ください。

-b --bindpath

外部 FASTCGI サーバーモードでのバインドパス (CGI のみ)。

-C --no-chdir

スクリプトのディレクトリへ chdir しません (CGI のみ)。

-q --no-header

静寂モード。HTTP ヘッダの出力を抑制します (CGI のみ)。

-T --timing

スクリプトを count 回繰り返して実行した時間を計測します (CGI のみ)。

-c --php-ini

このオプションを使用することにより、php.ini を探すディレクトリを 指定したり、カスタマイズされた INI ファイル (php.ini という名前である必要はありません)を直接指定する ことが可能です。例： 

$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php

このオプションを指定しない場合、ファイルは、 デフォルトの位置 で探索されます。

-n --no-php-ini

php.ini を完全に無視します。

-d --define

このオプションにより php.ini で指定できる設定ディレクティブに カスタム値を設定することができます。構文は以下のようになります。 

 -d configuration_directive[=value]
 

# 値の部分を省略すると、設定ディレクティブに"1"を指定します
$ php -d max_execution_time
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# 空の値を渡すと設定ディレクティブに""を設定します
php -d max_execution_time=
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# 設定ディレクティブは文字'='の後に指定したものを設定します
$  php -d max_execution_time=20
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php
        -d max_execution_time=doesntmakesense
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

-e --profile-info

デバッガ/プロファイラ用の拡張情報を出力します。

-f --file

-f オプションに指定したファイル名をパースし、 実行します。このスイッチはオプションで省略することもできます。 実行するスクリプトを指定するだけで充分です。

注意:

引数をスクリプトに渡すには、最初の引数を -- としなければなりません。 そうしないと、PHP は渡された内容を PHP のオプションとみなしてしまいます。

-h and -? --help and --usage このオプションを使用すると、実際の一連のコマンドラインオプションと 各1行の説明が情報を取得できます。
-i --info このコマンドラインオプションは、phpinfo() をコールし、 結果を出力します。PHP が正しく動作していない場合、 php -i を実行し、情報テーブルの前または中に 出力されるエラーメッセージを調べることをお勧めします。 CGI モードの場合、 出力が HTML 形式で行なわれるため 量がかなり多くなることに注意してください。
-l --syntax-check

このオプションにより、指定した PHP コードの 構文チェックのみを簡単に行なうことができます。成功した場合、 テキスト No syntax errors detected in <filename> が標準出力に書き込まれ、リターンコードは 0 となります。失敗した場合、テキスト Errors parsing <filename> に加え、内部パーサエラーメッセージ が標準出力に書き込まれ、シェルリターンコードは、 -1 となります。

このオプションは、(未定義の関数のような)致命的なエラー(fatal error) はみつけません。致命的なエラーについても調べたい場合は、 -f を使用してください。

注意:

このオプションは、オプション -r と共に使用することは できません。

-m --modules

例1 PHP に組み込まれた (そしてロードされた) Zend モジュールの表示

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-r --run

このオプションにより、コマンドラインのみで PHP の実行ができるようになります。 PHP の開始および終了タグ (<?php および ?>) は不要で、これらを付けると パーサエラーとなります。

注意:

このように PHP を実行する際に、コマンドラインの 変数がシェルにより行なわれる置換と干渉しないように注意してください。

例2 ダブルクォートの使用時に構文エラーが出る例

$ php -r "$foo = get_defined_constants();"
PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

Parse error: syntax error, unexpected '=' in Command line code on line 1

ここでの問題は、2 重引用符 " を用いた場合でも sh/bash が変数置換を行うことです。 $foo はおそらく定義されていないので、 空文字列に展開された後、実行用に PHP に そのコードが渡され、以下のように読み込むことになります。 

$ php -r " = get_defined_constants();"

正しい方法は、1 重引用符'を使用することです。 1 重引用符で括られた文字列の中の変数は、sh/bash により展開されません。

例3 シングルクォートを使い、シェルの変数置換を防ぐ例

$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=>
  int(1)
  ["E_WARNING"]=>
  int(2)
  ["E_PARSE"]=>
  int(4)
  ["E_NOTICE"]=>
  int(8)
  ["E_CORE_ERROR"]=>
  [...]

sh/bash 以外のシェルを使用している場合には、別の問題を経験したことが あるかもしれません。バグを » http://bugs.php.net/ に報告してください。 シェル変数をコードに取得しようとしたり、エスケープを行なうために バックスラッシュを使用したりした場合にも、容易に問題を発生する 可能性があります。注意が必要です。

注意:

-r は CLI SAPI で有効で、 CGI SAPI では使用できません。

注意:

このオプションはあくまで基本的な機能を提供するものです。そのため、 いくつかの設定ディレクティブ（例: auto_prepend_file および auto_append_file）は このモードでは無視されます。

-B --process-begin

標準入力を処理する前に実行する PHP コードを指定します。 PHP 5 で追加されました。

-R --process-code

それぞれの入力行に対して実行する PHP コードを指定します。 PHP 5 で追加されました。

このモードには 2 つの特別な変数 $argn と $argi が用意されています。 $argn は PHP がその瞬間に処理している行を含み、 $argi はその行番号を含んでいます。

-F --process-file

全ての入力行に対して実行する PHP ファイルを指定します。 PHP 5 で追加されました。

-E --process-end

入力を処理した後に実行する PHP コードを指定します。 PHP 5 で追加されました。

例4 とあるプロジェクトの行数をカウントするための -B , -R そして -E オプションの使用例 

$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
Total Lines: 37328

-S --server

ビルトインウェブサーバー を開始させます。PHP 5.4.0 以降で利用可能です。

-t --docroot ビルトインウェブサーバー のドキュメントルートを指定します。PHP 5.4.0 以降で利用可能です。
-s --syntax-highlight と --syntax-highlighting

カラー構文ハイライト表示されたソースを表示します。

このオプションは、ファイルをパースし、HTML ハイライト表示版のファイルを生成し、標準出力に書き出す内部機 構を使用します。行うのは <code> [...] </code> のブロックを 生成することだけで、HTML ヘッダは 出力されないことに注意してください。

注意:

このオプションは、-r オプションと同時に 使用することはできません。

-v --version

例5 -v による、SAPI 名および PHP と Zend のバージョンの取得

$ php -v
PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07) 
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies

-w --strip

コメントと空白文字を削除してソースを表示します。

注意:

このオプションは、-r オプションと同時に 使用することはできません。

-z --zend-extension

Zend エクステンションをロードします。ファイル名のみが指定された場合、 PHP はこの拡張をカレントのシステムのデフォルトライブラリパスから ロードしようとします (Linux システムの場合は /etc/ld.so.conf で 指定されています)。 ファイル名を絶対パスで指定した場合、システムのライブラリサーチパスを 使用しません。ディレクトリ情報を有する相対ファイル名を 指定すると、PHP は カレントのディレクトリの相対パスから拡張モジュールをロードする ことのみを行ないます。

  --ini

設定ファイルの名前、設定ファイルを検索するディレクトリを表示します。 PHP 5.2.3 以降で使用可能です。

例6 --ini の例

$ php --ini
Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
Scan for additional .ini files in: (none)
Additional .ini files parsed:      (none)
--rf --rfunction

指定した関数あるいはクラスメソッドについての情報 (たとえばパラメータの数と名前など) を表示します。 PHP 5.1.2 以降で使用可能です。

このオプションは、PHP が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例7 基本的な --rf の使用法

$ php --rf var_dump
Function [ <internal> public function var_dump ] {

  - Parameters [2] {
    Parameter #0 [ <required> $var ]
    Parameter #1 [ <optional> $... ]
  }
}
--rc --rclass

指定したクラスについての情報 (定数、プロパティおよびメソッドの一覧) を表示します。PHP 5.1.2 以降で使用可能です。

このオプションは、PHP が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例8 --rc の例

$ php --rc Directory
Class [ <internal:standard> class Directory ] {

  - Constants [0] {
  }

  - Static properties [0] {
  }

  - Static methods [0] {
  }

  - Properties [0] {
  }

  - Methods [3] {
    Method [ <internal> public method close ] {
    }

    Method [ <internal> public method rewind ] {
    }

    Method [ <internal> public method read ] {
    }
  }
}
--re --rextension

指定した拡張モジュールについての情報 (php.ini オプション、 定義されている関数、定数およびクラスの一覧) を表示します。 PHP 5.1.2 以降で使用可能です。

このオプションは、PHP が リフレクション のサポートつきでコンパイルされている場合にのみ使用可能です。

例9 --re の例

$ php --re json
Extension [ <persistent> extension #19 json version 1.2.1 ] {

  - Functions {
    Function [ <internal> function json_encode ] {
    }
    Function [ <internal> function json_decode ] {
    }
  }
}
--rz --rzendextension

指定した Zend 拡張モジュールについての情報 (phpinfo() が返す情報と同じもの) を表示します。 PHP 5.4.0 以降で使用可能です。

--ri --rextinfo

指定した拡張モジュールについての設定情報 (phpinfo() が返す情報と同じもの) を表示します。 PHP 5.2.2 以降で使用可能です。コア機能に関する設定情報は、 "main" というモジュール名で取得できます。

例10 --ri の例

$ php --ri date

date

date/time support => enabled
"Olson" Timezone Database Version => 2009.20
Timezone Database => internal
Default timezone => Europe/Oslo

Directive => Local Value => Master Value
date.timezone => Europe/Oslo => Europe/Oslo
date.default_latitude => 59.930972 => 59.930972
date.default_longitude => 10.776699 => 10.776699
date.sunset_zenith => 90.583333 => 90.583333
date.sunrise_zenith => 90.583333 => 90.583333

注意:

オプション -rBRFEH、--ini および --r[fcezi] は CLI でのみ使用可能です。

PHP ファイルの実行

CLI SAPI は、実行する PHP コードを 取得するために三種類の異なる手段をサポートしています。

  1. PHP に特定のファイルの実行を指示する。 

    $ php my_script.php

$ php -f my_script.php

    上記の方法は共に(-f スイッチの使用の如何に関らず) 指定したファイル my_script.php を実行します。 実行ファイルとしてあらゆるファイルを指定することができ、 PHP スクリプトは拡張子 .php で終わる必要がなく、任意の名前や拡張子を 使用することができます。

    注意:

    -f スイッチを使用している時にスクリプトに引数を渡したい場合は、 最初の引数として -- を渡す必要があります。

  2. 実行する PHP コードをコマンドラインで直接指定する。 

    $ php -r 'print_r(get_defined_constants());'

    シェル変数の置換と引用符の使用については特に注意してください。

    注意:

    この例をよくみてください。開始/終了タグがありません! -r スイッチを使用した場合、これらのタグは不要と なります。これらのタグを使用するとパーサエラーを発生します。

  3. 実行する PHP コードを標準入力 (stdin)で指定する。

    これは強力な機能で、以下の(仮想的な)例に示すように、動的に PHP コードを生成し、実行バイナリに入力すること ができます。 

    $ some_application | some_filter | php | sort -u > final_output.txt
これらのコードを実行する三種類の方法を組み合わせて使用することはできません。

他のシェルアプリケーションのように、PHP バイナリに 引数を指定することができるだけでなく、PHP スクリプトが この引数を取得することも可能です。スクリプトに指定できる 引数の数は PHP による制限を受けません (シェルは指定可能な文字数の最大値を設定しています。通常、この制限値を 越えることはできません)。スクリプトに指定した引数は、グローバル配列 $argv でアクセス可能です。 最初のインデックス (添字 0) には常に、 コマンドラインからコールしたスクリプト名が含まれています。 コマンドラインスイッチ -r を使ってインラインでコードを実行した場合は、 $argv[0] の値はダッシュ (-) となることに注意しましょう。STDIN の内容をパイプ経由で実行した場合も同じです。

登録される第 2 のグローバル変数は $argc で (スクリプトに指定された引数の数ではなく )、配列 $argv の要素数が含まれます。

スクリプトに指定する引数が文字 - で始まっていない 限り、特に留意すべきことはありません。スクリプトに指定する引数が文字 - で始まる場合、PHP 自体がこれを パースする必要があるとみなすため、問題を発生します。 これを防止するため、引数リストセパレータ -- を 使用してください。PHP にパースされる引数の後に このセパレータを置くと、その後の全ての引数はそのままパースされずに スクリプトに渡されます。 

# これは、指定したコードを実行せずに PHP の使用法を示します
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# これは '-h' を引数として解釈し、PHP の使用法を表示しません
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Unix システムでは、PHP をシェルスクリプトとして使用する他の手段があります。 最初の行が #!/usr/bin/php (必要に応じて、PHP CLI バイナリのパスを置き換えてください) で始まり、PHP の開始/終了タグの中に通常の PHP コードが続くスクリプトを書き、適当なファイル 実行属性を設定する(例: chmod +x test)ことが可能です。 この方法は、通常のシェル/Perl スクリプトと同様に実行することができます。

例1 シェルスクリプトとしての PHP スクリプトの実行

#!/usr/bin/php
<?php
var_dump($argv);
?>

このファイルの名前が test で、カレントディレクトリに あるとすると、以下のように実行することができます。 

$ chmod +x test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

見て分かるように、- で始まるスクリプトのパラメータを 指定する際に、特に注意する必要はありません。

PHP 実行バイナリは、Web サーバーから完全に独立して PHP スクリプトを 実行するために使用することができます。Unix システムを使用している場合、 実行可能とするためには PHP スクリプトの先頭に特別な一行を追加する必要が あります。これにより、システムがそのスクリプトを実行するプログラムを 知ることができます。 Windows 環境では、.php ファイルのダブルクリック オプションに php.exe を関連づけることができます。 または、PHP によりスクリプトを実行するバッチファイルを作成することも 可能です。Unix 上で動作させるためにスクリプトに追加された先頭行は、 Windows 環境での動作に悪影響を与えません。このため、この手法により、 クロスプラットフォーム環境で動作するプログラムを書くことができます。 コマンドライン PHP プログラムの書方の簡単な例を以下に示します。

例2 コマンドラインから実行されることを意図したスクリプト(script.php)

#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

これは、ひとつのオプションをとるコマンドラインの PHP スクリプトです。

  使用法:
  <?php echo $argv[0]; ?> <option>

  <option> は出力したい単語です。
  --help, -help, -h, あるいは -? を指定すると、
  このヘルプが表示されます。

<?php
} else {
    echo $argv[1];
}
?>

上のスクリプトでは、特殊な先頭行が用いられており、このファイルが PHP により実行されることを示しています。ここでは CLI 版を使用しているため、 HTTP ヘッダは出力されません。PHP で コマンドラインアプリケーションを使用する際には、2 つの変数 $argc および $argv を使用することが できます。 最初の変数は、引数の数に 1 (実行中のスクリプトの名前)を加えたものです。 2 番目の変数は、引数を保持する配列で、スクリプト名を有する 要素 0 ($argv[0]) から始まっています。

上のプログラムでは、引数が 1 より少ないかまたは多いかを調べています。 また、引数が --help , -help , -h または -? の場合、 ヘルプメッセージを出力し、動的にスクリプト名を出力します。 他の引数を受け取った場合、これを出力します。

上のスクリプトを Unix で実行する場合、実行可能とした後、 script.php echothis または script.php -h とする必要があります。 Windows では、この処理を行なう以下のようなバッチファイルを作成することができます。

例3 コマンドライン PHP スクリプトを実行するバッチファイル(script.bat)

@echo OFF
"C:\php\php.exe" script.php %*

上のプログラムが script.php という名前であるとし、 c:\php\php.exe に CLI php.exe があるとすると、このバッチファイルは、追加オプション script.bat echothis または script.bat -h を指定して、スクリプトを実行します。

PHP のコマンドラインアプリケーションを拡張するために使用できるその他の関数については、 拡張モジュール Readline に関するドキュメントも参照してください。

Windows 環境で使用している場合、PHP の設定によって C:\php\php.exe や拡張子 .php の指定を不要にすることもできます。Micosoft Windows コマンドラインでの PHP を参照ください。

入出力ストリーム

CLI SAPI には入出力ストリーム用の定数がいくつか定義されており、 これらを使うとコマンドライン用のプログラミングが多少簡単になります。

CLI 固有の定数
定数 説明
STDIN

stdin へのオープン済みのストリーム。 これにより、以下のようにオープンする必要がなくなります。

<?php
$stdin = fopen('php://stdin', 'r');
?>
stdin から1行読み込みたい場合、以下のようにします。
<?php
$line = trim(fgets(STDIN)); // STDIN から 1 行読み込む
fscanf(STDIN, "%d\n", $number); // STDIN から数値を読み込む
?>

STDOUT

stdout へのオープン済みのストリーム。 これにより、以下のようにオープンする必要がなくなります。

<?php
$stdout = fopen('php://stdout', 'w');
?>

STDERR

stderr へのオープン済みのストリーム。 これにより、以下のようにオープンする必要がなくなります。

<?php
$stderr = fopen('php://stderr', 'w');
?>

上記のように、stderr のようなストリームを自分で オープンする必要はなく、以下のようにストリームリソースの代わりに 定数を使用するだけでかまいません。 

php -r 'fwrite(STDERR, "stderr\n");'
これらのストリームを明示的に閉じる必要はありません。これは、 PHP により自動的に行われます。

注意:

これらの定数は、PHP スクリプトを stdin から読み込んだ場合は使用できません。

対話シェル

PHP 5.1.0 以降では、--with-readline オプションつきで PHP をコンパイルした場合に CLI SAPI で対話シェルが使えるようになりました。 対話シェルは、-a オプションで使うことができます。

対話シェルを使うと、PHP のコードを打ち込んで直接実行できるようになります。

例1 対話シェル上でのコードの実行

$ php -a
Interactive shell

php > echo 5+8;
13
php > function addTwo($n)
php > {
php { return $n + 2;
php { }
php > var_dump(addtwo(2));
int(4)
php >

対話シェル上では、タブ補完機能を使って 関数や定数、クラス名、変数名、静的なメソッドコール、そしてクラス定数を補完することができます。

例2 タブ補完

補完候補が複数あるときにタブキーを二度押すと、 補完候補の一覧が表示されます。 

php > strp[TAB][TAB]
strpbrk   strpos    strptime  
php > strp

候補がひとつしかないときは、タブキーを一度押せば残りを補完してくれます。 

php > strpt[TAB]ime(

対話シェルのセッション上で定義したものについても補完することができます。 

php > $fooThisIsAReallyLongVariableName = 42;
php > $foo[TAB]ThisIsAReallyLongVariableName

対話シェル上では操作履歴が保存され、上矢印キーと下矢印キーで履歴にアクセスすることができます。 履歴の保存先は ~/.php_history ファイルです。

PHP 5.4.0 以降、CLI SAPI に二つの新たな php.ini 設定が追加されました。cli.pager と cli.prompt です。cli.pager は、外部のプログラム (less など) を出力のページャとして指定することができます。 出力が画面に直接送られるかわりに、このページャに送られるようになります。 cli.prompt を指定すると、 php > プロンプトを変更することができます。

また、PHP 5.4.0 以降では、対話シェルの中で php.ini 項目を設定する際に短縮記法が使えるようにもなりました。

例3 対話シェル内での php.ini の設定

cli.prompt を設定します。 

php > #cli.prompt=hello world :> 
hello world :>

バッククォートを使うと、PHP のコードの実行結果をプロンプトとして用いることができます。 

php > #cli.prompt=`echo date('H:i:s');` php > 
15:49:35 php > echo 'hi';
hi
15:49:43 php > sleep(2);
15:49:45 php >

ページャを less に設定します。 

php > #cli.pager=less
php > phpinfo();
(出力が less に送られます)
php >

cli.prompt の設定は、次のようなエスケープシーケンスに対応しています。

cli.prompt のエスケープシーケンス
シーケンス 説明
\e プロンプトに色をつけます。たとえば \e[032m\v \e[031m\b \e[34m\> \e[0m のように使います。
\v PHP のバージョン。
\b PHP が今どのブロックにいるのかを示します。たとえば、 複数行コメントの中にいる場合は /* となります。 外側のスコープは php で表します。
\> プロンプト文字を示します。デフォルトでは > ですが、ブロックや文字列の途中にあるときは変わります。 ' " { ( > のような文字になることがあります。

注意:

auto_prepend_file および auto_append_file で インクルードされたファイルはこのモードでもパースされますが、 いくつかの制限があります。例えば、関数はそれがコールされる前に 定義されていなければなりません。

注意:

オートローディング は、PHP を CLI の対話モードで実行している場合は使用できません。

ビルトインウェブサーバー

PHP 5.4.0 から、CLI SAPI にはウェブサーバーの機能が組み込まれるようになりました。

このウェブサーバーは開発用としてのみ設計されたものであり、 実運用に使ってはいけません。

リクエストの処理はシーケンシャルに行います。

URI リクエストの処理は、PHP を開始した時点の作業ディレクトリから行われます。 -t オプションを使えば、ドキュメントルートを明示的に指定することができます。 URI リクエストにファイルが含まれない場合は、指定したディレクトリにある index.php あるいは index.html を返します。どちらも存在しない場合はレスポンスコード 404 を返します。

ウェブサーバーの開始時にコマンドラインで PHP ファイルを指定すると、 そのファイルをウェブサーバーの "ルーター" スクリプトとして使います。 このスクリプトは、各 HTTP リクエストの開始時に動きます。このスクリプトが FALSE を返すと、リクエストされたリソースをそのままの形式で返します。 それ以外の場合はスクリプトの出力をブラウザに返します。

Standard MIME types are returned for files with extensions: .css, .gif, .htm, .html, .jpe, .jpeg, .jpg, .js, .png, .svg, and .txt. The .htm and .svg extensions are recognized from PHP 5.4.4 onwards.

例1 ウェブサーバーの起動

$ cd ~/public_html
$ php -S localhost:8000

ターミナルには次のように表示されます。 

PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
Listening on localhost:8000
Document root is /home/me/public_html
Press Ctrl-C to quit

http://localhost:8000/ と http://localhost:8000/myscript.html をリクエストした後のターミナルの表示は、 このようになります。 

PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
Listening on localhost:8000
Document root is /home/me/public_html
Press Ctrl-C to quit.
[Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
[Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
[Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
[Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
[Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read

例2 ドキュメントルートディレクトリを指定した起動

$ cd ~/public_html
$ php -S localhost:8000 -t foo/

ターミナルには次のように表示されます。 

PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
Listening on localhost:8000
Document root is /home/me/public_html/foo
Press Ctrl-C to quit

例3 ルータースクリプトの使用

この例では、画像ファイルをリクエストすればそのまま表示し、HTML ファイルをリクエストすると "Welcome to PHP" と表示します。

<?php
// router.php
if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
    return false;    // serve the requested resource as-is.
} else { 
    echo "<p>Welcome to PHP</p>";
}
?> 
$ php -S localhost:8000 router.php

例4 Checking for CLI Web Server Use

To reuse a framework router script during development with the CLI web server and later also with a production web server:

<?php
// router.php
if (php_sapi_name() == 'cli-server') {
    /* route static assets and return false */
}
/* go on with normal index.php operations */
?> 
$ php -S localhost:8000 router.php

例5 Handling Unsupported File Types

If you need to serve a static resource whose MIME type is not handled by the CLI web server, use:

<?php
// router.php
$path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
if ($path["extension"] == "ogg") {
    header("Content-Type: video/ogg");
    readfile($_SERVER["SCRIPT_FILENAME"]);
}
else {
    return FALSE;
}
?> 
$ php -S localhost:8000 router.php

例6 Accessing the CLI Web Server From Remote Machines

You can make the web server accessible on port 8000 to any interface with: 

$ php -S 0.0.0.0:8000

INI 設定

CLI SAPI の設定オプション
名前 デフォルト 変更可能 変更履歴
cli_server.color "0" PHP_INI_ALL PHP 5.4.0 以降で利用可能。

以下に設定ディレクティブに関する 簡単な説明を示します。

cli_server.color boolean

組み込みの開発用ウェブサーバーで、ANSI カラーコードを使ってターミナルに出力できるようにします。

ガベージコレクション

目次

このセクションでは、PHP 5.3 の一部の、新しいガベージコレクション（別名GC）機構の メリットを説明します。

参照カウント法の原理

PHP 変数は「zval」と呼ばれるコンテナに保管されます。 zval コンテナには、変数の型と値の他に、情報の追加ビットを2つ含みます。 1つ目は「is_ref」と呼ばれ、変数が「参照集合」の一部かどうかを示すブール値 です。 このビットによって、通常の変数と参照を区別する方法を PHP エンジンが知ります。 &演算子によって作成されるように、PHP ではユーザーランドを参照できるので、 zval コンテナもメモリー使用状況を最適化するための内部的な参照カウント機構を 持ちます。 追加情報の2つ目は「refcount」と呼ばれ、この1つの zval コンテナをどれだけ多くの 変数名（シンボルとも呼ばれます）が指すかを含みます。 シンボルは全てシンボルテーブルに保管され、スコープごとにシンボルテーブルの 1つがあります。 関数やメソッドごとのスコープばかりではなく、メインスクリプト用のスコープ （すなわち、ブラウザによってリクエストされたスクリプト）があります。

新しい変数が定数値を使って作成されるとき、zval コンテナが作成されます。 例えば、

例1 新規 zval コンテナを作成

<?php
$a = "new string";
?>

この例では、新しいシンボル名（a）が現在のスコープで作成され、 新しい変数コンテナが string 型と値 new string で作成されます。 「is_ref」ビットはデフォルトで FALSE にセットされます。なぜなら、ユーザーランド 参照が作成されないからです。 この変数コンテナを利用するシンボルが1つだけあるので、「refcount」は 1 に設定されます。 「refcount」が 1 ならば、is_ref が常に FALSE である点に 注意してください。 もし » Xdebug をインストール済みなら、 xdebug_debug_zval()を呼ぶと、この情報を表示できます。

例2 zval 情報を表示

<?php
xdebug_debug_zval('a');
?>

上の例の出力は以下となります。

a: (refcount=1, is_ref=0)='new string'

この変数を他の変数名に代入すると、refcount が増加します。

例3 zval の refcount を増加

<?php
$a = "new string";
$b = $a;
xdebug_debug_zval( 'a' );
?>

上の例の出力は以下となります。

a: (refcount=2, is_ref=0)='new string'

この時、refcount は 2 です。なぜなら、同じ変数コンテナが a と b にリンクされるからです。 PHPは、必要ではない場合に実際の変数コンテナをコピーしないように十分スマートです。 「refcount」がゼロに達すると、変数コンテナは破棄されます。 変数コンテナにリンクされたあらゆるシンボルがスコープを抜ける （例えば関数が終わる）場合、またはシンボルに対して unset() が呼ばれた場合に「refcount」が減少します。 下記の例でこれを示します。

例4 zval refcount を減少

<?php
$a = "new string";
$c = $b = $a;
xdebug_debug_zval( 'a' );
unset( $b, $c );
xdebug_debug_zval( 'a' );
?>

上の例の出力は以下となります。

a: (refcount=3, is_ref=0)='new string'
a: (refcount=1, is_ref=0)='new string'

次に、unset($a); を呼ぶと、（型と値を含む）変数コンテナが メモリから除去されます。

複合型

array や object のような複合型では、事情が少し 複雑になります。 scalar 値ではなく、array と object では、それらのプロパティをそれら自身のシンボルテーブルに保管します。 これは、以下の例が3つの zval コンテナを作成することを意味します。

例5 array zval を作成

<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
xdebug_debug_zval( 'a' );
?>

上の例の出力は、 たとえば以下のようになります。

a: (refcount=1, is_ref=0)=array (
   'meaning' => (refcount=1, is_ref=0)='life',
   'number' => (refcount=1, is_ref=0)=42
)

つまり、図で示すと

単純配列に対する zval

3つのzvalコンテナは a、meaning および number です。「refcount」の増減に同様のルールが適用されます。 下記では、配列に他の要素を追加して、既存の要素の内容をその値に設定します。

例6 既存の要素を配列に追加

<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
$a['life'] = $a['meaning'];
xdebug_debug_zval( 'a' );
?>

上の例の出力は、 たとえば以下のようになります。

a: (refcount=1, is_ref=0)=array (
   'meaning' => (refcount=2, is_ref=0)='life',
   'number' => (refcount=1, is_ref=0)=42,
   'life' => (refcount=2, is_ref=0)='life'
)

つまり、図で示すと

参照を使った単純配列に対する zval

上記の Xdebug 出力では、新旧両方の配列要素が今や、refcount が 2 である zval コンテナを指すことがわかります。 Xdebugの出力では、'life' という値の zval コンテナが2つ 表示されますが、それらは同一です。 xdebug_debug_zval() 関数はこれを表示しませんが、 メモリ・ポインターを示すことによってもそれを確かめられます。

配列からの要素の除去は、スコープからシンボルを除去するようなものです。 そうすることによって、配列要素が指すコンテナの「refcount」は、減少します。 前と同じように、「refcount」がゼロに達すると、変数コンテナはメモリから 除去されます。前と同じように、これを示す例です。

例7 配列から要素を除去

<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
$a['life'] = $a['meaning'];
unset( $a['meaning'], $a['number'] );
xdebug_debug_zval( 'a' );
?>

上の例の出力は、 たとえば以下のようになります。

a: (refcount=1, is_ref=0)=array (
   'life' => (refcount=1, is_ref=0)='life'
)

次に、配列の要素として配列自体を追加すると、事情が面白くなります。 次の例で行います、そこでは、参照演算子にこっそり入りもします。 さもなければ PHP がコピーを作成するでしょう。

例8 それ自体の要素として配列自体を追加

<?php
$a = array( 'one' );
$a[] =& $a;
xdebug_debug_zval( 'a' );
?>

上の例の出力は、 たとえば以下のようになります。

a: (refcount=2, is_ref=1)=array (
   0 => (refcount=1, is_ref=0)='one',
   1 => (refcount=2, is_ref=1)=...
)

つまり、図で示すと

循環参照を使った配列に対する zval

配列変数 (a) が２番目の要素 (1) と同様に 「refcount」が 2 である変数コンテナを今や指していることがわかります。 上記の表示の「...」は入り組んだ再帰があることを示します。 もちろんこの場合には、「...」が元の配列を指すことを意味します。

ちょうど前のように、変数をアンセットするとシンボルが除去されます。 そして指す変数コンテナの参照カウントがアンセットにより減少します。 従って、上記のコードを実行した後に変数 $a をアンセットすると、 $a と要素「1」を指す変数コンテナの参照カウントは、 アンセットにより「2」から「1」に減少します。これは次のように表現されます。

例9 $a をアンセット

(refcount=1, is_ref=1)=array (
   0 => (refcount=1, is_ref=0)='one',
   1 => (refcount=1, is_ref=1)=...
)

つまり、図で示すと

メモリ・リークを実際に示す循環参照を使った配列を除去した後の zval

片づけの問題

この構造体を指すシンボルがいかなるスコープにももはや存在しないにもかかわらず、 配列要素「1」がこの同じ配列をまだ指すので、片づけられません。 それを指している外部シンボルがないので、ユーザーがこの構造体を片付ける方法が ありません。このようにしてメモリーリークとなります。 幸いにも、PHP はリクエスト終了後、このデータ構造を片付けます、しかし、それ以前に これはメモリ内の貴重な空間を占めています。 この状態は、「親」要素に再帰する「子」を持つ構文解析アルゴリズムなどの実装中に しばしば発生します。 もちろんオブジェクトでも同じ状態が起こり得ます。オブジェクトは常に暗黙のうちに 参照によって使われるので、実はその状態がより起こりそうです。

これが 1、2 回起こるだけであるならば、これは問題でないかもしれません。しかし、 これらのメモリ損失の数千または数百万さえあるならば、これは明らかに問題になり始めます。 これは、例えばリクエストが基本的に決して終わらないデーモンのような、長くかかる 実行中のスクリプトや、単体テストの大規模な集合で特に問題があります。 後者は、eZ コンポーネント・ライブラリのテンプレート・コンポーネントに対して 単体テストを実行中に問題を引き起こしました。 いくらかの事例で、それは 2GB 以上のメモリを必要とします。そしてテストサーバーは全く 持っていませんでした。

循環の収集

伝統的に、PHP で以前使われていたような参照カウント法記憶機構では、 循環参照メモリ・リークに対処できません。 しかしながら、5.3.0 現在、PHP ではその問題に焦点を当てた » Concurrent Cycle Collection in Reference Counted Systems レポートに由来する同期アルゴリズムを実装しています。

アルゴリズムの動作方法の詳しい説明がこのセクションの範囲の少し向こうにあります、 しかし、基本はここで説明されます。 まず第一に、いくつかの基本原則を確立しなければなりません。 refcount が増やされたら、それはまだ使用中で、従ってゴミではありません。 refcount が減少して、ゼロに達したら、zvalは解放可能です。 refcount 引数がゼロ以外の値に減少する場合、これは、ガベージサイクルを作成できる だけであることを意味します。 第２に、ガベージサイクルで、それらの refcount を減少させられるかどうかチェック することによって、どの部分がゴミか発見できます。 可能です、そして、zval のうちいずれがゼロの refcountを持つか調べます。

ガベージコレクションのアルゴリズム

refcount の減少が起こりうるたびにガベージ・サイクルのチェックを呼び出さなくても良いように、 代わりに、可能性があるルート (zvals) 全てをアルゴリズムはルート・バッファにたくわえます。 （それらは「紫」とマークされます) それは、可能性のあるガベージのルートそれぞれがバッファ内で一度だけで終わることも確認します。 ルート・バッファが満杯の場合だけ、内部のそれぞれの zval 全てに対して収集機構が動き出します。 上図のステップ A をご覧ください。

ステップ B では、見つけた各 zval の refcount を一つ減じるために、 可能性があるルート全てに対してアルゴリズムが深さ優先探索を実行します。 それは、同一の zval に対して refcount を２回減じていないことを確保します。 (それらを「灰色」とマークすることにより) 工程 C では、それぞれのルート・ノードからアルゴリズムが再び深さ優先探索を実行します。 それは各 zval の refcount を再度チェックするためです。 refcount がゼロと分かった場合、zval は「白」（図では青色です）とマークされます。 もしそれが正の数なら、それは、指し示すところからの深さ優先探索により refcount の減少を一つ戻します。 そしてそれらは再び「黒」とマークされます。 最後の工程 (D) では、アルゴリズムはルート・バッファを走査してそこから zval ルートを除去します。 そしてその一方で zval が前の工程で「白」とマークされていたかどうかをチェックします。 「白」としてマークされた zval が全て解放されます。

アルゴリズムが動作する方法の基礎を理解したので、 これと PHP を統合する方法を振り返りましょう。 デフォルトで、PHP のガベージコレクタは有効です。 しかしながら、これを変更できる php.ini の設定があります。 （それは） zend.enable_gc です。

ガベージコレクタがオンの場合、 ルート・バッファが満杯になるといつでも、先に述べたように循環検出法が実行されます。 ルート・バッファでは、可能性があるルートのサイズが一万件に固定されています。 （PHP のソースコードの Zend/zend_gc.c で GC_ROOT_BUFFER_MAX_ENTRIES 定数を変更して、PHP を再コンパイルすると変更できます） ガベージコレクタがオンの場合、循環検出法は実行されません。 しかしながら、可能性があるルートはルート・バッファに常に記録されます。 ガベージコレクション機構がこの構成設定値で起動したかどうかは問題ではありません。

ガベージコレクション機構がオフの時に、可能性があるルートでルート・バッファが満杯になると、 可能性があるルートは単にそれ以上記録されません。 記録されないそれらの可能性があるルートは、アルゴリズムによって決して分析されません。 もしそれらが循環参照サイクルの要素ならば、 それらは決してクリーンアップされないで、メモリリークを生み出します。

たとえ機構が無効だとしても、可能性があるルートが記録される理由は、 可能性があるルートが見つかるたびに機構がオンかどうかチェックしなければいけないよりも、 可能性があるルートを記録するほうが速いからです。 しかしながら、ガベージコレクションと分析機構そのものにかなりの時間がかかることがあります。

zend.enable_gc 構成設定値を変える他に、 gc_enable() や gc_disable() をそれぞれ呼ぶことでも、 ガベージコレクション機構をオン／オフできます。 それらの機能を呼ぶことと、構成設定値で機構をオン／オフすることには同じ影響があります。 たとえ可能性があるルートのバッファがまだ満杯でなくても、 循環の収集を強制することもできます。 このために、gc_collect_cycles() 関数を使用できます。 この関数は、アルゴリズムによって収集された循環の数を返します。

機構をオン／オフしたり、循環の収集を開始する機能の後ろ盾になる根拠は、 アプリケーションの一部分は非常に時間に敏感な可能性があることです。 それらの場合、ガベージコレクション機構が有効にならないほうが良いかもしれません。 もちろん、アプリケーションのある種の部分では、ガベージコレクションをオフにすることにより、 メモリリークを引き起こす危険があります。 なぜなら可能性があるルートの一部は有限のルート・バッファに収まらないかもしれないからです。 従って、ルート･バッファにすでに記録された、可能性があるルートを通じて失われる可能性のあるメモリを解放するために、 gc_disable() を呼ぶ直前に gc_collect_cycles() を呼ぶことは多分賢いでしょう。 そうすると、循環収集機構がオフの間、 可能性があるルートを保管するためのより多くの空間のための空のバッファが残ります。

パフォーマンスの考慮点

可能性があるルートを単純に収集すると、パフォーマンスにごくわずかな影響があると既に前述しました。 しかし、これは PHP 5.3 と PHP 5.2 を比較する場合です。 可能性があるルートを記録すると、PHP 5.2 のように全く記録しないものに比べてより遅いとはいえ、 PHP 5.3 のランタイムへの他の変更点により、この特有のパフォーマンス低下が一層際立つことが防止されています。

パフォーマンスが影響を受ける主な分野は2つあります。 1つ目は、減少したメモリ使用量で、 2つ目はガベージコレクション機構がそのメモリ・クリーンアップを実行する際の実行遅延です。 それら両方の問題を見てみましょう。

減少したメモリ使用量

まず第一に、ガベージコレクション機構を実装する理由は、 必要条件が満たされたらすぐに、循環参照された変数を整理してメモリ使用量を減らすことにあるのです。 PHP の実装では、ルート・バッファが満杯になるか、または、関数 gc_collect_cycles() が呼ばれるとすぐにこれが起こります。 下図で、下記のスクリプトのメモリ使用量を PHP 5.2 及び PHP 5.3 の両方で示します。 (ただし)起動時に PHP 自身が使用する基底メモリを除きます。

例1 メモリ使用量の例

<?php
class Foo
{
    public $var = '3.1415962654';
}

$baseMemory = memory_get_usage();

for ( $i = 0; $i <= 100000; $i++ )
{
    $a = new Foo;
    $a->self = $a;
    if ( $i % 500 === 0 )
    {
        echo sprintf( '%8d: ', $i ), memory_get_usage() - $baseMemory, "\n";
    }
}
?>
PHP 5.2 と PHP 5.3 のメモリ使用量の比較

このとても学術的な例では、 プロパティがオブジェクト自身を指すように設定されたオブジェクトを作成します。 スクリプト内の $a 変数がループの次の繰り返しで再設定されると、 一般的にメモリ・リークが発生します。 この場合、zval コンテナが２つリークします（オブジェクトの zval 及び プロパティの zval）。 しかし、可能性があるルートが一つだけ見つかります。 (それは)アンセットされた変数です。 一万回繰り返した後に（可能性があるルートを合計1万件伴って）ルート・バッファが満杯になると、 ガベージコレクション機構が有効になって、それらの可能性があるルートと関連するメモリを解放します。 これは PHP 5.3 での、のこぎりの歯のようなメモリ使用量グラフでとてもはっきりと分かります。 一万回繰り返す毎に機構が有効になって、循環参照された変数と関連するメモリを解放します。 この例ではリークした構造がとても単純なので、機構そのものが多くの仕事をする必要はありません。 図では、PHP 5.3 でのメモリ使用量の最大はおよそ 9MB と分かります。 ところが PHP 5.2 では、メモリ使用量は増加し続けます。

ランタイムの減速

ガベージコレクション機構がパフォーマンスに影響する２つ目の分野は、 ガベージコレクション機構が「リークした」メモリを解放するために 開始する際にかかる時間です。これがどの程度か見るためには、 反復回数をより多くし、間に入るメモリの使用量を除去するために、 前のスクリプトをちょっと修正します。 2つ目のスクリプトはこれです。

例2 GC パフォーマンスの影響

<?php
class Foo
{
    public $var = '3.1415962654';
}

for ( $i = 0; $i <= 1000000; $i++ )
{
    $a = new Foo;
    $a->self = $a;
}

echo memory_get_peak_usage(), "\n";
?>

このスクリプトを2回実行します。最初は zend.enable_gc 設定をオンにし、次はオフにします。

例3 上記のスクリプトを実行

time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php
# and
time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php

私のマシンでは、最初の命令は一貫しておよそ10.7秒かかるようです。 ところが、第2の命令にはおよそ11.4秒かかります。 これは、およそ7%の減速です。 しかしながら、スクリプトで使用されるメモリの最大量は、931MB から 10MB まで 98% 減ります。 このベンチマークはあまり学術的でもなく、現実のアプリケーションの代表でもありません。 しかし、このガベージコレクション機構が提供するメモリ使用量の利点を示します。 良い点は、スクリプト実行中に循環参照をより多く見つけて、 メモリ節約機能がますます多くのメモリを節約する一方で、 この個別のスクリプトで減速がいつでも同じく7%ということです。

PHP 内部の GC 統計

ガベージコレクション機構がPHP 内部から実行される方法に関して、 情報をもう少し上手に扱うことができます。 しかし、そうするためには、ベンチマークとデータ収集コードを使用可能にするために、 PHP を再コンパイルしなければなりません。 希望するオプションで ./configure を走らせる前に、 CFLAGS 環境変数を -DGC_BENCH=1 に設定しなければなりません。 以下の順序で目的に達するでしょう。

例4 GC ベンチマーキングを使用可能にするために PHP を再コンパイル

export CFLAGS=-DGC_BENCH=1
./config.nice
make clean
make

新しくビルドした PHP バイナリで上記のコード例を前と同じように実行すると、 PHP の実行終了後に、下記が表示されているでしょう。

例5 GC 統計

GC Statistics
-------------
Runs:               110
Collected:          2072204
Root buffer length: 0
Root buffer peak:   10000

      Possible            Remove from  Marked
        Root    Buffered     buffer     grey
      --------  --------  -----------  ------
ZVAL   7175487   1491291    1241690   3611871
ZOBJ  28506264   1527980     677581   1025731

最も有益な統計は、最初のブロックで示されます。 ここではガベージコレクション機構が 110 回実行されたことが分かります。 そして、全体では、それら 110 回の実行中に、 200万以上のメモリ割り当てが 解放されました。 ガベージコレクション機構が少なくとも一回実行されるや否や、 "Root buffer peak" は常に 10000 です。

結論

通常、循環収集アルゴリズムが実際に動作する際、PHP でのガベージコレクタは減速を 引き起こすだけです。一方、通常の（より小さい）スクリプトでは、打撃を受ける パフォーマンスが全くあってはいけません。

しかしながら、循環収集機構が通常のスクリプトに対して動作する場合には、 全体でそれほど多くのメモリが使われないので、 循環収集機構により提供されるメモリ節減により、それらのスクリプトの多くで サーバー上で平行して稼動できるようになります。

より長時間にわたるスクリプト（例えば長いテスト・スイートまたはデーモン・スクリプト）にとって 有利なことはとても明らかです。 また、ウェブ用のスクリプトに比べてたいていより長く動作する傾向がある » PHP-GTK アプリケーションについては、 時がたつにつれて忍び込むメモリリークに関して、新しい機構によるかなりの差が生じなければなりません。

関数リファレンス

ヒント

参考 拡張モジュールの一覧/分類.

PHP の振る舞いの変更

Alternative PHP Cache

導入

Alternative PHP Cache (APC) は、PHP の実行コードをキャッシュする仕組みで、 フリーかつオープンに使用できます。PHP の中間コードのキャッシュ・最適化を行うための、 フリーでオープンかつ堅牢なフレームワークを提供するということを目標としています。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/apc.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

注意: Windows 版の APC では、temp パスが存在し、 Web サーバーから書き込み可能になっていることが必要です。 APC は環境変数 TMP、TEMP、USERPROFILE の内容をこの順に調べ、 どれも設定されていない場合は WINDOWS ディレクトリを使用します。

注意: さらに深く踏み込んだ、実装についての高度な技術情報は、 »  developer-supplied TECHNOTES file を参照ください。

実行時設定

php.ini の設定により動作が変化します。

たいていの場合はデフォルトの APC 設定でうまく動作しますが、 きちんとチューニングをしたい場合は以下のパラメータを設定します。

あなたが決めなければいけないことは、以下の 2 つです。 まず APC にどれくらいの共有メモリを設定するかということ、そして、 ファイルの更新チェックをリクエストのたびに APC が行うかどうかということです。 これらに関連する ini ディレクティブが apc.shm_size および apc.stat です。これらのディレクティブについて、 以下の説明を注意深くお読みください。

サーバーを起動したら、この拡張モジュールに含まれているスクリプト apc.php をドキュメントルート以下に配置し、 ブラウザでアクセスしてください。 キャッシュの状態についての詳細な情報がここで得られます。 PHP で GD が使用可能になっている場合は、きれいなグラフも表示されます。 まず最初にチェックすべきなのは、当然、 実際にファイルがキャッシュされているかどうかでしょう。 実際に動作していることを確認したら、次は左側にある Cache full count の値に注目しましょう。 これは、キャッシュがいっぱいになったために強制削除が行われた (直近の apc.ttl 秒間にアクセスされなかったエントリが、 キャッシュから削除された) 回数を表します。 この値ができるだけ小さくなるようにキャッシュを設定しなければなりません。 キャッシュが絶えずいっぱいになっているようだと、 パフォーマンスに影響を及ぼします。 この場合は、APC に割り当てるメモリの量を増やすか、 キャッシュするスクリプトを絞り込むために apc.filters を使用します。

APC を mmap (メモリマッピング) サポート付きでコンパイルすると、 ひとつのメモリセグメントだけを使うようになります。一方、APC を SHM (SysV 共有メモリ) サポートでビルドした場合は複数のメモリセグメントを使います。 MMAP には、SHM における /proc/sys/kernel/shmmax のような最大値の制限はありません。 一般的には MMAP サポートを推奨します。 ウェブサーバーを再起動するよりも高速にメモリを再利用するし、 起動時のメモリ割り当て量も軽減できるからです。

APC の設定オプション
名前 デフォルト 変更可能 変更履歴
apc.enabled "1" PHP_INI_SYSTEM APC 2 で PHP_INI_SYSTEM。APC <= 3.0.12 で PHP_INI_ALL。
apc.shm_segments "1" PHP_INI_SYSTEM  
apc.shm_size "32M" PHP_INI_SYSTEM  
apc.optimization "0" PHP_INI_ALL  
apc.num_files_hint "1000" PHP_INI_SYSTEM  
apc.user_entries_hint "4096" PHP_INI_SYSTEM APC 3.0.0 以降で利用可能。
apc.ttl "0" PHP_INI_SYSTEM APC 3.0.0 以降で利用可能。
apc.user_ttl "0" PHP_INI_SYSTEM APC 3.0.0 以降で利用可能。
apc.gc_ttl "3600" PHP_INI_SYSTEM  
apc.cache_by_default "1" PHP_INI_ALL APC <= 3.0.12 で PHP_INI_SYSTEM。APC 3.0.0 以降で利用可能。
apc.filters NULL PHP_INI_SYSTEM  
apc.mmap_file_mask NULL PHP_INI_SYSTEM  
apc.slam_defense "1" PHP_INI_SYSTEM APC 3.0.0 以降で利用可能。APC 3.1.4 より前のバージョンでは、デフォルト値が "0" (無効) でした。
apc.file_update_protection "2" PHP_INI_SYSTEM APC 3.0.6 以降で利用可能。
apc.enable_cli "0" PHP_INI_SYSTEM APC 3.0.7 以降で利用可能。
apc.max_file_size "1M" PHP_INI_SYSTEM APC 3.0.7 以降で利用可能。
apc.use_request_time "1" PHP_INI_ALL APC 3.1.3 以降で利用可能。
apc.stat "1" PHP_INI_SYSTEM APC 3.0.10 以降で利用可能。
apc.write_lock "1" PHP_INI_SYSTEM APC 3.0.11 以降で利用可能。
apc.report_autofilter "0" PHP_INI_SYSTEM APC 3.0.11 以降で利用可能。
apc.include_once_override "0" PHP_INI_SYSTEM APC 3.0.12 以降で利用可能。
apc.rfc1867 "0" PHP_INI_SYSTEM APC 3.0.13 以降で利用可能。
apc.rfc1867_prefix "upload_" PHP_INI_SYSTEM  
apc.rfc1867_name "APC_UPLOAD_PROGRESS" PHP_INI_SYSTEM  
apc.rfc1867_freq "0" PHP_INI_SYSTEM  
apc.rfc1867_ttl "3600" PHP_INI_SYSTEM APC 3.1.1 以降で利用可能。
apc.localcache "0" PHP_INI_SYSTEM APC 3.0.14 以降で利用可能。
apc.localcache.size "512" PHP_INI_SYSTEM APC 3.0.14 以降で利用可能。
apc.coredump_unmap "0" PHP_INI_SYSTEM APC 3.0.16 以降で利用可能。
apc.stat_ctime "0" PHP_INI_SYSTEM APC 3.0.13 以降で利用可能。
apc.preload_path NULL PHP_INI_SYSTEM APC 3.1.1 以降で利用可能。
apc.file_md5 "0" PHP_INI_SYSTEM APC 3.1.1 以降で利用可能。
apc.canonicalize "1" PHP_INI_SYSTEM APC 3.1.1 以降で利用可能。
apc.lazy_functions 0 PHP_INI_SYSTEM APC 3.1.3 以降で利用可能。
apc.lazy_classes 0 PHP_INI_SYSTEM APC 3.1.3 以降で利用可能。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

apc.enabled boolean

apc.enabled を 0 にすることで APC を無効にできます。 APC が静的にコンパイルされて PHP に組み込まれており、 他に無効にする手段がない場合などに有用です (DSO としてコンパイルされている場合は、 単に php.ini の中の extension という行をコメントアウトするだけで無効にできます)。

apc.shm_segments integer

コンパイラキャッシュのために割り当てる共有メモリセグメントの数。 APC が割り当て済みの共有メモリを使い切ってしまっているが、 すでにシステムが許す限り apc.shm_size を拡大しているといった場合に、この値を大きくすることを試みます。

apc.shm_size integer

個々の共有メモリセグメントの大きさを MB 単位で指定します。デフォルトで、 共有メモリセグメントの大きさが非常に小さく設定されているシステムもあります (大半の BSD 系システムがこれに含まれます)。

apc.optimization integer

最適化レベル。ゼロは最適化を無効にし、 値を大きくするほど最適化のレベルが高くなります。 わずかながら速度の向上が期待できます。この項目は実験的なものです。

apc.num_files_hint integer

Web サーバーで読み込まれるソースファイルの総数についての 「ヒント」。よくわからない場合はゼロを指定するか、 単に無視してください。 何千ものソースファイルを扱っているようなサイトで有用です。

apc.user_entries_hint integer

apc.num_files_hint と同様に、 保存するユーザーキャッシュ変数の数についての「ヒント」。 よくわからない場合は、ゼロを設定するか無視してください。

apc.ttl integer

キャッシュされているエントリが、 他のエントリに割り当てられるまでスロットに残っていることの可能な秒数。 ゼロのままにしておくと、キャッシュの中身が古いエントリでいっぱいになってしまい、 新しいエントリがキャッシュできなくなります。 キャッシュが使用可能メモリを超えてしまった場合、 ttl が 0 ならキャッシュを完全に破棄します。 ttl が 0 より大きい場合は、APC は期限切れのエントリの削除を試みます。

apc.user_ttl integer

ユーザーキャッシュエントリが、 他のエントリに割り当てられるまでスロットに残っていることの可能な秒数。 ゼロのままにしておくと、キャッシュの中身が古いエントリでいっぱいになってしまい、 新しいエントリがキャッシュできなくなります。 キャッシュが使用可能メモリを超えてしまった場合、 ttl が 0 ならキャッシュを完全に破棄します。 ttl が 0 より大きい場合は、APC は期限切れのエントリの削除を試みます。

apc.gc_ttl integer

キャッシュエントリがガベージコレクションのリストに残り続ける秒数。 ソースファイルのキャッシュ中にサーバープロセスが死んだ場合の安全装置となります。 ソースファイルが変更された場合、メモリに割り当てられている古いバージョンは、 この TTL に達するまで再読み込みされません。 この機能を無効にするにはゼロを設定します。

apc.cache_by_default boolean

デフォルトで On です。しかし、これを Off にして + で始まる apc.filters とともに使用することで、 フィルタに一致したファイルのみをキャッシュすることが可能です。

apc.filters string

カンマで区切られた、POSIX 拡張正規表現のリスト。 ソースファイル名がいずれかのパターンにマッチした場合、そのファイルはキャッシュされません。 マッチングに使用されるファイル名は include/require に渡される名前であり、 絶対パスではないことに注意しましょう。正規表現が + で始まっている場合、その条件にマッチするファイルはキャッシュされます。 また - で始まっている場合は、 条件にマッチするファイルはキャッシュされません。 デフォルトは - なので、これは省略可能です。

apc.mmap_file_mask string

--enable-mmap を用いて MMAP サポートつきでコンパイルされている場合、ここで mktemp 形式のファイルマスクを指定します。mmap モジュールは、 mmap されたメモリ領域をファイルに置くか共有メモリに置くかを、 これによって判断します。 ファイルベースの mmap を使用するには、この値を /tmp/apc.XXXXXX （正確に 6 つの X）のように指定します。 POSIX 形式の shm_open/mmap を使用するには、.shm をマスクのどこかで指定します。例: /apc.shm.XXXXXX 。 また、/dev/zero を指定することで、カーネルの /dev/zero インターフェイスを使用した anonymous mmap を使用することもできます。未定義の場合は、この方式が用いられます。

apc.slam_defense integer

非常にアクセスの多いサーバーでは、 サーバーを起動したりファイルを書き換えたりするたびに 「多くのプロセスが」「同時に」「同じファイルを」 キャッシュしようとすることになります。このオプションを指定すると、 ある一定のパーセンテージでファイルをキャッシュせずに利用するようにします。 あるいは、単一のプロセスがキャッシュ処理をスキップする確率と考えることもできます。 たとえば、apc.slam_defense を 75 に設定すると、プロセスがキャッシュされていないファイルをキャッシュする処理を 75% の確率で抑えられます。つまり、この値を大きく設定することで、 キャッシュ処理の混雑を防ぐことが可能です。値を 0 に設定すると、この機能が無効になります。

非推奨です。かわりに apc.write_lock を使用しましょう。

apc.file_update_protection integer

稼動中の Web サーバー上のファイルを書き換える場合、 アトミックな手段で行うべきです。つまり、まずいったん一時ファイルに書き込み、 準備ができた時点でそれをリネーム（mv） して正しい位置に移動します。多くのテキストエディタや cp、tar その他のプログラムはこの方式ではありません。 ということは、ファイルの書き込み中にそのファイルがアクセスされる （そしてキャッシュされる）可能性があるわけです。 apc.file_update_protection は、 新しいファイルをキャッシュするまでの遅延を設定します。デフォルトは 2 秒で、ファイルの更新時刻（mtime）がアクセス時刻と 2 秒未満しか違わない場合はファイルをキャッシュしないという意味です。 更新の最中のファイルにアクセスしてしまった不幸な人には 変なデータが見えてしまいますが、 少なくともその変な状態がキャッシュされてしまうことはありません。 rsync などのアトミックな更新を保証する方式を利用することがわかっている場合は、 値を 0 に設定することでこの機能を無効にできます。 更新処理に 2 秒以上かかるようなシステムを利用している場合は、 この値をもう少し大きくしたくなるかもしれません。

apc.enable_cli integer

たいていは、テストやデバッグ用に使用します。これを設定すると CLI バージョンの PHP で APC を有効にします。通常は、すべての CLI リクエストに対して APC キャッシュを作成/格納/削除したいとは思わないでしょう。 しかし、CLI バージョンの APC を簡単に作成できるようにしておくことは、 多くのテストシナリオで有用です。

apc.max_file_size integer

この値よも大きなサイズのファイルは、キャッシュされません。 デフォルトは 1M です。

apc.stat integer

この設定を変更する場合は十分注意してください。デフォルト設定は On で、 これは、ファイルが変更されていないかどうかを スクリプトの実行のたびに APC が調べ、 もし変更されていれば、再コンパイルして新しいバージョンをキャッシュします。 この設定を Off にすると、変更されているかどうかがチェックされません。 つまり、変更内容を有効にするには Web サーバーを再起動する必要があるということです。 実運用環境ではコードを変更することはめったにないでしょうから、 この設定を Off にしておくことでパフォーマンスを大きく向上させられます。

include/require されたファイルについてもこのオプションは適用されますが、 もし相対パス (Unix の場合は / で始まらないすべてのパス) の include を使用している場合は、ファイルを一意に識別するために APC がチェックする必要があります。 絶対パスの include を使用している場合、 APC 絶対パスをファイルの識別子として使用し、 チェックを飛ばすことができます。

apc.write_lock boolean

多くの処理が実行されるサーバーでは、最初にサーバーを立ち上げたときや 多くのファイルを変更した場合などに、 すべてのプロセスが同一のファイルをコンパイルしたりキャッシュしたりしてしまうことがあります。 write_lock を有効にすると、ひとつのプロセスのみが 未キャッシュのスクリプトをコンパイルするようになります。 その間、他のプロセスはロック待ちをするのではなく キャッシュされていない状態で実行します。

apc.report_autofilter boolean

バインド時の問題によりキャッシュから自動的に除外されたスクリプトを記録します。

apc.include_once_override boolean

include_once および require_once を最適化し、コストの高いシステムコールの使用を避けるようにします。

警告

この機能は実験的なものです。 このディレクティブの挙動やディレクティブ名、そして関連するドキュメントなどは、 今後 APC の新バージョンがリリースされるときに予告なく変更される可能性があります。 この機能は自己責任の下で使うようにしましょう。

apc.rfc1867 boolean

RFC1867 のファイルアップロード進捗ハンドラが有効になるのは、 PHP 5.2.0 以降で APC をコンパイルした場合のみです。 これを有効にすると、ファイルアップロードフォームの file フィールドの前に APC_UPLOAD_PROGRESS というフィールドがある場合に APC が自動的にユーザーキャッシュエントリ upload_key を作成します。ここで、key はフォームの APC_UPLOAD_PROGRESS エントリの値となります。

APC_UPLOAD_PROGRESS で指定した hidden フィールドが file フィールドよりも前にこなければならないことに注意しましょう。 そうしないと、アップロードの進捗処理が正しく動作しません。

現時点では、ファイルアップロードの追跡はスレッドセーフではないことに注意しましょう。 前のアップロード処理が終わる前に別のアップロードを開始すると、 前のアップロードの追跡が無効になってしまいます。

rate が使えるのは、 すべてのファイルの転送が完了してからであることに注意しましょう。

例1 apc.rfc1867 の例

<?php
print_r(apc_fetch("upload_$_POST[APC_UPLOAD_PROGRESS]"));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [total] => 1142543
    [current] => 1142543
    [rate] => 1828068.8
    [filename] => test
    [name] => file
    [temp_filename] => /tmp/php8F
    [cancel_upload] => 0
    [done] => 1
)

apc.rfc1867_prefix string

rfc1867 のアップロード進捗処理機能で作成するユーザーキャッシュエントリの キーにつけるプレフィックスを指定します。

apc.rfc1867_name string

APC のアップロード進捗処理機能を有効にするフォームの hidden 項目名、そしてユーザーキャッシュエントリのキーのサフィックスを指定します。

apc.rfc1867_freq string

アップロードの進捗を記録するユーザーキャッシュエントリの更新頻度を指定します。 ファイルサイズに対するパーセンテージ、あるいはファイルサイズで指定します。 サイズを指定する場合は、最後に "k"、"m" あるいは "g" を指定することでそれぞれキロバイト、メガバイト、ギガバイトを指定できます (大文字小文字は区別しません)。 0 を指定すると、可能な限り進捗を更新するようにします。 これは、アップロードの速度を低下させてしまいます。

apc.rfc1867_ttl bool

rfc1867 エントリの TTL。

apc.localcache boolean

これは、ロックが不要なローカルプロセスのシャドウキャッシュを有効にします。 これにより、キャッシュが書き込まれる際のロックの競合を軽減します。

apc.localcache.size integer

ローカルプロセスのシャドウキャッシュの大きさ。 ある程度大きなな値を設定しておく必要があります。目安としては apc.num_files_hint の半分程度となります。

apc.coredump_unmap boolean

APC で SIGSEGV のようなシグナルを捕捉し、 シグナルの発生時にコアファイルを書き出せるようにします。 シグナルを受け取ると、 APC は共有メモリセグメントの割り当てを解除し、 コアファイルにそれが書き出されないようにします。 この設定を行うと、 APC の共有メモリセグメントを大きめに設定しているときに 致命的なシグナルを受け取った場合のシステムの安定性が向上します。

警告

この機能には危険性があります。 致命的なシグナルのハンドラで共有メモリセグメントの割り当てを解除しようとすると、 発生したエラーによっては未定義の振る舞いを起こす可能性があります。

注意:

カーネルによってはコアダンプファイルの生成時に共有メモリを無視する機能を持つものもありますが、 そのような実装は、たとえば Apache のスコアボードのような 重要な共有メモリセグメントも無視してしまう可能性があります。

apc.stat_ctime integer

ctime による検証を行えば、svn や rsync といったプログラムが引き起こす問題を回避することができます。 直近の状態から inode が変わっていないことを確実に確かめられるからです。 APC は、通常は mtime のみしか確認しません。

apc.canonicalize bool

オンにすると、no-stat モードのときに相対パスを正規化します。 これを設定すると、ストリームラッパー経由でインクルードしたファイルは キャッシュできなくなります。realpath() はストリームラッパーをサポートしていないからです。

apc.preload_path string

apc.use_request_time bool

SAPI リクエストの開始時刻を TTL に使用します。

apc.file_md5 bool

ファイルの md5 ハッシュを記録します。

apc.lazy_functions integer

関数の lazy loading を有効にします。

apc.lazy_classes integer

クラスの lazy loading を有効にします。

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

APC_BIN_VERIFY_CRC32 (integer)
APC_BIN_VERIFY_MD5 (integer)
APC_ITER_ALL (integer)
APC_ITER_ATIME (integer)
APC_ITER_CTIME (integer)
APC_ITER_DEVICE (integer)
APC_ITER_DTIME (integer)
APC_ITER_FILENAME (integer)
APC_ITER_INODE (integer)
APC_ITER_KEY (integer)
APC_ITER_MD5 (integer)
APC_ITER_MEM_SIZE (integer)
APC_ITER_MTIME (integer)
APC_ITER_NONE (integer)
APC_ITER_NUM_HITS (integer)
APC_ITER_REFCOUNT (integer)
APC_ITER_TTL (integer)
APC_ITER_TYPE (integer)
APC_ITER_VALUE (integer)
APC_LIST_ACTIVE (integer)
APC_LIST_DELETED (integer)

APC 関数

apc_add

(PECL apc >= 3.0.13)

apc_add — 新規の変数をデータ領域にキャッシュする

説明

bool apc_add ( string $key [, mixed $var [, int $ttl = 0 ]] )
array apc_add ( array $values [, mixed $unused [, int $ttl = 0 ]] )

まだ保存されていない場合にのみ、変数をデータ領域にキャッシュします。

注意: PHP の他の多くの仕組みと異なり、apc_add() を用いて格納された変数はリクエストを超えて （その値がキャッシュから取り除かれるまで）持続します。

パラメータ

key

この名前を用いて変数を格納します。key は キャッシュ内で一意です。そのため、apc_add() を使用して同一の key で新しい値を格納しようとしても、それは保存されません。 かわりに FALSE が返されます (これが、apc_add() と apc_store() の唯一の相違点です)。

var

格納する変数。

ttl

有効期間。var は、キャッシュに ttl 秒間だけ格納されます。 ttl が経過すると、格納されている変数は （次のリクエスト時に）キャッシュから削除されます。 ttl が指定されていない（あるいは ttl が 0 の場合）は、 キャッシュから手動で削除される・あるいはキャッシュに存在できなくなる （clear, restart など）まで値が持続します。

values

名前をキー、変数を値に指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。 二番目の構文は、エラーになったキーを含む配列を返します。

例

例1 apc_add() の例

<?php
$bar = 'BAR';
apc_add('foo', $bar);
var_dump(apc_fetch('foo'));
echo "\n";
$bar = 'NEVER GETS SET';
apc_add('foo', $bar);
var_dump(apc_fetch('foo'));
echo "\n";
?>

上の例の出力は以下となります。

string(3) "BAR"
string(3) "BAR"

参考

  • apc_store() - 変数をデータ領域にキャッシュする
  • apc_fetch() - 格納されている変数をキャッシュから取得する
  • apc_delete() - 格納されている変数をキャッシュから取り除く

apc_bin_dump

(PECL apc >= 3.1.4)

apc_bin_dump — 指定したファイルおよびユーザー変数のバイナリダンプを取得する

説明

string apc_bin_dump ([ array $files [, array $user_vars ]] )

指定したファイルおよびユーザー変数のバイナリダンプを APC キャッシュから返します。 files や user_vars に NULL を指定すると、全エントリを表します。 一方、array() を渡すと何もダンプしません。

パラメータ

files

ファイル。NULL を渡すと全エントリを意味し、 array() を渡すと何もダンプしません。

user_vars

ユーザー変数。NULL を渡すと全エントリを意味し、 array() を渡すと何もダンプしません。

返り値

指定したファイルおよびユーザー変数のバイナリダンプを APC キャッシュから返します。 APC が有効でない場合は FALSE、未知のエラーが発生した場合は NULL を返します。

参考

  • apc_bin_dumpfile() - キャッシュされたファイルやユーザー変数のバイナリダンプをファイルに出力する
  • apc_bin_load() - バイナリダンプを APC のファイル/ユーザーキャッシュに読み込む

apc_bin_dumpfile

(PECL apc >= 3.1.4)

apc_bin_dumpfile — キャッシュされたファイルやユーザー変数のバイナリダンプをファイルに出力する

説明

int apc_bin_dumpfile ( array $files , array $user_vars , string $filename [, int $flags = 0 [, resource $context ]] )

キャッシュされたファイルやユーザー変数のバイナリダンプを APC キャッシュから取得し、指定したファイルに出力します。

パラメータ

files

The file names being dumped.

user_vars

The user variables being dumped.

filename

The filename where the dump is being saved.

flags

Flags passed to the filename stream. See the file_put_contents() documentation for details.

context

The context passed to the filename stream. See the file_put_contents() documentation for details.

返り値

The number of bytes written to the file, otherwise FALSE if APC is not enabled, filename is an invalid file name, filename can't be opened, the file dump can't be completed (e.g., the hard drive is out of disk space), or an unknown error was encountered.

参考

  • apc_bin_dump() - 指定したファイルおよびユーザー変数のバイナリダンプを取得する
  • apc_bin_load() - バイナリダンプを APC のファイル/ユーザーキャッシュに読み込む

apc_bin_load

(PECL apc >= 3.1.4)

apc_bin_load — バイナリダンプを APC のファイル/ユーザーキャッシュに読み込む

説明

bool apc_bin_load ( string $data [, int $flags = 0 ] )

指定したバイナリダンプを APC のファイル/ユーザーキャッシュに読み込みます。

パラメータ

data

読み込むバイナリダンプ。通常は apc_bin_dump() で出力したもの。

flags

APC_BIN_VERIFY_CRC32、APC_BIN_VERIFY_MD5 あるいはその両方。

返り値

バイナリダンプの読み込みに成功した場合に TRUE、 それ以外の場合に FALSE を返します。FALSE が返される理由には、 APC が有効でない場合や data が有効な APC バイナリダンプでない (予期せぬサイズなど) 場合などがあります。

例

例1 apc_bin_load() の例

<?php
$data = apc_bin_dump(NULL, NULL);
apc_bin_load($data, APC_BIN_VERIFY_MD5 | APC_BIN_VERIFY_CRC32);
?>

参考

  • apc_bin_dump() - 指定したファイルおよびユーザー変数のバイナリダンプを取得する
  • apc_bin_loadfile() - バイナリダンプをファイルから APC のファイル/ユーザーキャッシュに読み込む

apc_bin_loadfile

(PECL apc >= 3.1.4)

apc_bin_loadfile — バイナリダンプをファイルから APC のファイル/ユーザーキャッシュに読み込む

説明

bool apc_bin_loadfile ( string $filename [, resource $context [, int $flags ]] )

指定したファイルから、バイナリダンプを APC のファイル/ユーザーキャッシュに読み込みます。

パラメータ

filename

ダンプを含むファイルの名前。通常は apc_bin_dumpfile() で出力したもの。

context

ファイルのコンテキスト。

flags

APC_BIN_VERIFY_CRC32、APC_BIN_VERIFY_MD5 あるいはその両方。

返り値

バイナリダンプの読み込みに成功した場合に TRUE、 それ以外の場合に FALSE を返します。FALSE が返される理由には、 APC が有効でない場合や filename が無効なファイルの場合、空のファイルの場合、 filename のオープンに失敗した場合、 ダンプが不完全な場合、そして data が有効な APC バイナリダンプでない (予期せぬサイズなど) 場合などがあります。

参考

  • apc_bin_dumpfile() - キャッシュされたファイルやユーザー変数のバイナリダンプをファイルに出力する
  • apc_bin_load() - バイナリダンプを APC のファイル/ユーザーキャッシュに読み込む

apc_cache_info

(PECL apc >= 2.0.0)

apc_cache_info — APC のデータから、キャッシュされた情報を取得する

説明

array apc_cache_info ([ string $cache_type [, bool $limited = false ]] )

APC のデータから、キャッシュされた情報およびメタデータを取得します。

パラメータ

cache_type

cache_type が "user" の場合はユーザーキャッシュの情報を返します。

cache_type が "filehits" の場合は、現在のリクエストにおいて バイトコードキャッシュから提供したファイルがどれなのかについての情報を返します。 この機能を使用するには、コンパイル時に --enable-filehits を指定する必要があります。

cache_type に無効な値を指定したり、 値を指定しなかったりした場合は、 システムキャッシュ (キャッシュされたファイル) の情報を返します。

limited

limited が TRUE の場合は、 返り値にキャッシュエントリの個々の一覧が含まれません。 これは、統計情報の収集時に呼び出しを最適化したい場合などに有用です。

返り値

キャッシュされたデータ（およびメタデータ）の配列を返します。 失敗した場合に FALSE を返します

注意: もし APC キャッシュのデータを取得できなかった場合、 apc_cache_info() は警告を発生します。これが起こるのは、 一般的には APC が有効になっていない場合などです。

変更履歴

バージョン 説明
3.0.11 パラメータ limited が追加されました。
3.0.16 "filehits" オプションが cache_type パラメータに追加されました。

例

例1 apc_cache_info() の例

<?php
print_r(apc_cache_info());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [num_slots] => 2000
    [ttl] => 0
    [num_hits] => 9
    [num_misses] => 3
    [start_time] => 1123958803
    [cache_list] => Array
        (
            [0] => Array
                (
                    [filename] => /path/to/apc_test.php
                    [device] => 29954
                    [inode] => 1130511
                    [type] => file
                    [num_hits] => 1
                    [mtime] => 1123960686
                    [creation_time] => 1123960696
                    [deletion_time] => 0
                    [access_time] => 1123962864
                    [ref_count] => 1
                    [mem_size] => 677
                )
            [1] => Array (...iterates for each cached file)
)

参考

apc_cas

(PECL apc >= 3.1.1)

apc_cas — 古い値を新しい値に更新する

説明

bool apc_cas ( string $key , int $old , int $new )

apc_cas() は、既に保存されている整数値が old パラメータにマッチする値のときに、それを new パラメータの値に更新します。

パラメータ

key

更新する値のキー。

old

古い値 (現在保存されている値)。

new

新しく更新したい値。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 apc_cas() の例

<?php
apc_store('foobar', 2);
echo '$foobar = 2', PHP_EOL;
echo '$foobar == 1 ? 2 : 1 = ', (apc_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
echo '$foobar == 2 ? 1 : 2 = ', (apc_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;

echo '$foobar = ', apc_fetch('foobar'), PHP_EOL;

echo '$f__bar == 1 ? 2 : 1 = ', (apc_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;

apc_store('perfection', 'xyz');
echo '$perfection == 2 ? 1 : 2 = ', (apc_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;

echo '$foobar = ', apc_fetch('foobar'), PHP_EOL;
?>

上の例の出力は、 たとえば以下のようになります。

$foobar = 2
$foobar == 1 ? 2 : 1 = fail
$foobar == 2 ? 1 : 2 = ok
$foobar = 1
$f__bar == 1 ? 2 : 1 = fail
$perfection == 2 ? 1 : 2 = epic fail
$foobar = 1

参考

  • apc_dec() - 保存した数値を減らす
  • apc_store() - 変数をデータ領域にキャッシュする

apc_clear_cache

(PECL apc >= 2.0.0)

apc_clear_cache — APC キャッシュをクリアする

説明

bool apc_clear_cache ([ string $cache_type ] )

ユーザー/システム キャッシュをクリアします。

パラメータ

cache_type

cache_type が "user" の場合はユーザーキャッシュがクリアされます。 それ以外の場合はシステムキャッシュ (キャッシュされたファイル) がクリアされます。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

  • apc_cache_info() - APC のデータから、キャッシュされた情報を取得する

apc_compile_file

(PECL apc >= 3.0.13)

apc_compile_file — ファイルをバイトコードキャッシュに保存し、すべてのフィルタをバイパスする

説明

mixed apc_compile_file ( string $filename [, bool $atomic = true ] )

ファイルをバイトコードキャッシュに保存し、すべてのフィルタをバイパスします。

パラメータ

filename

コンパイルし、バイトコードキャッシュに保存したい PHP ファイルへの完全パスあるいは相対パス。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

  • apc_bin_dumpfile() - キャッシュされたファイルやユーザー変数のバイナリダンプをファイルに出力する
  • apc_bin_loadfile() - バイナリダンプをファイルから APC のファイル/ユーザーキャッシュに読み込む

apc_dec

(PECL apc >= 3.1.1)

apc_dec — 保存した数値を減らす

説明

int apc_dec ( string $key [, int $step = 1 [, bool &$success ]] )

保存した整数値を減らします。

パラメータ

key

減らしたい値のキー。

step

減らしたい数。

success

この参照渡しの変数に、成功したか失敗したかの結果が格納されます。

返り値

成功した場合に key の現在値を返します。 失敗した場合に FALSE を返します

例

例1 apc_dec() の例

<?php
echo "Let's do something with success", PHP_EOL;

apc_store('anumber', 42);

echo apc_fetch('anumber'), PHP_EOL;

echo apc_dec('anumber'), PHP_EOL;
echo apc_dec('anumber', 10), PHP_EOL;
echo apc_dec('anumber', 10, $success), PHP_EOL;

var_dump($success);

echo "Now, let's fail", PHP_EOL, PHP_EOL;

apc_store('astring', 'foo');

$ret = apc_dec('astring', 1, $fail);

var_dump($ret);
var_dump($fail);
?>

上の例の出力は、 たとえば以下のようになります。

Let's do something with success
42
41
31
21
bool(true)

Now, let's fail
bool(false)
bool(false)

参考

apc_define_constants

(PECL apc >= 3.0.0)

apc_define_constants — 定数の組を定義し、それを取得あるいは一括定義する

説明

bool apc_define_constants ( string $key , array $constants [, bool $case_sensitive = true ] )

ご存知のとおり、define() は非常に遅いです。 APC を使用する主な利点はスクリプト/アプリケーションのパフォーマンスの改善なので、 大量の定数を定義する手順を合理化するために、この仕組みが提供されています。 しかし、この関数は期待通りの動作をしません。

よりよい解決策として、PECL の » hidef 拡張モジュールを試してみましょう。

注意: （キャッシュ全体をクリアすることなく）格納されている定数を削除するには、 constants に空の配列を渡します。そうすれば、 そこに格納されていた値は事実上削除されます。

パラメータ

key

key は、格納される定数群の名前を表します。 この key は、格納されている定数を apc_load_constants() で取得するために使用されます。

constants

constant_name => value 形式の連想配列。 constant_name は、一般の 定数 の命名規則に従う 必要があります。 value は、スカラ値でなければ なりません。

case_sensitive

デフォルトでは、定数名の大文字・小文字は区別されます。すなわち、 CONSTANT と Constant は別の値を表します。このパラメータを FALSE にすると、 定数名の大文字・小文字は区別されなくなります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 apc_define_constants() の例

<?php
$constants = array(
    'ONE'   => 1,
    'TWO'   => 2,
    'THREE' => 3,
);
apc_define_constants('numbers', $constants);
echo ONE, TWO, THREE;
?>

上の例の出力は以下となります。

123

参考

apc_delete_file

(PECL apc >= 3.1.1)

apc_delete_file — ファイルを opcode キャッシュから削除する

説明

mixed apc_delete_file ( mixed $keys )

指定したファイルを opcode キャッシュから削除します。

パラメータ

keys

削除したいファイル。文字列、文字列の配列、あるいは APCIterator オブジェクトで指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。 keys が配列なら、 成功した場合は空の配列を返します。失敗した場合は失敗したファイルを含む配列を返します。

例

例1 apc_delete_file() の例

<?php
$filename = 'file.php';

if (apc_compile_file($filename)) {

    if (apc_delete_file($filename)) {
        echo "Successfully deleted file $filename from APC cache.", PHP_EOL;
    }
}

if (apc_compile_file($filename)) {

    if ($good = apc_delete_file(array($filename, 'donotexist.php'))) {
        var_dump($good);
    }
}

$bad = apc_delete_file('donotexist.php');
var_dump($bad);
?>

上の例の出力は、 たとえば以下のようになります。

Successfully deleted file file.php from APC cache.
[Mon May 24 09:30:33 2010] [apc-warning] Could not stat file donotexist.php, unable to delete from cache. in /tmp/test.php on line 13.
array(1) {
  [0]=>
  string(14) "donotexist.php"
}
[Mon May 24 09:30:33 2010] [apc-warning] Could not stat file donotexist.php, unable to delete from cache. in /tmp/test.php on line 18.
bool(false)

参考

apc_delete

(PECL apc >= 3.0.0)

apc_delete — 格納されている変数をキャッシュから取り除く

説明

mixed apc_delete ( string $key )

格納されている変数をキャッシュから取り除きます。

パラメータ

key

（apc_store() を用いて）値を格納する際に 使用された key 。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 apc_delete() の例

<?php
$bar = 'BAR';
apc_store('foo', $bar);
apc_delete('foo');
// もちろん、このような使い方は無意味
?>

参考

  • apc_store() - 変数をデータ領域にキャッシュする
  • apc_fetch() - 格納されている変数をキャッシュから取得する

apc_exists

(PECL apc >= 3.1.4)

apc_exists — APC キーが存在するかどうかを調べる

説明

mixed apc_exists ( mixed $keys )

指定した APC キーが存在するかどうかを調べます。

パラメータ

keys

キーを含む文字列、あるいは文字列の配列。

返り値

キーが存在する場合に TRUE、それ以外の場合に FALSE を返します。 keys に配列を渡したときは、 存在するキーをすべて含む配列を返します。 どれも存在しない場合は空の配列を返します。

例

例1 apc_exists() の例

<?php
$fruit  = 'apple';
$veggie = 'carrot';

apc_store('foo', $fruit);
apc_store('bar', $veggie);

if (apc_exists('foo')) {
    echo "Foo exists: ";
    echo apc_fetch('foo');
} else {
    echo "Foo does not exist";
}

echo PHP_EOL;
if (apc_exists('baz')) {
    echo "Baz exists.";
} else {
    echo "Baz does not exist";
}

echo PHP_EOL;

$ret = apc_exists(array('foo', 'donotexist', 'bar'));
var_dump($ret);

?>

上の例の出力は、 たとえば以下のようになります。

Foo exists: apple
Baz does not exist
array(2) {
  ["foo"]=>
  bool(true)
  ["bar"]=>
  bool(true)
}

参考

  • apc_cache_info() - APC のデータから、キャッシュされた情報を取得する
  • apc_fetch() - 格納されている変数をキャッシュから取得する

apc_fetch

(PECL apc >= 3.0.0)

apc_fetch — 格納されている変数をキャッシュから取得する

説明

mixed apc_fetch ( mixed $key [, bool &$success ] )

格納されている変数をキャッシュから取得します。

パラメータ

key

(apc_store() を用いて) 値を格納する際に使用された key。 配列を渡した場合は、各要素について取得した値を返します。

success

成功したばあいに TRUE、失敗した際に FALSE が設定されます。

返り値

成功した場合に格納されていた変数 (あるいは配列)、失敗した場合に FALSE を返します。

例

例1 apc_fetch() の例

<?php
$bar = 'BAR';
apc_store('foo', $bar);
var_dump(apc_fetch('foo'));
?>

上の例の出力は以下となります。

string(3) "BAR"

変更履歴

バージョン 説明
3.0.17 success パラメータが追加されました。

参考

apc_inc

(PECL apc >= 3.1.1)

apc_inc — 保存した数値を増やす

説明

int apc_inc ( string $key [, int $step = 1 [, bool &$success ]] )

保存した整数値を増やします。

パラメータ

key

増やしたい値のキー。

step

増やしたい数。

success

この参照渡しの変数に、成功したか失敗したかの結果が格納されます。

返り値

成功した場合に key の現在値を返します。 失敗した場合に FALSE を返します

例

例1 apc_inc() の例

<?php
echo "Let's do something with success", PHP_EOL;

apc_store('anumber', 42);

echo apc_fetch('anumber'), PHP_EOL;

echo apc_inc('anumber'), PHP_EOL;
echo apc_inc('anumber', 10), PHP_EOL;
echo apc_inc('anumber', 10, $success), PHP_EOL;

var_dump($success);

echo "Now, let's fail", PHP_EOL, PHP_EOL;

apc_store('astring', 'foo');

$ret = apc_inc('astring', 1, $fail);

var_dump($ret);
var_dump($fail);
?>

上の例の出力は、 たとえば以下のようになります。

42
43
53
63
bool(true)
Now, let's fail

bool(false)
bool(false)

参考

apc_load_constants

(PECL apc >= 3.0.0)

apc_load_constants — 定数群をキャッシュから読み込む

説明

bool apc_load_constants ( string $key [, bool $case_sensitive = true ] )

定数群をキャッシュから読み込みます。

パラメータ

key

取得したい定数群（apc_define_constants() を使用して格納されたもの）。

case_sensitive

デフォルトでは、定数名の大文字・小文字は区別されます。すなわち、 CONSTANT と Constant は別の値を表します。このパラメータを FALSE にすると、 定数名の大文字・小文字は区別されなくなります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 apc_load_constants() の例

<?php
$constants = array(
    'ONE'   => 1,
    'TWO'   => 2,
    'THREE' => 3,
);
apc_define_constants('numbers', $constants);
apc_load_constants('numbers');
echo ONE, TWO, THREE;
?>

上の例の出力は以下となります。

123

参考

apc_sma_info

(PECL apc >= 2.0.0)

apc_sma_info — APC の共有メモリ割り当てに関する情報を取得する

説明

array apc_sma_info ([ bool $limited = false ] )

APC の共有メモリ割り当てに関する情報を取得します。

パラメータ

limited

FALSE (デフォルト) を設定すると、apc_sma_info() は各セグメントの詳細な情報を返します。

返り値

共有メモリ割り当てデータの配列を返します。失敗した場合は FALSE を返します。

例

例1 apc_sma_info() の例

<?php
print_r(apc_sma_info());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [num_seg] => 1
    [seg_size] => 31457280
    [avail_mem] => 31448408
    [block_lists] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [size] => 31448408
                            [offset] => 8864
                        )

                )

        )

)

apc_store

(PECL apc >= 3.0.0)

apc_store — 変数をデータ領域にキャッシュする

説明

bool apc_store ( string $key , mixed $var [, int $ttl = 0 ] )
array apc_store ( array $values [, mixed $unused [, int $ttl = 0 ]] )

変数をデータ領域にキャッシュします。

注意: PHP の他の多くの仕組みと異なり、apc_store() を用いて格納された変数はリクエストを超えて （その値がキャッシュから取り除かれるまで）持続します。

パラメータ

key

この名前を用いて変数を格納します。key は キャッシュ内で一意です。そのため、同一の key で新しい値を格納すると、元の値は上書きされます。

var

格納する変数。

ttl

有効期間。var は、キャッシュに ttl 秒間だけ格納されます。 ttl が経過すると、格納されている変数は （次のリクエスト時に）キャッシュから削除されます。 ttl が指定されていない（あるいは ttl が 0 の場合）は、 キャッシュから手動で削除される・あるいはキャッシュに存在できなくなる （clear, restart など）まで値が持続します。

values

名前をキー、変数を値に指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。 二番目の構文は、エラーになったキーを含む配列を返します。

例

例1 A apc_store() の例

<?php
$bar = 'BAR';
apc_store('foo', $bar);
var_dump(apc_fetch('foo'));
?>

上の例の出力は以下となります。

string(3) "BAR"

参考

  • apc_add() - 新規の変数をデータ領域にキャッシュする
  • apc_fetch() - 格納されている変数をキャッシュから取得する
  • apc_delete() - 格納されている変数をキャッシュから取り除く

目次

  • apc_add — 新規の変数をデータ領域にキャッシュする
  • apc_bin_dump — 指定したファイルおよびユーザー変数のバイナリダンプを取得する
  • apc_bin_dumpfile — キャッシュされたファイルやユーザー変数のバイナリダンプをファイルに出力する
  • apc_bin_load — バイナリダンプを APC のファイル/ユーザーキャッシュに読み込む
  • apc_bin_loadfile — バイナリダンプをファイルから APC のファイル/ユーザーキャッシュに読み込む
  • apc_cache_info — APC のデータから、キャッシュされた情報を取得する
  • apc_cas — 古い値を新しい値に更新する
  • apc_clear_cache — APC キャッシュをクリアする
  • apc_compile_file — ファイルをバイトコードキャッシュに保存し、すべてのフィルタをバイパスする
  • apc_dec — 保存した数値を減らす
  • apc_define_constants — 定数の組を定義し、それを取得あるいは一括定義する
  • apc_delete_file — ファイルを opcode キャッシュから削除する
  • apc_delete — 格納されている変数をキャッシュから取り除く
  • apc_exists — APC キーが存在するかどうかを調べる
  • apc_fetch — 格納されている変数をキャッシュから取得する
  • apc_inc — 保存した数値を増やす
  • apc_load_constants — 定数群をキャッシュから読み込む
  • apc_sma_info — APC の共有メモリ割り当てに関する情報を取得する
  • apc_store — 変数をデータ領域にキャッシュする

APCIterator クラス

(PECL apc >= 3.1.1)

導入

APCIterator クラスを使うと、巨大な APC キャッシュの反復処理を容易に行えます。 巨大なキャッシュを順を追って処理し、 ロックインスタンス単位で決まった数のエントリを取得することができます。 そのため、キャッシュ全体を抱え込んで 100 件 (デフォルト) のエントリを取り込むのではなく、 キャッシュのロックを解放して他の操作ができる状態にすることが可能です。 また、正規表現によるマッチングは C 言語レベルで行われるのでより効率的です。

クラス概要

APCIterator implements Iterator , Traversable {
/* Methods */
public __construct ( string $cache [, mixed $search = null [, int $format [, int $chunk_size = 100 [, int $list ]]]] )
public mixed current ( void )
public int getTotalCount ( void )
public int getTotalHits ( void )
public int getTotalSize ( void )
public string key ( void )
public void next ( void )
public void rewind ( void )
public void valid ( void )
}

APCIterator::__construct

(PECL apc >= 3.1.1)

APCIterator::__construct — APCIterator イテレータオブジェクトを作成する

説明

public APCIterator::__construct ( string $cache [, mixed $search = null [, int $format [, int $chunk_size = 100 [, int $list ]]]] )

APCIterator オブジェクトを作成します。

パラメータ

cache

キャッシュの形式。user あるいは file となります。

search

APC のキーの名前にマッチする PCRE 正規表現。 単一の正規表現の場合は文字列で、複数の正規表現の場合は配列で指定します。 NULL を渡すと、検索をスキップします。

format

希望する書式。 APC_ITER_* 定数の組み合わせで指定します。

chunk_size

チャンクサイズ。0 より大きい値でなければなりません。 デフォルト値は 100 です。

list

一覧にする形式。APC_LIST_ACTIVE あるいは APC_LIST_DELETED を渡します。

返り値

成功した場合に APCIterator オブジェクト、 失敗した場合に NULL を返します。

例

例1 APCIterator::__construct() の例

<?php
foreach (new APCIterator('user', '/^counter\./') as $counter) {
    echo "$counter[key]: $counter[value]\n";
    apc_dec($counter['key'], $counter['value']);
}
?>

参考

  • apc_exists() - APC キーが存在するかどうかを調べる
  • apc_cache_info() - APC のデータから、キャッシュされた情報を取得する

APCIterator::current

(PECL apc >= 3.1.1)

APCIterator::current — 現在の項目を取得する

説明

public mixed APCIterator::current ( void )

APCIterator から現在の項目を取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に現在の項目を返します。 もう項目が失敗した場合や取得に失敗した場合は FALSE を返します。

参考

APCIterator::getTotalCount

(PECL apc >= 3.1.1)

APCIterator::getTotalCount — 総数を取得する

説明

public int APCIterator::getTotalCount ( void )

総数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

総数を返します。

参考

APCIterator::getTotalHits

(PECL apc >= 3.1.1)

APCIterator::getTotalHits — キャッシュヒットの総数を取得する

説明

public int APCIterator::getTotalHits ( void )

キャッシュヒットの総数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合にヒット数、失敗した場合に FALSE を返します。

参考

APCIterator::getTotalSize

(PECL apc >= 3.1.1)

APCIterator::getTotalSize — キャッシュのサイズの合計を取得する

説明

public int APCIterator::getTotalSize ( void )

キャッシュのサイズの合計を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

キャッシュのサイズの合計を返します。

参考

APCIterator::key

(PECL apc >= 3.1.1)

APCIterator::key — イテレータのキーを取得する

説明

public string APCIterator::key ( void )

現在のイテレータのキーを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合にキー、失敗した場合に FALSE を返します。

参考

APCIterator::next

(PECL apc >= 3.1.1)

APCIterator::next — ポインタを次の項目に移動させる

説明

public void APCIterator::next ( void )

イテレータのポインタを次の要素に移動させます。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

APCIterator::rewind

(PECL apc >= 3.1.1)

APCIterator::rewind — イテレータを巻き戻す

説明

public void APCIterator::rewind ( void )

イテレータを最初の要素に巻き戻します。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

APCIterator::valid

(PECL apc >= 3.1.1)

APCIterator::valid — 現在位置が有効かどうかを調べる

説明

public void APCIterator::valid ( void )

イテレータの現在位置が有効かどうかを調べます。

パラメータ

この関数にはパラメータはありません。

返り値

イテレータの現在位置が有効な場合に TRUE、それ以外の場合に FALSE を返します。

参考

目次

Advanced PHP debugger

導入

APD は進化した PHP デバッガです。PHP コードのプロファイリングやデバッグの機能を提供すること、 また完全なスタックトレースを出力する機能を提供することを目的として作成されています。 APD は対話形式のデバッグもサポートしていますが、 デフォルトではデータをトレースファイルに書き出すようになっています。 また、さまざまなレベルの情報 (関数のコール・渡された引数・時間などを含む) をイベント発生時に記録することができ、 それを個々のスクリプト単位で有効にしたり無効にしたりできます。

警告

APD は Zend 拡張モジュールで、PHP 内部関数のコール方法に手を加えます。 そのため、他の Zend 拡張モジュール (たとえば Zend Optimizer など) との相性に注意が必要です。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/apd

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

INI ファイルに以下の行を追加します。 

zend_extension = /absolute/path/to/apd.so
apd.dumpdir = /absolute/path/to/trace/directory
apd.statement_tracing = 0

PHP のビルド状況によって、 zend_extension ディレクティブは以下のうちのいずれかひとつとなります。 

zend_extension              (非 ZTS, 非 debug ビルド)
zend_extension_ts           (   ZTS, 非 debug ビルド)
zend_extension_debug        (非 ZTS,    debug ビルド)
zend_extension_debug_ts     (   ZTS,    debug ビルド)

Win32 でのビルド

Windows で APD をビルドするには、http://php.net/ で述べられているような PHP コンパイル環境が必要です。 -- 基本的には、Microsoft Visual C++・ win32build.zip・bison/flex・そしてそれらをうまく動かすためのちょっとしたコツが必要になります。 また adp.dsp の改行コードは必ず DOS 形式にしてください。 Unix 形式の改行コードだと、Microsoft Visual C++ に文句を言われます。

実行時設定

php.ini の設定により動作が変化します。

APD の設定オプション
名前 デフォルト 変更可能 変更履歴
apd.dumpdir NULL PHP_INI_ALL  
apd.statement_tracing "0" PHP_INI_ALL apd 0.9 以降で利用可能です。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

apd.dumpdir string

APD がプロファイルのダンプファイルを書き出すディレクトリを設定します。 絶対パス・相対パスのどちらも指定可能です。

apd_set_pprof_trace() へ引数を渡すことで、 指定した以外の場所に書き出すことも可能です。

apd.statement_tracing boolean

行単位のトレースをするかしないかを設定します。これを on (1) にすると、アプリケーションのパフォーマンスに衝撃的な影響を与えます。

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

APD の定数
定数 値 説明
FUNCTION_TRACE (integer) 1  
ARGS_TRACE (integer) 2  
ASSIGNMENT_TRACE (integer) 4  
STATEMENT_TRACE (integer) 8  
MEMORY_TRACE (integer) 16  
TIMING_TRACE (integer) 32  
SUMMARY_TRACE (integer) 64  
ERROR_TRACE (integer) 128  
PROF_TRACE (integer) 256  
APD_VERSION (string) 例: 1.0.2-dev  

例

目次

スクリプト中で PHP-APD を使用する方法

  1. トレースを開始するには、PHP スクリプトの最初の行で apd_set_pprof_trace() 関数をコールします。

    <?php
    apd_set_pprof_trace    ();
    ?>

    この行はスクリプト内のどの場所にでも挿入可能ですが、 もしスクリプトの最初からトレースを始めなければ、 あなたをパフォーマンスのボトルネックに導いてくれるかもしれないデータを捨てることになってしまいます。

  2. さあ、スクリプトを実行しましょう。ダンプ結果は apd.dumpdir/pprof_pid.ext に出力されます。

    ヒント

    CGI 版の PHP を使用している場合は、apd が正しく動作するように '-e' フラグつきで実行し、拡張情報を有効にしてください。たとえば php -e -f script.php のように実行します。

  3. プロファイルデータを整形して表示するには、お好みの並べ替えオプション・ 表示オプションを指定して pprofp コマンドを実行してください。 整形された出力は以下のようになります。 

    bash-2.05b$ pprofp -R /tmp/pprof.22141.0

Trace for /home/dan/testapd.php
Total Elapsed Time = 0.00
Total System Time  = 0.00
Total User Time    = 0.00


Real         User        System             secs/    cumm
%Time (excl/cumm)  (excl/cumm)  (excl/cumm) Calls    call    s/call  Memory Usage Name
--------------------------------------------------------------------------------------
100.0 0.00 0.00  0.00 0.00  0.00 0.00     1  0.0000   0.0009            0 main
56.9 0.00 0.00  0.00 0.00  0.00 0.00     1  0.0005   0.0005            0 apd_set_pprof_trace
28.0 0.00 0.00  0.00 0.00  0.00 0.00    10  0.0000   0.0000            0 preg_replace
14.3 0.00 0.00  0.00 0.00  0.00 0.00    10  0.0000   0.0000            0 str_replace

    この例で使われている -R オプションは、 その関数を実行するのにかかった時間の順でプロファイルテーブルを並べ替えます。 "cumm call" 列には個々の関数が何回コールされたか、 そして "s/call" 列には 1 回のコールあたりの平均所要時間が表示されます。

  4. KCacheGrind にインポートできる形式のファイルを作成するには、 pprof2calltree コマンドを実行してください。

APD 関数

連絡先の情報

コメント・バグフィックス・機能拡張・あるいは開発を手伝いたいなどの場合は、 メールを » apd@mail.communityconnect.com に送ってください。大歓迎します。

apd_breakpoint

(PECL apd >= 0.2)

apd_breakpoint — インタプリタの処理を停止し、ソケットからの CR を待つ

説明

bool apd_breakpoint ( int $debug_level )

スクリプトの実行を停止し、接続しているソケットからの応答を待ち受ける ために使用します。プログラムのステップ実行を行うには、Enter キーを押す (空行を送る) あるいは実行したい PHP コマンドを入力します。

パラメータ

debug_level

XXX_TRACE 定数の組み合わせによる整数値。

MEMORY_TRACE を用いることは推奨しません。 これは非常に低速で、またあまり正確ではないようだからです。 ASSIGNMENT_TRACE は、まだ実装されていません。

すべての機能 (TIMING, FUNCTIONS, ARGS SUMMARY (strace -c のようなもの)) のトレースを有効にするには、値 99 を指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 tcplisten を使用した典型的なセッション

bash#tcplisten localhost 7777

APD - Advanced PHP Debugger Trace File
---------------------------------------------------------------------------
Process Pid (6118)
Trace Begun at Sun Mar 10 23:13:12 2002
---------------------------------------------------------------------------
(  0.000000): apd_set_session_trace called at /home/alan/Projects/project2/test. 
php:5
(  0.074824): apd_set_session_trace_socket() at /home/alan/Projects/project2/tes 
t.php:5 returned.  Elapsed (0.074824)
(  0.074918): apd_breakpoint() /home/alan/Projects/project2/test.php:7
              ++ argv[0] $(??) = 9
apd_breakpoint() at /home/alan/Projects/project2/test.php:7 returned.  Elapsed ( 
-2089521468.1073275368)
>\n 
statement: /home/alan/Projects/project2/test.php:8
>\n 
statement: /home/alan/Projects/project2/test.php:8
>\n 
statement: /home/alan/Projects/project2/test.php:10
>apd_echo($i);
EXEC: apd_echo($i);
0
>apd_echo(serialize(apd_get_active_symbols()));
EXEC:  apd_echo(serialize(apd_get_active_symbols()));
a:47:{i:0;s:4:"PWD";i:1;s:10:"COLORFGBG";i:2;s:11:"XAUTHORITY";i:3;s:14:"
COLORTERM_BCE";i:4;s:9:"WINDOWID";i:5;s:14:"ETERM_VERSION";i:6;s:16:"SE
SSION_MANAGER";i:7;s:4:"PS1";i:8;s:11:"GDMSESSION";i:9;s:5:"USER";i:10;s:5:"
MAIL";i:11;s:7:"OLDPWD";i:12;s:5:"LANG";i:13;s:10:"COLORTERM";i:14;s:8:"DISP
LAY";i:15;s:8:"LOGNAME";i:16;s:6:"
>apd_echo(system('ls /home/mydir'));
........
>apd_continue(0);

apd_callstack

(PECL apd 0.2-0.4)

apd_callstack — 現在のコールスタックを配列で返す

説明

array apd_callstack ( void )

現在のコールスタックを配列形式で返します。

返り値

現在のコールスタックを含む配列を返します。

例

例1 apd_callstack() の例

<?php
print_r(apd_callstack());
?>

apd_clunk

(PECL apd 0.2-0.4)

apd_clunk — 警告とコールスタックをスローする

説明

void apd_clunk ( string $warning [, string $delimiter ] )

perl の Carp::cluck と同じように動作します。警告とコールバックをスローします。 デフォルトの行区切り文字は "<BR />\n" です。

パラメータ

warning

スローする警告。

delimiter

区切り文字。デフォルトは <BR />。

返り値

値を返しません。

例

例1 apd_clunk() の例

<?php
apd_clunk("Some Warning", "<br/>");
?>

参考

  • apd_croak() - エラーとコールスタックをスローし、終了する

apd_continue

(PECL apd >= 0.2)

apd_continue — インタプリタを再開する

説明

bool apd_continue ( int $debug_level )

インタプリタを再開するために、一般的にはソケット経由で送信します。

パラメータ

debug_level

XXX_TRACE 定数の組み合わせによる整数値。

MEMORY_TRACE を用いることは推奨しません。 これは非常に低速で、またあまり正確ではないようだからです。 ASSIGNMENT_TRACE は、まだ実装されていません。

すべての機能 (TIMING, FUNCTIONS, ARGS SUMMARY (strace -c のようなもの)) のトレースを有効にするには、値 99 を指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 apd_continue() の例

<?php
apd_continue(0);
?>

apd_croak

(PECL apd 0.2-0.4)

apd_croak — エラーとコールスタックをスローし、終了する

説明

void apd_croak ( string $warning [, string $delimiter ] )

perl の Carp::croak と同じように動作します。エラーとコールバックをスローし、 終了します。

パラメータ

warning

スローする警告。

delimiter

区切り文字。デフォルトは <BR />。

返り値

値を返しません。

例

例1 apd_croak() の例

<?php
apd_croak("Some Warning","<P>");
?>

参考

  • apd_clunk() - 警告とコールスタックをスローする

apd_dump_function_table

(Unknown)

apd_dump_function_table — 現在の関数テーブルを出力する

説明

void apd_dump_function_table ( void )

現在の関数テーブルを出力します。

返り値

値を返しません。

例

例1 apd_dump_function_table() の例

<?php
apd_dump_function_table();
?>

apd_dump_persistent_resources

(PECL apd 0.2-0.4)

apd_dump_persistent_resources — すべての持続的なリソースを配列で返す

説明

array apd_dump_persistent_resources ( void )

すべての持続的なリソースを配列で返します。

返り値

現在のコールスタックを含む配列を返します。

例

例1 apd_dump_persistent_resources() の例

<?php
print_r(apd_dump_persistent_resources());
?>

参考

apd_dump_regular_resources

(PECL apd 0.2-0.4)

apd_dump_regular_resources — 現在のすべての一般リソースを配列で返す

説明

array apd_dump_regular_resources ( void )

現在のすべての一般リソースを配列で返します。

返り値

現在の一般リソースを含む配列を返します。

例

例1 apd_dump_regular_resources() の例

<?php
print_r(apd_dump_regular_resources());
?>

参考

apd_echo

(PECL apd >= 0.2)

apd_echo — デバッグ用ソケットに表示する

説明

bool apd_echo ( string $output )

実行中のスクリプトに関する情報を、 一般的にはソケット経由でリクエストします。

パラメータ

output

デバッグされた変数。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 apd_echo() の例

<?php
apd_echo($i);
?>

apd_get_active_symbols

(PECL apd 0.2)

apd_get_active_symbols — ローカルスコープ内の現在の変数名を配列で取得する

説明

array apd_get_active_symbols ( void )

アクティブなスコープ内で定義されているすべての変数名を返します (変数の値ではありません)。

返り値

すべての変数を含む多次元配列を返します。

例

例1 apd_get_active_symbols() の例

<?php
apd_echo(apd_get_active_symbols());
?>

apd_set_pprof_trace

(PECL apd >= 0.2)

apd_set_pprof_trace — セッションのデバッグを開始する

説明

string apd_set_pprof_trace ([ string $dump_directory [, string $fragment = "pprof" ]] )

ダンプディレクトリの pprof_{process_id} へのデバッグを開始します。

パラメータ

dump_directory

プロファイルのダンプファイルを書き込むディレクトリ。 指定しない場合は、php.ini の設定 apd.dumpdir を使用します。

fragment

返り値

対象となるファイルへのパスを返します。

例

例1 apd_set_pprof_trace() の例

<?php
apd_set_pprof_trace();
?>

参考

apd_set_session_trace_socket

(PECL apd >= 0.2)

apd_set_session_trace_socket — リモートセッションのデバッグを開始する

説明

bool apd_set_session_trace_socket ( string $tcp_server , int $socket_type , int $port , int $debug_level )

指定した tcp_server (tcplisten など) に接続し、 デバッグデータをソケットに送信します。

パラメータ

tcp_server

TCP サーバーの IP あるいは Unix ドメインソケット (ファイルなど)。

socket_type

ファイルベースのソケットなら AF_UNIX、 標準の tcp/ip なら APD_AF_INET。

port

任意のポートを使用できますが、できるだけ大きめの数を使用するほうがいいでしょう。 小さい数は他のシステムサービスが使っている可能性があります。

debug_level

XXX_TRACE 定数の組み合わせによる整数値。

MEMORY_TRACE を用いることは推奨しません。 これは非常に低速で、またあまり正確ではないようだからです。 ASSIGNMENT_TRACE は、まだ実装されていません。

すべての機能 (TIMING, FUNCTIONS, ARGS SUMMARY (strace -c のようなもの)) のトレースを有効にするには、値 99 を指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 apd_set_session_trace_socket() の例

<?php
  apd_set_session_trace_socket("127.0.0.1",APD_AF_INET,7112,0);
?>

apd_set_session_trace

(PECL apd 0.2-0.4)

apd_set_session_trace — セッションのデバッグを開始する

説明

void apd_set_session_trace ( int $debug_level [, string $dump_directory ] )

ダンプディレクトリの apd_dump_{process_id} へのデバッグを開始します。

パラメータ

debug_level

XXX_TRACE 定数の組み合わせによる整数値。

MEMORY_TRACE を用いることは推奨しません。 これは非常に低速で、またあまり正確ではないようだからです。 ASSIGNMENT_TRACE は、まだ実装されていません。

すべての機能 (TIMING, FUNCTIONS, ARGS SUMMARY (strace -c のようなもの)) のトレースを有効にするには、値 99 を指定します。

dump_directory

プロファイルのダンプファイルを書き込むディレクトリ。 指定しない場合は、php.ini の設定 apd.dumpdir を使用します。

返り値

値を返しません。

例

例1 apd_set_session_trace() の例

<?php
apd_set_session_trace(99);
?>

apd_set_session

(PECL apd 0.2-0.4)

apd_set_session — 現在のデバッグレベルを変更あるいは設定する

説明

void apd_set_session ( int $debug_level )

アプリケーション内で、場所によってデバッグのレベルを増減する際に使用可能です。

パラメータ

debug_level

XXX_TRACE 定数の組み合わせによる整数値。

MEMORY_TRACE を用いることは推奨しません。 これは非常に低速で、またあまり正確ではないようだからです。 ASSIGNMENT_TRACE は、まだ実装されていません。

すべての機能 (TIMING, FUNCTIONS, ARGS SUMMARY (strace -c のようなもの)) のトレースを有効にするには、値 99 を指定します。

返り値

値を返しません。

例

例1 apd_set_session() の例

<?php
apd_set_session(9);
?>

override_function

(PECL apd >= 0.2)

override_function — 組み込みの関数を上書きする

説明

bool override_function ( string $function_name , string $function_args , string $function_code )

シンボルテーブルを書き換えることで、組み込みの関数を上書きします

パラメータ

function_name

上書きする関数。

function_args

関数への引数をカンマ区切りの文字列で指定します。

通常は、このパラメータだけでなく function_code パラメータも (シングルクォート区切りの文字列で) 指定することでしょう。シングルクォートで囲んだ文字列を使用する理由は、 変数名がパースされないようにするためです。 ダブルクォートを使用するなら、変数名をエスケープして \$your_var のようにしなければなりません。

function_code

関数の新しいコード。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 override_function() の例

<?php
override_function('test', '$a,$b', 'echo "DOING TEST"; return $a * $b;');
?>

rename_function

(PECL apd >= 0.2)

rename_function — グローバルの関数テーブルで関数名を変更する

説明

bool rename_function ( string $original_name , string $new_name )

グローバルの関数テーブルで関数名を変更します。 一時的に組み込み関数を上書きする際に有用です。

パラメータ

original_name

もとの関数名。

new_name

関数 original_name の新しい名前。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 rename_function() の例

<?php
rename_function('mysql_connect', 'debug_mysql_connect' );
?>

目次

PHP バイトコードコンパイラ

導入

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

Bcompiler は、以下のような目的で作成されました。

  • プロプライエタリな PHP アプリケーションのスクリプト全体をエンコードするため
  • プロプライエタリな PHP アプリケーションの一部のクラスや関数をエンコードするため
  • クライアントのデスクトップで動作する php-gtk アプリケーションを、 php.exe を用いずに実行させるため
  • PHP から C へのコンバータの実現可能性を調べるため
最初の目的は bcompiler_write_header()、 bcompiler_write_file() および bcompiler_write_footer() を使用することで実現できます。バイトコードのファイルが、 圧縮されていないかあるいはプレーンな形式で書き出されます。 出来上がったバイトコードは、単純に include や require を用いることで使用可能です。

2 番目の目的を実現するには bcompiler_write_header()、 bcompiler_write_class()、 bcompiler_write_footer()、 bcompiler_read() および bcompiler_load() 関数を使用します。 バイトコードのファイルが、圧縮されていないか あるいはプレーンな形式で書き出されます。 bcompiler_load() は、bzip で圧縮された バイトコードファイルを読み込みます。これは元のファイルに比べて 1/3 程度の大きさになります。

EXE 形式のファイルを作成するには、修正された sapi ファイルか 共有ライブラリとしてコンパイルされた PHP とともに bcompiler を使用する必要があります。この場合、bcompiler は 圧縮されたバイトコードを exe ファイルの後ろから読み込みます。

圧縮しないバイトコードのみで使用した場合、bcompiler によって 処理速度を約 30% 向上させることが可能です。しかし、圧縮しない バイトコードは元のソースコードに比べて 5 倍程度の大きさに なることに気をつけてください。バイトコードを圧縮することで 容量を節約することが可能ですが、圧縮ファイルを展開するのには ソースコードをパースするよりはるかに長い時間がかかります。 bcompiler はバイトコードに対する最適化を一切行いません。 これは将来のバージョンで対応する予定です…。

コードの保護という点に関しては、もとのソースコードやコメントを 復元することは不可能であると考えて間違いありません。bcompiler のバイトコードをもとにしてコードを復元し、クラスに手を加える といったことは無意味です。しかし、bcompiler で作成した バイトコードファイルからデータを取り出すことは可能です。 個人的なパスワードなどの情報をバイトコードの中に含めないでください。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/bcompiler.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

実行時設定

設定ディレクティブは定義されていません。

リソース型

リソース型は定義されていません。

定義済み定数

定数は定義されていません。

bcompiler 関数

連絡先

コメント・バグ修正・機能拡張の提案や、 開発を手伝ってくださるという方は、» alan_k@php.net までメールをください。お待ちしています。

bcompiler_load_exe

(PECL bcompiler >= 0.4)

bcompiler_load_exe — bcompiler の exe ファイルを読み込み、クラスを生成する

説明

bool bcompiler_load_exe ( string $filename )

bcompiler の exe ファイルからデータを読み込み、バイトコードからクラスを生成します。

パラメータ

filename

exe ファイルのパスを表す文字列。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_load_exe() の例

<?php

bcompiler_load_exe("/tmp/example.exe");
print_r(get_defined_classes());

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

  • bcompiler_load() - bz 圧縮されたファイルを読み込み、クラスを生成する

bcompiler_load

(PECL bcompiler >= 0.4)

bcompiler_load — bz 圧縮されたファイルを読み込み、クラスを生成する

説明

bool bcompiler_load ( string $filename )

bzip 圧縮されたファイルを読み込み、バイトコードからクラスを生成します。

パラメータ

filename

bzcompress されたファイルのパスを表す文字列。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_load() の例

<?php

bcompiler_load("/tmp/example");

print_r(get_defined_classes());

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

注意:

バイトコードをパースするには、include 文や require 文を 使用してください。この関数を使用するよりも、そのほうが より移植性が高く便利です。

この関数は、バイトコードファイルに含まれるスクリプト本体のコードを 実行するわけではないことに注意しましょう。

参考

bcompiler_parse_class

(PECL bcompiler >= 0.4)

bcompiler_parse_class — クラスのバイトコードを読み込み、ユーザー関数をコールする

説明

bool bcompiler_parse_class ( string $class , string $callback )

クラスのバイトコードを読み込み、ユーザー関数をコールします。

パラメータ

class

クラス名を表す文字列。

callback

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_parse_class() の例

<?php

function readByteCodes($data) {
    print_r($data);
}

bcompiler_parse_class("DB","readByteCodes");

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

注意:

bcompiler 0.5 以降ではこの関数は削除されており、 もはや使用することはできません。

bcompiler_read

(PECL bcompiler >= 0.4)

bcompiler_read — ファイルハンドルを読み込み、クラスを生成する

説明

bool bcompiler_read ( resource $filehandle )

開いているファイルハンドルからデータを読み込み、バイトコードからクラスを生成します。

パラメータ

filehandle

fopen() が返すファイルハンドル。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_read() の例

<?php
$fh = fopen("/tmp/example","r");
bcompiler_read($fh);
fclose($fh);
print_r(get_defined_classes());

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

注意:

バイトコードをパースするには、include 文や require 文を 使用してください。この関数を使用するよりも、そのほうが より移植性が高く便利です。

この関数は、バイトコードファイルに含まれるスクリプト本体のコードを 実行するわけではないことに注意しましょう。

bcompiler_write_class

(PECL bcompiler >= 0.4)

bcompiler_write_class — 定義したクラスをバイトコードとして書き込む

説明

bool bcompiler_write_class ( resource $filehandle , string $className [, string $extends ] )

この関数は、PHP から既存のクラスをバイトコードとして読み込み、 開かれているファイルハンドルに書き込みます。

パラメータ

filehandle

fopen() が返すファイルハンドル。

className

クラス名を表す文字列。

extends

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_write_class() example

<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_class($fh,"DB");
// DB_mysql が DB_common を継承しているのなら、
// DB_mysql より前に DB_common を書き込む必要があります。
bcompiler_write_class($fh,"DB_common");
bcompiler_write_class($fh,"DB_mysql");
bcompiler_write_footer($fh);
fclose($fh);

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

注意:

この関数は依存性のチェックを行わないので、 読み込んだ際に undefined class とならないように、書き込む順序に注意が必要です。

参考

bcompiler_write_constant

(PECL bcompiler >= 0.5)

bcompiler_write_constant — 定義した定数をバイトコードとして書き込む

説明

bool bcompiler_write_constant ( resource $filehandle , string $constantName )

この関数は、PHP から既存の定数をバイトコードとして読み込み、 開かれているファイルハンドルに書き込みます。

パラメータ

filehandle

fopen() が返すファイルハンドル。

constantName

定義済みの定数名を表す文字列。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_write_constant() の例

<?php
define("MODULE_MAX", 30);

$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_constant($fh,"MODULE_MAX");
bcompiler_write_footer($fh);
fclose($fh);

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

bcompiler_write_file

(PECL bcompiler >= 0.6)

bcompiler_write_file — php ソースファイルをバイトコードとして書き込む

説明

bool bcompiler_write_file ( resource $filehandle , string $filename )

この関数は、指定したソースファイルをバイトコードにコンパイルし、 開かれているファイルハンドルに書き込みます。

パラメータ

filehandle

fopen() が返すファイルハンドル。

filename

ソースファイルのパスを表す文字列。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_write_file() の例

<?php
$fh = fopen("example.phb", "w");
bcompiler_write_header($fh);
bcompiler_write_file($fh, "example.php");
bcompiler_write_footer($fh);
fclose($fh);
/* 以下はまったく同等となります。
include "example.php";
   および
include "example.phb";
*/
?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

bcompiler_write_function

(PECL bcompiler >= 0.5)

bcompiler_write_function — 定義した関数をバイトコードとして書き込む

説明

bool bcompiler_write_function ( resource $filehandle , string $functionName )

この関数は、PHP から既存の関数をバイトコードとして読み込み、 開かれているファイルハンドルに書き込みます。書き込む順序を気にする 必要はありません (例えば、関数 b が関数 a を使用している場合に 下の例のようにコンパイルしたとしても正常に動作します)。

パラメータ

filehandle

fopen() が返すファイルハンドル。

functionName

関数名を表す文字列。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_write_function() の例

<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_function($fh,"my_function_a");
bcompiler_write_function($fh,"my_function_b");
bcompiler_write_footer($fh);
fclose($fh);

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

bcompiler_write_functions_from_file

(PECL bcompiler >= 0.5)

bcompiler_write_functions_from_file — ファイル内で定義されているすべての関数をバイトコードとして書き込む

説明

bool bcompiler_write_functions_from_file ( resource $filehandle , string $fileName )

指定したファイル内で定義されているすべての関数を検索し、 対応するバイトコードを、 開かれているファイルハンドルに書き込みます。

パラメータ

filehandle

fopen() が返すファイルハンドル。

fileName

コンパイルしたいファイル。 コンパイルしたいファイルを include/require することを忘れないでください。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_write_functions_from_file() の例

<?php
require('module.php');

$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_functions_from_file($fh,'module.php');
bcompiler_write_footer($fh);
fclose($fh);

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

bcompiler_write_header

(PECL bcompiler >= 0.3)

bcompiler_write_header — bcompiler のヘッダを書き込む

説明

bool bcompiler_write_header ( resource $filehandle [, string $write_ver ] )

bcompiler ファイルのヘッダを書き込みます。

パラメータ

filehandle

fopen() が返すファイルハンドル。

write_ver

以前に使われていたフォーマットでバイトコードを書き込む際に使用します。 これにより、古いバージョンの bcompiler でバイトコードを使用することが可能となります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 bcompiler_write_header() の例

<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_class($fh,"DB");
bcompiler_write_footer($fh);
fclose($fh);

?>

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

参考

bcompiler_write_included_filename

(PECL bcompiler >= 0.5)

bcompiler_write_included_filename — インクルードされたファイルをバイトコードとして書き込む

説明

bool bcompiler_write_included_filename ( resource $filehandle , string $filename )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

注意

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

目次

エラー処理およびログ記録

導入

以下の関数は、エラー処理およびログ記録を行います。これらの関数によ り、独自のエラー処理規則を定義することが可能になり、同時にエラーの ログを記録する方法を修正することが可能になります。これにより、ニーズに 即したエラー出力の変更と拡張が可能になります。

ログ記録関数により他のマシンやemail(またはポケベルのゲートウエイ に!)、システムログ等に直接メッセージを送信することが可能になります。 これにより、ログを行うものを選択したり、アプリケーションやWebサイ トに最も重要な部分をモニタすることが可能になります。

エラー出力関数により、エラーのフィードバックのレベルと種類、 簡単な通知からカスタマイズされた関数までエラーの際に返すもの をカスタマイズすることが可能になります。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

実行時設定

php.ini の設定により動作が変化します。

エラーおよびロギング設定オプション
名前 デフォルト 変更可能 変更履歴
error_reporting NULL PHP_INI_ALL  
display_errors "1" PHP_INI_ALL  
display_startup_errors "0" PHP_INI_ALL  
log_errors "0" PHP_INI_ALL  
log_errors_max_len "1024" PHP_INI_ALL PHP 4.3.0 以降で有効です。
ignore_repeated_errors "0" PHP_INI_ALL PHP 4.3.0 以降で有効です。
ignore_repeated_source "0" PHP_INI_ALL PHP 4.3.0 以降で有効です。
report_memleaks "1" PHP_INI_ALL PHP 4.3.0 以降で有効です。
track_errors "0" PHP_INI_ALL  
html_errors "1" PHP_INI_ALL PHP <= 4.2.3 では PHP_INI_SYSTEM 。
xmlrpc_errors "0" PHP_INI_SYSTEM PHP 4.1.0 以降で有効です。
xmlrpc_error_number "0" PHP_INI_ALL PHP 4.1.0 以降で有効です。
docref_root "" PHP_INI_ALL PHP 4.3.0 以降で有効です。
docref_ext "" PHP_INI_ALL PHP 4.3.2 以降で有効です。
error_prepend_string NULL PHP_INI_ALL  
error_append_string NULL PHP_INI_ALL  
error_log NULL PHP_INI_ALL  
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブの簡単な説明を示します。

error_reporting integer

エラー出力レベルを設定します。パラメータは、あるビットフィールドを表 す整数か定数名で指定します。このerror_reportingのレベルと定数は、 定義済の定数および php.iniに記述されています。 実行時に設定するには、 error_reporting() 関数を指定してください。 display_errors ディレクティブも参照してください。

PHP 4 と PHP 5 のデフォルトは E_ALL & ~E_NOTICE です。 この設定はE_NOTICEレベルのエラーは出力されません。 開発時にはこのエラーを表示させたい場合もあるかもしれません。

注意:

開発時にE_NOTICEを有効にすることにはいくつ かの利点があります。デバッグのために、NOTICE メッセージはコード の中のバグの可能性について警告を与えます。例えば、代入されていな い値を使用した場合は、警告を発生します。 これは、書き間違いを見付け、デバッグの時間を節約するために非常 に有用です。NOTICEメッセージは、好ましくないコードに警告します。 例えば、$arr[item] は $arr['item'] と書く方が好ましいです。 これは、PHPが "item" を定数として取り扱うためです。 定数でない場合、PHPは配列の添字用の文字列と判断します。

注意:

PHP 5では新しいエラーレベルE_STRICTを使用できます。 E_STRICTはE_ALLには 含まれないため、明示的にこのエラーレベルを設定する必要があります。 開発中にE_STRICTを有効にすることは いくつかの利点があります。STRICTメッセージは最新かつもっとも有効で 推奨されるコーディングメソッドを使用するように手助けしてくれます。 例えば推奨されない関数を使用したさいに警告を発します。

注意: PHP 定数の、PHP 以外での使用

PHP の定数を、httpd.conf など PHP の外部で使用しても何の意味もありません。外部で使用する場合には、 integer 型の値を指定しなければなりません。 また、エラーレベルはこれからも追加されることがあるので、 最大値 (E_ALL に対応する値) は変わる可能性があります。そこで、E_ALL を指定する場面では 2147483647 (E_ALL だけではなくすべてのエラーを含める) のような数を指定するようにしましょう。 これは現状の全ビットに対応した上で、かつ値が将来追加された場合にも対応できます。

display_errors string

エラーをHTML出力の一部として画面に出力するかどうかを定義します。

"stderr" を指定すると、エラーの内容を stdout (標準出力) ではなく stderr (標準エラー出力) に送ります。この値は PHP 5.2.4 以降で使用可能です。それより前のバージョンでは、 このディレクティブは boolean 型でした。

注意:

開発をサポートする仕組みであり、本番のシステムでは 使用すべきではありません (例えばインターネットに接続されたシステムなど)。

注意:

display_errors は実行時にも設定可能（ini_set() 関数を用いて）ですが、スクリプトが致命的（fatal）なエラーを発生した場合は その設定は反映されません。なぜなら、要求されたアクションは 実行されなかったからです。

display_startup_errors boolean

display_errorsをonにした場合でも、PHPの起動シーケンスにおいて発 生したエラーは表示されません。デバッグ時を除き、 display_startup_errorsをoffにしておくことが強く推奨されます。

log_errors boolean

エラーメッセージを、サーバーのエラーログまたはerror_logに記録するかどうかを指定 します。このオプションはサーバーに依存します。

注意:

実用Webサイトではエラー表示を行う代わりにエラーを記録することを 強く推奨します。

log_errors_max_len integer

log_errorsの最大長をバイト単位で設定します。 error_log には、 この設定で情報が追加されます。デフォルトは 1024 で、0 を指定すると 最大長の制限は全く適用されなくなります。 この長さはエラーログへの記録や エラーの表示、そして $php_errormsg に適用されます。

integerを使用する際、 その値はバイト単位で測られます。 この FAQ に記載された 短縮表記を使用することも可能です。
ignore_repeated_errors boolean

繰り返されるメッセージを記録しません。エラーの繰り返しは、 ignore_repeated_sourceが trueに設定されるまで同じファイルの同じ行で発生します。

ignore_repeated_source boolean

メッセージの繰り返しを無視する場合にメッセージのソースを無視しま す。この設定をOnにすると、異なるファイルまたはソース行からの同じ エラーメッセージの繰り返しを記録しなくなります。

report_memleaks boolean

このパラメータを On (デフォルト) にすると、Zend メモリマネージャーが検出した メモリリークの報告を表示します。この報告は、Posix プラットフォームでは標準エラー出力に送られます。 Windows では、デバッガに OutputDebugString() を使って送られ、 » DbgView のようなツールで見ることができます。 このパラメータが使えるのはデバッグビルドだけであり、かつ error_reporting で E_WARNING を有効にしている場合のみです。

track_errors boolean

有効にした場合、直近のエラーメッセージが、 $php_errormsg 変数に常に代入されます。

html_errors boolean

エラーメッセージのHTMLタグをオフにします。htmlエラー用の新しい形 式では、ユーザーがエラーまたはエラーを発生した関数を説明するページ に導くようクリック可能なメッセージを出力します。これらのリファレ ンスは、docref_root およ び docref_extの設定に依存 します。

xmlrpc_errors boolean

通常のエラー報告を無効にし、XML-RPC 形式のエラーメッセージとします。

xmlrpc_error_number integer

XML-RPC の faultCode 要素の値として使用します。

docref_root string

新しいエラーフォーマットはエラーやエラーの原因となった関数に関するマニュアル のページの情報を含んでいます。マニュアルのページによっては母国語でダウンロードが 可能であり、このiniディレクティブをマニュアルのローカルコピーのURLにセット することができます。 マニュアルのローカルコピーが "/manual/" でアクセスできるとすると、単に docref_root=/manual/とするだけです。 ローカルコピーのファイルの拡張子はdocref_ext=.html で指定できます。拡張リファレンスを使用することもできます。例えば docref_root=http://manual/en/または docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon&url=http%3A%2F%2Fwww.php.net%2F"が使用できます。

ほとんどの場合 docref_root の値の最後を "/" にしようと思うでしょう。 しかし上の二つ目の例を見ではその必要はありません。

docref_ext string

docref_rootを参照して下さ い。

注意:

docref_extの値はドット "." で始まる必要があります。

error_prepend_string string

エラーメッセージの前に出力する文字列。

error_append_string string

エラーメッセージの後に出力する文字列。

error_log string

スクリプトエラーが記録されるファイル名です。 ファイルはウェブサーバーユーザーで書き込めなければなりません。 syslog が指定されると、エラーはファイルではなく システムロガーに送られます。これは Unix では syslog(3) であり Windows NT ではイベントログのことです。システムロガーは Windows 95 ではサポートされていません。 syslog() も参照してください。 このディレクティブが設定されていない場合、エラーは SAPI エラーロガーに送信されます。これは、例えば Apache のエラーログ、 あるいは CLI なら stderr になります。

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

注意: 以下の定数をphp.iniで使用することができますが、 httpd.confのようなPHPの外部では、 代わりにビットマスク値を使用する必要があります。

エラーとロギング
値 定数 説明 注記
1 E_ERROR (integer) 重大な実行時エラー。これは、メモリ確保に関する問題のように復帰で きないエラーを示します。スクリプトの実行は中断されます。
2 E_WARNING (integer) 実行時の警告 (致命的なエラーではない)。スクリプトの実行は中断さ れません。  
4 E_PARSE (integer) コンパイル時のパースエラー。パースエラーはパーサでのみ生成されま す。  
8 E_NOTICE (integer) 実行時の警告。エラーを発しうる状況に遭遇したことを示す。 ただし通常のスクリプト実行の場合にもこの警告を発することがありうる。  
16 E_CORE_ERROR (integer) PHPの初期始動時点での致命的なエラー。E_ERRORに 似ているがPHPのコアによって発行される点が違う。  
32 E_CORE_WARNING (integer) （致命的ではない）警告。PHPの初期始動時に発生する。 E_WARNINGに似ているがPHPのコアによって発行される 点が違う。  
64 E_COMPILE_ERROR (integer) コンパイル時の致命的なエラー。E_ERRORに 似ているがZendスクリプティングエンジンによって発行される点が違う。  
128 E_COMPILE_WARNING (integer) コンパイル時の警告（致命的ではない）。E_WARNINGに 似ているがZendスクリプティングエンジンによって発行される点が違う。  
256 E_USER_ERROR (integer) ユーザーによって発行されるエラーメッセージ。E_ERROR に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。  
512 E_USER_WARNING (integer) ユーザーによって発行される警告メッセージ。E_WARNING に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。  
1024 E_USER_NOTICE (integer) ユーザーによって発行される注意メッセージ。E_NOTICEに に似ているがPHPコード上でtrigger_error()関数を 使用した場合に発行される点が違う。  
2048 E_STRICT (integer) コードの相互運用性や互換性を維持するために PHP がコードの変更を提案する。 PHP 5 より
4096 E_RECOVERABLE_ERROR (integer) キャッチできる致命的なエラー。危険なエラーが発生したが、 エンジンが不安定な状態になるほどではないことを表す。 ユーザー定義のハンドラでエラーがキャッチされなかった場合 (set_error_handler() も参照ください) は、 E_ERROR として異常終了する。 PHP 5.2.0 より
8192 E_DEPRECATED (integer) 実行時の注意。これを有効にすると、 将来のバージョンで動作しなくなるコードについての警告を受け取ることができる。 PHP 5.3.0 より
16384 E_USER_DEPRECATED (integer) ユーザー定義の警告メッセージ。これは E_DEPRECATED と同等だが、 PHP のコード上で関数 trigger_error() によって作成されるという点が異なる。 PHP 5.3.0 より
32767 E_ALL (integer) サポートされる全てのエラーと警告。 PHP 5.4.0 より前のバージョンでは、E_STRICT レベルのエラーは除く。 PHP 5.4.x では 32767、 PHP 5.3.x では 30719、 PHP 5.2.x では 6143、 それより前のバージョンでは 2047 でした。

上記の値（数値も論理値も）はどのエラーをレポートするかを指定する ビットマスクを組み立てる。ビット演算子 を使用して値を組み合わせたり特定のエラータイプをマスクすることができる。 php.ini では'|', '~', '!', '^' and '&'のみが解釈されることに 注意すべきである。

例

エラー処理機能を PHP で使用するための例を示します。 ファイルに(XML 形式で)情報を記録し、論理的に致命的なエラーの場合に、 開発者に電子メールを送信するようなエラー処理関数を定義します。

例1 スクリプト内でのエラー処理

<?php
// 自分のエラーハンドリングを行います
error_reporting(0);

// ユーザーの定義したエラーハンドリング関数
function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars) 
{
    // エラーエントリのタイムスタンプ
    $dt = date("Y-m-d H:i:s (T)");

    // エラー文字列の連想配列を定義します。
    // 実際のところ、考慮する必要があるのは
    // E_WARNING、E_NOTICE、E_USER_ERROR、
    // E_USER_WARNING そして E_USER_NOTICE だけです。
    $errortype = array (
                E_ERROR              => 'Error',
                E_WARNING            => 'Warning',
                E_PARSE              => 'Parsing Error',
                E_NOTICE             => 'Notice',
                E_CORE_ERROR         => 'Core Error',
                E_CORE_WARNING       => 'Core Warning',
                E_COMPILE_ERROR      => 'Compile Error',
                E_COMPILE_WARNING    => 'Compile Warning',
                E_USER_ERROR         => 'User Error',
                E_USER_WARNING       => 'User Warning',
                E_USER_NOTICE        => 'User Notice',
                E_STRICT             => 'Runtime Notice',
                E_RECOVERABLE_ERROR  => 'Catchable Fatal Error'
                );
    // set of errors for which a var trace will be saved
    $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);
    
    $err = "<errorentry>\n";
    $err .= "\t<datetime>" . $dt . "</datetime>\n";
    $err .= "\t<errornum>" . $errno . "</errornum>\n";
    $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
    $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
    $err .= "\t<scriptname>" . $filename . "</scriptname>\n";
    $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

    if (in_array($errno, $user_errors)) {
        $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
    }
    $err .= "</errorentry>\n\n";
    
    // テスト用
    // echo $err;

    // エラーログを保存し、重大なユーザーエラーは自分にメールする
    error_log($err, 3, "/usr/local/php4/error.log");
    if ($errno == E_USER_ERROR) {
        mail("phpdev@example.com", "Critical User Error", $err);
    }
}


function distance($vect1, $vect2) 
{
    if (!is_array($vect1) || !is_array($vect2)) {
        trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
        return NULL;
    }

    if (count($vect1) != count($vect2)) {
        trigger_error("Vectors need to be of the same size", E_USER_ERROR);
        return NULL;
    }

    for ($i=0; $i<count($vect1); $i++) {
        $c1 = $vect1[$i]; $c2 = $vect2[$i];
        $d = 0.0;
        if (!is_numeric($c1)) {
            trigger_error("Coordinate $i in vector 1 is not a number, using zero", 
                            E_USER_WARNING);
            $c1 = 0.0;
        }
        if (!is_numeric($c2)) {
            trigger_error("Coordinate $i in vector 2 is not a number, using zero", 
                            E_USER_WARNING);
            $c2 = 0.0;
        }
        $d += $c2*$c2 - $c1*$c1;
    }
    return sqrt($d);
}

$old_error_handler = set_error_handler("userErrorHandler");

// 未定義定数による警告の生成
$t = I_AM_NOT_DEFINED;

// いくつかの「ベクタ」定義
$a = array(2, 3, "foo");
$b = array(5.5, 4.3, -1.6);
$c = array(1, -3);

// ユーザーエラーの生成
$t1 = distance($c, $b) . "\n";

// 他のユーザーエラーの生成
$t2 = distance($b, "i am not an array") . "\n";

// 警告の生成
$t3 = distance($a, $b) . "\n";

?>

エラー処理関数

参考

syslog()も参照してください。

debug_backtrace

(PHP 4 >= 4.3.0, PHP 5)

debug_backtrace — バックトレースを生成する

説明

array debug_backtrace ([ int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT [, int $limit = 0 ]] )

debug_backtrace() は PHP バックトレースを生成します。

パラメータ

options

PHP 5.3.6 以降、このパラメータは次のオプションのビットマスクとなります。

debug_backtrace() のオプション
DEBUG_BACKTRACE_PROVIDE_OBJECT "object" インデックスを埋めるかどうか。
DEBUG_BACKTRACE_IGNORE_ARGS "args" インデックスを無視してすべての関数/メソッドの引数をメモリに格納するかどうか。
5.3.6 より前のバージョンでは TRUE あるいは FALSE しか指定できませんでした。これは DEBUG_BACKTRACE_PROVIDE_OBJECT オプションを指定するかしないかを意味します。

limit

5.4.0 以降、このパラメータを使ってスタックフレームの数を制限できるようになりました。 デフォルト (limit=0) は、すべてのスタックフレームを返します。

返り値

連想配列の配列を返します。連想配列の要素として返される可能性があるものは以下のとおりです。

debug_backtrace() から返される可能性がある要素
名前 型 説明
function string カレントの関数名。 __FUNCTION__ も参照してください。
line integer カレントの行番号。 __LINE__ も参照してください。
file string カレントのファイル名。 __FILE__ も参照してください。
class string カレントのクラス名。 __CLASS__ も参照してください。
object object カレントのオブジェクト。
type string カレントのコール方式。メソッド呼び出しの場合は "->"、 静的なメソッド呼び出しの場合は "::" が返されます。 関数呼び出しの場合は何も返されません。
args array 関数の内部の場合、関数の引数のリストとなります。 インクルードされたファイル内では、 読み込まれたファイルの名前となります。

変更履歴

バージョン 説明
5.4.0 オプションのパラメータ limit が追加されました。
5.3.6 provide_object パラメータが options パラメータに変わり、オプション DEBUG_BACKTRACE_IGNORE_ARGS が追加されました。
5.2.5 オプションのパラメータ provide_object が追加されました。
5.1.1 現在のオブジェクトを返せるようになりました。

例

例1 debug_backtrace() の例

<?php
// ファイル名: /tmp/a.php

function a_test($str)
{
    echo "\nHi: $str";
    var_dump(debug_backtrace());
}

a_test('friend');
?>

<?php
// ファイル名: /tmp/b.php
include_once '/tmp/a.php';
?>

/tmp/b.php を実行した際の結果は以下のようになります。 

Hi: friend
array(2) {
[0]=>
array(4) {
    ["file"] => string(10) "/tmp/a.php"
    ["line"] => int(10)
    ["function"] => string(6) "a_test"
    ["args"]=>
    array(1) {
      [0] => &string(6) "friend"
    }
}
[1]=>
array(4) {
    ["file"] => string(10) "/tmp/b.php"
    ["line"] => int(2)
    ["args"] =>
    array(1) {
      [0] => string(10) "/tmp/a.php"
    }
    ["function"] => string(12) "include_once"
  }
}

参考

debug_print_backtrace

(PHP 5)

debug_print_backtrace — バックトレースを表示する

説明

void debug_print_backtrace ([ int $options = 0 [, int $limit = 0 ]] )

debug_print_backtrace() は PHP バックトレースを 表示します。関数のコール、include / require されているファイル、 そして eval() された内容などが表示されます。

パラメータ

options

PHP 5.3.6 の時点では、このパラメータは次のオプションのビットマスクとなります。

debug_print_backtrace() のオプション
DEBUG_BACKTRACE_IGNORE_ARGS "args" インデックスを無視してすべての関数/メソッドの引数をメモリに格納するかどうか。

limit

5.4.0 以降、このパラメータを使ってスタックフレームの数を制限できるようになりました。 デフォルト (limit=0) は、すべてのスタックフレームを表示します。

返り値

値を返しません。

変更履歴

バージョン 説明
5.4.0 オプションのパラメータ limit が追加されました。
5.3.6 オプションのパラメータ options が追加されました。

例

例1 debug_print_backtrace() の例

<?php
// ファイル名: include.php

function a() {
    b();
}

function b() {
    c();
}

function c(){
    debug_print_backtrace();
}

a();

?>
<?php
// ファイル名: test.php
// このファイルを実行する

include 'include.php';
?>

上の例の出力は、 たとえば以下のようになります。

#0  c() called at [/tmp/include.php:10]
#1  b() called at [/tmp/include.php:6]
#2  a() called at [/tmp/include.php:17]
#3  include(/tmp/include.php) called at [/tmp/test.php:3]

参考

error_get_last

(PHP 5 >= 5.2.0)

error_get_last — 最後に発生したエラーを取得する

説明

array error_get_last ( void )

最後に発生したエラーについての情報を取得します。

返り値

最後に発生したエラーについての情報を連想配列で返します。連想配列のキーは "type"、"message"、"file" および "line" となります。 PHP の内部関数で発生したエラーの場合は、 "message" の先頭に関数名が含まれています。 エラーが発生していない場合は NULL を返します。

例

例1 error_get_last() の例

<?php
echo $a;
print_r(error_get_last());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [type] => 8
    [message] => Undefined variable: a
    [file] => C:\WWW\index.php
    [line] => 2
)

error_log

(PHP 4, PHP 5)

error_log — エラーメッセージを送信する

説明

bool error_log ( string $message [, int $message_type = 0 [, string $destination [, string $extra_headers ]]] )

エラーメッセージを Web サーバーのエラーログあるいはファイルに送ります。

パラメータ

message

ログに記録されるエラーメッセージ。

message_type

メッセージをどこに送るのかを指定します。以下の中から指定できます。

error_log() ログタイプ
0 message は、オペレーティング・システム のシステムログのメカニズムまたはファイルのいずれかを使って PHP のシステム・ロガーに送られます。どちらが使われるかは、 設定ディレクティブ error_log の内容により決定されます。これはデフォルトのオプションです。
1 message は、destination パラメータで指定されたアドレスに、電子メール により送られます。このメッセージタイプの場合にのみ、 4 番目のパラメータである extra_headers が使われます。
2 このオプションは存在しません。
3 message は destination で指定されたファイルに追加されます。 明示的に指定しない限り、message の 最後には改行文字は追加されません。
4 message は、直接 SAPI のログ出力ハンドラに送信されます。

destination

メッセージの送信先。その設定は、上で説明している message_type パラメータの値によります。

extra_headers

追加のヘッダ。message_type パラメータが 1 に設定される場合に利用されます。 このメッセージタイプは、mail() と同様に 内部関数を利用します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.2.7 message_type の値として 4 が使用できるようになりました。

例

例1 error_log() の例

<?php
// データベースに接続できない場合、
// サーバーログを通してエラーを通知する。
if (!Ora_Logon($username, $password)) {
    error_log("オラクルのデータベースが使用できません!", 0);
}

// FOO に失敗したら、管理者に email で通知する
if (!($foo = allocate_new_foo())) {
    error_log("大変です。FOO に失敗しました!", 1,
               "operator@example.com");
}

// これ以外の error_log() のコール方法：
error_log("大変だ!", 3, "/var/tmp/my-errors.log");
?>

error_reporting

(PHP 4, PHP 5)

error_reporting — 出力する PHP エラーの種類を設定する

説明

int error_reporting ([ int $level ] )

error_reporting() 関数は、 error_reporting ディレクティブを 実行時に設定します。PHP には多くのエラーレベルがあり、 この関数によりスクリプトの持続時間(実行時間)のレベルが設定されます。 オプションの level を指定しなかった場合は、 error_reporting() は単に現在のエラーレベルを返します。

パラメータ

level

新しい error_reporting レベル。ビットマスクまたは名前つき定数のどちらかです。将来の バージョンとの互換性を保証するために、名前つき定数の使用が 強く推奨されています。エラーレベルが追加されると、整数の幅は増加します。 そのため、以前の整数を使用するエラーレベルは常に期待通りに動作するとは 限りません。

利用可能なエラーレベル定数とその実際の意味は、 定義済みの定数に 記述されています。

返り値

変更前の error_reporting レベルを返します。level パラメータを指定しなかった場合は、現在のレベルを返します。

変更履歴

バージョン 説明
5.4.0 E_STRICT が E_ALL に含まれるようになりました。
5.3.0 E_DEPRECATED と E_USER_DEPRECATED が追加されました。
5.2.0 E_RECOVERABLE_ERROR が追加されました。
5.0.0 E_STRICT が追加されました (これは E_ALL には含まれません)。

例

例1 error_reporting() の例

<?php

// 全てのエラー出力をオフにする
error_reporting(0);

// 単純な実行時エラーを表示する
error_reporting(E_ERROR | E_WARNING | E_PARSE);

// E_NOTICE を表示させるのもおすすめ（初期化されていない
// 変数、変数名のスペルミスなど…）
error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);

// E_NOTICE 以外の全てのエラーを表示する
// これは php.ini で設定されているデフォルト値
error_reporting(E_ALL ^ E_NOTICE);

// 全ての PHP エラーを表示する (Changelog を参照ください)
error_reporting(E_ALL);

// 全ての PHP エラーを表示する
error_reporting(-1);

// error_reporting(E_ALL); と同じ
ini_set('error_reporting', E_ALL);

?>

注意

警告

ほとんどの E_STRICT レベルのエラーは スクリプトのコンパイル時に発生します。そのため、 error_reporting で E_STRICT を含むように設定されている環境では これらのエラーを検出できません (逆も同様です)。

ヒント

値に -1 を指定すると、仮に将来のバージョンの PHP で新しいレベルと定数が追加されたとしてもすべてのエラーを表示するようになります。 E_ALL 定数も、PHP 5.4 以降これと同じ挙動になります。

参考

restore_error_handler

(PHP 4 >= 4.0.1, PHP 5)

restore_error_handler — 以前のエラーハンドラ関数を回復する

説明

bool restore_error_handler ( void )

set_error_handler() を使用してエラーハンドラ関数を 変更した後、元のエラーハンドラ(組込またはユーザー定義関数)に戻すために 使用されます。

返り値

この関数は常に TRUE を返します。

例

例1 restore_error_handler() の例

unserialize() がエラーを発生した場合に 元のエラーハンドラに戻すことにする

<?php
function unserialize_handler($errno, $errstr)
{
    echo "Invalid serialized value.\n";
}

$serialized = 'foo';
set_error_handler('unserialize_handler');
$original = unserialize($serialized);
restore_error_handler();
?>

上の例の出力は以下となります。

Invalid serialized value.

注意

注意:

error_handler 関数の中から restore_error_handler() がコールされた場合、 それは無視されます。

参考

restore_exception_handler

(PHP 5)

restore_exception_handler — 以前の例外ハンドラ関数を回復する

説明

bool restore_exception_handler ( void )

set_exception_handler() を使用して例外ハンドラ関数を 変更した後、元の例外ハンドラ(組込またはユーザー定義関数)に戻すために 使用されます。

返り値

この関数は常に TRUE を返します。

例

例1 restore_exception_handler() の例

<?php
    function exception_handler_1(Exception $e)
    {
        echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
    }

    function exception_handler_2(Exception $e)
    {
        echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
    }

    set_exception_handler('exception_handler_1');
    set_exception_handler('exception_handler_2');

    restore_exception_handler();

    throw new Exception('This triggers the first exception handler...');
?>

上の例の出力は以下となります。

[exception_handler_1] This triggers the first exception handler...

参考

set_error_handler

(PHP 4 >= 4.0.1, PHP 5)

set_error_handler — ユーザー定義のエラーハンドラ関数を設定する

説明

mixed set_error_handler ( callable $error_handler [, int $error_types = E_ALL | E_STRICT ] )

スクリプトのエラー処理を行うユーザー関数 (error_handler)を設定します。

この関数は、実行時のエラー処理をユーザーが定義するために使用します。 例えば、致命的なエラーの際にデータやファイルを消去する必要があるような アプリケーションや、ある条件のもとに (trigger_error()を使用して)エラーを発生する必要がある アプリケーションがこの場合にあたります。

コールバック関数が FALSE を返さない限り、error_types で指定した型のエラーでは PHP 標準のエラーハンドラが完全にバイパスされることに注意してください。 error_reporting() の設定にかかわらず、どのような場合でも ユーザーが設定したエラーハンドラがコールされます。ただし、この場合でも ハンドラで error_reporting() のカレントの値を読み、 それにあわせて適切に動作させることは可能です。エラーを発生した命令の前に @ エラー制御演算子 が付加されている場合、この値は 0 となることには注意しましょう。

ユーザーハンドラ関数は、必要に応じて die() を コールする責任があることにも注意しましょう。エラーハンドラ関数が リターンした場合、スクリプトの実行は、エラーを発生した命令の次の命令に 継続されます。

以下のエラータイプは、ユーザー定義の関数では扱えません。 E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING および set_error_handler() がコールされたファイルで発生した 大半の E_STRICT 。

(ファイルアップロードのように)スクリプトが実行される前にエラーが 発生した場合、カスタムエラーハンドラはコールされません。 これは、その時点では登録されていないためです。

パラメータ

error_handler

ユーザー関数は、エラーコードとエラーを記述する文字列の 2 つの引数を 受け取る必要があります。さらにオプションのパラメータとして 3 つの引数が 追加されています。これらは、エラーが発生したファイル名、エラーが 発生した行、発生したエラーのコンテキスト(エラーが発生した場所での アクティブなシンボルテーブルを指す配列)です。関数は以下のようになります。

handler ( int $errno , string $errstr [, string $errfile [, int $errline [, array $errcontext ]]] )
errno
最初のパラメータ errno は、発生させる エラーのレベルを整数で格納します。
errstr
2 番目のパラメータ errstr は、 エラーメッセージを文字列で格納します。
errfile
3 番目のパラメータ errfile はオプションで、 エラーが発生したファイルの名前を文字列で格納します。
errline
4 番目のパラメータ errline はオプションで、 エラーが発生した行番号を整数で格納します。
errcontext
5 番目のパラメータ errcontext はオプションで、 エラーが発生した場所のアクティブシンボルテーブルを指す配列です。 つまり、エラーが発生したスコープ内でのすべての変数の内容を格納した 配列が errcontext だということです。 ユーザーエラーハンドラは、決してエラーコンテキストを書き換えては いけません。

この関数が FALSE を返した場合は、通常のエラーハンドラが処理を引き継ぎます。

error_types

設定パラメータ error_reporting で表示するエラーを制御するのと全く同様に、 error_handler の起動を制御する際に 使用可能です。 このマスクを指定しない場合、 error_handler は error_reporting の設定によらず 全てのエラーに関してコールされます。

返り値

前に定義されたエラーハンドラ(ある場合)を含む文字列を返します。 組み込みのエラーハンドラを使用している場合は NULL を返します。 また、無効なコールバックなどでエラーとなった場合も NULL を返します。 前に定義されたハンドラがクラスメソッドの場合、この関数は、 クラスとメソッド名からなる添字配列を返します。

変更履歴

バージョン 説明
5.2.0 $php_errormsg の内容を設定するため、エラーハンドラは必ず FALSE を返さなければなりません。
5.0.0 error_types パラメータが追加されました。
4.3.0 error_handler として、関数名のかわりに オブジェクトへのリファレンスとメソッド名を含む配列を指定することも できます。
4.0.2 ユーザー定義関数 error_handler で 3 つの オプションパラメータが利用できるようになりました。filename, line number, および context です。

例

例1 set_error_handler() および trigger_error() によるエラー処理

以下の例では、エラーを発生させることによる内部例外の処理や それらをユーザー定義関数で処理する方法を説明します。

<?php
// エラーハンドラ関数
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
    if (!(error_reporting() & $errno)) {
        // error_reporting 設定に含まれていないエラーコードです
        return;
    }

    switch ($errno) {
    case E_USER_ERROR:
        echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
        echo "  Fatal error on line $errline in file $errfile";
        echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
        echo "Aborting...<br />\n";
        exit(1);
        break;

    case E_USER_WARNING:
        echo "<b>My WARNING</b> [$errno] $errstr<br />\n";
        break;

    case E_USER_NOTICE:
        echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";
        break;

    default:
        echo "Unknown error type: [$errno] $errstr<br />\n";
        break;
    }

    /* PHP の内部エラーハンドラを実行しません */
    return true;
}

// エラー処理のテスト用関数
function scale_by_log($vect, $scale)
{
    if (!is_numeric($scale) || $scale <= 0) {
        trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);
    }

    if (!is_array($vect)) {
        trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);
        return null;
    }

    $temp = array();
    foreach($vect as $pos => $value) {
        if (!is_numeric($value)) {
            trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);
            $value = 0;
        }
        $temp[$pos] = log($scale) * $value;
    }

    return $temp;
}

// 定義したエラーハンドラを設定する
$old_error_handler = set_error_handler("myErrorHandler");

// エラーを発生します。まず、数値でない項目が混ざった配列を定義します。
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);

// 二番目の配列を生成します。
echo "----\nvector b - a notice (b = log(PI) * a)\n";
/* Value at position $pos is not a number, using 0 (zero) */
$b = scale_by_log($a, M_PI);
print_r($b);

// 配列の代わりに文字列を渡しており、問題を発生します。
echo "----\nvector c - a warning\n";
/* Incorrect input vector, array of values expected */
$c = scale_by_log("not array", 2.3);
var_dump($c); // NULL

// ゼロまたは負数の対数が定義されないという致命的なエラーを発生します。
echo "----\nvector d - fatal error\n";
/* log(x) for x <= 0 is undefined, you used: scale = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // ここには到達しません
?>

上の例の出力は、 たとえば以下のようになります。

vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>My NOTICE</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - a warning
<b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />
NULL
----
vector d - fatal error
<b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
  Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Aborting...<br />

参考

set_exception_handler

(PHP 5)

set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する

説明

callable set_exception_handler ( callable $exception_handler )

例外が try/catch ブロックの中でキャッチされなかった場合の デフォルトの例外ハンドラを設定します。 例外は、exception_handler がコールされた後に 停止します。

パラメータ

exception_handler

キャッチされない例外が発生した際にコールされる関数の名前。 この関数は、set_exception_handler() をコールする前に定義する必要があります。 このハンドラ関数は、パラメータをひとつとる必要があります。 このパラメータは、スローされた例外オブジェクトとなります。

注意:

NULL を渡すと、このハンドラをデフォルトの状態に戻せます。

返り値

前に定義された例外ハンドラの名前、またはエラー発生時に NULL を返します。 前にハンドラが定義されていない場合にも NULL が返されます。 NULL を渡した場合は、このハンドラをデフォルトの状態に戻して TRUE を返します。

例

例1 set_exception_handler() の例

<?php
function exception_handler($exception) {
  echo "Uncaught exception: " , $exception->getMessage(), "\n";
}

set_exception_handler('exception_handler');

throw new Exception('Uncaught Exception');
echo "Not Executed\n";
?>

参考

trigger_error

(PHP 4 >= 4.0.1, PHP 5)

trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する

説明

bool trigger_error ( string $error_msg [, int $error_type = E_USER_NOTICE ] )

ユーザーエラーを発生するために使用され、 組み込みのエラーハンドラまたは新しいエラーハンドラ (set_error_handler()) として設定済みのユーザー定義関数と組み合わせて使用されます。

この関数は、実行時の例外に特定の応答を生成する必要がある場合に便利です。

パラメータ

error_msg

このエラーに割り当てられたメッセージ。長さは最大 1024 文字までです。 1024 文字を超える部分は切り捨てられます。

error_type

このエラーに割り当てられたエラー型。E_USER 関連の定数のみが指定可能で、 デフォルトは E_USER_NOTICE です。

返り値

この関数は、間違った error_type が指定された場合に FALSE を、それ以外の場合に TRUE を返します。

例

例1 trigger_error() の例

より拡張した例については set_error_handler() を参照ください。

<?php
if ($divisor == 0) {
    trigger_error("ゼロで割ることはできません", E_USER_ERROR);
}
?>

注意

警告

error_msg の HTML エンティティはエスケープされません。 エラーをブラウザに表示するのなら、メッセージに対して htmlentities() を使ってください。

参考

user_error

(PHP 4, PHP 5)

user_error — trigger_error() のエイリアス

説明

この関数は次の関数のエイリアスです。 trigger_error().

目次

すべての SAPI での htaccess 風機能のサポート

導入

htscanner 拡張モジュールを使用すると、htaccess 風のファイルを使ってディレクトリ単位で PHP の設定を行うことができます。ちょうど apache の htaccess のような機能です。 これは、特に fastcgi (ISS5/6/7、lighttpd など) の環境で有用です。

インストール/設定

目次

要件

PHP バージョン 5.2.0 以降が必要です。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/htscanner

実行時設定

php.ini の設定により動作が変化します。

htscanner 設定オプション
名前 デフォルト 変更可能 Changelog
htscanner.config_file ".htscanner" PHP_INI_SYSTEM  
htscanner.default_docroot "/" PHP_INI_SYSTEM  
htscanner.default_ttl "300" PHP_INI_SYSTEM  
htscanner.stop_on_error "Off" PHP_INI_SYSTEM  
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

htscanner.config_file string

設定ファイルとして使用するファイルの名前。

htscanner.default_docroot string

デフォルトのドキュメントルート。

htscanner.default_ttl int

設定データのキャッシュのタイムアウト秒数。

htscanner.stop_on_error int

エラー時 (パースエラー、ini 項目の設定に失敗など) に停止する。

リソース型

リソース型は定義されていません。

インクルード階層ビューア

導入

ファイルのインクルードやクラスの継承の階層を、実行時にトレースして出力します。

ファイルのインクルードは include、include_once、 require あるいは require_once を用いて行います。

クラス継承の依存関係も報告されます。

インストール/設定

目次

要件

PHP バージョン 5.1.0 以降が必要です。

同梱されているファイル gengraph.php は » graphviz ライブラリを使用しますが、 これは必須ではありません。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/inclued

実行時設定

php.ini の設定により動作が変化します。

inclued 設定オプション
名前 デフォルト 変更可能 変更履歴
inclued.enabled Off PHP_INI_SYSTEM  
inclued.dumpdir NULL PHP_INI_SYSTEM  
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

inclued.enabled bool

inclued を有効にするか否か。

inclued.dumpdir string

inclued ファイルを保存するディレクトリの場所 (パス)。 これを設定すると、PHP リクエスト単位でファイルを作成します。 このファイルは、inclued_get_data() が生成する内容をシリアライズしたものなので、 unserialize() を使えば復元することができます。

警告

リクエストのたびにファイルを作成するので、 このディレクトリはあっという間にいっぱいになってしまいます!

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

定数は定義されていません。

例

目次

inclued をアプリケーションに組み込む例

この例では、inclued を既存のアプリケーションに組み込んで結果を見る方法を説明します。

例1 PHP アプリケーション自身 (関数) 内のデータの取得

<?php
// inclued の情報を保存するファイル
$fp = fopen('/tmp/wp.ser', 'w');
if ($fp) {
    $clue = inclued_get_data();
    if ($clue) {
        fwrite($fp, serialize($clue));
    }
    fclose($fp);
}
?>

データが取得できたら、それを何らかの形式で図にしてみたいと思われることでしょう。 inclued 拡張モジュールには gengraph.php という PHP ファイルが組み込まれています。 このファイルは、» graphviz ライブラリで使える dot ファイルを作成します。 しかし、これは必須ではありません。

例2 gengraph.php の使用例

この例は、inclued のデータを示す画像 inclued.png を作成します。 

# まず dot ファイルを作成します
$ php graphviz.php -i /tmp/wp.ser -o wp.dot

# そして画像を作成します
$ dot -Tpng -o inclued.png wp.dot

例3 inclued のダンプデータの一覧

inclued.dumpdir を使うと、ファイル (include 情報) がリクエストのたびに出力されます。 それらの一覧を取得して unserialize() する例です。

<?php
$path = ini_get('inclued.dumpdir');
if ($path && is_dir($path)) {

    echo "Path: $path", PHP_EOL;

    $inclues = new GlobIterator($path . DIRECTORY_SEPARATOR . 'inclued*');

    if ($inclues->count() === 0) {
        echo 'No clues today', PHP_EOL;
        exit;
    }

    foreach ($inclues as $inclue) {

        echo 'Inclued file: ', $inclue->getFilename(), PHP_EOL;

        $data = file_get_contents($inclue->getPathname());
        if ($data) {
            $inc = unserialize($data);
            echo ' -- filename: ', $inc['request']['SCRIPT_FILENAME'], PHP_EOL;
            echo ' -- number of includes: ', count($inc['includes']), PHP_EOL;
        }
        echo PHP_EOL;
    }
} else {
    echo 'I am totally clueless today.', PHP_EOL;
}
?>

上の例の出力は、 たとえば以下のようになります。

PATH: /tmp/inclued
Inclued file: inclued.56521.1
 -- filename: /Users/philip/test.php
 -- number of includes: 1

Inclued file: inclued.56563.1
 -- filename: /tmp/none.php
 -- number of includes: 0

Inclued file: inclued.56636.1
 -- filename: /tmp/three.php
 -- number of includes: 3

inclued 関数

inclued_get_data

(PECL inclued >= 0.1.0)

inclued_get_data — inclued データを取得する

説明

array inclued_get_data ( void )

inclued データを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

inclued データを返します。

例

例1 inclued_get_data() の例

このデータを用いてグラフを作成する方法については inclued の例 のセクションを参照ください。

<?php 
include 'x.php';

$clue = inclued_get_data();

print_r($clue);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
  [includes] => Array
    (
      [0] => Array
        (
          [operation] => include
          [op_type] => 2
          [filename] => x.php
          [opened_path] => /tmp/x.php
          [fromfile] => /tmp/z.php
          [fromline] => 2
        )
    )
)

参考

目次

Memtrack

導入

この拡張モジュールは、最もメモリを食うスクリプトや関数がどれなのかを調べます。

memtrack は、PHP スクリプトのメモリ消費を追跡し、 ユーザーが設定したあるレベル以上に達したときに報告 (警告) します。 これを実現するために、デフォルトのエグゼキュータ関数を置き換えています。 この特別な関数で、本来のエグザキュータを実行する前後のメモリ使用量を比較しています。 こうすることで、コードの現在の部分でメモリ使用量がどれだけ変化したかを知ることができます。

Zend Engine は、エグゼキュータを opcode 配列 (op_array) 単位で実行します。これは、通常は関数やプレーンスクリプトなどの単位になります。 つまり、memtrack はパフォーマンスに対する影響は及ぼしません。

memtrack は何も関数は提供しません。 動作させるための INI ディレクティブが追加されるだけです。

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/memtrack

実行時設定

php.ini の設定により動作が変化します。

Memtrack 設定オプション
名前 デフォルト 変更可能
memtrack.enabled "0" PHP_INI_SYSTEM
memtrack.soft_limit "0" PHP_INI_ALL
memtrack.hard_limit "0" PHP_INI_ALL
memtrack.vm_limit "0" PHP_INI_ALL
memtrack.ignore_functions "" PHP_INI_SYSTEM
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

memtrack.enabled boolean

この拡張モジュールを有効あるいは無効にします。デフォルトは 0、つまり無効です。

memtrack.soft_limit int

ソフトメモリリミット。

この拡張モジュールは、op_array の実行前後のメモリ消費量を調べ、 その差がハードリミット以上になった場合に警告を発します。 ただし、その関数が無視されていない場合のみです。

このオプションを 0 にすると、ソフトリミットとハードリミットの両方の警告が無効になります。 デフォルト値は 0、つまり警告は一切発生しません。

memtrack.hard_limit int

ハードメモリリミット。

この拡張モジュールは、op_array の実行前後のメモリ消費量を調べ、 その差がハードリミット以上になった場合に その関数が無視されていたとしても 警告を発します。このオプションを 0 にするとハードリミットの警告が完全に無効となります。 デフォルト値は 0、つまり警告は一切発生しません。

memtrack.vm_limit int

仮装メモリリミット (プロセスに対して設定します)。

このリミットをチェックするのはシャットダウン時のみです。 値がこのリミット以上であった場合に警告を発します。

このオプションを現在サポートしているのは、mailinfo() 関数が使用可能な OS (Linux など) のみです。

memtrack.ignore_functions string

カンマあるいはスペースで区切った関数名の一覧。 ここで指定した関数は soft_limit で無視されます。 大文字小文字は区別されます。また、クラスメソッドは class::method 形式で指定します。

リソース型

リソース型は定義されていません。

定義済み定数

定数は定義されていません。

例

目次

基本的な使用法

memtrack 拡張モジュールの基本的な使用例です。

例1 関数内での巨大な配列の作成

<?php

/* /tmp/example1.php */

function foo() {
    $a = array();
    for ($i = 0; $i < 10000; $i++) $a[] = "test";
    return $a;
}
$arr = foo();

?>

このサンプルを、次のようなコマンドで実行します。 

php -d memtrack.enabled=1 -d memtrack.soft_limit=1M -d memtrack.vm_limit=3M /tmp/example1.php

上の例の出力は、 たとえば以下のようになります。

Warning: [memtrack] [pid 26177] user function foo() executed in /tmp/example1.php on line 10 allocated 4194304 bytes in /tmp/example1.php on line 0
Warning: [memtrack] [pid 26177] virtual memory usage on shutdown: 32911360 bytes in Unknown on line 0

出力バッファリング制御

導入

出力制御関数により、スクリプトから送信される出力を制御することが可 能になります。この機能は、複数の異なった場面、特にスクリプトがデー タ出力を開始した後にヘッダをブラウザに送信する必要がある場合に有用 です。出力制御関数は、header() または setcookie()を使用して送信されたヘッダには作用せ ず、echo のような関数とPHPコードのブロック間 のデータにのみ作用します。

注意:

PHP 4.1.x (および 4.2.x) から 4.3.x に更新する際、前のバージョンのバグのせいで、 php.ini の implicit_flush を OFF にする必要があります。さもないと、 ob_start() を使用する全ての出力は、 出力を抑制することができなくなります。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

実行時設定

php.ini の設定により動作が変化します。

出力制御設定オプション
名前 デフォルト 変更可能 変更履歴
output_buffering "0" PHP_INI_PERDIR  
output_handler NULL PHP_INI_PERDIR PHP 4.0.4 以降で使用可能です。
implicit_flush "0" PHP_INI_ALL PHP <= 4.2.3 では PHP_INI_PERDIR です。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

output_buffering boolean/integer

このディレクティブを 'On' と設定することにより、全てのファイルに 関して出力バッファリングを有効にすることができます。 特定の大きさにバッファの大きさを制限したい場合、このディレクティブの 値として 'On' の代わりに最大バイト数(例:output_buffering=4096) を使用することができます。 PHP 4.3.5 以降、PHP-CLI ではこのディレクティブが常に Off となります。

output_handler string

スクリプトの全ての出力を関数にリダイレクトすることができます。 例えば、output_handler に mb_output_handler() を指定した場合、文字エンコーディングは透過的に指定したエンコーディングに 変換されます。出力ハンドラを指定することにより自動的に出力 バッファリングを on にします。

注意:

ob_iconv_handler() と mb_output_handler() の両方で使用することは できません。また、 ob_gzhandler() と zlib.output_compression の両方を使用することはできません。

注意:

このディレクティブには、組み込み関数のみが使用可能です。ユーザー定義の 関数については、ob_start() を使用してください。

implicit_flush boolean

デフォルトは FALSE です。これを TRUE に変更すると、PHP が 各出力ブロックの後で自動的に出力レイヤをフラッシュするよう 指定します。これは、各 print あるいは echo そして HTML ブロックの後で flush() 関数をコールすることと等価です。

Web 環境の中で PHP を使用している時に このオプションを on に変更すると、著しい性能低下が生じるため、 通常はデバッグ目的のみにすることが推奨されます。CLI SAPI のもとで実行される時、この値はデフォルトで TRUE になっています。

ob_implicit_flush() も参照ください。

リソース型

リソース型は定義されていません。

定義済み定数

定数は定義されていません。

例

目次

基本的な使用法

例1 出力制御の例

<?php

ob_start();
echo "Hello\n";

setcookie("cookiename", "cookiedata");

ob_end_flush();

?>

上記の例では、echo からの出力は、 ob_end_flush() がコールされるまで出力バッファに 保存されます。この際、 setcookie()をコールするとエラーを発生することな くクッキーが保存されます (通常、データの送信後はブラウザにヘッダ を送信することはできません)。

出力制御 関数

参考

header()およびsetcookie() も参照ください。

flush

(PHP 4, PHP 5)

flush — 出力バッファをフラッシュする

説明

void flush ( void )

PHP および PHP が使っている (CGI, Web サーバーなどの) バックエンドの書き込みバッファをフラッシュします。 それまでのすべての出力をユーザーのブラウザに対して出力しようと試みますが、 注意すべき点があります。

flush() はウェブサーバーのバッファリング手法を上書きすることはできません。 また、クライアント側のブラウザでのバッファリングにはなんの影響も及ぼしません。 PHP のユーザーレベルでの出力バッファリングの仕組みにも影響を及ぼしません。 つまり、もし ob 出力バッファを使用しているのなら ob_flush() と flush() の両方をコールしなければなりません。

いくつかのサーバー、特に Win32 上ではスクリプトからの出力をブラウザに 結果を送信する前にスクリプトが終了するまでバッファに溜めることがあります。

mod_gzip のような Apache 用のサーバーモジュールはそれ自体がバッファリングを行います。 そのため、flush() をコールしても 即時にデータをクライアントに送信しないという結果につながります。

ブラウザ側で表示前に入力をバッファリングすることもあり得ます。 Netscape では例えば改行または開始タグを受信するまでテキストは バッファリングされ、最も外側のテーブルの </table> タグが現れるまでテーブルは描画されません。

いくつかのバージョンの Microsoft Internet Explorer は、256 バイトの 出力を受けてからページを表示し始めます。このため、これらのブラウザに ページを表示させるには、フラッシュする前に余分な空白を送信する 必要があるかもしれません。

返り値

値を返しません。

ob_clean

(PHP 4 >= 4.2.0, PHP 5)

ob_clean — 出力バッファをクリア(消去)する

説明

void ob_clean ( void )

この関数は、出力バッファの内容を消去します。

この関数は、ob_end_clean() のように出力バッファを破棄するわけではありません。

返り値

値を返しません。

参考

  • ob_flush() - 出力バッファをフラッシュ(送信)する
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

ob_end_clean

(PHP 4, PHP 5)

ob_end_clean — 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

説明

bool ob_end_clean ( void )

出力用バッファの内容を消去し、出力のバッファリングをオフにします。 バッファの内容について更に何らかの処理を行いたい場合には、 バッファの内容は ob_end_clean() がコールされると 破棄されるため、ob_end_clean() の前に ob_get_contents() をコールしなければなりません。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。 失敗する原因は、まず、アクティブなバッファ以外に対して この関数をコールしたか、あるいは何らかの理由により バッファを消去することができなかった場合です（特殊なバッファ等）。

エラー / 例外

この関数は失敗すると E_NOTICE レベルのエラーを発行します。

変更履歴

バージョン 説明
4.2.0 boolean 型の戻り値が追加されました。

例

以下は全ての出力バッファを消去する簡単な方法の例です。

例1 ob_end_clean() の例

<?php
ob_start();
echo 'Text that won\'t get displayed.';
ob_end_clean();
?>

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_flush() - 出力バッファをフラッシュ(送信)する

ob_end_flush

(PHP 4, PHP 5)

ob_end_flush — 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする

説明

bool ob_end_flush ( void )

この関数は、出力用バッファの内容を出力し、出力のバッファリングをオフにします。 出力用バッファの内容を更に処理したい場合には、 バッファの内容は ob_end_flush() がコールされた後に消去されるため、 ob_end_flush() の前に ob_get_contents() をコールする必要があります。

注意: この関数は ob_get_flush() に似ていますが、 ob_get_flush() はバッファを文字列として返すという点が違います。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。 失敗する原因は、まず、アクティブなバッファ以外に対してこの 関数をコールしたか、あるいは何らかの理由により バッファを消去することができなかった場合です（特殊なバッファ等）。

エラー / 例外

この関数は失敗すると E_NOTICE レベルのエラーを発行します。

変更履歴

バージョン 説明
4.2.0 boolean 型の戻り値が追加されました。

例

例1 ob_end_flush() example

以下は全ての出力バッファをフラッシュし終了する簡単な方法の例です。

<?php
  while (@ob_end_flush());
?>

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_get_flush() - 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する
  • ob_flush() - 出力バッファをフラッシュ(送信)する
  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

ob_flush

(PHP 4 >= 4.2.0, PHP 5)

ob_flush — 出力バッファをフラッシュ(送信)する

説明

void ob_flush ( void )

この関数は、(ある場合に)出力バッファの内容を送信します。 更にバッファの内容を処理したい場合には、ob_flush() がコールされた後にバッファの内容が破棄されるので、 ob_flush() の前に ob_get_contents() をコールする必要があります。

この関数は、ob_end_flush() のように出力バッファを破棄しません。

返り値

値を返しません。

参考

  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_clean() - 出力バッファをクリア(消去)する
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

ob_get_clean

(PHP 4 >= 4.3.0, PHP 5)

ob_get_clean — 現在のバッファの内容を取得し、出力バッファを削除する

説明

string ob_get_clean ( void )

現在のバッファの中身を取得し、出力バッファを削除します。

ob_get_clean() は、基本的に ob_get_contents() および ob_end_clean() を同時に実行するのと同じです。

返り値

出力バッファの内容を返した後で出力のバッファリングを終了します。 出力バッファリングが開始されていない場合は FALSE が返されます。

例

例1 単純な ob_get_clean() の例

<?php

ob_start();

echo "Hello World";

$out = ob_get_clean();
$out = strtolower($out);

var_dump($out);
?>

上の例の出力は以下となります。


string(11) "hello world"

参考

ob_get_contents

(PHP 4, PHP 5)

ob_get_contents — 出力用バッファの内容を返す

説明

string ob_get_contents ( void )

出力用バッファの内容を取得します。バッファの内容はクリアしません。

返り値

出力用バッファの内容を返します。 出力のバッファリングがアクティブでない場合には FALSE を返します。

例

例1 単純な ob_get_contents() の例

<?php

ob_start();

echo "Hello ";

$out1 = ob_get_contents();

echo "World";

$out2 = ob_get_contents();

ob_end_clean();

var_dump($out1, $out2);
?>

上の例の出力は以下となります。

string(6) "Hello "
string(11) "Hello World"

参考

ob_get_flush

(PHP 4 >= 4.3.0, PHP 5)

ob_get_flush — 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する

説明

string ob_get_flush ( void )

ob_get_flush() は、 出力バッファをフラッシュしてその内容を文字列として返した後、 出力バッファリングを終了します。

注意: この関数は ob_end_flush() と似ていますが、 この関数はバッファの内容を文字列として返します。

返り値

出力バッファを返します。バッファリングが開始されていない場合は FALSE を返します。

例

例1 ob_get_flush() の例

<?php
// 出力バッファリングを On にします
print_r(ob_list_handlers());

// バッファをファイルに保存します
$buffer = ob_get_flush();
file_put_contents('buffer.txt', $buffer);

print_r(ob_list_handlers());
?>

上の例の出力は以下となります。

Array
(
    [0] => default output handler
)
Array
(
)

参考

  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_list_handlers() - 使用中の出力ハンドラの一覧を取得する

ob_get_length

(PHP 4 >= 4.0.2, PHP 5)

ob_get_length — 出力バッファの長さを返す

説明

int ob_get_length ( void )

この関数は、出力バッファの内容の長さを返します。

返り値

出力バッファの内容の長さを返します。 出力のバッファリングがアクティブでない場合には、FALSE を返します。

例

例1 単純な ob_get_length() の例

<?php

ob_start();

echo "Hello ";

$len1 = ob_get_length();

echo "World";

$len2 = ob_get_length();

ob_end_clean();

echo $len1 . ", ." . $len2;
?>

上の例の出力は以下となります。

6, 11

参考

ob_get_level

(PHP 4 >= 4.2.0, PHP 5)

ob_get_level — 出力バッファリング機構のネストレベルを返す

説明

int ob_get_level ( void )

出力バッファリングハンドラのネストレベルを返します。

返り値

出力バッファリングハンドラのネストレベルを返します。 バッファリングがアクティブでない場合はゼロを返します。

参考

ob_get_status

(PHP 4 >= 4.2.0, PHP 5)

ob_get_status — 出力バッファのステータスを取得する

説明

array ob_get_status ([ bool $full_status = FALSE ] )

ob_get_status() は、トップレベルの出力バッファの ステータス情報を返します。full_status が TRUE に設定されている場合は、すべてのアクティブな出力バッファの ステータス情報を返します。

パラメータ

full_status

TRUE を指定すると、すべてのアクティブな出力バッファを返します。 FALSE を指定した場合、あるいは省略した場合は、 トップレベルの出力バッファのみを返します。

返り値

パラメータ full_status を指定していなかったり full_status = FALSE としていた場合は、 以下の要素を保持する配列が返されます。 

Array
(
    [level] => 2
    [type] => 0
    [status] => 0
    [name] => URL-Rewriter
    [del] => 1
)
単純な ob_get_status() の出力結果
キー:level
値:出力階層レベル
キー:type
値:PHP_OUTPUT_HANDLER_INTERNAL (0) あるいは PHP_OUTPUT_HANDLER_USER (1)
キー:status
値:PHP_OUTPUT_HANDLER_START (0)、PHP_OUTPUT_HANDLER_CONT (1) あるいは PHP_OUTPUT_HANDLER_END (2) のいずれか
キー:name
値:アクティブな出力ハンドラの名前、あるいは設定されていない場合は ' default output handler'
キー:del
値:ob_start() が設定した削除フラグ

full_status = TRUE を指定してコールした場合、 出力バッファごとにひとつの要素を保持する配列が返されます。 出力レベルが配列のキーとして使用され、対応する値として 各出力レベルのステータス情報を配列として保持します。 

Array
(
    [0] => Array
        (
            [chunk_size] => 0
            [size] => 40960
            [block_size] => 10240
            [type] => 1
            [status] => 0
            [name] => default output handler
            [del] => 1
        )

    [1] => Array
        (
            [chunk_size] => 0
            [size] => 40960
            [block_size] => 10240
            [type] => 0
            [buffer_size] => 0
            [status] => 0
            [name] => URL-Rewriter
            [del] => 1
        )

)

完全な出力には、追加項目として以下の要素が含まれます。

完全な ob_get_status() の出力結果
キー:chunk_size
値:ob_start() で設定したチャンクの大きさ
キー:size
値:...
キー:blocksize
値:...

参考

ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5)

ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数

説明

string ob_gzhandler ( string $buffer , int $mode )

ob_gzhandler() は ob_start() 用のコールバック関数として使用されることを意図したもので、 圧縮されたページをサポートしている web ブラウザに対して gz エンコードされたデータを送信することを容易にします。 ob_gzhandler() は 実際に圧縮されたデータを送信する前にブラウザがサポートする content encoding の種類("gzip"、"deflate" またはなし)を調べ、それに基づいて 出力を返します。すべてのブラウザがサポートされています。 というのも、ブラウザは、 自分が圧縮されたページをサポートするかどうかを表す 適切なヘッダを送信することになっているからです。 圧縮されたページをブラウザがサポートしていない場合、 この関数は FALSE を返します。

パラメータ

buffer

mode

返り値

変更履歴

バージョン 説明
4.0.5 mode パラメータが追加されました。

例

例1 ob_gzhandler() の例

<?php

ob_start("ob_gzhandler");

?>
<html>
<body>
<p>このページは圧縮されます。</p>
</body>
</html>

注意

注意:

ob_gzhandler() は、zlib 拡張モジュールを必要とします。

注意:

ob_gzhandler() と zlib.output_compression の両方を使用することはできません。 また、 zlib.output_compression を使用すると、それは ob_gzhandler() よりも優先されることに注意してください。

参考

  • ob_start() - 出力のバッファリングを有効にする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする

ob_implicit_flush

(PHP 4, PHP 5)

ob_implicit_flush — 自動フラッシュをオンまたはオフにする

説明

void ob_implicit_flush ([ int $flag = true ] )

ob_implicit_flush() は、 自動フラッシュをオンまたはオフに切替えます。 自動フラッシュにより、出力関数のコールが行われるたびに フラッシュ操作が行われるようになります。このため、flush() を明示的にコールする必要はなくなります。

パラメータ

flag

TRUE で自動フラッシュをオンに、FALSE でオフにします。

返り値

値を返しません。

参考

  • flush() - 出力バッファをフラッシュする
  • ob_start() - 出力のバッファリングを有効にする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする

ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5)

ob_list_handlers — 使用中の出力ハンドラの一覧を取得する

説明

array ob_list_handlers ( void )

使用中の出力ハンドラの一覧を返します。

返り値

これは、使用中の出力ハンドラを（もし存在すれば）配列で返します。もし output_buffering が 有効になっているか、あるいは ob_start() で 無名関数が使用されている場合、ob_list_handlers() は "default output handler" を返します。

例

例1 ob_list_handlers() の例

<?php
// 出力バッファリングを On にします
print_r(ob_list_handlers());
ob_end_flush();

ob_start("ob_gzhandler");
print_r(ob_list_handlers());
ob_end_flush();

// 無名関数
ob_start(create_function('$string', 'return $string;'));
print_r(ob_list_handlers());
ob_end_flush();
?>

上の例の出力は以下となります。

Array
(
    [0] => default output handler
)

Array
(
    [0] => ob_gzhandler
)

Array
(
    [0] => default output handler
)

参考

  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_get_flush() - 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する
  • ob_start() - 出力のバッファリングを有効にする

ob_start

(PHP 4, PHP 5)

ob_start — 出力のバッファリングを有効にする

説明

bool ob_start ([ callable $output_callback [, int $chunk_size = 0 [, bool $erase = true ]]] )

この関数は出力のバッファリングをオンにします。 出力のバッファリングを有効にすると、 (ヘッダ以外の) スクリプトからの出力は実際には行われず、 代わりに内部バッファに保存されます。

この内部バッファの内容は、ob_get_contents() を用いて文字列変数にコピーされます。 内部バッファの内容を出力するには ob_end_flush() を使用します。 ob_end_clean() は、バッファの内容を出力せずに消去します。

警告

web サーバーによっては (例: Apache)、コールバック関数からコールされた際に、 スクリプトの実行ディレクトリを変更するものがあります。 コールバック関数の内部で chdir(dirname($_SERVER['SCRIPT_FILENAME'])) などと指定することで、これをもとに戻すことが可能です。

出力バッファはスタッカブルであり、このため、他の ob_start() がアクティブの間に ob_start() をコールすることが可能です。この場合、 ob_end_flush() を適切な回数コールするようにしてください。 複数の出力コールバック関数がアクティブの場合、 ネストした順番で逐次連続的に出力がフィルタ処理されます。

パラメータ

output_callback

オプションの引数 output_callback 関数を指定することが可能です。この関数は、パラメータとして文字列をとり、 文字列を返します。このコールバック関数は、 出力バッファがフラッシュ (送信) あるいは消去 (ob_flush(), ob_clean() あるいは同等の関数で) された場合、 またはリクエストの最後にブラウザに出力をフラッシュする際にコールされます。 output_callback がコールされた際に、 この関数は出力バッファの内容をパラメータとして受け取ります。このコールバック関数は、 新規の出力バッファを実際に出力される結果として返す必要があり、 この結果はブラウザに送信されます。 output_callback がコール可能な関数ではない場合は FALSE を返します。

コールバック関数が 2 つの引数をとる場合、 2 番目のパラメータは以下のビットフィールド PHP_OUTPUT_HANDLER_START、 PHP_OUTPUT_HANDLER_CONT および PHP_OUTPUT_HANDLER_END を含みます。

output_callback が FALSE を返すと、元の入力がそのままブラウザに送信されます。

output_callback パラメータに NULL 値を渡すと、 これをバイパスすることができます。

ob_end_clean()、 ob_end_flush()、ob_clean()、 ob_flush() および ob_start() をコールバック関数の内部からコールすることはできません。 実際にコールした際の挙動は未定義です。バッファの内容を消去したい際には、 コールバック関数から "" (空文字列) を返してください。 同じく、print_r($expression, true) や highlight_file($filename, true) のような 出力バッファリング関数も、 コールバック関数の内部からコールすることはできません。

注意:

PHP 4.0.4 において、Web ページの圧縮をサポートする圧縮 gz エンコード されたデータの Web ブラウザへの送信を容易にするために ob_gzhandler() がサポートされています。 ob_gzhandler() は、ブラウザが受け入れる content encoding の型を調べ、それに基づいて出力を返します。

chunk_size

オプションのパラメータ chunk_size が渡された場合、 バッファの長さが chunk_size バイトを超えるたびに、 出力の後でバッファがフラッシュされます。 デフォルト値は 0 で、これは出力関数がコールされるのが 出力バッファが閉じたときだけであることを意味します。

PHP 5.4.0 より前のバージョンでは、1 にも特別な意味があり、 これを指定するとチャンクサイズが 4096 バイトになります。

erase

オプションのパラメータ erase に FALSE を指定すると、 スクリプトが終了するまでバッファは削除されません。その結果、 flush 関数や clean 関数がコールされると notice が発生し、FALSE を返すようになります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.4.0 チャンクサイズに 1 を指定したときに、 1 バイトのチャンクを出力バッファに送るようになりました。
4.3.2 output_callback を実行することができない場合に FALSE を返すように変更されました。
4.2.0 erase パラメータが追加されました。

例

例1 ユーザー定義のコールバック関数の例

<?php

function callback($buffer)
{
  // apples を全て oranges に置換する
  return (str_replace("apples", "oranges", $buffer));
}

ob_start("callback");

?>
<html>
<body>
<p>It's like comparing apples to oranges.</p>
</body>
</html>
<?php

ob_end_flush();

?>

上の例の出力は以下となります。

<html>
<body>
<p>It's like comparing oranges to oranges.</p>
</body>
</html>

参考

  • ob_get_contents() - 出力用バッファの内容を返す
  • ob_end_clean() - 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_end_flush() - 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_implicit_flush() - 自動フラッシュをオンまたはオフにする
  • ob_gzhandler() - 出力バッファを gzip 圧縮するための ob_start コールバック関数
  • ob_iconv_handler() - 出力バッファハンドラとして文字エンコーディングを変換する
  • mb_output_handler() - 出力バッファ内で文字エンコーディングを変換するコールバック関数
  • ob_tidyhandler() - バッファを修正するための ob_start コールバック関数

output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5)

output_add_rewrite_var — URL リライタの値を追加する

説明

bool output_add_rewrite_var ( string $name , string $value )

この関数は、URL リライト機構に新しい名前/値の組を追加します。 名前および値は、URL (GET パラメータとして) およびフォーム (hidden フィールドとして) で追加されます。これは、session.use_trans_sid で透過的 URL リライティングが有効になっている場合に セッション ID が渡される方法と同じです。 絶対 URL (http://example.com/..) はリライトされないことに注意しましょう。

この関数の挙動は、php.ini パラメータ url_rewriter.tags によって制御されます。

注意: もし出力バッファリングが有効になっていない場合、この関数を コールすると出力バッファリングが暗黙的に開始されます。

パラメータ

name

変数名。

value

変数の値。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 output_add_rewrite_var() の例

<?php
output_add_rewrite_var('var', 'value');

// リンク
echo '<a href="file.php">リンク</a>
<a href="http://example.com">リンク2</a>';

// フォーム
echo '<form action="script.php" method="post">
<input type="text" name="var2" />
</form>';

print_r(ob_list_handlers());
?>

上の例の出力は以下となります。

<a href="file.php?var=value">リンク</a>
<a href="http://example.com">リンク2</a>

<form action="script.php" method="post">
<input type="hidden" name="var" value="value" />
<input type="text" name="var2" />
</form>

Array
(
    [0] => URL-Rewriter
)

参考

output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5)

output_reset_rewrite_vars — URL リライタの値をリセットする

説明

bool output_reset_rewrite_vars ( void )

この関数は URL リライタをリセットし、 output_add_rewrite_var() 関数や セッション管理機構 (session.use_trans_sid が session_start() に設定されている場合) によって事前に設定されたリライト変数を削除します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 output_reset_rewrite_vars() の例

<?php
session_start();
output_add_rewrite_var('var', 'value');

echo '<a href="file.php">link</a>';
ob_flush();

output_reset_rewrite_vars();
echo '<a href="file.php">link</a>';
?>

上の例の出力は以下となります。

<a href="file.php?PHPSESSID=xxx&var=value">link</a>
<a href="file.php">link</a>

参考

目次

  • flush — 出力バッファをフラッシュする
  • ob_clean — 出力バッファをクリア(消去)する
  • ob_end_clean — 出力用バッファをクリア(消去)し、出力のバッファリングをオフにする
  • ob_end_flush — 出力用バッファをフラッシュ(送信)し、出力のバッファリングをオフにする
  • ob_flush — 出力バッファをフラッシュ(送信)する
  • ob_get_clean — 現在のバッファの内容を取得し、出力バッファを削除する
  • ob_get_contents — 出力用バッファの内容を返す
  • ob_get_flush — 出力バッファをフラッシュし、その内容を文字列として返した後で出力バッファリングを終了する
  • ob_get_length — 出力バッファの長さを返す
  • ob_get_level — 出力バッファリング機構のネストレベルを返す
  • ob_get_status — 出力バッファのステータスを取得する
  • ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数
  • ob_implicit_flush — 自動フラッシュをオンまたはオフにする
  • ob_list_handlers — 使用中の出力ハンドラの一覧を取得する
  • ob_start — 出力のバッファリングを有効にする
  • output_add_rewrite_var — URL リライタの値を追加する
  • output_reset_rewrite_vars — URL リライタの値をリセットする

オブジェクトプロパティとメソッドコールのオーバーロード

導入

この拡張モジュールの用途は、オブジェクトのプロパティへのアクセスと メソッドのコールのオーバーロードを可能にすることです。この 拡張モジュールで定義されている関数は 1 つだけです。この関数、 overload() は、この機能を有効にするクラスの名前を 引数とします。名前を指定されたクラスでこの機能を使用したい場合は 以下の適当なメソッドを定義する必要があります。これらは、 __get()、__set()、 __call() で、それぞれプロパティを取得、 プロパティを設定、メソッドをコールするためのものです。 オーバーロード機能は選択可能です。これらのハンドラ関数の中で オーバーロードを無効とすることができ、 この場合、オブジェクトのプロパティに普通にアクセスできます。

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

警告

この拡張モジュールは PHP 5 には含まれていません。PHP 5 では __get()、__set() および __call() をネイティブにサポートしています。詳細は PHP 5 のオーバーロード のページを参照ください。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

以下の関数を使用するには、オプション --enable-overload を指定して PHP を コンパイルする必要があります。この拡張モジュールは、 PHP 4.3.0 ではデフォルトで有効になっています。 --disable--overload により オーバーロードのサポートを無効とすることができます。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

注意: オーバーロードの組み込みサポートは PHP 4.3.0 で利用可能となりました。

実行時設定

設定ディレクティブは定義されていません。

リソース型

リソース型は定義されていません。

定義済み定数

定数は定義されていません。

例

目次

基本的な使用法

overload() 関数の簡単な使用例をいくつか示します。

例1 PHP クラスのオーバーロード

<?php

class OO {
   var $a = 111;
   var $elem = array('b' => 9, 'c' => 42);

   // プロパティを取得するためのコールバックメソッド
   function __get($prop_name, &$prop_value) 
   {
       if (isset($this->elem[$prop_name])) {
           $prop_value = $this->elem[$prop_name];
           return true;
       } else {
           return false;
       }
   }

   // プロパティを設定するためのコールバックメソッド
   function __set($prop_name, $prop_value) 
   {
       $this->elem[$prop_name] = $prop_value;
       return true;
   }
}

// OO オブジェクトをオーバーロードします
overload('OO');

$o = new OO;
echo "\$o->a: $o->a\n"; // print: $o->a: 111
echo "\$o->b: $o->b\n"; // print: $o->b: 9
echo "\$o->c: $o->c\n"; // print: $o->c: 42
echo "\$o->d: $o->d\n"; // print: $o->d:

// OO の $elem 配列に新規アイテムを追加します
$o->x = 56; 

// (PHP 4 に組み込まれている) stdclass のインスタンスを生成します
// $val はオーバーロードされていません!
$val = new stdclass;
$val->prop = 555;

// $val オブジェクトを有する配列として "a" を設定します
// しかし、__set() はこれを $elem 配列に代入します
$o->a = array($val);
var_dump($o->a[0]->prop);

?>

オブジェクトのオーバーロード 関数

overload

(PHP 4 >= 4.3.0)

overload — クラスのプロパティおよびメソッドに関してオーバーロードを可能にする

説明

void overload ( string $class_name )

overload() 関数は、 class_name で指定されたクラスのプロパティと メソッドコールをオーバーロードします。

パラメータ

class_name

オーバーロードするクラス名。

返り値

値を返しません。

例

このパートの導入部にある 例 を参照ください。

目次

  • overload — クラスのプロパティおよびメソッドに関してオーバーロードを可能にする

PHP オプションと情報

導入

以下の関数によりPHP自体に関する多くの情報(例えば、実行時の設定、 ロードされている拡張モジュール、バージョン等)を 得ることができます。実行しているPHPのオプションを設定する関数もあ ります。おそらく最も有名な関数であるphpinfo() もここにあります。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

実行時設定

php.ini の設定により動作が変化します。

PHP オプション/情報設定オプション
名前 デフォルト 変更可能 変更履歴
assert.active "1" PHP_INI_ALL  
assert.bail "0" PHP_INI_ALL  
assert.warning "1" PHP_INI_ALL  
assert.callback NULL PHP_INI_ALL  
assert.quiet_eval "0" PHP_INI_ALL  
enable_dl "1" PHP_INI_SYSTEM この非推奨の機能は、きっと 将来 削除 されるでしょう。
max_execution_time "30" PHP_INI_ALL  
max_input_time "-1" PHP_INI_PERDIR PHP 4.3.0 以降で有効
max_input_nesting_level "64" PHP_INI_PERDIR 4.4.8 以降および PHP 5.2.3 以降で有効。
max_input_vars 1000 PHP_INI_PERDIR PHP 5.3.9 以降で有効
magic_quotes_gpc "1" PHP_INI_PERDIR PHP <= 4.2.3 では PHP_INI_ALL。PHP 5.4.0 で削除。
magic_quotes_runtime "0" PHP_INI_ALL PHP 5.4.0 で削除。
zend.enable_gc "1" PHP_INI_ALL PHP 5.3.0 以降で有効。
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

assert.active boolean

assert() の評価を有効にします。

assert.bail boolean

assertion が失敗した時にスクリプトの実行を終了します。

assert.warning boolean

assertion が失敗する度に PHP 警告を発行します。

assert.callback string

assertion が失敗した時にコールされるユーザー関数

assert.quiet_eval boolean

assertion 式の評価時に error_reporting() の現在の 設定を使用します。有効な場合、評価時にエラーは表示されません。 (暗黙のうちに error_reporting(0) とします) 無効な場合、エラーは、error_reporting() の設定に 基づき設定されます。

enable_dl boolean

このディレクティブは、Apacheモジュール版のPHPを使用した場合にのみ 有用です。PHPの動的ロード拡張機能をdl()で 仮想サーバー毎またはディレクトリ毎にオンまたはオフに変更することが できます。

動的ロード機能をオフにするのは主としてセキュリティ上の理由によります。 動的ロード機能により、 open_basedir の拘束を全て 無視することが可能になります。 デフォルトでは、セーフモードを 使用している場合以外、動的ロードが可能です。セーフモードにおいては、 dl() を使用することが常に不可能になります。

max_execution_time integer

スクリプトがパーサにより強制終了されるまでに許容される最大の 時間を秒単位で指定します。この命令は、いい加減に書かれた スクリプトがサーバーの負荷を上げることを防止するのに役立ちます。 デフォルトでは、30 に設定されています。 PHP を コマンドライン から実行する場合のデフォルト設定は 0 です。

最大実行時間は、システムコール、ストリーム操作等の 影響を受けません。より詳細な情報については、 set_time_limit() 関数の説明を参照ください。

セーフモードで実行している場合にはこの設定を ini_set() で変更することはできません。次善策としては セーフモード をオフにするか あるいは php.ini 上で制限時間を変えるしかありません。

Web サーバー側でもタイムアウトの設定項目を持ち、 その設定で PHP の実行が中断されることもあります。 Apache には Timeout ディレクティブ、IIS には CGI タイムアウト関数があり、どちらもデフォルトで 300 秒に設定されています。 これらの意味については、Web サーバーのドキュメントを参照ください。

max_input_time integer

スクリプトが POST、GET などの入力を パースする最大の時間を、秒単位で指定します。 これは、サーバーがすべてのデータを受け取ってからスクリプトの実行を開始するまでの時間です。

max_input_nesting_level integer

外部からの入力変数 ($_GET や $_POST など) のネストの深さの最大値を設定します。

max_input_vars integer

入力変数 を最大で何個まで受け付けるかを指定します。 このディレクティブを使うと、ハッシュの衝突を悪用したサービス不能攻撃を受ける可能性を軽減できます。 このディレクティブで設定した数を超える入力変数があった場合は E_WARNING が発生し、 それ以降の入力変数はリクエストから削除されます。 多次元配列の場合、この制限は個々の次元ごとにしか適用されません。

magic_quotes_gpc boolean
警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

GPC(Get/Post/Cookie) 処理に関する magic_quotes の設定を行います。 magic_quotes が on の場合、'(シングルクオート)、" (ダブルクオート)、\(バックスラッシュ) 、NULL には全て自動的に バックスラッシュでエスケープ処理が行われます。magic_quotes_sybase も on の場合、シングルクオートは、バックスラッシュではなく シングルクオートでエスケープされます。

注意:

PHP 4 では、$_ENV 変数もエスケープの対象となります。

注意:

magic_quotes_sybase ディレクティブもONの場合、このオプションは、 magic_quotes_gpc を完全に上書きします。両方のオプションを有効に することにより、シングルクオートのみが '' のようにエスケープされます。 2重引用符、バックスラッシュ、NULは変更されず、エスケープされません。

get_magic_quotes_gpc() も参照してください。

magic_quotes_runtime boolean
警告

この機能は PHP 5.3.0 で 非推奨となり、 PHP 5.4.0 で削除されました。

magic_quotes_runtime が有効の場合、 データベースおよびテクストファイルを含む外部ソースから データを返す全ての関数のクオートは、バックスラッシュで エスケープされます。magic_quotes_sybase も on の場合、シングルクオートは、バックスラッシュの代わりに シングルクオートでエスケープされます。

magic_quotes_runtime の影響を受ける関数は次のとおりです (PECL の関数は除きます)。

zend.enable_gc boolean

循環参照コレクタを有効あるいは無効にします。

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

定義済の phpcredits() 定数
定数 値 説明
CREDITS_GROUP 1 コア開発者のリスト
CREDITS_GENERAL 2 一般的なクレジット: 言語設計とコンセプト、PHP と PHP SAPIモジュールの作者。
CREDITS_SAPI 4 PHPのサーバーAPIモジュールとその作者の一覧。
CREDITS_MODULES 8 PHPの拡張モジュールとその作者の一覧。
CREDITS_DOCS 16 ドキュメント作成チームのクレジット
CREDITS_FULLPAGE 32 通常、他のフラグと組み合わせて使用されます。 他のフラグで示される情報を含む完全に独立したHTMLページを出力する ことを指定します。
CREDITS_QA 64 品質管理チームのクレジット
CREDITS_ALL -1 全てのクレジット、CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_FULLPAGE を指定した場合と同じ。 この定数は、適当なタグを有する完全にスタンドアローンのHTMLページ を生成します。
phpinfo() の定数
定数 値 説明
INFO_GENERAL 1 configureオプション、php.ini の場所、構築日、Webサーバー、システム等。
INFO_CREDITS 2 PHP クレジット。phpcredits()も参照してください。
INFO_CONFIGURATION 4 PHPディレクティブの現在のローカルおよびマスター値。 ini_get()も参照してください。
INFO_MODULES 8 ロードされているモジュールとそれぞれの設定。
INFO_ENVIRONMENT 16 環境変数に関する情報で、$_ENVでも入手可能です。
INFO_VARIABLES 32 EGPCS (Environment, GET, POST, Cookie, Server)から定義済の変数を表示します。
INFO_LICENSE 64 PHPライセンス情報。» license faqも参照してください。
INFO_ALL -1 上記を全て表示します。これがデフォルト値です。
INI 定数
定数 値 説明
INI_USER 1 未使用
INI_PERDIR 2 未使用
INI_SYSTEM 4 未使用
INI_ALL 7 未使用

Assert 定数。これらの値を使用して、 assert_options() のオプションを設定します。

assert() 定数
定数 INI 設定 説明
ASSERT_ACTIVE assert.active assert() の評価を有効にします。
ASSERT_CALLBACK assert.callback アサーションに失敗した場合に実行するコールバック。
ASSERT_BAIL assert.bail アサーションに失敗した時点に実行を中断します。
ASSERT_WARNING assert.warning アサーションに失敗するたびに PHP の警告を発行します。
ASSERT_QUIET_EVAL assert.quiet_eval アサーション式の評価中は error_reporting を無効にします。

次の定数は、ホスト OS が Windows の場合にのみ使用可能なものです。 バージョン情報を知ることができるので、さまざまな機能を使う際に役立ちます。 これらの定数は PHP 5.3.0 以降で使用可能です。

Windows 固有の定数
定数 説明
PHP_WINDOWS_VERSION_MAJOR Windows のメジャーバージョン。4 (NT4/Me/98/95)、 5 (XP/2003 R2/2003/2000) あるいは 6 (Vista/2008) となります。
PHP_WINDOWS_VERSION_MINOR Windows のマイナーバージョン。0 (Vista/2008/2000/NT4/95)、 1 (XP)、2 (2003 R2/2003/XP x64)、10 (98) あるいは 90 (ME) となります。
PHP_WINDOWS_VERSION_BUILD Windows のビルド番号 (たとえば Windows Vista SP1 はビルド 6001 となります)。
PHP_WINDOWS_VERSION_PLATFORM PHP が現在動作しているプラットフォーム。この値は Windows Vista/XP/2000/NT4, Server 2008/2003 では 2、 Windows ME/98/95 では 1 となります。
PHP_WINDOWS_VERSION_SP_MAJOR インストールされているサービスパックのメジャーバージョン。サービスパックがインストールされていない場合は 0 となります。たとえば Windows XP にサービスパック 3 をインストールした場合、この値は 3 となります。
PHP_WINDOWS_VERSION_SP_MINOR インストールされているサービスパックのマイナーバージョン。サービスパックがインストールされていない場合は 0 となります。
PHP_WINDOWS_VERSION_SUITEMASK Windows のさまざまな機能がインストールされているかどうかを示すビットマスク。 各フィールドの意味については以下の表を参照ください。
PHP_WINDOWS_VERSION_PRODUCTTYPE PHP_WINDOWS_NT_* 定数を決定するために使用する値を含みます。 この値は PHP_WINDOWS_NT_* 定数のいずれかとなり、 プラットフォームの形式を示します。
PHP_WINDOWS_NT_DOMAIN_CONTROLLER これはドメインコントローラです。
PHP_WINDOWS_NT_SERVER これはサーバーシステム (Server 2008/2003/2000 など) です。もしドメインコントローラである場合は PHP_WINDOWS_NT_DOMAIN_CONTROLLER と報告されることに注意しましょう。
PHP_WINDOWS_NT_WORKSTATION これはワークステーションシステム (Vista/XP/2000/NT4 など) です。

この表は、PHP_WINDOWS_VERSION_SUITEMASK のビットマスクを使用して確認できる機能の一覧を示すものです。

Windows suitemask ビットフィールド
ビット 説明
0x00000004 Microsoft BackOffice コンポーネントがインストールされています。
0x00000400 Windows Server 2003, Web Edition がインストールされています。
0x00004000 Windows Server 2003, Compute Cluster Edition がインストールされています。
0x00000080 Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition あるいは Windows 2000 Datacenter Server がインストールされています。
0x00000002 Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server あるいは Windows NT Server 4.0 Enterprise Edition がインストールされています。
0x00000040 Windows XP Embedded がインストールされています。
0x00000200 Windows Vista Home Premium, Windows Vista Home Basic あるいは Windows XP Home Edition がインストールされています。
0x00000100 リモートデスクトップに対応していますが、 ひとつのインタラクティブセッションしかサポートしていません。 この値は、システムがアプリケーションサーバーモードで実行中でない場合に設定されます。
0x00000001 Microsoft Small Business Server がかつてインストールされていましたが、 Windows の別のバージョンにアップグレードされました。
0x00000020 Microsoft Small Business Server が、制限クライアントライセンスでインストールされています。
0x00002000 Windows Storage Server 2003 R2 あるいは Windows Storage Server 2003 がインストールされています。
0x00000010 ターミナルサービスがインストールされています。 この値は常に設定されています。もしこの値が設定されているのに 0x00000100 が設定されていなければ、 そのシステムはアプリケーションサーバーモードで動作しています。
0x00008000 Windows Home Server がインストールされています。

PHP オプション/情報 関数

assert_options

(PHP 4, PHP 5)

assert_options — 様々な assert フラグを設定/取得する

説明

mixed assert_options ( int $what [, mixed $value ] )

種々の assert() 制御オプションを設定したり、 単に現在の設定を調べたりします。

パラメータ

what

assert オプション
オプション INI 設定 デフォルト値 説明
ASSERT_ACTIVE assert.active 1 assert() による評価を有効にする
ASSERT_WARNING assert.warning 1 assersion に失敗した場合に PHP 警告を発生する
ASSERT_BAIL assert.bail 0 assersion に失敗した場合に実行を終了する
ASSERT_QUIET_EVAL assert.quiet_eval 0 assersion 式については error_reporting を無効にする
ASSERT_CALLBACK assert.callback (NULL) assertion に失敗した場合にコールされるコールバック

value

オプションに指定する新しい値。

返り値

そのオプションの元の値、あるいはエラー時に FALSE を返します。

例

例1 assert_options() の例

<?php
// これは、assert に失敗した際の
// 処理を行う関数です
function assert_failure()
{
    echo 'Assert failed';
}

// これがテスト関数です
function test_assert($parameter)
{
    assert(is_bool($parameter));
}

// assert オプションを設定します
assert_options(ASSERT_ACTIVE,   true);
assert_options(ASSERT_BAIL,     true);
assert_options(ASSERT_WARNING,  false);
assert_options(ASSERT_CALLBACK, 'assert_failure');

// 失敗する assert です
test_assert(1);

// ASSERT_BAIL が true なので
// 決してここには到達しません
echo 'Never reached';
?>

参考

  • assert() - assertion が FALSE であるかどうかを調べる

assert

(PHP 4, PHP 5)

assert — assertion が FALSE であるかどうかを調べる

説明

bool assert ( mixed $assertion )

assert() は、指定した assertion を調べて、結果が FALSE の場合に適切な動作をします。

assertion が文字列として指定された場合、 assert()によりPHPコードとして評価されます。 文字列 assertionが優れているところは、 assertion のチェックがオフになった場合のオーバーヘッドがより少な いことであり、assertionが失敗した場合のメッセージを式 assertionに有しています。 つまり、もし論理型の条件を assertion として渡した場合、この条件が assert_options() 関数で指定したハンドラ関数への引数とはならないということです。 条件はハンドラ関数をコールする前に文字列に変換され、論理型の FALSE は空文字列に変換されます。

assertion は、デバッグ目的にのみ使用するべきです。 assertion を常にTRUEとなる条件を調べる不具合診断に使用し、TRUE でない場合に何らかのプログラミングエラーを示したり、extension 関数または特定のシステム制限や機能といった、 特定の機能の存在をチェックするために使用することが可能です。

assersion は、入力パラメータのチェックのような通常の実行動作に 使用するべきではありません。一般的には、assertion のチェックを無効にしても そのコードが正常に動作しなければなりません。

assert() の動作は、 assert_options() またはマニュアルの関数の部分 に記述された .ini の設定により設定することが可能です。

関数 assert_options() や ASSERT_CALLBACK 設定ディレクティブにより失敗した assertion を処理するコールバック関数を設定することが可能です。

assert() のコールバックは、assertion が発生した場所に関する情報と共に assertion に渡されたコードを容易にキャプチャーできるため、 特に自動テストセットを構築する際に便利です。 この情報は他の手法でもキャプチャー可能ですが、assertion を使用することにより、より簡単かつ容易に行なうことが可能です!

コールバック関数は、3つの引数を受ける必要があります。最初の引数は、 assertionが失敗したファイルが含まれます。2番目の引数には、 assertionが失敗した行が含まれ、3番目の引数には失敗した式が含まれます (もしある場合のみ。1 または "two" のようなリテラルの値は、 この引数に渡されません)。

パラメータ

assertion

assertion。

返り値

アサーションが false となった場合に FALSE、それ以外の場合に TRUE を返します。

例

例1 失敗した assertion をカスタムハンドラで処理する

<?php
// assertを有効にし、出力を抑制する
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// ハンドラ関数を作成する
function my_assert_handler($file, $line, $code)
{
    echo "<hr>Assertion Failed:
        File '$file'<br />
        Line '$line'<br />
        Code '$code'<br /><hr />";
}

// コールバックを設定する
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// 失敗するassertionを作成
assert('mysql_query("")');
?>

参考

dl

(PHP 4, PHP 5)

dl — 実行時に PHP 拡張モジュールをロードする

説明

bool dl ( string $library )

library で指定された PHP 拡張モジュールを読み込みます。

その拡張モジュールが既に使用可能かどうかを調べまるには、 extension_loaded() を使用します。 これは、組み込みのモジュールと (php.ini か、あるいは dl() を使用して) 動的に読み込むモジュールの両方に対応しています。

警告

この関数は、PHP 5.3 以降でいくつかの SAPI からは削除されました。

パラメータ

library

このパラメータに指定できるのは拡張モジュールの ファイル名だけであり、それはプラットフォームに依存します。 例えば、Unix プラットフォームでは sockets 拡張モジュール (共有モジュールとしてコンパイルされていれば。デフォルトでは有りません!) は sockets.so と呼ばれていますし、一方 Windows プラットフォームでは php_sockets.dll と呼ばれます。

拡張モジュールを読み込むディレクトリは、プラットフォームによって異なります。

Windows - php.ini に明記されていない場合、デフォルトでは 拡張モジュールは c:\php4\extensions\ (PHP 4) あるいは C:\php5\ (PHP 5) からロードされます。

Unix - php.ini に明記されていない場合、デフォルトでは 以下に依存します。

  • PHP をビルドする際に --enable-debug を指定しているか否か
  • PHP をビルドする際に (実験段階の) ZTS (Zend Thread Safety) サポートを有効にしているか否か
  • 現在の ZEND_MODULE_API_NO(Zend 内部モジュール API 番号。基本的にはメジャーモジュール API の変更が発生した日時。 例:20010901)
上記を考慮して、ディレクトリのデフォルトは <install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO となる。 例: /usr/local/php/lib/php/extensions/debug-non-zts-20010901 または /usr/local/php/lib/php/extensions/no-debug-zts-20010901.

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。 拡張モジュールのロード機能が無効だったり、あるいは 無効化されている(enable_dl でオフにされているか または php.ini で セーフモード が有効になっている)場合は、 E_ERROR を発行して実行は停止されます。 指定されたライブラリをロードできず dl() が 失敗した場合、FALSE に加えて E_WARNING メッセージが 発行されます。

例

例1 dl() の例

<?php
// OS によってロードするファイルを切り替える
if (!extension_loaded('sqlite')) {
    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
        dl('php_sqlite.dll');
    } else {
        dl('sqlite.so');
    }
}

// PHP 4.3.0 では PHP_SHLIB_SUFFIX 定数を利用することも可能
if (!extension_loaded('sqlite')) {
    $prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
    dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
}
?>

変更履歴

バージョン 説明
5.3.0 dl() がいくつかの SAPI で無効になりました。 安定性に問題があったためです。 現在 dl() が使える SAPI は CLI と Embed(組み込み) だけです。 かわりに 拡張モジュール読み込みディレクティブ を使ってください。

注意

注意:

dl() は、ZTS サポートつきでビルドされた PHP ではサポートされていません。かわりに 拡張モジュール読み込みディレクティブ を使ってください。

注意:

dl() は Unix プラットフォーム上では 大文字小文字を区別します。

注意: この関数は、PHP が safe-mode で動作している場合は無効となります。

参考

extension_loaded

(PHP 4, PHP 5)

extension_loaded — ある拡張機能がロードされているかどうかを調べる

説明

bool extension_loaded ( string $name )

拡張モジュールがロードされているかどうかを調べます。

パラメータ

name

拡張モジュールの名前。

phpinfo()を使って種々の拡張モジュールの 名前を見ることができます。PHP の CGIまたはCLIバージョン を使っている場合には -m スイッチで、 使用できる全ての拡張モジュールのリストを得ることができます: 

$ php -m
[PHP Modules]
xml
tokenizer
standard
sockets
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

返り値

name で指定する拡張機能がロードされている場合に TRUE を返します。さもなければ FALSE を返します。

例

例1 extension_loaded() の例

<?php
if (!extension_loaded('gd')) {
    if (!dl('gd.so')) {
        exit;
    }
}
?>

変更履歴

バージョン 説明
5.0.0 extension_loaded() は、 内部的な拡張モジュール名を使ってそのモジュールが使用可能かどうかを判断します。 内部的な拡張モジュール名はほとんどの場合は小文字ですが、 大文字を使っているものもあるかもしれません。PHP 5 より前のバージョンでは、 この関数は大文字小文字を区別して名前を比較していました。

参考

  • get_loaded_extensions() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • get_extension_funcs() - あるモジュールの関数名を配列として返す
  • phpinfo() - PHP の設定情報を出力する
  • dl() - 実行時に PHP 拡張モジュールをロードする
  • function_exists() - 指定した関数が定義されている場合に TRUE を返す

gc_collect_cycles

(PHP 5 >= 5.3.0)

gc_collect_cycles — すべての既存ガベージサイクルを強制的に収集する

説明

int gc_collect_cycles ( void )

すべての既存ガベージサイクルを強制的に収集します。

パラメータ

この関数にはパラメータはありません。

返り値

収集したサイクルの数を返します。

gc_disable

(PHP 5 >= 5.3.0)

gc_disable — 循環参照コレクタを無効にする

説明

void gc_disable ( void )

zend.enable_gc を 0 に設定して、循環参照コレクタを無効にします。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

gc_enable

(PHP 5 >= 5.3.0)

gc_enable — 循環参照コレクタを有効にする

説明

void gc_enable ( void )

zend.enable_gc を 1 に設定して、循環参照コレクタを有効にします。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

gc_enabled

(PHP 5 >= 5.3.0)

gc_enabled — 循環参照コレクタの状態を返す

説明

bool gc_enabled ( void )

循環参照コレクタの状態を返します。

パラメータ

この関数にはパラメータはありません。

返り値

ガベージコレクタが有効な場合に TRUE、そうでない場合に FALSE を返します。

例

例1 gc_enabled() の例

<?php
if(gc_enabled()) gc_collect_cycles();
?>

get_cfg_var

(PHP 4, PHP 5)

get_cfg_var — PHP 設定オプションの値を取得する

説明

string get_cfg_var ( string $option )

PHP の設定オプション option の値を取得します。

この関数は、 PHP がコンパイルされた際にセットされた設定情報や Apache の設定ファイルから読んだ設定情報は返しません。

システムが 設定ファイル を使用しているかどうかを確認するには、cfg_file_path の設定値を取得してみてください。 この値が利用可能なら、設定ファイルが使用されています。

パラメータ

option

設定オプションの名前。

返り値

option で指定された PHP 設定オプションの現在の値を返し、 エラーの場合は FALSE を返します。

変更履歴

バージョン 説明
5.3.0 get_cfg_var() は、 配列形式の ini オプションを返せるようになりました。

参考

get_current_user

(PHP 4, PHP 5)

get_current_user — 現在の PHP スクリプトの所有者の名前を取得する

説明

string get_current_user ( void )

現在の PHP スクリプトの所有者の名前を返します。

返り値

ユーザー名を表す文字列。

例

例1 get_current_user() の例

<?php
echo 'Current script owner: ' . get_current_user();
?>

上の例の出力は、 たとえば以下のようになります。

Current script owner: SYSTEM

参考

  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmypid() - PHP のプロセス ID を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する

get_defined_constants

(PHP 4 >= 4.1.0, PHP 5)

get_defined_constants — すべての定数の名前とその値を連想配列として返す

説明

array get_defined_constants ([ bool $categorize = false ] )

現在定義されている全ての定数の名前と値を返します。返される値には、 拡張モジュールにより作成された定数や define() 関数で作成された定数も含まれます。

パラメータ

categorize

これを渡すと、この関数は多次元の配列を返すようになります。 最初の次元のキーがカテゴリとなり、 そのカテゴリ内の定数とその値が下位レベルに格納されます。

<?php
define("MY_CONSTANT", 1);
print_r(get_defined_constants(true));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [Core] => Array
        (
            [E_ERROR] => 1
            [E_WARNING] => 2
            [E_PARSE] => 4
            [E_NOTICE] => 8
            [E_CORE_ERROR] => 16
            [E_CORE_WARNING] => 32
            [E_COMPILE_ERROR] => 64
            [E_COMPILE_WARNING] => 128
            [E_USER_ERROR] => 256
            [E_USER_WARNING] => 512
            [E_USER_NOTICE] => 1024
            [E_ALL] => 2047
            [TRUE] => 1
        )

    [pcre] => Array
        (
            [PREG_PATTERN_ORDER] => 1
            [PREG_SET_ORDER] => 2
            [PREG_OFFSET_CAPTURE] => 256
            [PREG_SPLIT_NO_EMPTY] => 1
            [PREG_SPLIT_DELIM_CAPTURE] => 2
            [PREG_SPLIT_OFFSET_CAPTURE] => 4
            [PREG_GREP_INVERT] => 1
        )

    [user] => Array
        (
            [MY_CONSTANT] => 1
        )

)

返り値

変更履歴

バージョン 説明
5.3.1 Windows のみ: コア定数のカテゴリが Core になりました。 それまでは mhash でした。
5.3.0 コア定数のカテゴリが Core になりました。 それまでは internal でした。Windows では、 コア定数のカテゴリは mhash となります。
5.2.11 categorize パラメータが正しく動作するようになりました。 これまでは categorize パラメータが !is_null($categorize) で解釈されており、 NULL 以外の値を指定すると定数を強制的にカテゴリ分類させてしまっていました。
5.0.0 パラメータ categorize が追加されました。

例

例1 get_defined_constants() の例

<?php
print_r(get_defined_constants());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [E_ERROR] => 1
    [E_WARNING] => 2
    [E_PARSE] => 4
    [E_NOTICE] => 8
    [E_CORE_ERROR] => 16
    [E_CORE_WARNING] => 32
    [E_COMPILE_ERROR] => 64
    [E_COMPILE_WARNING] => 128
    [E_USER_ERROR] => 256
    [E_USER_WARNING] => 512
    [E_USER_NOTICE] => 1024
    [E_ALL] => 2047
    [TRUE] => 1
)

参考

get_extension_funcs

(PHP 4, PHP 5)

get_extension_funcs — あるモジュールの関数名を配列として返す

説明

array get_extension_funcs ( string $module_name )

この関数は、module_name で示したモジュールで定義された全ての関数の名前を返します。

パラメータ

module_name

モジュール名。

注意:

このパラメータは 小文字 でなければなりません。

返り値

すべての関数を含む配列を返します。 module_name が拡張モジュールでない場合は FALSE を返します。

例

例1 XML 関数の出力

<?php
print_r(get_extension_funcs("xml"));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => xml_parser_create
    [1] => xml_parser_create_ns
    [2] => xml_set_object
    [3] => xml_set_element_handler
    [4] => xml_set_character_data_handler
    [5] => xml_set_processing_instruction_handler
    [6] => xml_set_default_handler
    [7] => xml_set_unparsed_entity_decl_handler
    [8] => xml_set_notation_decl_handler
    [9] => xml_set_external_entity_ref_handler
    [10] => xml_set_start_namespace_decl_handler
    [11] => xml_set_end_namespace_decl_handler
    [12] => xml_parse
    [13] => xml_parse_into_struct
    [14] => xml_get_error_code
    [15] => xml_error_string
    [16] => xml_get_current_line_number
    [17] => xml_get_current_column_number
    [18] => xml_get_current_byte_index
    [19] => xml_parser_free
    [20] => xml_parser_set_option
    [21] => xml_parser_get_option
    [22] => utf8_encode
    [23] => utf8_decode
)

参考

get_include_path

(PHP 4 >= 4.3.0, PHP 5)

get_include_path — 現在の include_path 設定オプションを取得する

説明

string get_include_path ( void )

現在の include_path 設定オプションを取得します。

返り値

パスを表す文字列を返します。

例

例1 get_include_path() の例

<?php
// PHP 4.3.0 以降で動作します
echo get_include_path();

// すべてのバージョンの PHP で動作します
echo ini_get('include_path');
?>

参考

get_included_files

(PHP 4, PHP 5)

get_included_files — include または require で読み込まれたファイルの名前を配列として返す

説明

array get_included_files ( void )

この関数は、 include、include_once、 require あるいは require_once によりスクリプトにロードされたすべてのファイルの名前を取得します。

返り値

すべてのファイル名を含む配列を返します。

最初にコールされたスクリプトは "include されたファイル" という扱いに なります。そのため、 include やその仲間たちにより 読み込まれたファイルの一覧に含めて表示されます。

複数回読み込まれているファイルも、 返される配列には一度しかあらわれません。

変更履歴

バージョン 説明
4.0.1 PHP 4.0.1および以前のバージョンにおいて、 get_included_files() は読み込まれるファイルが拡張子 .php となることを仮定しており、他の拡張子のファイルは返されませんでした。 get_included_files() により返される配列は 連想配列であり、 include および include_once で読み込まれたファイルのみが一覧に含まれていました。

例

例1 get_included_files() の例

<?php
// このファイルは abc.php です

include 'test1.php';
include_once 'test2.php';
require 'test3.php';
require_once 'test4.php';

$included_files = get_included_files();

foreach ($included_files as $filename) {
    echo "$filename\n";
}

?>

上の例の出力は以下となります。

abc.php
test1.php
test2.php
test3.php
test4.php

注意

注意:

設定ディレクティブ auto_prepend_file で読み込まれたファイルは、返される配列には含まれません。

参考

get_loaded_extensions

(PHP 4, PHP 5)

get_loaded_extensions — コンパイル/ロードされている全てのモジュールの名前を配列として返す

説明

array get_loaded_extensions ([ bool $zend_extensions = false ] )

この関数は、PHPインタプリタにコンパイル、 ロードされている全てのモジュールの名前を返します。

パラメータ

zend_extensions

Zend 拡張モジュールのみを返します。指定しない場合は、 mysqli のような通常の拡張モジュールを返します。デフォルトは FALSE (通常の拡張モジュールを返す) です。

返り値

モジュール名の配列を返します。

変更履歴

バージョン 説明
5.2.4 オプションの zend_extensions パラメータが追加されました。

例

例1 get_loaded_extensions() の例

<?php
print_r(get_loaded_extensions());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
   [0] => xml
   [1] => wddx
   [2] => standard
   [3] => session
   [4] => posix
   [5] => pgsql
   [6] => pcre
   [7] => gd
   [8] => ftp
   [9] => db
   [10] => calendar
   [11] => bcmath
)

参考

  • get_extension_funcs() - あるモジュールの関数名を配列として返す
  • extension_loaded() - ある拡張機能がロードされているかどうかを調べる
  • dl() - 実行時に PHP 拡張モジュールをロードする
  • phpinfo() - PHP の設定情報を出力する

get_magic_quotes_gpc

(PHP 4, PHP 5)

get_magic_quotes_gpc — magic_quotes_gpc の現在の設定を得る

説明

bool get_magic_quotes_gpc ( void )

magic_quotes_gpc の現在の設定を返します。

実行時に magic_quotes_gpc をセットしようとしても反映されないことに留意してください。

magic_quotes についての詳細な情報は セキュリティの欄 を参照してください。

返り値

magic_quotes_gpc がオフの場合に 0、そうでない場合に 1 を返します。 PHP 5.4.0 以降は、常に FALSE を返します。

変更履歴

バージョン 説明
5.4.0 マジッククォート機能は削除され、常に FALSE 返すようになりました。

例

例1 get_magic_quotes_gpc() の例

<?php
echo get_magic_quotes_gpc();         // 1
echo $_POST['lastname'];             // O\'reilly
echo addslashes($_POST['lastname']); // O\\\'reilly

if (get_magic_quotes_gpc()) {
    $lastname = stripslashes($_POST['lastname']);
}
else {
    $lastname = $_POST['lastname'];
}

// MySQL を使っている場合
$lastname = mysql_real_escape_string($lastname);

echo $lastname; // O\'reilly
$sql = "INSERT INTO lastnames (lastname) VALUES ('$lastname')";
?>

注意

注意:

magic_quotes_sybase ディレクティブがONの場合、magic_quotes_gpcは 完全に上書きされます。そのためget_magic_quotes_gpc() がTRUEを返したとしてもダブルクォーテーションやバックスラッシュ、 NULLはエスケープされません。シングルクォーテーションだけがエスケープ されます。そのケースでは''のように見えます。

参考

get_magic_quotes_runtime

(PHP 4, PHP 5)

get_magic_quotes_runtime — magic_quotes_runtime の現在アクティブな設定値を取得する

説明

bool get_magic_quotes_runtime ( void )

magic_quotes_runtime の現在アクティブな値を返します。

返り値

magic_quotes_runtime がオフの場合に 0、そうでない場合に 1 を返します。 PHP 5.4.0 以降は、常に FALSE を返します。

変更履歴

バージョン 説明
5.4.0 マジッククォート機能は削除され、常に FALSE 返すようになりました。

例

例1 get_magic_quotes_runtime() の例

<?php
// magic_quotes_runtime が有効かどうかを調べます
if(get_magic_quotes_runtime())
{
    // 無効にします
    set_magic_quotes_runtime(false);
}
?>

参考

get_required_files

(PHP 4, PHP 5)

get_required_files — get_included_files() のエイリアス

説明

この関数は次の関数のエイリアスです。 get_included_files().

getenv

(PHP 4, PHP 5)

getenv — 環境変数の値を取得する

説明

string getenv ( string $varname )

環境変数の値を取得します。

phpinfo() を使えば、すべての環境変数の一覧を見ることができます。 これらの変数の多くは、 » RFC 3875 の section 4.1, "Request Meta-Variables" に挙げられているものです。

パラメータ

varname

変数の名前。

返り値

varname が示す環境変数の値を返し、 環境変数 varname が存在しない場合はFALSEを返します。

例

例1 getenv() の例

<?php
// getenv() の使用例
$ip = getenv('REMOTE_ADDR');

// または単純にスーパーグローバル（$_SERVER または $_ENV）を使用します
$ip = $_SERVER['REMOTE_ADDR'];
?>

参考

getlastmod

(PHP 4, PHP 5)

getlastmod — 最終更新時刻を取得する

説明

int getlastmod ( void )

現在のページの最終更新時刻を取得します。

別のファイルの最終更新時刻が知りたい場合は、 filemtime() を使用してください。

返り値

現在のページの最終更新時刻を返します。 この値は Unix のタイムスタンプで、そのまま date ()に渡す事ができます。エラーの場合は FALSE を返します。

例

例1 getlastmod() の例

<?php
// たとえば、'最終更新時刻：March 04 1998 20:43:59.' を出力します
echo "最終更新時刻: " . date ("F d Y H:i:s.", getlastmod());
?>

参考

  • date() - ローカルの日付/時刻を書式化する
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmygid() - PHP スクリプトの所有者の GID を得る
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • filemtime() - ファイルの更新時刻を取得する

getmygid

(PHP 4 >= 4.1.0, PHP 5)

getmygid — PHP スクリプトの所有者の GID を得る

説明

int getmygid ( void )

現在のスクリプトのグループ ID を取得します。

返り値

現在のスクリプトのグループ ID を返します。またはエラー時に FALSE を返します。

参考

  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する

getmyinode

(PHP 4, PHP 5)

getmyinode — 現在のスクリプトの inode を取得する

説明

int getmyinode ( void )

現在のスクリプトの inode を取得します。

返り値

現在のスクリプトの inode を表す整数値、あるいはエラーの場合は FALSE を返します。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getlastmod() - 最終更新時刻を取得する

getmypid

(PHP 4, PHP 5)

getmypid — PHP のプロセス ID を取得する

説明

int getmypid ( void )

現在の PHP プロセスの ID を取得します。

返り値

現在の PHP のプロセス ID を返し、エラーの場合は FALSE を返します。

注意

警告

プロセス ID は一意ではなく、エントロピ源として優れたものではありません。 セキュリティが問題となる状況では、PID に頼らないようにしましょう。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する

getmyuid

(PHP 4, PHP 5)

getmyuid — PHP スクリプト所有者のユーザー ID を取得する

説明

int getmyuid ( void )

現在のスクリプトのユーザー ID を取得します。

返り値

現在のスクリプトのユーザー ID を返し、エラーの場合は FALSE を返します。

参考

  • getmygid() - PHP スクリプトの所有者の GID を得る
  • getmypid() - PHP のプロセス ID を取得する
  • get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
  • getmyinode() - 現在のスクリプトの inode を取得する
  • getlastmod() - 最終更新時刻を取得する

getopt

(PHP 4 >= 4.3.0, PHP 5)

getopt — コマンドライン引数のリストからオプションを取得する

説明

array getopt ( string $options [, array $longopts ] )

スクリプトに渡されたオプションをパースします。

パラメータ

options
この文字列の各文字をオプション文字として使用し、 スクリプトにハイフンひとつ (-) で始まるオプションとして渡された内容とマッチさせます。 たとえば、オプション文字列 "x" は -x というオプションを認識します。 a-z、A-Z および 0-9 のみを認識します。
longopts
オプションの配列。 この配列の各要素をオプション文字列として使用し、 スクリプトにハイフンふたつ (--) で始まるオプションとして渡された内容とマッチさせます。 たとえば、longopts の要素 "opt" は --opt というオプションを認識します。

options パラメータに含まれる要素には次のようなものがあります。

  • 単一の文字 (値を受け付けない)
  • 文字の後にコロンをひとつ続けたもの (値が必須であるパラメータ)
  • 文字の後にコロンをふたつ続けたもの (値がオプションであるパラメータ)
オプションの値は、文字列の後の最初の引数となります。 値の前に空白があるかどうかは関係ありません。

注意: オプションの値で、" " (空白) を区切り文字として使用することはできません。

注意:

options と longopts の書式はほぼ同じです。唯一の違いは、 longopts はオプションの配列 (その各要素がオプションとなる) を受け取るけれども options は文字列 (その各文字がオプションとなる) を受け取るということです。

返り値

この関数はオプション/引数のペアを連想配列で返します。 失敗した場合は FALSE を返します。

注意:

オプション以外のものが見つかった時点でオプションのパースは終了し、 それ以降の内容は破棄されます。

変更履歴

バージョン 説明
5.3.0 "=" を引数/値の区切り文字として使用できるようになりました。
5.3.0 オプションの値 ("::" で指定します) に対応しました。
5.3.0 パラメータ longopts がすべてのプラットフォームで使えるようになりました。
5.3.0 この関数はシステムに依存しなくなり、今では Windows でも動作するようになりました。

例

例1 getopt() の例

<?php
$options = getopt("f:hp:");
var_dump($options);
?>

上のスクリプトを php script.php -fvalue -h として実行すると、次のようになります。 

array(2) {
  ["f"]=>
  string(5) "value"
  ["h"]=>
  bool(false)
}

例2 getopt() の例 その2

<?php
$shortopts  = "";
$shortopts .= "f:";  // 値が必須
$shortopts .= "v::"; // 値がオプション
$shortopts .= "abc"; // これらのオプションは値を受け取りません

$longopts  = array(
    "required:",     // 値が必須
    "optional::",    // 値がオプション
    "option",        // 値なし
    "opt",           // 値なし
);
$options = getopt($shortopts, $longopts);
var_dump($options);
?>

上のスクリプトを php script.php -f "value for f" -v -a --required value --optional="optional value" --option として実行すると、次のようになります。 

array(6) {
  ["f"]=>
  string(11) "value for f"
  ["v"]=>
  bool(false)
  ["a"]=>
  bool(false)
  ["required"]=>
  string(5) "value"
  ["optional"]=>
  string(14) "optional value"
  ["option"]=>
  bool(false)
}

例3 getopt() の例 その3

複数のオプションを一度に渡す例

<?php
$options = getopt("abc");
var_dump($options);
?>

上のスクリプトを php script.php -aaac として実行すると、次のようになります。 

array(2) {
  ["a"]=>
  array(3) {
    [0]=>
    bool(false)
    [1]=>
    bool(false)
    [2]=>
    bool(false)
  }
  ["c"]=>
  bool(false)
}

参考

getrusage

(PHP 4, PHP 5)

getrusage — 現在のリソース使用状況を取得する

説明

array getrusage ([ int $who = 0 ] )

この関数は、getrusage(2) へのインターフェイスです。 システムコールから返されたデータを含む連想配列を返します。

パラメータ

who

who が 1 の場合、getrusage は RUSAGE_CHILDREN を付けてコールされます。

返り値

システムコールから返されたデータを含む連想配列を返します。 すべてのエントリは、記述されたフィールド名を用いてアクセス可能です。

例

例1 getrusage() の例

<?php
$dat = getrusage();
echo $dat["ru_nswap"];         // スワップの数
echo $dat["ru_majflt"];        // ページフォルトの数
echo $dat["ru_utime.tv_sec"];  // 使用するユーザー時間 (秒)
echo $dat["ru_utime.tv_usec"]; // 使用するユーザー時間 (マイクロ秒)
?>

注意

注意: この関数は Windows 環境にはまだ実装されていません。

参考

  • getrusage(2) についてのシステムの man ページ

ini_alter

(PHP 4, PHP 5)

ini_alter — ini_set() のエイリアス

説明

この関数は次の関数のエイリアスです。 ini_set().

ini_get_all

(PHP 4 >= 4.2.0, PHP 5)

ini_get_all — すべての設定オプションを得る

説明

array ini_get_all ([ string $extension [, bool $details = true ]] )

すべての登録済み設定オプションを返します。

パラメータ

extension

オプションで指定する拡張モジュール名。指定した場合は、 その拡張モジュールに関するオプションのみを返します。

details

詳細な設定を取得するか、あるいは各設定の現在の値のみを取得するか。 デフォルトは TRUE (詳細情報を取得する) です。

返り値

ディレクティブ名をキーとする連想配列を返します。

details が TRUE (デフォルト) の場合、 配列の値は、 global_value (php.iniで設定されている)、 local_value (おそらくini_set()または .htaccessでセットされている)、access (アクセスレベル) を含む配列となります。

details が FALSE の場合、 配列の値はそのオプションの現在の値となります。

アクセスレベルの意味についてはマニュアルを参照ください。

注意:

ひとつのディレクティブに複数のアクセスレベルを設定することができます。 access がビットマスク値となっているのはそのためです。

変更履歴

バージョン 説明
5.3.0 details が追加されました。

例

例1 ini_get_all() の例

<?php
print_r(ini_get_all("pcre"));
print_r(ini_get_all());
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [pcre.backtrack_limit] => Array
        (
            [global_value] => 100000
            [local_value] => 100000
            [access] => 7
        )

    [pcre.recursion_limit] => Array
        (
            [global_value] => 100000
            [local_value] => 100000
            [access] => 7
        )

)
Array
(
    [allow_call_time_pass_reference] => Array
        (
            [global_value] => 0
            [local_value] => 0
            [access] => 6
        )

    [allow_url_fopen] => Array
        (
            [global_value] => 1
            [local_value] => 1
            [access] => 4
        )

    ...

)

例2 details を無効にする例

<?php
print_r(ini_get_all("pcre", false)); // PHP 5.3.0 で追加されました
print_r(ini_get_all(null, false)); // PHP 5.3.0 で追加されました
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [pcre.backtrack_limit] => 100000
    [pcre.recursion_limit] => 100000
)
Array
(
    [allow_call_time_pass_reference] => 0
    [allow_url_fopen] => 1
    ...
)

参考

ini_get

(PHP 4, PHP 5)

ini_get — 設定オプションの値を得る

説明

string ini_get ( string $varname )

成功時に、設定オプションの値を返します。

パラメータ

varname

設定オプションの名前。

返り値

成功した場合に設定オプションの値、 null 値の場合は空の文字列を返します。 その設定オプションが存在しない場合は FALSE を返します。

例

例1 ini_get() の例

<?php
/*
php.ini で以下のように設定されているものとします

display_errors = On
register_globals = Off
post_max_size = 8M
*/

echo 'display_errors = ' . ini_get('display_errors') . "\n";
echo 'register_globals = ' . ini_get('register_globals') . "\n";
echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
echo 'post_max_size+1 = ' . (ini_get('post_max_size')+1) . "\n";
echo 'post_max_size in bytes = ' . return_bytes(ini_get('post_max_size'));

function return_bytes($val) {
    $val = trim($val);
    $last = strtolower($val[strlen($val)-1]);
    switch($last) {
        // 'G' は PHP 5.1.0 以降で使用可能です
        case 'g':
            $val *= 1024;
        case 'm':
            $val *= 1024;
        case 'k':
            $val *= 1024;
    }

    return $val;
}

?>

上の例の出力は、 たとえば以下のようになります。


display_errors = 1
register_globals = 0
post_max_size = 8M
post_max_size+1 = 9
post_max_size in bytes = 8388608

注意

注意: boolean 値を探す場合

off という boolean の ini 値は空文字列または "0" として返されます。 一方で on の ini 値は "1" として返されます。 また、この関数はリテラル文字列で設定された INI 値を返すこともできます。

注意: メモリサイズの値を探す場合

upload_max_filesize のようなメモリサイズの値の場合、 php.ini上で省略形で格納されています。 ini_get()はphp.iniに格納されている値を そのままの形式で返します。整数表現に変換したりはしません。 これらの値に通常の算術的な関数を施すと予期しない結果を 得てしまいます。上の例では、省略形の表記から本来のバイト数に変換する PHP ソースのひとつの例を示しています。

参考

ini_restore

(PHP 4, PHP 5)

ini_restore — 設定オプションの値を元に戻す

説明

void ini_restore ( string $varname )

指定した設定オプションを元の値に戻します。

パラメータ

varname

設定オプションの名前。

返り値

値を返しません。

例

例1 ini_restore() の例

<?php
$setting = 'y2k_compliance';

echo 'Current value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

ini_set($setting, ini_get($setting) ? 0 : 1);
echo 'New value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

ini_restore($setting);
echo 'Original value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
?>

上の例の出力は以下となります。

Current value for 'y2k_compliance': 1
New value for 'y2k_compliance': 0
Original value for 'y2k_compliance': 1

参考

  • ini_get() - 設定オプションの値を得る
  • ini_get_all() - すべての設定オプションを得る
  • ini_set() - 設定オプションの値を設定する

ini_set

(PHP 4, PHP 5)

ini_set — 設定オプションの値を設定する

説明

string ini_set ( string $varname , string $newvalue )

指定した設定オプションの値を設定します。 設定オプションは、スクリプトの実行中は新しい値を保持し、 スクリプト終了時に元の値へ戻されます。

パラメータ

varname

全てのオプションが ini_set() を使用して変更することが 可能なわけではありません。有効なオプションの完全な一覧は 付録 を参照ください。

newvalue

オプションの新しい値。

返り値

成功した場合に元の値、失敗した場合に FALSE を返します。

例

例1 ini オプションの設定

<?php
echo ini_get('display_errors');

if (!ini_get('display_errors')) {
    ini_set('display_errors', 1);
}

echo ini_get('display_errors');
?>

参考

magic_quotes_runtime

(PHP 4, PHP 5)

magic_quotes_runtime — set_magic_quotes_runtime() のエイリアス

説明

この関数は次の関数のエイリアスです。 set_magic_quotes_runtime()

main

main — main() のダミー

説明

PHP のソースを除き、main() という名前の関数は 存在しません。PHP 4.3.0 では、PHP ソースにおいて新しいタイプの エラー処理(php_error_docref)が追加されました。そのひとつの機能として、 html_errors (デフォルトでオン)と docref_root (PHP 4.3.2 まではデフォルトでオン)のディレクティブがセットされている 場合に、PHP のエラーメッセージ上に PHP のマニュアルへのリンクが 表示されるようになりました。

ときおり、エラーメッセージは main() 関数の マニュアルを指すことがあります。それがこのページが存在する理由です。 もしそんな参照を発見したら、ぜひ » バグ報告をお願いします。 エラー時のリンク先が main() となっている PHP の関数を指摘してくだされば、それを修正して適切なドキュメントを指すようにします。

現在判明している、main() を指すエラー
関数名 このバージョン以降、ここを指すことはありません
include 5.1.0
include_once 5.1.0
require 5.1.0
require_once 5.1.0

memory_get_peak_usage

(PHP 5 >= 5.2.0)

memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す

説明

int memory_get_peak_usage ([ bool $real_usage = false ] )

PHP スクリプトに割り当てられたメモリの最大値を、バイト単位で返します。

パラメータ

real_usage

これを TRUE に設定すると、システムが割り当てた実際のメモリの大きさを取得します。 省略したり FALSE を設定したりすると、 emalloc() が使用するメモリのみを報告します。

返り値

メモリの最大値をバイト数で返します。

変更履歴

バージョン 説明
5.2.1 この関数を使用するために、 --enable-memory-limit でコンパイルすることは必須ではなくなりました。
5.2.0 real_usage が追加されました。

参考

memory_get_usage

(PHP 4 >= 4.3.2, PHP 5)

memory_get_usage — PHP に割り当てられたメモリの量を返す

説明

int memory_get_usage ([ bool $real_usage = false ] )

現在の PHP スクリプトに割り当てられたメモリの量をバイト単位で返します。

パラメータ

real_usage

これを TRUE に設定すると、システムが割り当てた実際のメモリの大きさを取得します。 省略したり FALSE を設定したりすると、 emalloc() が使用するメモリのみを報告します。

返り値

メモリの量をバイト単位で返します。

変更履歴

バージョン 説明
5.2.1 この関数を使用するために、 --enable-memory-limit でコンパイルすることは必須ではなくなりました。
5.2.0 real_usage が追加されました。

例

例1 memory_get_usage() の例

<?php
// これは単なる例にすぎません。
// 以下の数値はシステムによって変化します。

echo memory_get_usage() . "\n"; // 36640

$a = str_repeat("Hello", 4242);

echo memory_get_usage() . "\n"; // 57960

unset($a);

echo memory_get_usage() . "\n"; // 36744

?>

参考

php_ini_loaded_file

(PHP 5 >= 5.2.4)

php_ini_loaded_file — 読み込まれた php.ini ファイルのパスを取得する

説明

string php_ini_loaded_file ( void )

php.ini ファイルが読み込まれているかどうかを調べ、 そのパスを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

読み込まれている php.ini のパス、 あるいは読み込まれていない場合に FALSE を返します。

例

例1 php_ini_loaded_file() の例

<?php
$inipath = php_ini_loaded_file();

if ($inipath) {
    echo 'Loaded php.ini: ' . $inipath;
} else {
    echo 'A php.ini file is not loaded';
}
?>

上の例の出力は、 たとえば以下のようになります。

Loaded php.ini: /usr/local/php/php.ini

参考

php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5)

php_ini_scanned_files — 追加の ini ディレクトリにある .ini ファイルのリストを取得する

説明

string php_ini_scanned_files ( void )

php_ini_scanned_files()は、php.iniをパースした 後で、設定ファイルのリストをカンマ区切りで返します。 これらのファイルは、PHPのコンパイル時に --with-config-file-scan-dir オプションを使って指定されたディレクトリから取得されます。

戻り値のファイル名には --with-config-file-scan-dir オプションで 指定されたパスが含まれます。

返り値

成功すると、.iniファイルをカンマ区切りにした文字列が返されます。 --with-config-file-scan-dir がセットされていなければ、 FALSEを返します。指定されたディレクトリが空であれば、 空文字列が返されます。ファイルが認識できないものであれば、 そのファイルは文字列には含まれますが同時にPHPがエラーを起こします。 このエラーはコンパイルの時と、php_ini_scanned_files() 関数を使用したときの両方で発生します。

例

例1 返される ini ファイルを一覧する例

<?php
if ($filelist = php_ini_scanned_files()) {
    if (strlen($filelist) > 0) {
        $files = explode(',', $filelist);

        foreach ($files as $file) {
            echo "<li>" . trim($file) . "</li>\n";
        }
    }
}
?>

参考

php_logo_guid

(PHP 4, PHP 5)

php_logo_guid — ロゴの guid を取得する

説明

string php_logo_guid ( void )

ビルトインされている画像を使って PHP ロゴを表示する際に使用できる ID を返します。 ロゴが表示されるのは、expose_php が On の場合のみです。

返り値

PHPE9568F34-D428-11d2-A769-00AA001ACF42 を返します。

例

例1 php_logo_guid() の例

<?php

echo '<img src="' . $_SERVER['PHP_SELF'] .
     '?=' . php_logo_guid() . '" alt="PHP Logo !" />';

?>

参考

php_sapi_name

(PHP 4 >= 4.0.1, PHP 5)

php_sapi_name — ウェブサーバーと PHP の間のインターフェイスの型を返す

説明

string php_sapi_name ( void )

PHP が使用しているインターフェイス (サーバー API、SAPI) の型を小文字の文字列で返します。たとえば、CLI 版の PHP ではこの文字列は "cli" となります。Apache と組み合わせて使用している場合は、 実際に使用している SAPI によってさまざまな結果となります。 返されうる値の一覧を以下にあげます。

返り値

インターフェイスの型を小文字の文字列で返します。

これがすべてではありませんが、以下のような値が返されます。 aolserver, apache, apache2filter, apache2handler, caudium, cgi (PHP 5.3 まで), cgi-fcgi, cli, continuity, embed, isapi, litespeed, milter, nsapi, phttpd, pi3web, roxen, thttpd, tux そして webjames

例

例1 php_sapi_name() の例

この例では、文字列の一部に cgi が含まれるかどうかを調べています。というのも cgi-fcgi となることもあり得るからです。

<?php
$sapi_type = php_sapi_name();
if (substr($sapi_type, 0, 3) == 'cgi') {
    echo "CGI 版の PHP を使用しています\n";
} else {
    echo "CGI 版の PHP を使用していません\n";
}
?>

注意

注意: 別の方法

PHP の定数 PHP_SAPI は、 php_sapi_name() と同じ値となります。

ヒント

失敗しがちな点

定義されている SAPI は、わかりやすいものばかりではないかもしれません。 たとえば apache の場合は apache2handler や apache2filter と定義されることもあります。

参考

php_uname

(PHP 4 >= 4.0.2, PHP 5)

php_uname — PHP が稼動しているオペレーティングシステムに関する情報を返す

説明

string php_uname ([ string $mode = "a" ] )

php_uname() は、PHP が稼動しているオペレーティング システムに関する説明を返します。これは、phpinfo() の出力の先頭に出てくるものと同じです。 単に OS の名前を取得したい場合には PHP_OS 定数の利用を考えてください。ただし、 この定数が返すのは PHP が構築された OS の 情報であることに注意しましょう。

古い UNIX プラットフォームの中には現在の OS 情報を取得できないものもあります。 そんな場合は、PHP をビルドした OS の情報を表示します。 これがおこるのは、 uname() ライブラリコールが存在しないか機能していない場合のみです。

パラメータ

mode

mode は、どのような情報を返すのかを一文字で指定します:

  • 'a': デフォルトです。すべてのモードを "s n r v m" の順で返します。
  • 's': オペレーティングシステム名。 例: FreeBSD
  • 'n': ホスト名。 例: localhost.example.com
  • 'r': リリース名。 例: 5.1.2-RELEASE
  • 'v': バージョン情報。 オペレーティングシステムによって大きく変わります。
  • 'm': マシン型。例: i386

返り値

説明を文字列で返します。

例

例1 php_uname() の例

<?php
echo php_uname();
echo PHP_OS;

/* 出力の例
Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
Linux

FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
FreeBSD

Windows NT XN1 5.1 build 2600
WINNT
*/

if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
    echo 'このサーバーは Windows です!';
} else {
    echo 'このサーバーは Windows ではありません!';
}

?>

関連する 定義済みの定数 を使うほうが簡単なこともあります。例えばこのようになります。

例2 OS 関連の定数の例

<?php
// *nix
echo DIRECTORY_SEPARATOR; // /
echo PHP_SHLIB_SUFFIX;    // so
echo PATH_SEPARATOR;      // :

// Win*
echo DIRECTORY_SEPARATOR; // \
echo PHP_SHLIB_SUFFIX;    // dll
echo PATH_SEPARATOR;      // ;
?>

参考

  • phpversion() - 現在の PHP バージョンを取得する
  • php_sapi_name() - ウェブサーバーと PHP の間のインターフェイスの型を返す
  • phpinfo() - PHP の設定情報を出力する

phpcredits

(PHP 4, PHP 5)

phpcredits — PHP に関するクレジットを出力する

説明

bool phpcredits ([ int $flag = CREDITS_ALL ] )

この関数は、PHP 開発者、モジュール等のリストを有するクレジットを出力します。 ページに情報を挿入するために、適切な HTML コードが生成されます。

パラメータ

flag

独自のクレジットページを出力したい場合に flag を利用するとよいでしょう。

定義済みの phpcredits() フラグ
名前 説明
CREDITS_ALL すべてのクレジットを含めます。 CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_FULLPAGE と同等です。これは、適切なタグを含んだ それ単体で成立する HTML ページを生成します。
CREDITS_DOCS ドキュメントチームのクレジット
CREDITS_FULLPAGE 通常、他のフラグと組み合わせて使用します。 他のフラグで指定した情報を含む、それ単体で完全に独立した HTML ページを出力することを指定します。
CREDITS_GENERAL 一般的なクレジット: 言語の設計およびコンセプト、PHP 作者、SAPIモジュール
CREDITS_GROUP コア開発者のリスト
CREDITS_MODULES PHPの拡張モジュール、およびその作者のリスト
CREDITS_SAPI PHP のサーバー API モジュールとその作者のリスト

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 全般的なクレジットの出力

<?php
phpcredits(CREDITS_GENERAL);
?>

例2 コア開発者およびドキュメントグループの表示

<?php
phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
?>

例3 すべてのクレジットの表示

<html>
 <head>
  <title>独自のクレジットページ</title>
 </head>
 <body>
<?php
// あなたが書いた独自のコード
phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
// さらに別のコード
?>
 </body>
</html>

参考

phpinfo

(PHP 4, PHP 5)

phpinfo — PHP の設定情報を出力する

説明

bool phpinfo ([ int $what = INFO_ALL ] )

現在の PHP の状態に関する、多くの情報を出力します。出力される情報には、 PHP コンパイルオプションと拡張機能、PHP のバージョン、 サーバー情報と環境（モジュールとしてコンパイルされた場合）、 PHP の環境、OS バージョン情報、パス、構成オプションのマスター およびローカルの値、HTTP ヘッダ、PHP License などがあります。

システムの設定はそれぞれ違うため、実行時設定 や 利用できる 定義済みの変数 を調べるために phpinfo() がよく使われます。

また、phpinfo() には EGPCS (Environment, GET, POST, Cookie, Server) の情報が含まれているため、デバッグツールとしても便利です。

パラメータ

what

以下にあるconstantsビット値をひとつまたは 複数個を加算して、オプションのwhat引数に 渡すことによって出力をカスタマイズできます。 それぞれの定数やビット値をor演算子 で結んで渡すこともできます。

phpinfo() のオプション
名前(定数) 値 説明
INFO_GENERAL 1 configure オプション、php.ini の場所、ビルド日時、 Web サーバー、オペレーティングシステム等。
INFO_CREDITS 2 PHP クレジット。phpcredits() も参照ください。
INFO_CONFIGURATION 4 ローカルおよびマスタの、現在の PHP ディレクティブの値。 ini_get() も参照ください。
INFO_MODULES 8 ロードされているモジュールと、それぞれの設定。 get_loaded_extensions() も参照ください。
INFO_ENVIRONMENT 16 $_ENV で取得できる環境変数の情報。
INFO_VARIABLES 32 EGPCS（環境変数・GET・POST・クッキー・サーバー変数）から すべての 定義済みの変数を表示します。
INFO_LICENSE 64 PHP ライセンス情報。» ライセンス FAQ も参照ください。
INFO_ALL -1 上記のすべてを表示します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.2.2 "Loaded Configuration File" 情報が追加されました。これまでは "Configuration File (php.ini) Path" しかありませんでした。

例

例1 phpinfo() の例

<?php

// すべての情報を表示します。デフォルトは INFO_ALL です。
phpinfo();

// モジュール情報だけを表示します。
// phpinfo(8) としても同じです。
phpinfo(INFO_MODULES);

?>

注意

注意:

expose_php が off の場合、一部の情報は表示されません。 これにはPHPとZendのロゴ、そしてクレジットが含まれます。

注意:

CLI モードを利用している場合、phpinfo() は HTML ではなくプレーンテキストで結果を出力します。

参考

phpversion

(PHP 4, PHP 5)

phpversion — 現在の PHP バージョンを取得する

説明

string phpversion ([ string $extension ] )

現在動作中の PHP パーサあるいは拡張モジュールのバージョンを表す文字列を返します。

パラメータ

extension

オプションで指定する拡張モジュール名。

返り値

オプションの extension パラメータが指定されている場合、phpversion() はその拡張モジュールのバージョンを返します。 関連するバージョン情報が存在しない場合、 あるいは拡張モジュールが有効でない場合は FALSE を返します。

例

例1 phpversion() の例

<?php
// たとえば 'Current PHP version: 4.1.1' などと表示します
echo 'Current PHP version: ' . phpversion();

// たとえば '2.0' などと表示します。拡張モジュールが有効でない場合は何も表示しません
echo phpversion('tidy');
?>

例2 PHP_VERSION_ID の例および使用法

<?php
// PHP_VERSION_ID は PHP 5.2.7 以降で使用可能です。
// それより古いバージョンでは、このようにエミュレートします
if (!defined('PHP_VERSION_ID')) {
    $version = explode('.', PHP_VERSION);

    define('PHP_VERSION_ID', ($version[0] * 10000 + $version[1] * 100 + $version[2]));
}

// PHP_VERSION_ID は数値として定義されており、数字が大きいほど PHP の
// バージョンが新しいことになります。その定義は、上で使用しているような
// 式となります。
//
// $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
//
// PHP_VERSION_ID を使えば、その PHP のバージョンで使える機能を調べる
// ことができます。ある機能に対応しているかどうかを調べるために、毎回
// version_compare() を使う必要がなくなります。
//
// たとえば、PHP 5.2.7 より前のバージョンには存在しない定数
// PHP_VERSION_* を、次のように定義することができます。

if(PHP_VERSION_ID < 50207)
{
    define('PHP_MAJOR_VERSION',   $version[0]);
    define('PHP_MINOR_VERSION',   $version[1]);
    define('PHP_RELEASE_VERSION', $version[2]);

    // などなど
}
?>

注意

注意:

この情報は、定義済みの定数 PHP_VERSION でも取得可能です。その他のバージョン関連の情報は、定数 PHP_VERSION_* で取得可能です。

参考

putenv

(PHP 4, PHP 5)

putenv — 環境変数の値を設定する

説明

bool putenv ( string $setting )

サーバーの環境変数に setting を追加します。 この環境変数は、カレントのリクエストを実行している間のみ存在します。 リクエスト終了時、環境変数は元の状態に戻されます。

ある種の環境変数が変更されることは潜在的なセキュリティリスクとなる 可能性があります。safe_mode_allowed_env_vars ディレクティブには接頭辞のカンマ区切りのリストが含まれます。セーフ モードでは、ユーザーはこのディレクティブで指定された接頭辞で始まる名前 を有する環境変数のみを変更可能となります。 デフォルトでは、ユーザーはPHP_ で始まる環境変数 (例えばPHP_FOO=BAR)のみを変更可能です。注意:この ディレクティブが空の場合、PHPはユーザーに全ての環境変数を修正できる許可 を与えてしまいます!

safe_mode_protected_env_vars ディレクティブには、 カンマ区切りの環境変数のリストが含まれます。ユーザーは、この環境変数 をputenv()により変更することができません。これら の変数は、safe_mode_allowed_env_varsが変更するこ とを許可している場合でも保護されます。

パラメータ

setting

"FOO=BAR" 形式の設定。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 環境変数の設定

<?php
putenv("UNIQID=$uniqid");
?>

注意

警告

safe_mode_allowed_env_vars ディレクティブおよび safe_mode_protected_env_vars ディレクティブは、 セーフモード が有効な場合にのみ効果があります!

参考

  • getenv() - 環境変数の値を取得する

restore_include_path

(PHP 4 >= 4.3.0, PHP 5)

restore_include_path — include_path 設定オプションの値を元に戻す

説明

void restore_include_path ( void )

include_path 設定値を php.ini でセットされたオリジナルの設定に戻します。

返り値

値を返しません。

例

例1 restore_include_path() の例

<?php

echo get_include_path();  // .:/usr/local/lib/php

set_include_path('/inc');

echo get_include_path();  // /inc

// PHP 4.3.0 以降で動作します
restore_include_path();

// すべてのバージョンの PHP で動作します
ini_restore('include_path');

echo get_include_path();  // .:/usr/local/lib/php

?>

参考

set_include_path

(PHP 4 >= 4.3.0, PHP 5)

set_include_path — include_path 設定オプションをセットする

説明

string set_include_path ( string $new_include_path )

include_path 設定オプションの値を、このスクリプト内でだけ変更します。

パラメータ

new_include_path

include_path の新しい値。

返り値

成功した場合に元の include_path の値、失敗した場合に FALSE を返します。

例

例1 set_include_path() の例

<?php
// PHP 4.3.0 以降で動作します
set_include_path('/usr/lib/pear');

// すべてのバージョンの PHP で動作します
ini_set('include_path', '/usr/lib/pear');
?>

例2 include path の追加

PATH_SEPARATOR 定数を利用することで、 オペレーティングシステムに依存せずに include path を追加することが可能です。

この例では、既存の include_path の最後に /usr/lib/pear を追加します。

<?php
$path = '/usr/lib/pear';
set_include_path(get_include_path() . PATH_SEPARATOR . $path);
?>

参考

set_magic_quotes_runtime

(PHP 4, PHP 5)

set_magic_quotes_runtime — magic_quotes_runtime の現在アクティブな設定をセットする

説明

bool set_magic_quotes_runtime ( bool $new_setting )

magic_quotes_runtime の現在アクティブな設定をセットします。

警告

この関数は PHP 5.3.0 で 非推奨となりました。 この機能を使用しないことを強く推奨します。

パラメータ

new_setting

FALSE はオフ、TRUE はオンを表します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 set_magic_quotes_runtime() の例

<?php
// 一時的なファイルポインタを作成します
$fp = tmpfile();

// データをポインタに書き込みます
fwrite($fp, '\'PHP\' is a Recursive acronym');

// magic_quotes_runtime なしの場合
rewind($fp);
set_magic_quotes_runtime(false);

echo 'Without magic_quotes_runtime: ' . fread($fp, 64), PHP_EOL;

// magic_quotes_runtime ありの場合
rewind($fp);
set_magic_quotes_runtime(true);

echo 'With magic_quotes_runtime: ' . fread($fp, 64), PHP_EOL;

// 後始末
fclose($fp);
?>

上の例の出力は以下となります。

Without magic_quotes_runtime: 'PHP' is a Recursive acronym
With magic_quotes_runtime: \'PHP\' is a Recursive acronym

参考

set_time_limit

(PHP 4, PHP 5)

set_time_limit — 実行時間の最大値を制限する

説明

void set_time_limit ( int $seconds )

スクリプトが実行可能な秒数を設定します。 この制限にかかるとスクリプトは致命的エラーを返します。 デフォルトの制限値は 30 秒です。 なお、php.iniでmax_execution_timeの 値が定義されている場合にはそれを用います。

この関数がコールされた場合、 タイムアウトカウンタをゼロから再スタートします。 言いかえると、タイムアウトがデフォルトの 30 秒で スクリプト実行までに 25 秒かかる場合に、 set_time_limit(20) を実行すると、スクリプトは、 タイムアウトまでに全体で 45秒 の間実行されます。

パラメータ

seconds

最大実行時間を表す秒数。ゼロを設定すると、時間制限を行いません。

返り値

値を返しません。

注意

警告

この関数は、PHP が セーフモード で実行されている場合には効果がないことに注意してください。 セーフモードをオフにするか、php.ini の時間制限を変更する以外に対策はありません。

注意:

関数 set_time_limit() と設定ディレクティブ max_execution_time は、 このスクリプト自体の実行時間にのみ影響を与えます。 system() を用いたシステムコール、ストリーム操作、 データベースクエリ等のスクリプト実行以外で発生する処理にかかった時間は スクリプトが実行される最大時間を定義する際には含まれません。 ただし、Windows ではこれは当てはまりません。 計測された時間は実際の時間と等しくなります。

sys_get_temp_dir

(PHP 5 >= 5.2.1)

sys_get_temp_dir — 一時ファイル用に使用されるディレクトリのパスを返す

説明

string sys_get_temp_dir ( void )

PHP が一時ファイルを保存するデフォルトのディレクトリのパスを返します。

返り値

一時ディレクトリのパスを返します。

例

例1 sys_get_temp_dir() の例

<?php
// sys_get_temp_dir() を使用して
// 一時ファイルディレクトリにファイルを作成します
$temp_file = tempnam(sys_get_temp_dir(), 'Tux');

echo $temp_file;
?>

上の例の出力は、 たとえば以下のようになります。

C:\Windows\Temp\TuxA318.tmp

参考

  • tmpfile() - テンポラリファイルを作成する
  • tempnam() - 一意なファイル名を生成する

version_compare

(PHP 4 >= 4.1.0, PHP 5)

version_compare — ふたつの "PHP 標準" バージョン番号文字列を比較する

説明

mixed version_compare ( string $version1 , string $version2 [, string $operator ] )

version_compare()は、ふたつの "PHP 標準" バージョン 番号文字列を比較します。この関数は、いくつかのバージョンの PHP でのみ 動作するプログラムを書きたい場合に有用です。

この関数はまず、バージョン文字列の _, -, + をドット . で置き換えます。 さらに、数値でない部分の前後にドット . を追加します。 例えば '4.3.2RC1' は '4.3.2.RC.1' となります。 次に、explode('.', $ver) とするのと同じように結果を分割し、左から右へ 各部分を比較していきます。特殊な文字列が含まれている場合は以下の順で 並べ替えます: ここにないすべての文字列 < dev < alpha = a < beta = b < RC = rc < # < pl = p この方法により、'4.1' と '4.1.2' のようなバージョンの違いだけではなく PHP 固有の開発ステータスの違いも判断することが可能となります。

パラメータ

version1

最初のバージョン番号。

version2

ふたつめのバージョン番号。

operator

三番目のオプション引数 operator を指定した場合、 特定の関係を調べることが可能です。指定可能な演算子を以下に示します。 <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne

このパラメータは大文字小文字を区別するので、すべて小文字で指定しなければなりません。

返り値

デフォルトでは、version_compare() の返り値は 最初のバージョンが 2 番目のバージョンより小さい場合に -1、 同じ場合に 0、そして 2 番目のバージョンのほうが小さい場合に 1 となります。

オプションの引数 operator を使用すると、 指定した演算子による関係を満たす場合に TRUE、それ以外の場合に FALSE を返すようになります。

例

以下の例では定数 PHP_VERSION を使用しています。 この定数には、コードを実行している PHP のバージョンが格納されています。

例1 version_compare() の例

<?php
if (version_compare(PHP_VERSION, '6.0.0') >= 0) {
    echo '6.0.0 より新しいバージョンの PHP を使っています。バージョンは ' . PHP_VERSION . " です。\n";
}

if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
    echo '5.3.0 より新しいバージョンの PHP を使っています。バージョンは ' . PHP_VERSION . " です。\n";
}

if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
    echo 'PHP 5 を使っています。バージョンは ' . PHP_VERSION . " です。\n";
}

if (version_compare(PHP_VERSION, '5.0.0', '<')) {
    echo 'PHP 4 を使っています。バージョンは ' . PHP_VERSION . " です。\n";
}
?>

注意

注意:

PHP_VERSION 定数には現在の PHP のバージョンが格納されます。

注意:

プレリリース版 (たとえば 5.3.0-dev など) は、それに対応する正式版 (5.3.0) より小さいとみなされます。

参考

  • phpversion() - 現在の PHP バージョンを取得する
  • php_uname() - PHP が稼動しているオペレーティングシステムに関する情報を返す
  • function_exists() - 指定した関数が定義されている場合に TRUE を返す

zend_logo_guid

(PHP 4, PHP 5)

zend_logo_guid — Zend guid を取得する

説明

string zend_logo_guid ( void )

この関数は、ビルトインされている画像を使って Zend ロゴを表示する際に使用できる ID を返します。

返り値

PHPE9568F35-D428-11d2-A769-00AA001ACF42 を返します。

例

例1 zend_logo_guid() の例

<?php

echo '<img src="' . $_SERVER['PHP_SELF'] .
     '?=' . zend_logo_guid() . '" alt="Zend Logo !" />';

?>

参考

zend_thread_id

(PHP 5)

zend_thread_id — 現在のスレッドの一意な ID を返す

説明

int zend_thread_id ( void )

この関数は、現在のスレッドの一意な ID を返します。

返り値

スレッドの ID を表す整数値を返します。

例

例1 zend_thread_id() の例

<?php
$thread_id = zend_thread_id();

echo 'Current thread id is: ' . $thread_id;
?>

上の例の出力は、 たとえば以下のようになります。

Current thread id is: 7864

注意

注意:

この関数が使用できるのは、PHP を ZTS (Zend Thread Safety) サポートつきのデバッグモード (--enable-debug) でビルドした場合のみです。

zend_version

(PHP 4, PHP 5)

zend_version — 現在の Zend Engine のバージョンを取得する

説明

string zend_version ( void )

現在実行中の Zend Engine のバージョンを含む文字列を返します。

返り値

Zend Engine のバージョン番号を文字列で返します。

例

例1 zend_version() の例

<?php
echo "Zend engine version: " . zend_version();
?>

上の例の出力は、 たとえば以下のようになります。

Zend engine version: 2.2.0

参考

目次

  • assert_options — 様々な assert フラグを設定/取得する
  • assert — assertion が FALSE であるかどうかを調べる
  • dl — 実行時に PHP 拡張モジュールをロードする
  • extension_loaded — ある拡張機能がロードされているかどうかを調べる
  • gc_collect_cycles — すべての既存ガベージサイクルを強制的に収集する
  • gc_disable — 循環参照コレクタを無効にする
  • gc_enable — 循環参照コレクタを有効にする
  • gc_enabled — 循環参照コレクタの状態を返す
  • get_cfg_var — PHP 設定オプションの値を取得する
  • get_current_user — 現在の PHP スクリプトの所有者の名前を取得する
  • get_defined_constants — すべての定数の名前とその値を連想配列として返す
  • get_extension_funcs — あるモジュールの関数名を配列として返す
  • get_include_path — 現在の include_path 設定オプションを取得する
  • get_included_files — include または require で読み込まれたファイルの名前を配列として返す
  • get_loaded_extensions — コンパイル/ロードされている全てのモジュールの名前を配列として返す
  • get_magic_quotes_gpc — magic_quotes_gpc の現在の設定を得る
  • get_magic_quotes_runtime — magic_quotes_runtime の現在アクティブな設定値を取得する
  • get_required_files — get_included_files のエイリアス
  • getenv — 環境変数の値を取得する
  • getlastmod — 最終更新時刻を取得する
  • getmygid — PHP スクリプトの所有者の GID を得る
  • getmyinode — 現在のスクリプトの inode を取得する
  • getmypid — PHP のプロセス ID を取得する
  • getmyuid — PHP スクリプト所有者のユーザー ID を取得する
  • getopt — コマンドライン引数のリストからオプションを取得する
  • getrusage — 現在のリソース使用状況を取得する
  • ini_alter — ini_set のエイリアス
  • ini_get_all — すべての設定オプションを得る
  • ini_get — 設定オプションの値を得る
  • ini_restore — 設定オプションの値を元に戻す
  • ini_set — 設定オプションの値を設定する
  • magic_quotes_runtime — set_magic_quotes_runtime のエイリアス
  • main — main のダミー
  • memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す
  • memory_get_usage — PHP に割り当てられたメモリの量を返す
  • php_ini_loaded_file — 読み込まれた php.ini ファイルのパスを取得する
  • php_ini_scanned_files — 追加の ini ディレクトリにある .ini ファイルのリストを取得する
  • php_logo_guid — ロゴの guid を取得する
  • php_sapi_name — ウェブサーバーと PHP の間のインターフェイスの型を返す
  • php_uname — PHP が稼動しているオペレーティングシステムに関する情報を返す
  • phpcredits — PHP に関するクレジットを出力する
  • phpinfo — PHP の設定情報を出力する
  • phpversion — 現在の PHP バージョンを取得する
  • putenv — 環境変数の値を設定する
  • restore_include_path — include_path 設定オプションの値を元に戻す
  • set_include_path — include_path 設定オプションをセットする
  • set_magic_quotes_runtime — magic_quotes_runtime の現在アクティブな設定をセットする
  • set_time_limit — 実行時間の最大値を制限する
  • sys_get_temp_dir — 一時ファイル用に使用されるディレクトリのパスを返す
  • version_compare — ふたつの "PHP 標準" バージョン番号文字列を比較する
  • zend_logo_guid — Zend guid を取得する
  • zend_thread_id — 現在のスレッドの一意な ID を返す
  • zend_version — 現在の Zend Engine のバージョンを取得する

runkit

導入

runkit 拡張モジュールは、定数・ユーザー定義関数 およびユーザー定義クラスを変更する機能を提供します。 また、独自のスーパーグローバル変数を定義したり、 サンドボックスを利用した組み込みインタプリタの作成も可能です。

このパッケージには、 » classkit パッケージに 取って代わるための機能も含まれています。 ./configure に --enable-runkit=classkit オプションを つけてコンパイルすると、classkit と互換性のある関数や定数を提供します。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

RUNKIT_IMPORT_FUNCTIONS (integer)
runkit_import() のフラグで、 指定したファイルから通常の関数が読み込まれることを示します。
RUNKIT_IMPORT_CLASS_METHODS (integer)
runkit_import() のフラグで、 指定したファイルからクラスメソッドが読み込まれることを示します。
RUNKIT_IMPORT_CLASS_CONSTS (integer)
runkit_import() のフラグで、 指定したファイルからクラス定数が読み込まれることを示します。 このフラグは PHP のバージョン 5.1.0 以降でしか意味を持たないことに 注意しましょう。
RUNKIT_IMPORT_CLASS_PROPS (integer)
runkit_import() のフラグで、 指定したファイルからクラスのプロパティが読み込まれることを示します。
RUNKIT_IMPORT_CLASSES (integer)
runkit_import() のフラグで、 RUNKIT_IMPORT_CLASS_* の論理和（ビット OR）を表します。
RUNKIT_IMPORT_OVERRIDE (integer)
runkit_import() のフラグで、 すでに存在する関数・メソッド・定数 あるいはプロパティが指定された場合に新しい定義で置き換えることを 示します。このフラグが設定されていない場合、すでに定義されている 内容については新しい定義は無視されます。
RUNKIT_ACC_PUBLIC (integer)
runkit_method_add() の PHP5 限定のフラグです。
RUNKIT_ACC_PROTECTED (integer)
runkit_method_add() の PHP5 限定のフラグです。
RUNKIT_ACC_PRIVATE (integer)
runkit_method_add() の PHP5 限定のフラグです。
CLASSKIT_ACC_PUBLIC (integer)
runkit_method_add() の PHP5 限定のフラグです。 classkit 互換モードが有効になっている場合にのみ定義されます。
CLASSKIT_ACC_PROTECTED (integer)
runkit_method_add() の PHP5 限定のフラグです。 classkit 互換モードが有効になっている場合にのみ定義されます。
CLASSKIT_ACC_PRIVATE (integer)
runkit_method_add() の PHP5 限定のフラグです。 classkit 互換モードが有効になっている場合にのみ定義されます。
CLASSKIT_AGGREGATE_OVERRIDE (integer)
classkit_import() の PHP5 限定のフラグです。 classkit 互換モードが有効になっている場合にのみ定義されます。
RUNKIT_VERSION (string)
runkit パッケージのバージョンを定義します。
CLASSKIT_VERSION (string)
runkit パッケージのバージョンを定義します。 classkit 互換モードが有効になっている場合にのみ定義されます。

インストール/設定

目次

要件

定数・関数・クラス・メソッドの変更機能 は、PHP 4 と PHP 5 の全てのリリースで動作します。特別な動作条件はありません。

独自のスーパーグローバル変数 は PHP 4.2.0 以降で使用可能です。

サンドボックスのサポート は、PHP 5.1.0 以降か あるいは TSRM パッチを適用した PHP 5.0.0 が必要です。 どのバージョンの PHP を使用しているかにかかわらず、コンパイル時に --enable-maintainer-zts オプションが必要です。 詳しい情報は、runkit パッケージに含まれる README ファイルを参照ください。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/runkit.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

実行時設定

php.ini の設定により動作が変化します。

Runkit 設定オプション
名前 デフォルト 変更可能 変更履歴
runkit.superglobal "" PHP_INI_PERDIR  
runkit.internal_override "0" PHP_INI_SYSTEM  
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

runkit.superglobal string
スーパーグローバルとして扱いたい変数名の、カンマ区切りのリストです。 これはシステム全体で利用する php.ini ファイルで指定すべきですが、SAPI の設定によってはディレクトリローカルで指定しても動作するかもしれません。

例1 php.ini で runkit.superglobal=_FOO,_BAR と指定した場合のスーパーグローバル

<?php
function show_values() {
  echo "Foo is $_FOO\n";
  echo "Bar is $_BAR\n";
  echo "Baz is $_BAZ\n";
}

$_FOO = 'foo';
$_BAR = 'bar';
$_BAZ = 'baz';

/* foo と bar が表示されるが、baz は表示されない */
show_values();
?>
runkit.internal_override boolean
内部関数の変更/リネーム/削除機能を有効にします。

リソース型

リソース型は定義されていません。

runkit 関数

Runkit_Sandbox

(PECL runkit >= 0.7.0)

Runkit_Sandbox — Runkit Sandbox クラス -- PHP バーチャルマシン

説明

Runkit_Sandbox クラスをインスタンス化すると、 独自のスコープとプログラムスタックを持つ新しいスレッドが生成されます。 コンストラクタに渡すオプションを設定することで、この環境では インタプリタの機能を制限することが可能す。そのため、ユーザーから渡された コードを実行する場合などに、より安全な環境を提供可能です。

注意: サンドボックスのサポート (runkit_lint(), runkit_lint_file(), および Runkit_Sandbox クラスで使用)は、 PHP 5.1.0 以降または特別なパッチを適用した PHP 5.0 でのみ利用可能であり、スレッドセーフを有効にしておく必要があります。 詳細については、runkit パッケージに含まれる README ファイルを参照してください。

コンストラクタ

void Runkit_Sandbox::__construct ([ array $options ] )

options は連想配列で、その中に 以下の ini オプションの組み合わせを格納します。

safe_mode

Runkit_Sandbox クラスをインスタンス化した 外部スクリプトが safe_mode = off と設定されている 場合、サンドボックス内の safe_mode を on にすることが可能です。 外部スクリプトで safe_mode が有効になっている 場合に、サンドボックス内でそれを無効にすることはできません。

safe_mode_gid

Runkit_Sandbox クラスをインスタンス化した 外部スクリプトが safe_mode_gid = on と設定されている 場合、サンドボックス内の safe_mode_gid を off にすることが可能です。 外部スクリプトで safe_mode_gid が無効になっている 場合に、サンドボックス内でそれを有効にすることはできません。

safe_mode_include_dir

Runkit_Sandbox クラスをインスタンス化した 外部スクリプトが safe_mode_include_dir を 組み込んで configure されていた場合、サンドボックス内の safe_mode_include_dir を定義されているディレクトリ以下に指定することが 可能です。この機能を無効にすることを示すため、safe_mode_include_dir をクリアすることも可能です。 外部スクリプトで safe_mode_include_dir が空白になっているが safe_mode は有効でない場合、任意の safe_mode_include_dir を 指定して safe_mode を on にすることが可能です。

open_basedir

open_basedir は、カレントの open_basedir 以下の任意のパスを指定可能です。 グローバルスコープで open_basedir が指定されていない場合、それはルートディレクトリと判断され、 どの場所でも指定可能となります。

allow_url_fopen

safe_mode と同様、より厳しくする方向にのみ 指定可能です。この場合は TRUE と指定されている場合に FALSE を 指定することが可能となります。

disable_functions

サンドボックス内のインタプリタで無効とする関数を、カンマ区切りの リストで指定します。現在すでに無効になっている関数名を含める必要は ありません。それらはリストに載っているか否かにかかわらず無効となります。

disable_classes

サンドボックス内のインタプリタで無効とするクラスを、カンマ区切りの リストで指定します。現在すでに無効になっているクラス名を含める必要は ありません。それらはリストに載っているか否かにかかわらず無効となります。

runkit.superglobal

サンドボックス内のインタプリタでスーパーグローバルとして扱う変数を、 カンマ区切りのリストで指定します。これらの変数は、既に内部で 定義されている変数やグローバルの runkit.superglobal 設定に 追加して使用されます。

runkit.internal_override

Ini オプション runkit.internal_override は、 サンドボックス内では無効になる（そして、再度有効にはならない） かもしれません。

例1 機能を制限したサンドボックスのインスタンス化

<?php
$options = array(
  'safe_mode'=>true,
  'open_basedir'=>'/var/www/users/jdoe/',
  'allow_url_fopen'=>'false',
  'disable_functions'=>'exec,shell_exec,passthru,system',
  'disable_classes'=>'myAppClass');
$sandbox = new Runkit_Sandbox($options);
/* 制限されていない ini 項目は、普通に設定できる */
$sandbox->ini_set('html_errors',true);
?>

変数へのアクセス

サンドボックス環境内のすべてのグローバル変数は、サンドボックス オブジェクトのプロパティとしてアクセス可能です。しかし、 オブジェクト変数やリソース変数はインタプリタ越しに 利用することができないことに注意しましょう。これは、これらの 2 つのスレッドのメモリ管理が仮想マシン上で行われていることが原因です。 さらに、配列はすべてディープコピーされ、参照渡しのデータは 失われます。つまり、参照渡しのデータをインタプリタ越しに使用することは できないということです。

例2 サンドボックス内部の変数の扱い

<?php
$sandbox = new Runkit_Sandbox();

$sandbox->foo = 'bar';
$sandbox->eval('echo "$foo\n"; $bar = $foo . "baz";');
echo "{$sandbox->bar}\n";
if (isset($sandbox->foo)) unset($sandbox->foo);
$sandbox->eval('var_dump(isset($foo));');
?>

上の例の出力は以下となります。

bar
barbaz
bool(false)

PHP 関数のコール

サンドボックス内で定義されている関数は、すべてサンドボックス オブジェクトのメソッドとしてコールできます。これには、擬似関数として 扱われる以下のような言語構造も含みます。eval()、 include、include_once、 require、require_once、 echo、print、 die() および exit()。

例3 サンドボックス内の関数のコール

<?php
$sandbox = new Runkit_Sandbox();

echo $sandbox->str_replace('a','f','abc');
?>

上の例の出力は以下となります。

fbc

サンドボックス内の関数への引数は、外部の PHP インスタンスから 渡されます。もしサンドボックスのスコープから引数を渡したい場合は、 上で示したようにサンドボックスのプロパティとしてそれにアクセスする ようにしてください。

例4 サンドボックス内の関数に引数を渡す

<?php
$sandbox = new Runkit_Sandbox();

$foo = 'bar';
$sandbox->foo = 'baz';
echo $sandbox->str_replace('a',$foo,'a');
echo $sandbox->str_replace('a',$sandbox->foo,'a');
?>

上の例の出力は以下となります。

bar
baz

サンドボックス設定の変更

runkit バージョン 0.5 以降では、配列へのアクセスと同じ構文で、 実行時にサンドボックスの一部の設定を変更することが可能です。 active は読み込み専用で、現在の状態に ついての情報を提供します。output_handler は通常の配列オフセットと同様に読み書きが可能です。 将来的には書き込み専用の設定項目も現れるかもしれませんが、 今のところはそのような項目はありません。

サンドボックス設定 / 状態のインジケータ
設定 型 目的 デフォルト
active Boolean (Read Only) サンドボックスが使用可能な状態である場合に TRUE 、 die() や exit() のコールもしくは致命的なエラーなどで リクエストから抜けた状態である場合に FALSE 。 TRUE (Initial)
output_handler Callback 有効なコールバックを指定すると、サンドボックス インスタンスの生成するすべての出力に対してその 関数が適用されます。 サンドボックス出力ハンドラは、システム全体の 出力ハンドラと同じ呼び出し規約に従います。 なし
parent_access Boolean サンドボックスが Runkit_Sandbox_Parent クラスのインスタンスを使用するかどうか。使用するには、 その他の Runkit_Sandbox_Parent 関連の設定を有効にする必要があります。 FALSE
parent_read Boolean サンドボックスが親コンテキストの変数を読み込むかどうか。 FALSE
parent_write Boolean サンドボックスが親コンテキストの変数を変更するかどうか。 FALSE
parent_eval Boolean サンドボックスが親コンテキストの任意のコードを評価する（evaluate） かどうか。危険です。 FALSE
parent_include Boolean サンドボックスが親コンテキストの php ファイルを include するかどうか。 危険です。 FALSE
parent_echo Boolean サンドボックスが親コンテキストのデータを表示する際に、それ自身の 出力ハンドラを回避するかどうか。 FALSE
parent_call Boolean サンドボックスが親コンテキストの関数をコールするかどうか。 FALSE
parent_die Boolean サンドボックスが親コンテキスト（そして自分自身）を終了させるかどうか。 FALSE
parent_scope Integer 親のプロパティに対してどのようなスコープでアクセスするか。 0 == Global scope, 1 == Calling scope, 2 == Scope preceeding calling scope, 3 == The scope before that, etc..., etc... 0 (Global)
parent_scope String parent_scope に文字列値が設定されている場合は、 グローバルスコープの配列変数名を表します。アクセス時にその名前の 変数が存在しない場合は、空の配列が作成されます。変数が存在するが 配列ではない場合は、その変数への参照を含むダミー配列が作成されます。  

Runkit_Sandbox_Parent

(PECL runkit >= 0.7.0)

Runkit_Sandbox_Parent — Runkit 反サンドボックス（Anti-Sandbox）クラス

説明

void Runkit_Sandbox_Parent::__construct ( void )

Runkit_Sandbox クラスが作成した サンドボックス環境から Runkit_Sandbox_Parent クラスのインスタンスを作成し、サンドボックスからその親インスタンスに アクセスするための（管理された）手段を提供します。

注意: サンドボックスのサポート (runkit_lint(), runkit_lint_file(), および Runkit_Sandbox クラスで使用)は、 PHP 5.1.0 以降または特別なパッチを適用した PHP 5.0 でのみ利用可能であり、スレッドセーフを有効にしておく必要があります。 詳細については、runkit パッケージに含まれる README ファイルを参照してください。

Runkit_Sandbox_Parent の機能を有効にするには、 親のコンテキストから各サンドボックス単位で parent_access フラグを有効にする必要があります。

例1 サンドボックスから変数を使用する

<?php
$sandbox = new Runkit_Sandbox();
$sandbox['parent_access'] = true;
?>

親の変数にアクセスする

サンドボックス内の変数へのアクセスと同様、親の変数の読み込みや 親の変数への書き込みが可能です。これは Runkit_Sandbox_Parent クラスのプロパティとして 扱われます。親の変数の読み込みは、parent_read 設定を有効にすることで可能となります（それに加えて、基本となる parent_access の設定も必要です）。 一方、書き込みについては parent_write の設定により 可能となります。

サンドボックス内の変数へのアクセスとは異なり、変数のスコープが グローバルに限定されることはありません。parent_scope を適切な整数値に設定することで、アクティブなコールスタック内で 他のスコープが使用可能です。0（デフォルト）は、グローバルスコープで 変数に直接アクセスします。1 は、サンドボックスのコードが実行された ブロック内のスコープを設定します。それより大きい値を指定した場合、 サンドボックスのコードを実行した関数の呼び出し元を順にたどり、 そのスコープの変数にアクセスしようと試みます。

例2 親の変数にアクセスする

<?php
$php = new Runkit_Sandbox();
$php['parent_access'] = true;
$php['parent_read'] = true;

$test = "Global";

$php->eval('$PARENT = new Runkit_Sandbox_Parent;');

$php['parent_scope'] = 0;
one();

$php['parent_scope'] = 1;
one();

$php['parent_scope'] = 2;
one();

$php['parent_scope'] = 3;
one();

$php['parent_scope'] = 4;
one();

$php['parent_scope'] = 5;
one();

function one() {
    $test = "one()";
    two();
}

function two() {
    $test = "two()";
    three();
}

function three() {
    $test = "three()";
    $GLOBALS['php']->eval('var_dump($PARENT->test);');
}
?>

上の例の出力は以下となります。

string(6) "Global"
string(7) "three()"
string(5) "two()"
string(5) "one()"
string(6) "Global"
string(6) "Global"

親の関数をコールする

適切な設定を有効にすることで、サンドボックスはその親の関数に アクセスすることが可能となります。 parent_call を有効にすると、サンドボックスから 親スコープの全ての関数をコールすることが可能となります。 言語構造については、以下のように個々の設定項目で管理されます。 print および echo は parent_echo を有効にすると使用可能です。 die() および exit() は parent_die を有効にすると使用可能です。 eval() は parent_eval を 有効にすると使用可能です。また while include、include_once、 require および require_once は parent_include を有効にすると使用可能です。

runkit_class_adopt

(PECL runkit >= 0.7.0)

runkit_class_adopt — ある基底クラスを、他のクラスを継承させたクラスに変換する。親クラスの適切なメソッドを追加する

説明

bool runkit_class_adopt ( string $classname , string $parentname )

パラメータ

classname

変換の対象となるクラス。

parentname

継承させる親クラス。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_class_adopt() の例

<?php
class myParent {
  function parentFunc() {
    echo "Parent Function Output\n";
  }
}

class myChild {
}

runkit_class_adopt('myChild','myParent');
myChild::parentFunc();
?>

上の例の出力は以下となります。

Parent Function Output

参考

  • runkit_class_emancipate() - 他のクラスを継承しているクラスから継承関係を解消し、 親クラスから継承しているメソッドを取り除く

runkit_class_emancipate

(PECL runkit >= 0.7.0)

runkit_class_emancipate — 他のクラスを継承しているクラスから継承関係を解消し、 親クラスから継承しているメソッドを取り除く

説明

bool runkit_class_emancipate ( string $classname )

パラメータ

classname

継承関係を解消するクラス。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_class_emancipate() の例

<?php
class myParent {
  function parentFunc () {
    echo "Parent Function Output\n";
  }
}
class myChild extends myParent {
}

myChild::parentFunc();
runkit_class_emancipate('myChild');
myChild::parentFunc();
?>

上の例の出力は以下となります。

Parent Function Output
Fatal error: Call to undefined function:  parentFunc() in example.php on line 12

参考

  • runkit_class_adopt() - ある基底クラスを、他のクラスを継承させたクラスに変換する。親クラスの適切なメソッドを追加する

runkit_constant_add

(PECL runkit >= 0.7.0)

runkit_constant_add — define() と同じだが、クラス定数も指定可能

説明

bool runkit_constant_add ( string $constname , mixed $value )

パラメータ

constname

定義する定数名。グローバル定数を表す文字列、あるいは classname::constname 形式でクラス定数を示す。

value

新しい定数に定義する値。 NULL, Bool, Long, Double, String, あるいは Resource のいずれかの型の値。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

runkit_constant_redefine

(PECL runkit >= 0.7.0)

runkit_constant_redefine — 定義済みの定数を再定義する

説明

bool runkit_constant_redefine ( string $constname , mixed $newvalue )

パラメータ

constname

再定義する定数名。グローバル定数を表す文字列、あるいは classname::constname 形式でクラス定数を示す。

newvalue

定数に新しく設定する値。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

runkit_constant_remove

(PECL runkit >= 0.7.0)

runkit_constant_remove — 定義済みの定数を削除する

説明

bool runkit_constant_remove ( string $constname )

パラメータ

constname

削除する定数名。グローバル定数を表す文字列、あるいは classname::constname 形式でクラス定数を示す。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

runkit_function_add

(PECL runkit >= 0.7.0)

runkit_function_add — 新しい関数を追加する。create_function() と同じ

説明

bool runkit_function_add ( string $funcname , string $arglist , string $code )

パラメータ

funcname

作成する関数の名前。

arglist

カンマ区切りの引数のリスト。

code

関数のコード。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_function_add() の例

<?php
runkit_function_add('testme','$a,$b','echo "The value of a is $a\n"; echo "The value of b is $b\n";');
testme(1,2);
?>

上の例の出力は以下となります。

The value of a is 1
The value of b is 2

参考

runkit_function_copy

(PECL runkit >= 0.7.0)

runkit_function_copy — 関数を別の名前でコピーする

説明

bool runkit_function_copy ( string $funcname , string $targetname )

パラメータ

funcname

既存の関数の名前。

targetname

コピー後の新しい関数の名前。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_function_copy() の例

<?php
function original() {
  echo "In a function\n";
}
runkit_function_copy('original','duplicate');
original();
duplicate();
?>

上の例の出力は以下となります。

In a function
In a function

参考

runkit_function_redefine

(PECL runkit >= 0.7.0)

runkit_function_redefine — 関数の定義を新しい実装で置き換える

説明

bool runkit_function_redefine ( string $funcname , string $arglist , string $code )

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

funcname

再定義する関数の名前。

arglist

再定義後の関数が受け取る引数のリスト。

code

新しい実装コード。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_function_redefine() の例

<?php
function testme() {
  echo "Original Testme Implementation\n";
}
testme();
runkit_function_redefine('testme','','echo "New Testme Implementation\n";');
testme();
?>

上の例の出力は以下となります。

Original Testme Implementation
New Testme Implementation

参考

runkit_function_remove

(PECL runkit >= 0.7.0)

runkit_function_remove — 関数の定義を削除する

説明

bool runkit_function_remove ( string $funcname )

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

funcname

削除する関数の名前。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

runkit_function_rename

(PECL runkit >= 0.7.0)

runkit_function_rename — 関数名を変更する

説明

bool runkit_function_rename ( string $funcname , string $newname )

注意: デフォルトでは、 削除・リネーム・変更が可能なのはユーザー定義関数だけです。組み込み関数を オーバーライドするには、php.ini で runkit.internal_override を有効にする必要があります。

パラメータ

funcname

現在の関数名。

newname

新しい関数名。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

runkit_import

(PECL runkit >= 0.7.0)

runkit_import — ファイルから関数やクラスの定義を読み込み、必要に応じて書き換える

説明

bool runkit_import ( string $filename [, int $flags = RUNKIT_IMPORT_CLASS_METHODS ] )

include と似ていますが、関数やクラスの外部に あるコードは無視されます。 また、flags の設定により、 現在実行中の環境内の既存の関数やクラスを自動的に上書きします。

パラメータ

filename

関数やクラスの定義を読み込むファイル名。

flags

RUNKIT_IMPORT_* 系の定数の論理和。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

runkit_lint_file

(PECL runkit >= 0.7.0)

runkit_lint_file — 指定したファイルの PHP 文法をチェックする

説明

bool runkit_lint_file ( string $filename )

runkit_lint_file() 関数は、指定したファイルの 文法チェック（lint）を行い、スクリプトのエラーをチェックします。 これは、コマンドラインから php -l を実行するのと同じです。

注意: サンドボックスのサポート (runkit_lint(), runkit_lint_file(), および Runkit_Sandbox クラスで使用)は、 PHP 5.1.0 以降または特別なパッチを適用した PHP 5.0 でのみ利用可能であり、スレッドセーフを有効にしておく必要があります。 詳細については、runkit パッケージに含まれる README ファイルを参照してください。

パラメータ

filename

PHP コードを含む、チェック対象のファイル。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

  • runkit_lint() - 指定した PHP コードの文法をチェックする

runkit_lint

(PECL runkit >= 0.7.0)

runkit_lint — 指定した PHP コードの文法をチェックする

説明

bool runkit_lint ( string $code )

runkit_lint() 関数は、指定した PHP コードの 文法チェック（lint）を行い、スクリプトのエラーをチェックします。 これは、コマンドラインから php -l を実行するのと同じですが、 runkit_lint() はファイル名ではなくコードそのものを 受け付けます。

注意: サンドボックスのサポート (runkit_lint(), runkit_lint_file(), および Runkit_Sandbox クラスで使用)は、 PHP 5.1.0 以降または特別なパッチを適用した PHP 5.0 でのみ利用可能であり、スレッドセーフを有効にしておく必要があります。 詳細については、runkit パッケージに含まれる README ファイルを参照してください。

パラメータ

code

チェック対象の PHP コード。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

runkit_method_add

(PECL runkit >= 0.7.0)

runkit_method_add — 指定したクラスに、新しいメソッドを動的に追加する

説明

bool runkit_method_add ( string $classname , string $methodname , string $args , string $code [, int $flags = RUNKIT_ACC_PUBLIC ] )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

classname

メソッドを追加するクラスの名前。

methodname

追加するメソッドの名前。

args

カンマで区切った、新しいメソッドの引数。

code

methodname がコールされた際に 評価されるコード。

flags

作成するメソッドの型。 RUNKIT_ACC_PUBLIC、 RUNKIT_ACC_PROTECTED あるいは RUNKIT_ACC_PRIVATE のいずれか。

注意:

このパラメータは PHP 5 以降でのみ使用されます。なぜなら、それ以前の バージョンでは全てのメソッドが public だからです。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_method_add() の例

<?php
class Example {
    function foo() {
        echo "foo!\n";
    }
}

// Example のオブジェクトを作成
$e = new Example();

// 新しい public メソッドの追加
runkit_method_add(
    'Example',
    'add',
    '$num1, $num2',
    'return $num1 + $num2;',
    RUNKIT_ACC_PUBLIC
);

// 12 + 4 を計算する
echo $e->add(12, 4);
?>

上の例の出力は以下となります。

16

参考

runkit_method_copy

(PECL runkit >= 0.7.0)

runkit_method_copy — あるクラスのメソッドを別のクラスにコピーする

説明

bool runkit_method_copy ( string $dClass , string $dMethod , string $sClass [, string $sMethod ] )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

dClass

メソッドのコピー先のクラス。

dMethod

コピー先のメソッド名。

sClass

メソッドのコピー元のクラス。

sMethod

元のクラスからコピーするメソッドの名前。指定されなかった場合は dMethod と同じであるとみなされます。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_method_copy() の例

<?php
class Foo {
    function example() {
        return "foo!\n";
    }
}

class Bar {
    // 最初は、何もメソッドがない
}

// Foo クラスの example() メソッドを Bar クラスに baz() という名前でコピーする
runkit_method_copy('Bar', 'baz', 'Foo', 'example');

// コピーされた関数の出力
echo Bar::baz();
?>

上の例の出力は以下となります。

foo!

参考

runkit_method_redefine

(PECL runkit >= 0.7.0)

runkit_method_redefine — 指定されたメソッドのコードを動的に変更する

説明

bool runkit_method_redefine ( string $classname , string $methodname , string $args , string $code [, int $flags = RUNKIT_ACC_PUBLIC ] )

注意: この関数は、 現在実行中(もしくはチェーンド)のメソッドを操作することはできません。

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

classname

メソッドを再定義するクラス。

methodname

再定義するメソッドの名前。

args

カンマで区切られた、再定義後のメソッドの引数。

code

methodname がコールされた際に 評価される、新しいコード。

flags

再定義するメソッドの型。 RUNKIT_ACC_PUBLIC、 RUNKIT_ACC_PROTECTED あるいは RUNKIT_ACC_PRIVATE のいずれか。

注意:

このパラメータは PHP 5 以降でのみ使用されます。なぜなら、それ以前の バージョンでは全てのメソッドが public だからです。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_method_redefine() の例

<?php
class Example {
    function foo() {
        return "foo!\n";
    }
}

// Example オブジェクトの作成
$e = new Example();

// Example::foo() の出力（再定義前）
echo "Before: " . $e->foo();

// 'foo' メソッドの再定義
runkit_method_redefine(
    'Example',
    'foo',
    '',
    'return "bar!\n";',
    RUNKIT_ACC_PUBLIC
);

// Example::foo() の出力（再定義後）
echo "After: " . $e->foo();
?>

上の例の出力は以下となります。

Before: foo!
After: bar!

参考

runkit_method_remove

(PECL runkit >= 0.7.0)

runkit_method_remove — 指定したメソッドを動的に削除する

説明

bool runkit_method_remove ( string $classname , string $methodname )

注意: この関数は、 現在実行中(もしくはチェーンド)のメソッドを操作することはできません。

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

classname

メソッドを削除するクラス。

methodname

削除するメソッドの名前。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_method_remove() の例

<?php
class Example {
    function foo() {
        return "foo!\n";
    }
    
    function bar() {
        return "bar!\n";
    }
}

// 'foo' メソッドを削除する
runkit_method_remove(
    'Example',
    'foo'
);

echo implode(' ', get_class_methods('Example'));

?>

上の例の出力は以下となります。

bar

参考

runkit_method_rename

(PECL runkit >= 0.7.0)

runkit_method_rename — 指定したメソッドの名前を動的に変更する

説明

bool runkit_method_rename ( string $classname , string $methodname , string $newname )

注意: この関数は、 現在実行中(もしくはチェーンド)のメソッドを操作することはできません。

警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

パラメータ

classname

メソッド名を変更するクラス。

methodname

変更するメソッドの名前。

newname

変更後のメソッドの名前。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 runkit_method_rename() の例

<?php
class Example {
    function foo() {
        return "foo!\n";
    }
}

// 'foo' メソッドの名前を 'bar' に変更する
runkit_method_rename(
    'Example',
    'foo',
    'bar'
);

// 変更後の関数の出力
echo Example::bar();
?>

上の例の出力は以下となります。

foo!

参考

runkit_return_value_used

(PECL runkit >= 0.8.0)

runkit_return_value_used — 現在の関数の返り値が使用されているかどうかを調べる

説明

bool runkit_return_value_used ( void )

返り値

呼び出し元のスコープで関数の返り値が使用されている場合に TRUE、 それ以外の場合に FALSE を返します。

例

例1 runkit_return_value_used() の例

<?php
function foo() {
  var_dump(runkit_return_value_used());
}

foo();
$f = foo();
?>

上の例の出力は以下となります。

bool(false)
bool(true)

runkit_sandbox_output_handler

(PECL runkit >= 0.7.0)

runkit_sandbox_output_handler — サンドボックス内での出力を取得・処理するための関数を指定する

説明

mixed runkit_sandbox_output_handler ( object $sandbox [, mixed $callback ] )

通常、echo や print などのあらゆる出力は、親のスコープから出力しているかのように出力されます。 しかし、runkit_sandbox_output_handler() を使用すると サンドボックス内の出力（エラーを含む）をサンドボックス外で受け取ることが 可能です。

注意: サンドボックスのサポート (runkit_lint(), runkit_lint_file(), および Runkit_Sandbox クラスで使用)は、 PHP 5.1.0 以降または特別なパッチを適用した PHP 5.0 でのみ利用可能であり、スレッドセーフを有効にしておく必要があります。 詳細については、runkit パッケージに含まれる README ファイルを参照してください。

注意: 非推奨

runkit バージョン 0.5 以降この関数は非推奨となっており、1.0 が リリースされるまでに削除される予定です。指定した Runkit_Sandbox インスタンスの出力ハンドラは、配列オフセット構文を使用して 取得/設定が可能です。この方法について、 Runkit_Sandbox のクラス定義で説明しています。

パラメータ

sandbox

出力の処理を設定する Runkit_Sandbox クラスのインスタンス。

callback

ひとつのパラメータを受け取る関数の名前。 sandbox による出力がこのコールバックに 渡されます。コールバックが返す値は通常通り表示されます。 このパラメータが渡されなかった場合、出力の操作方法は変わりません。 真でない値が渡された場合、出力の操作は無効となり直接表示されます。

返り値

前に定義されていた出力ハンドラコールバックの名前を返します。 ハンドラが定義されていなかった場合は FALSE を返します。

例

例1 出力を変数に送る

<?php
function capture_output($str) {
  $GLOBALS['sandbox_output'] .= $str;

  return '';
}

$sandbox_output = '';

$php = new Runkit_Sandbox();
runkit_sandbox_output_handler($php, 'capture_output');
$php->echo("Hello\n");
$php->eval('var_dump("Excuse me");');
$php->die("I lost myself.");
unset($php);

echo "Sandbox Complete\n\n";
echo $sandbox_output;
?>

上の例の出力は以下となります。

Sandbox Complete

Hello
string(9) "Excuse me"
I lost myself.

runkit_superglobals

(PECL runkit >= 0.7.0)

runkit_superglobals — 登録されているスーパーグローバルを、数値添字の配列で返す

説明

array runkit_superglobals ( void )

返り値

登録されているスーパーグローバルを、数値添字の配列で返します。 スーパーグローバルとは、例えば _GET、_POST、_REQUEST、_COOKIE、_SESSION、_SERVER、_ENV、_FILES などです。

目次

エラー抑制演算子の無効化

導入

scream 拡張モジュールは、 エラー制御演算子 を無効化してすべてのエラーを報告させるようにするものです。 この機能は ini 設定で制御します。

インストール/設定

目次

要件

PHP バージョン 5.2.0 以降に対応しています。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/scream

実行時設定

php.ini の設定により動作が変化します。

scream 設定オプション
名前 デフォルト 変更可能 Changelog
scream.enabled Off PHP_INI_ALL  
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

scream.enabled int

scream を有効にするかどうか。

リソース型

リソース型は定義されていません。

例

目次

scream の効果を示す例

この例は、scream で PHP のエラーハンドラの挙動を変更するものです。

例1 実行時における scream の有効化/無効化

<?php
// エラーが表示されるようにします
ini_set('display_errors', true);
error_reporting(E_ALL);

// scream を無効 (デフォルト) にしてエラーを発生させます
ini_set('scream.enabled', false);
echo "Opening http://example.com/not-existing-file\n";
@fopen('http://example.com/not-existing-file', 'r');

// それでは scream を有効にしてもう一度
ini_set('scream.enabled', true);
echo "Opening http://example.com/not-existing-file\n";
@fopen('http://example.com/another-not-existing-file', 'r');
?>

上の例の出力は、 たとえば以下のようになります。

Opening http://example.com/not-existing-file
Opening http://example.com/not-existing-file

Warning: fopen(http://example.com/another-not-existing-file): failed to open stream: HTTP request failed! HTTP/1.1 404 Not Found in example.php on line 14

注意: 通常は、コードの中で変更するのではなく php.ini 設定ファイル で設定します。

Weak References

導入

Weak references provide a non-intrusive gateway to ephemeral objects. Unlike normal (strong) references, weak references do not prevent the garbage collector from freeing that object. For this reason, an object may be destroyed even though a weak reference to that object still exists. In such conditions, the weak reference seamlessly becomes invalid.

例1 Weakref usage example

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}

unset($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}
?>

上の例の出力は以下となります。

Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/weakref.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

リソース型

リソース型は定義されていません。

The WeakRef class

(PECL weakref >= 0.1.0)

導入

The WeakRef class provides a gateway to objects without preventing the garbage collector from freeing those objects. It also provides a way to turn a weak reference into a strong one.

クラス概要

WeakRef {
/* メソッド */
public Weakref::__construct ([ object $object ] )
public bool Weakref::acquire ( void )
public object Weakref::get ( void )
public bool Weakref::release ( void )
public bool Weakref::valid ( void )
}

例

例1 WeakRef usage example

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new WeakRef($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}

unset($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}
?>

上の例の出力は以下となります。

Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!

Weakref::acquire

(PECL weakref >= 0.1.0)

Weakref::acquire — Acquires a strong reference on that object

説明

public bool Weakref::acquire ( void )

Acquires a strong reference on that object, virtually turning the weak reference into a strong one.

パラメータ

この関数にはパラメータはありません。

返り値

Returns TRUE if the reference was valid and could be turned into a strong reference, FALSE otherwise.

例

例1 Weakref::acquire() example

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

$r1->acquire();

echo "Unsetting o1...\n";
unset($o1);

$o2 = $r1->get();

$r1->release();

echo "Unsetting o2...\n";
unset($o2);
?>

上の例の出力は以下となります。

Unsetting o1...
Unsetting o2...
Destroying object!

例2 Nested acquire/release example

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

echo "Acquiring...\n";
$r1->acquire();

echo "  Unsetting...\n";
unset($o1);

echo "  Acquiring...\n";
$r1->acquire();

echo "    Acquiring...\n";
$r1->acquire();

echo "    Releasing...\n";
$r1->release();

echo "  Releasing...\n";
$r1->release();

echo "Releasing...\n";
$r1->release();

?>

上の例の出力は以下となります。

Acquiring...
  Unsetting...
  Acquiring...
    Acquiring...
    Releasing...
  Releasing...
Releasing...
Destroying object!

参考

Weakref::__construct

(PECL weakref >= 0.1.0)

Weakref::__construct — Constructs a new weak reference

説明

public Weakref::__construct() ([ object $object ] )

Constructs a new weak reference.

パラメータ

object

The object to reference.

返り値

値を返しません。

例

例1 Weakref::__construct() example

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}

unset($o1);

if ($r1->valid()) {
    echo "Object still exists!\n";
    var_dump($r1->get());
} else {
    echo "Object is dead!\n";
}
?>

上の例の出力は以下となります。

Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!

Weakref::get

(PECL weakref >= 0.1.0)

Weakref::get — Returns the object pointed to by the weak reference

説明

public object Weakref::get ( void )

Returns the object pointed to by the weak reference.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the object if the reference is still valid, NULL otherwise.

参考

Weakref::release

(PECL weakref >= 0.1.0)

Weakref::release — Releases a previously acquired reference

説明

public bool Weakref::release ( void )

Releases a previously acquired reference. Potentially turning a strong reference back into a weak reference.

パラメータ

この関数にはパラメータはありません。

返り値

Returns TRUE if the reference was previously acquired and thus could be released, FALSE otherwise.

例

例1 Weakref::release() example

<?php
class MyClass {
    public function __destruct() {
        echo "Destroying object!\n";
    }
}

$o1 = new MyClass;

$r1 = new Weakref($o1);

$r1->acquire();

echo "Unsetting o1...\n";
unset($o1);

$o2 = $r1->get();

$r1->release();

echo "Unsetting o2...\n";
unset($o2);
?>

上の例の出力は以下となります。

Unsetting o1...
Unsetting o2...
Destroying object!

参考

Weakref::valid

(PECL weakref >= 0.1.0)

Weakref::valid — Checks whether the object referenced still exists

説明

public bool Weakref::valid ( void )

Checks whether the object referenced still exists.

パラメータ

この関数にはパラメータはありません。

返り値

Returns TRUE if the object still exists and is thus still accessible via Weakref::get(), FALSE otherwise.

参考

  • Weakref::get() - Returns the object pointed to by the weak reference

目次

The WeakMap class

(PECL weakref >= 0.2.0)

導入

クラス概要

WeakMap implements Countable , ArrayAccess , Iterator , Traversable {
/* メソッド */
public __construct ( void )
public int count ( void )
public mixed current ( void )
public object key ( void )
public void next ( void )
public bool offsetExists ( object $object )
public mixed offsetGet ( object $object )
public void offsetSet ( object $object , mixed $value )
public void offsetUnset ( object $object )
public void rewind ( void )
public bool valid ( void )
}

例

例1 Weakmap usage example

<?php
$wm = new WeakMap();

$o = new StdClass;

class A {
    public function __destruct() {
        echo "Dead!\n";
    }
}

$wm[$o] = new A;

var_dump(count($wm));
echo "Unsetting..\n";
unset($o);
echo "Done\n";
var_dump(count($wm));

上の例の出力は以下となります。

int(1)
Unsetting..
Dead!
Done
int(0)

WeakMap::__construct

(PECL weakref >= 0.2.0)

WeakMap::__construct — Constructs a new map

説明

public WeakMap::__construct ( void )

Constructs a new map.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

WeakMap::count

(PECL weakref >= 0.2.0)

WeakMap::count — Counts the number of live entries in the map

説明

public int WeakMap::count ( void )

Counts the number of live entries in the map.

パラメータ

この関数にはパラメータはありません。

返り値

Returns the number of live entries in the map.

WeakMap::current

(PECL weakref >= 0.2.0)

WeakMap::current — Returns the current value under iteration

説明

public mixed WeakMap::current ( void )

Returns the current value being iterated on in the map.

パラメータ

この関数にはパラメータはありません。

返り値

The value currently being iterated on.

WeakMap::key

(PECL weakref >= 0.2.0)

WeakMap::key — Returns the current key under iteration.

説明

public object WeakMap::key ( void )

Returns the object serving as key in the map, at the current iterating position.

パラメータ

この関数にはパラメータはありません。

返り値

The object key currently being iterated.

WeakMap::next

(PECL weakref >= 0.2.0)

WeakMap::next — Advances to the next map element

説明

public void WeakMap::next ( void )

Advances to the next map element.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

WeakMap::offsetExists

(PECL weakref >= 0.2.0)

WeakMap::offsetExists — Checks whether a certain object is in the map

説明

public bool WeakMap::offsetExists ( object $object )

Checks whether the passed object is referenced in the map.

パラメータ

object

Object to check for.

返り値

Returns TRUE if the object is contained in the map, FALSE otherwise.

WeakMap::offsetGet

(PECL weakref >= 0.2.0)

WeakMap::offsetGet — Returns the value pointed to by a certain object

説明

public mixed WeakMap::offsetGet ( object $object )

Returns the value pointed to by a certain object.

パラメータ

object

Some object contained as key in the map.

返り値

Returns the value associated to the object passed as argument, NULL otherwise.

WeakMap::offsetSet

(PECL weakref >= 0.2.0)

WeakMap::offsetSet — Updates the map with a new key-value pair

説明

public void WeakMap::offsetSet ( object $object , mixed $value )

Updates the map with a new key-value pair. If the key already existed in the map, the old value is replaced with the new.

パラメータ

object

The object serving as key of the key-value pair.

value

The arbitrary data serving as value of the key-value pair.

返り値

値を返しません。

WeakMap::offsetUnset

(PECL weakref >= 0.2.0)

WeakMap::offsetUnset — Removes an entry from the map

説明

public void WeakMap::offsetUnset ( object $object )

Removes an entry from the map.

パラメータ

object

The key object to remove from the map.

返り値

値を返しません。

WeakMap::rewind

(PECL weakref >= 0.2.0)

WeakMap::rewind — Rewinds the iterator to the beginning of the map

説明

public void WeakMap::rewind ( void )

Rewinds the iterator to the beginning of the map.

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

WeakMap::valid

(PECL weakref >= 0.2.0)

WeakMap::valid — Returns whether the iterator is still on a valid map element

説明

public bool WeakMap::valid ( void )

Returns whether the iterator is still on a valid map element.

パラメータ

この関数にはパラメータはありません。

返り値

Returns TRUE if the iterator is on a valid element that can be accessed, FALSE otherwise.

目次

PHP 用の Windows キャッシュ

導入

Windows Cache Extension for PHP は、PHP のアクセラレータです。 Windows および Windows サーバー上での PHP アプリケーションの動作速度を向上させます。 Windows Cache Extension for PHP を有効にして PHP エンジンに読み込むと、 PHP アプリケーションのコードに一切手を加えずに恩恵を受けることができます。

Windows Cache Extension には 5 種類のキャッシュが含まれています。 それぞれのキャッシュ型の目的と利点を以下にまとめました。

  • PHP Opcode キャッシュ - PHP はスクリプト処理エンジンです。 テキストや PHP の命令からなるデータストリームを入力として読み込み、 別の形式 (通常は HTML 形式) のデータストリームを生成します。 つまり、ウェブクライアントからのリクエストを受け取るたびに、 PHP エンジンが PHP スクリプトの読み込みとパース、コンパイルそして実行を行っているわけです。 読み込み、パースそしてコンパイルはウェブサーバーの CPU やファイルシステムに負荷をかけ、 PHP ウェブアプリケーション全体のパフォーマンスに影響を及ぼします。 PHP バイトコード (opcode) キャッシュを使うと、コンパイル済みのスクリプトのバイトコードを共有メモリに置きます。 同じスクリプトが再びリクエストされたときには、PHP エンジンはこのバイトコードを再利用します。

  • ファイルキャッシュ - PHP opcode のキャッシュを有効にしたとしても、 PHP エンジンはファイルシステム上のスクリプトファイルにアクセスしなければなりません。 PHP のスクリプトをリモートの UNC ファイル共有に置いている場合には、 ファイル操作はパフォーマンス面での深刻なオーバーヘッドとなります。 Windows Cache Extension for PHP にはファイルキャッシュ機能が組み込まれており、 PHP スクリプトファイルの内容を共有メモリに格納することができます。 これにより、PHP エンジンからのファイルシステム操作の量を減らすことができます。

  • ファイルパス解決キャッシュ - PHP スクリプトでは、 相対ファイルパス指定によるファイル操作やインクルードが頻繁に発生します。 このとき、PHP エンジンは相対パスを絶対パスに変換しなければなりません。 PHP のアプリケーションで、相対パス指定した PHP ファイルへのアクセスが多くなると、 パスの解決がアプリケーションのパフォーマンスに大きな影響を及ぼします。 Windows Cache Extension for PHP のファイルパス解決キャッシュを使うと、 相対パスと絶対パスの対応を保存しておくことができます。 これにより、PHP エンジンが行わなければならないパス解決の量を減らすことができます。

  • ユーザーキャッシュ (バージョン 1.1.0 以降で使用可能) - ユーザーキャッシュ API を使うと、PHP スクリプトから共有メモリキャッシュを使うことができます。 PHP のオブジェクトや変数をユーザーキャッシュに格納し、 別のリクエストでそれを再利用することができるのです。 これは PHP スクリプトのパフォーマンスを向上させ、 複数の PHP プロセスからのデータへのアクセスを共有することができます。

  • セッションハンドラ (バージョン 1.1.0 以降で使用可能) - WinCache セッションハンドラを使うと、PHP のセッションデータを共有メモリキャッシュに置くことができます。 セッションデータの読み書き時のファイルシステム操作が不要になり、 大量のデータを PHP セッションに格納するときのパフォーマンスが向上します。

インストール/設定

目次

要件

この拡張モジュールは、現在は次の構成のみをサポートしています。

Windows OS

  • Windows XP SP3 上での IIS 5.1 および » FastCGI Extension
  • Windows Server 2003 上での IIS 6.0 および » FastCGI Extension
  • Windows Vista SP1 上での IIS 7.0 および FastCGI Module
  • Windows Server 2008 上での IIS 7.0 および FastCGI Module
  • Windows 7 上での IIS 7.5 および FastCGI Module
  • Windows Server 2008 R2 上での IIS 7.5 および FastCGI Module

PHP

  • PHP 5.2.X, Non-thread-safe build
  • PHP 5.3 X86, Non-thread-safe VC9 build

注意: WinCache 拡張モジュールは、IIS の設定で PHP を FastCGI 経由で動かすようにしている場合しか使えません。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/wincache.

この拡張モジュールには二種類のパッケージがあります。PHP 5.2.X 用と PHP 5.3.X 用です。使っている PHP のバージョンにあわせて適切なほうを選びましょう。

この拡張モジュールをインストールする手順は次のとおりです。

  1. どこか一時的な場所にパッケージを展開します。

  2. php_wincache.dll を PHP の拡張モジュール用フォルダにコピーします。 このフォルダは、通常は PHP のバイナリファイルがあるフォルダと同じ場所にあって "ext" という名前です。たとえば C:\Program Files\PHP\ext のようになります。

  3. php.ini ファイルをテキストエディタで開きます。通常は PHP のバイナリファイルと同じ場所にあります。 たとえば C:\Program Files\PHP\php.ini のようになります。

  4. php.ini ファイルの最後に extension = php_wincache.dll という行を追加します。

  5. php.ini ファイルを保存して終了します。

  6. IIS Application Pools for PHP をリサイクルして設定の変更を適用します。 この拡張モジュールが有効になったことを確かめるには、 phpinfo 関数をコールする PHP のコードを書いた phpinfo.php というファイルをつくります。

  7. PHP を使う IIS ウェブサイトのルートフォルダに phpinfo.php を保存し、 http://localhost/phpinfo.php を開きます。そして、表示されたウェブページから wincache というセクションを探します。 拡張モジュールが有効になっていれば、 phpinfo の出力に WinCache の設定項目が含まれるはずです。

注意: 拡張モジュールが有効になっていることを確認し終えたら、忘れずに phpinfo.php をウェブサイトのルートフォルダから削除しておきましょう。

実行時設定

php.ini の設定により動作が変化します。

この表は、WinCache 拡張モジュールが提供する設定項目をまとめたものです。

WinCache の設定オプション
名前 デフォルト 最小 最大 変更可能 変更履歴
wincache.fcenabled "1" "0" "1" PHP_INI_ALL WinCache 1.0.0 以降で使用可能
wincache.fcenabledfilter "NULL" "NULL" "NULL" PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.fcachesize "24" "5" "255" PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.fcndetect "1" "0" "1" PHP_INI_SYSTEM WinCache 1.1.0 以降で使用可能
wincache.maxfilesize "256" "10" "2048" PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.ocenabled "1" "0" "1" PHP_INI_ALL WinCache 1.0.0 以降で使用可能
wincache.ocenabledfilter "NULL" "NULL" "NULL" PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.ocachesize "96" "15" "255" PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.filecount "4096" "1024" "16384" PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.chkinterval "30" "0" "300" PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.ttlmax "1200" "0" "7200" PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.enablecli 0 0 1 PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.ignorelist NULL NULL NULL PHP_INI_ALL WinCache 1.0.0 以降で使用可能
wincache.namesalt NULL NULL NULL PHP_INI_SYSTEM WinCache 1.0.0 以降で使用可能
wincache.ucenabled 1 0 1 PHP_INI_SYSTEM WinCache 1.1.0 以降で使用可能
wincache.ucachesize 8 5 85 PHP_INI_SYSTEM WinCache 1.1.0 以降で使用可能
wincache.scachesize 8 5 85 PHP_INI_SYSTEM WinCache 1.1.0 以降で使用可能
wincache.rerouteini NULL NULL NULL PHP_INI_SYSTEM WinCache 1.2.0 以降で使用可能
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

wincache.fcenabled boolean
ファイルキャッシュ機能を有効あるいは無効にします。
wincache.fcenabledfilter string
ファイルキャッシュ有効あるいは無効にする IIS ウェブサイト識別子の一覧を、 カンマ区切りで指定します。この設定は wincache.fcenabled との組み合わせで機能します。 wincache.fcenabled が 1 の場合は、 wincache.fcenabledfilter のファイルキャッシュが無効になります。 wincache.fcenabled が 0 の場合は wincache.fcenabledfilter のファイルキャッシュが有効になります。
wincache.fcachesize integer
ファイルキャッシュに割り当てる最大メモリ容量 (メガバイト単位) を指定します。 キャッシュされたファイルの総容量がこの設定値を超えると、 いちばん古いファイルから順にファイルキャッシュから取り除かれます。
wincache.fcndetect boolean
ファイルの変更通知検出機能を有効あるいは無効にします。 ファイル変更通知がサポートされているときは、対応するファイルがファイスシステム上で変更されるとすぐに opcode キャッシュおよびファイルキャッシュも更新します。 ファイル変更通知をサポートしていないとき (ネットワークファイル共有を使っている場合など) は、 wincache.chkinterval で指定した間隔ごとに wincache がファイル更新を確認します。
wincache.maxfilesize integer
キャッシュする個々のファイルの最大サイズ (キロバイト単位) を指定します。 この大きさを超えるサイズのファイルはキャッシュされません。 この設定は、ファイルにのみ適用されます。
wincache.ocenabled boolean
opcode キャッシュ機能を有効あるいは無効にします。
wincache.ocenabledfilter string
opcode キャッシュ有効あるいは無効にする IIS ウェブサイト識別子の一覧を、 カンマ区切りで指定します。この設定は wincache.ocenabled との組み合わせで機能します。 wincache.ocenabled が 1 の場合は、 wincache.ocenabledfilter に指定したサイトの opcode キャッシュを無効にします。 wincache.ocenabled が 0 の場合は、 wincache.ocenabledfilter に指定したサイトの opcode キャッシュを有効にします。
wincache.ocachesize integer
opcode キャッシュに割り当てる最大メモリ容量 (メガバイト単位) を指定します。 キャッシュされた opcode の総容量がこの設定値を超えると、 いちばん古い opcode から順に opcode キャッシュから取り除かれます。 opcode キャッシュのサイズは、少なくともファイルキャッシュの三倍以上でなければならないことに注意しましょう。 そうなっていなければ、opcode キャッシュのサイズが自動的に拡張されます。
wincache.filecount integer
この拡張モジュールがどれくらいの数のファイルをキャッシュすることを想定しているのかを指定し、 起動時に適切なサイズのメモリを確保できるようにします。ファイルの数がこの設定値を超えると、 WinCache は必要に応じてさらにメモリを確保します。
wincache.chkinterval integer
ファイルの変更チェックとそれに伴うキャッシュの更新を何秒間隔で行うかを指定します。 0 にすると、キャッシュの更新機能が無効になります。 その場合は、キャッシュエントリが scavenger で削除されたり IIS アプリケーションプールがリサイクルされたり wincache_refresh_if_changed 関数がコールされたりしない限り ファイルの変更がキャッシュに反映されなくなります。
wincache.ttlmax integer
未使用状態のキャッシュエントリの最大生存期間 (秒単位) を定義します。 これを 0 にすると、キャッシュの scavenger を無効にします。 そのため、IIS ワーカープロセスが生き続ける限りキャッシュエントリは削除されなくなります。
wincache.enablecli boolean
PHP がコマンドライン (CLI) モードで動いているときのキャッシュを有効にするかどうかを設定します。
wincache.ignorelist string

この拡張モジュールでキャッシュをしないファイルの一覧を定義します。 ファイルリストにはファイル名のみを指定し、パイプ記号 "|" で区切ります。

例1 wincache.ignorelist の例

wincache.ignorelist = "index.php|misc.php|admin.php"

wincache.namesalt string
この拡張モジュールが使うオブジェクトを共有メモリに格納する際に、 そのオブジェクトの名前に使う文字列を定義します。 IIS ワーカープロセス内の別のアプリケーションとの間で名前の衝突を起こさないようにするために、 これを使います。namesalt 文字列の長さは最大 8 文字までです。
wincache.ucenabled boolean
ユーザーキャッシュ機能を有効あるいは無効にします。
wincache.ucachesize integer
ユーザーキャッシュに割り当てる最大メモリ容量 (メガバイト単位) を指定します。 ユーザーキャッシュに格納された変数のサイズがこの設定値を超えると、 いちばん古い変数から順にキャッシュから取り除かれます。
wincache.scachesize integer
セッションキャッシュに割り当てる最大メモリ容量 (メガバイト単位) を指定します。 セッションキャッシュに格納されたデータのサイズがこの設定値を超えると、 いちばん古いデータから順にキャッシュから取り除かれます。
wincache.rerouteini string
reroute.ini ファイルへの絶対パスあるいは相対パスを指定します。 このファイルには、同等の WinCache 関数で実装を置き換える PHP 関数の一覧を記述します。 相対パスで指定した場合は、php-cgi.exe の場所を基準としたパスとみなします。

WinCache 統計スクリプト

WinCache のインストールパッケージには wincache.php という PHP スクリプトが含まれています。 これを使えば、キャッシュ情報や統計情報を取得することができます。

WinCache 拡張モジュールのインストールを Microsoft Web Platform Installer で行った場合は、このスクリプトの場所は %SystemDrive%\Program Files\IIS\Windows Cache for PHP\ となります。64 ビット版の Windows サーバー OS の場合は %SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP です。拡張モジュールを手動でインストールした場合は、 インストールパッケージを展開した場所と同じフォルダに wincache.php があります。

wincache.php を使うには、 ウェブサイトのルートフォルダあるいはその配下のサブフォルダにこのファイルをコピーします。 スクリプトを保護するために、このファイルをテキストエディタで開いて、定数 USERNAME と PASSWORD の値を変更しましょう。サーバー上で何らかの IIS 認証を有効にしている場合は、 コメントに書かれている指示に従います。

例1 wincache.php 用の認証設定

<?php
/**
 * ======================== CONFIGURATION SETTINGS ==============================
 * If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
 * If you use authentication then replace the default password.
 */
define('USE_AUTHENTICATION', 1);
define('USERNAME', 'wincache');
define('PASSWORD', 'wincache');

/**
 * The Basic PHP authentication will work only when IIS is configured to support 
 * Anonymous Authentication' and nothing else. If IIS is configured to support/use
 * any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
 * In that case use the array below to define the names of users in your 
 * domain/network/workgroup which you want to grant access to.
 */
$user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');

/**
 * If the array contains string 'all', then all the users authenticated by IIS
 * will have access to the page. Uncomment the below line and comment above line
 * to grant access to all users who gets authenticated by IIS.
 */
/* $user_allowed = array('all'); */

/** ===================== END OF CONFIGURATION SETTINGS ========================== */
?>

注意: 組み込みの認証あるいはサーバーの認証機構を使って、常に wincache.php スクリプトを保護するようにしましょう。 このスクリプトを保護せずに放置しておくと、アプリケーションやウェブサーバーを危険にさらすことになってしまいます。

WinCache セッションハンドラ

WinCache セッションハンドラ (WinCache 1.1.0 以降で使用可能) を使うと、 PHP のセッションデータを共有メモリ上のセッションキャッシュに格納できるようになります。 デフォルトのファイル保存方式のかわりに共有メモリを使うことで、 大量のデータをセッションで扱う PHP アプリケーションのパフォーマンスを向上させることができます。 Wincache のセッションキャッシュはファイルをバックに置いた共有メモリなので、 IIS アプリケーションプールをリサイクルするときにもセッションのデータが失われません。

PHP で WinCache セッションハンドラを使うには、php.ini の session.save_handler を wincache にします。デフォルトでは、Windows のテンポラリファイルと同じ場所にセッションデータを保存します。 セッションファイルの場所を変えるには session.save_path ディレクティブを設定します。

例1 WinCache セッションハンドラの有効化

session.save_handler = wincache
session.save_path = C:\inetpub\temp\session\

WinCache 関数への切り替え

WinCache の関数切り替え機能 (WinCache 1.2.0 以降で使用可能) を使うと、 その用途向けに最適化した同等の関数で組み込みの PHP 関数を置き換えることができます。 WinCache 拡張モジュールには、PHP のファイル操作関数を Windows 向けに最適化した実装が含まれています。PHP でネットワーク共有上のファイルにアクセスする必要がある場合などに、 これを使うとアプリケーションのパフォーマンスを向上させることができるでしょう。 最適化した実装が用意されている関数は、次のとおりです。

WinCache の関数切り替え機能を使えるよう設定するには、WinCache のインストールパッケージに含まれている reroute.ini ファイルを使います。このファイルを php.ini があるディレクトリにコピーしましょう。 それから php.ini に wincache.rerouteini の設定を追加し、ここに reroute.ini ファイルへの絶対パスあるいは相対パスを指定します。

例1 WinCache の関数切り替えの有効化

wincache.rerouteini = C:\PHP\reroute.ini

注意: WinCache の関数切り替え機能を使う場合は、ファイルキャッシュのサイズを増やすことを推奨します。 このサイズは wincache.fcachesize を使って設定します。

reroute.ini ファイルには、PHP の関数とそれに対応する WinCache の関数のマッピングを記述します。 ファイルの各行に、次の構文で関数のマッピングを定義します。

<PHP の関数名>:[<関数のパラメータの数>]=<wincache の関数名>

ファイルの例を以下に示します。この例では、PHP の関数 file_get_contents() がコールされると、それが wincache_file_get_contents() へのコールに置き換えられます。 ただし、関数に渡されたパラメータが 2 個以下の場合に限ります。パラメータ数の指定が役立つのは、 置き換え用の関数が元の関数のすべてのパラメータに対応しているわけではないという場合です。

例2 Reroute.ini ファイルの内容

[FunctionRerouteList]
file_exists=wincache_file_exists
file_get_contents:2=wincache_file_get_contents
readfile:2=wincache_readfile
is_readable=wincache_is_readable
is_writable=wincache_is_writable
is_writeable=wincache_is_writable
is_file=wincache_is_file
is_dir=wincache_is_dir
realpath=wincache_realpath
filesize=wincache_filesize

リソース型

リソース型は定義されていません。

定義済み定数

定数は定義されていません。

WinCache 関数

wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — ファイルキャッシュにキャッシュされたファイルについての情報を取得する

説明

array wincache_fcache_fileinfo ([ bool $summaryonly = false ] )

ファイルキャッシュの中身とその利用状況についての情報を取得します。

パラメータ

summaryonly

返される配列に、ファイルキャッシュの概要に加えて個々のキャッシュエントリの情報を含めるかどうか。

返り値

ファイルキャッシュについてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • total_cache_uptime - ファイルキャッシュがアクティブになってからの経過秒数。
  • total_file_count - 現在ファイルキャッシュに入っているファイルの数。
  • total_hit_count - ファイルキャッシュからファイルが取り出された回数。
  • total_miss_count - ファイルがファイルキャッシュに見つからなかった回数。

  • file_entries - キャッシュされているファイルに関する情報を含む配列。

    • file_name - キャッシュされているファイルの絶対パスでのファイル名。
    • add_time - ファイルキャッシュに追加されてからの経過秒数。
    • use_time - ファイルキャッシュ内でアクセスされてからの経過秒数。
    • last_check - ファイルの変更をチェックされてからの経過秒数。
    • hit_count - ファイルがキャッシュから取り出された回数。
    • file_size - キャッシュされたファイルのサイズ (バイト単位)。

例

例1 wincache_fcache_fileinfo() の例

<pre>
<?php
print_r(wincache_fcache_fileinfo());
?>
</pre>

上の例の出力は以下となります。

Array
(   [total_cache_uptime] => 3234
    [total_file_count] => 5
    [total_hit_count] => 0
    [total_miss_count] => 1
    [file_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 1
                    [use_time] => 0
                    [last_check] => 1
                    [hit_count] => 1
                    [file_size] => 2435
                )
            [2] => Array (...iterates for each cached file)
        )
)

参考

wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — ファイルキャッシュのメモリ使用状況についての情報を取得する

説明

array wincache_fcache_meminfo ( void )

ファイルキャッシュによるメモリ使用状況についての情報を取得します。

返り値

ファイルキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - ファイルキャッシュ用に確保されたメモリのバイト数。
  • memory_free - ファイルキャッシュで使える空きメモリのバイト数。
  • num_used_blks - ファイルキャッシュが使っているメモリブロック数。
  • num_free_blks - ファイルキャッシュで使える空きメモリブロック数。
  • memory_overhead - ファイルキャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_fcache_meminfo() の例

<pre>
<?php
print_r(wincache_fcache_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [memory_total] => 134217728
    [memory_free] => 131339120
    [num_used_blks] => 361
    [num_free_blks] => 3
    [memory_overhead] => 5856
)

参考

wincache_lock

(PECL wincache >= 1.1.0)

wincache_lock — 指定したキーで排他ロックを確保する

説明

bool wincache_lock ( string $key [, bool $isglobal = false ] )

指定したキーについての排他ロックを確保します。 ロックを確保するまでは、現在のスクリプトの実行はブロックされます。 ロックを確保できたら、その後は他のスクリプトから同じキーのロックを要求があってもそれをブロックします。 現在のスクリプトが wincache_unlock() でロックを解放するまでは他のスクリプトからロックを確保できません。

警告

wincache_lock() および wincache_unlock() を使っていると、FastCGI のようなマルチプロセス環境において PHP スクリプトがデッドロックを引き起こすことがあります。 本当にそれが必要である場合でない限り、これらの関数は使わないようにしましょう。 キャッシュ上でのさまざまな操作の大半は、これらの関数を使う必要のないものです。

パラメータ

key

ロックを取得したいキャッシュ内のキーの名前。

isglobal

ロックのスコープをシステム全体にするかローカルにするかを制御します。 ローカルロックのスコープは、IIS FastCGI のアプリケーションプール内 あるいは同一の親プロセス ID を持つ PHP プロセス群全体となります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 wincache_lock() の使用

<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (wincache_lock(“lock_txt_lock”)) { // 排他ロックを確保します
    ftruncate($fp, 0); // ファイルを切り詰めます
    fwrite($fp, "Write something here\n");
    wincache_unlock(“lock_txt_lock”); // ロックを解放します
} else {
    echo "Couldn't get the lock!";
}
fclose($fp);
?>

参考

wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — opcode キャッシュにキャッシュされたファイルについての情報を取得する

説明

array wincache_ocache_fileinfo ([ bool $summaryonly = false ] )

opcode キャッシュの中身とその利用状況についての情報を取得します。

パラメータ

summaryonly

返される配列に、opcode キャッシュの概要に加えて個々のキャッシュエントリの情報を含めるかどうか。

返り値

opcode キャッシュについてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • total_cache_uptime - opcode キャッシュがアクティブになってからの経過秒数。
  • total_file_count - 現在 opcode キャッシュに入っているファイルの数。
  • total_hit_count - opcode キャッシュからファイルが取り出された回数。
  • total_miss_count - ファイルが opcode キャッシュに見つからなかった回数。
  • is_local_cache - ローカルキャッシュインスタンスのメタデータである場合は true、 グローバルキャッシュのメタデータである場合は false。

  • file_entries - キャッシュされているファイルに関する情報を含む配列。

    • file_name - キャッシュされているファイルの絶対パスでのファイル名。
    • add_time - opcode キャッシュに追加されてからの経過秒数。
    • use_time - opcode キャッシュ内でアクセスされてからの経過秒数。
    • last_check - ファイルの変更をチェックされてからの経過秒数。
    • hit_count - ファイルがキャッシュから取り出された回数。
    • function_count - キャッシュされたファイル内の関数の数。
    • class_count - キャッシュされたファイルの中のクラスの数。

例

例1 wincache_ocache_fileinfo() の例

<pre>
<?php
print_r(wincache_ocache_fileinfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [total_cache_uptime] => 17357
    [total_file_count] => 121
    [total_hit_count] => 36562
    [total_miss_count] => 201
    [file_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 17356
                    [use_time] => 7
                    [last_check] => 10
                    [hit_count] => 454
                    [function_count] => 0
                    [class_count] => 1
                )
            [2] => Array (...iterates for each cached file)
        )
)

参考

wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — opcode キャッシュのメモリ使用状況についての情報を取得する

説明

array wincache_ocache_meminfo ( void )

opcode キャッシュによるメモリ使用状況についての情報を取得します。

返り値

opcode キャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - opcode キャッシュ用に確保されたメモリのバイト数。
  • memory_free - opcode キャッシュで使える空きメモリのバイト数。
  • num_used_blks - opcode キャッシュが使っているメモリブロック数。
  • num_free_blks - opcode キャッシュで使える空きメモリブロック数。
  • memory_overhead - opcode キャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_ocache_meminfo() の例

<pre>
<?php
print_r(wincache_ocache_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [memory_total] => 134217728
    [memory_free] => 112106972
    [num_used_blks] => 15469
    [num_free_blks] => 4
    [memory_overhead] => 247600
)

参考

wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — キャッシュされたファイルのキャッシュエントリをリフレッシュする

説明

bool wincache_refresh_if_changed ([ array $files ] )

ファイルのキャッシュエントリをリフレッシュします。ファイル名は引数で渡します。 引数を指定しなかった場合は、キャッシュ内のすべてのエントリをリフレッシュします。

パラメータ

files

リフレッシュしたいファイル名の配列。 絶対パスあるいは相対パスのどちらでもかまいません。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

WinCache はキャッシュされたファイルを定期的にチェックし、 もしファイルが変更されていれば、キャッシュ内の対応するエントリを更新します。 デフォルトでは、このチェックは 30 秒おきに行います。 たとえば、ある PHP スクリプトが アプリケーションの設定が書かれている別の PHP スクリプトを更新するような場合、 設定はファイルに保存されているのに アプリケーション側ではキャッシュにある以前の設定を利用するという状況も発生し得ます。 そのような場合は、ファイルが変更されたらすぐにキャッシュをリフレッシュすることを推奨します。 次の例は、これをどのように行うかを示すものです。

例1 wincache_refresh_if_changed() の例

<?php 
$filename = 'C:\inetpub\wwwroot\config.php';
$handle = fopen($filename, 'w+');
if ($handle === FALSE) die('Failed to open file '.$filename.' for writing');
fwrite($handle, '<?php $setting=something; ?>');
fclose($handle);
wincache_refresh_if_changed(array($filename));
?>

参考

wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — ファイルパス解決キャッシュについての情報を取得する

説明

array wincache_rplist_fileinfo ([ bool $summaryonly = false ] )

相対ファイルパスとそれに対応する絶対ファイルパスとの対応を記録したキャッシュについての情報を取得します。

返り値

ファイルパス解決キャッシュについてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • total_file_count - キャッシュに格納されたファイルパスのマッピングの数。

  • rplist_entries - キャッシュされたすべてのファイルパスに関する情報を含む配列。

    • resolve_path - ファイルへのパス。
    • subkey_data - 対応する絶対パス。

例

例1 wincache_rplist_fileinfo() の例

<pre>
<?php
print_r(wincache_rplist_fileinfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [total_file_count] => 5
    [rplist_entries] => Array
        (
            [1] => Array
                (
                    [resolve_path] => checkcache.php
                    [subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
                )

            [2] => Array (...iterates for each cached file)
        )
)

参考

wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する

説明

array wincache_rplist_meminfo ( void )

ファイルパス解決キャッシュによるメモリ使用状況についての情報を取得します。

返り値

ファイルパス解決キャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に FALSE を返します

The array returned by this function contains the following elements:

  • memory_total - ファイルパス解決キャッシュ用に確保されたメモリのバイト数。
  • memory_free - ファイルパス解決キャッシュで使える空きメモリのバイト数。
  • num_used_blks - ファイルパス解決キャッシュが使っているメモリブロック数。
  • num_free_blks - ファイルパス解決キャッシュで使える空きメモリブロック数。
  • memory_overhead - ファイルパス解決キャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_rplist_meminfo() の例

<pre>
<?php
print_r(wincache_rplist_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [memory_total] => 9437184
    [memory_free] => 9416744
    [num_used_blks] => 23
    [num_free_blks] => 1
    [memory_overhead] => 416
)

参考

wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — セッションキャッシュにキャッシュされたファイルについての情報を取得する

説明

array wincache_scache_info ([ bool $summaryonly = false ] )

セッションキャッシュの中身とその利用状況についての情報を取得します。

パラメータ

summaryonly

返される配列に、セッションキャッシュの概要に加えて個々のキャッシュエントリの情報を含めるかどうか。

返り値

セッションキャッシュについてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • total_cache_uptime - セッションキャッシュがアクティブになってからの経過秒数。
  • total_item_count - 現在セッションキャッシュに入っている要素の数。
  • is_local_cache - メタデータがローカルキャッシュ用のものである場合に true、 グローバルキャッシュ用のものである場合に false。
  • total_hit_count - キャッシュからファイルが取り出された回数。
  • total_miss_count - ファイルがキャッシュに見つからなかった回数。

  • scache_entries - キャッシュされているアイテムに関する情報を含む配列。

    • key_name - データを保存する際に使うキーの名前。
    • value_type - キーに関連づけて格納する値の型。
    • use_time - セッションキャッシュ内でアクセスされてからの経過秒数。
    • last_check - ファイルの変更をチェックされてからの経過秒数。
    • ttl_seconds - データをキャッシュ内に残す残り時間。0 は無制限。
    • age_seconds - データがキャッシュに追加されてからのおよその経過時間。
    • hitcount - キャッシュからファイルが取り出された回数。

例

例1 wincache_scache_info() の例

<pre>
<?php
print_r(wincache_scache_info());
?>
</pre>

上の例の出力は以下となります。

Array
(
    [total_cache_uptime] => 17357
    [total_file_count] => 121
    [total_hit_count] => 36562
    [total_miss_count] => 201
    [scache_entries] => Array
        (
            [1] => Array
                (
                    [file_name] => c:\inetpub\wwwroot\checkcache.php
                    [add_time] => 17356
                    [use_time] => 7
                    [last_check] => 10
                    [hit_count] => 454
                    [function_count] => 0
                    [class_count] => 1
                )
            [2] => Array (...iterates for each cached file)
        )
)

参考

wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — セッションキャッシュのメモリ使用状況についての情報を取得する

説明

array wincache_scache_meminfo ( void )

セッションキャッシュによるメモリ使用状況についての情報を取得します。

返り値

セッションキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - セッションキャッシュ用に確保されたメモリのバイト数。
  • memory_free - セッションキャッシュで使える空きメモリのバイト数。
  • num_used_blks - セッションキャッシュが使っているメモリブロック数。
  • num_free_blks - セッションキャッシュで使える空きメモリブロック数。
  • memory_overhead - セッションキャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_scache_meminfo() の例

<pre>
<?php
print_r(wincache_scache_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array 
( 
    [memory_total] => 5242880 
    [memory_free] => 5215056 
    [num_used_blks] => 6 
    [num_free_blks] => 3 
    [memory_overhead] => 176
)

参考

wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

説明

bool wincache_ucache_add ( string $key , mixed $value [, int $ttl = 0 ] )
bool wincache_ucache_add ( array $values [, mixed $unused [, int $ttl = 0 ]] )

変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加します。 追加された変数は、有効期限に達するか、 wincache_ucache_delete() あるいは wincache_ucache_clear() で削除されるまではキャッシュに残り続けます。

パラメータ

key

変数を格納するときに、この名前のキーを使います。 同じキーで既に変数が格納されているときは、この関数は失敗して FALSE を返します。 key は大文字小文字を区別します。同じキーがあっても値を上書きしたい場合は wincache_ucache_set() 関数をかわりに使います。 key には name => value のペアの配列を渡すこともできます。 この場合は name がキーとなります。 この形式を使えば複数の値を一度の操作でキャッシュに格納できるので、競合状態になることを防げます。

value

格納したい変数の値。ファイルハンドルのようなリソース型以外のすべてのデータ型をサポートしています。 最初のパラメータが配列の場合は、このパラメータは無視されます。 一般的な指針として、key に配列を渡す場合は value を NULL にしておきましょう。 value がオブジェクト、あるいはオブジェクトを含む配列である場合は、 オブジェクトがシリアライズされます。オブジェクトのシリアライズについての詳細は __sleep() を参照ください。

values

キーと値の連想配列。

ttl

変数のキャッシュ内での生存時間を秒単位で指定します。 ttl で指定した秒数が経過すると、 格納されている変数はキャッシュから削除されます。 このパラメータのデフォルト値は 0 で、これは wincache_ucache_delete() あるいは wincache_ucache_clear() で明示的に削除するまでキャッシュに残り続けることを意味します。

返り値

key が文字列のときは、成功した場合に TRUE、失敗した場合に FALSE を返します。

key が配列のときの返り値は、次のようになります。

  • 配列内のすべての name => value ペアが設定できた場合は、空の配列を返します。
  • 配列内の name => value ペアがひとつも設定できなかった場合は、FALSE を返します。
  • 成功したペアと失敗したペアがある場合は、ユーザーキャッシュへの追加に失敗した name=>value ペアを含む配列を返します。

例

例1 wincache_ucache_add() で key を文字列にする例

<?php
$bar = 'BAR';
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_get('foo'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
string(3) "BAR"

例2 wincache_ucache_add() で key を配列にする例

<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>

上の例の出力は以下となります。

array(0) { } 
array(4) { 
  ["green"]=> int(-1) 
  ["Blue"]=> int(-1) 
  ["yellow"]=> int(-1) 
  ["cyan"]=> int(-1) 
} 
string(1) "6"

参考

wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — 変数を古い値と比較して新しい値を代入する

説明

bool wincache_ucache_cas ( string $key , int $old_value , int $new_value )

指定したキーの変数を old_value と比較し、 マッチした場合はそこに new_value を代入します。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。

old_value

ユーザーキャッシュ内の key が指す変数の古い値。 この値は long 型でなければならず、 それ以外の場合はこの関数は FALSE を返します。

new_value

マッチしたときに key が指す変数に代入する新しい値。 この値は long 型でなければならず、 それ以外の場合はこの関数は FALSE を返します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 wincache_ucache_cas() の使用法

<?php
wincache_ucache_set('counter', 2922);
var_dump(wincache_ucache_cas('counter', 2922, 1));
var_dump(wincache_ucache_get('counter'));
?>

上の例の出力は以下となります。

bool(true) 
int(1)

参考

wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — ユーザーキャッシュの中身全体を削除する

説明

bool wincache_ucache_clear ( void )

ユーザーキャッシュに格納されているすべての値を消去/削除します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 wincache_ucache_clear() の使用法

<?php
wincache_ucache_set('green', 1);
wincache_ucache_set('red', 2);
wincache_ucache_set('orange', 4);
wincache_ucache_set('blue', 8);
wincache_ucache_set('cyan', 16);
$array1 = array('green', 'red', 'orange', 'blue', 'cyan');
var_dump(wincache_ucache_get($array1));
var_dump(wincache_ucache_clear());
var_dump(wincache_ucache_get($array1));
?>

上の例の出力は以下となります。

array(5) { ["green"]=> int(1) 
           ["red"]=> int(2) 
           ["orange"]=> int(4) 
           ["blue"]=> int(8) 
           ["cyan"]=> int(16) } 
bool(true) 
bool(false)

参考

  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — キーに関連づけられた値を減少させる

説明

mixed wincache_ucache_dec ( string $key [, int $dec_by = 1 [, bool &$success ]] )

key に関連づけられた値を、1 あるいは dec_by で指定した数だけ減らします。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。

dec_by

key に関連づけられた変数の減少幅。 浮動小数点数を指定した場合は、最も近い整数に丸められます。 key に関連づけられた変数は long 型でなければならず、 それ以外の場合はこの関数は失敗して FALSE を返します。

success

成功した場合に TRUE、失敗した場合に FALSE が設定されます。

返り値

成功した場合に減少後の値、失敗した場合に FALSE を返します。

例

例1 wincache_ucache_dec() の使用法

<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_dec('counter', 2923, $success));
var_dump($success);
?>

上の例の出力は以下となります。

int(2922) 
bool(true)

参考

wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — 変数をユーザーキャッシュから削除する

説明

bool wincache_ucache_delete ( mixed $key )

key が指す要素をユーザーキャッシュから削除します。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。 key にはキーの配列を指定することもできます。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

key が配列のときは、配列の要素がどれも削除できなかった場合に FALSE を返します。それ以外の場合は、削除されたすべてのキーを含む配列を返します。

例

例1 wincache_ucache_delete() で key に文字列を使う例

<?php
wincache_ucache_set('foo', 'bar');
var_dump(wincache_ucache_delete('foo'));
var_dump(wincache_ucache_exists('foo'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

例2 wincache_ucache_delete() で key に配列を使う例

<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'blue', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>

上の例の出力は以下となります。

array(4) { [0]=> string(5) "green" 
           [1]=> string(4) "Blue" 
           [2]=> string(6) "yellow" 
           [3]=> string(4) "cyan" }

例3 wincache_ucache_delete() で key に配列を使い、いくつかの要素の削除に失敗する例

<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('orange', 'red', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>

上の例の出力は以下となります。

array(2) { [0]=> string(6) "yellow" 
           [1]=> string(4) "cyan" }

参考

  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_exists() - 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — 変数がユーザーキャッシュに存在するかどうかを調べる

説明

bool wincache_ucache_exists ( string $key )

指定したキーの変数がユーザーキャッシュに存在するかどうかを調べます。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。

返り値

指定したキーの変数が存在する場合に TRUE、 それ以外の場合に FALSE を返します。

例

例1 wincache_ucache_exists() の使用法

<?php
if (!wincache_ucache_exists('green'))
    wincache_ucache_set('green', 1);
var_dump(wincache_ucache_exists('green'));
?>

上の例の出力は以下となります。

bool(true)

参考

  • wincache_ucache_set() - 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_ucache_add() - 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_get() - ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_clear() - ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_delete() - 変数をユーザーキャッシュから削除する
  • wincache_ucache_meminfo() - ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_info() - ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — ユーザーキャッシュに格納された変数を取得する

説明

mixed wincache_ucache_get ( mixed $key [, bool &$success ] )

ユーザーキャッシュに格納された変数を取得します。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。 key にはキーの配列を指定することもできます。 その場合の返り値は、key 配列の各要素の値の配列となります。 オブジェクト、あるいはオブジェクトを含む配列が返されるときには、 オブジェクトがデシリアライズされます。シリアライズしたオブジェクトの復元についての詳細は __wakeup() を参照ください。

success

成功した場合に TRUE、失敗した場合に FALSE が設定されます。

返り値

key が文字列のときは、そのキーに格納された変数の値を返します。 success には、成功した場合に TRUE、 失敗した場合に FALSE が設定されます。

key が配列のときは、success には常に TRUE が設定されます。返される配列 (name => value のペア) には、取得に成功したペアだけが含まれます。指定したキーがひとつもユーザーキャッシュから見つからなかった場合は 空の配列を返します。

例

例1 wincache_ucache_get() で key に文字列を使う例

<?php
wincache_ucache_add('color', 'blue');
var_dump(wincache_ucache_get('color', $success));
var_dump($success);
?>

上の例の出力は以下となります。

string(4) "blue"
bool(true)

例2 wincache_ucache_get() で key に配列を使う例

<?php
$array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'Blue', 'yellow', 'cyan');
var_dump(wincache_ucache_get($array2, $success));
var_dump($success);
?>

上の例の出力は以下となります。

array(4) { ["green"]=> string(1) "5" 
           ["Blue"]=> string(1) "6" 
           ["yellow"]=> string(1) "7" 
           ["cyan"]=> string(1) "8" } 
bool(true)

参考

wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — キーに関連づけられた値を増加させる

説明

mixed wincache_ucache_inc ( string $key [, int $inc_by = 1 [, bool &$success ]] )

key に関連づけられた値を、1 あるいは inc_by で指定した数だけ増やします。

パラメータ

key

変数をキャッシュに格納するときに使ったキーの名前。 key は大文字小文字を区別します。

inc_by

key に関連づけられた変数の増加幅。 浮動小数点数を指定した場合は、最も近い整数に丸められます。 key に関連づけられた変数は long 型でなければならず、 それ以外の場合はこの関数は失敗して FALSE を返します。

success

成功した場合に TRUE、失敗した場合に FALSE が設定されます。

返り値

成功した場合に増加後の値、失敗した場合に FALSE を返します。

例

例1 wincache_ucache_inc() の使用法

<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_inc('counter', 2921, $success));
var_dump($success);
?>

上の例の出力は以下となります。

int(2922) 
bool(true)

参考

wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

説明

array wincache_ucache_info ([ bool $summaryonly = false [, string $key ]] )

ユーザーキャッシュに格納されたデータについての情報を取得します。

パラメータ

summaryonly

返される配列に、ユーザーキャッシュの概要に加えて個々のキャッシュエントリの情報を含めるかどうか。

key

ユーザーキャッシュ内のエントリのキー。 これを指定すると、返される配列にはそのキャッシュエントリの情報だけを含むようになります。 これを指定せず、さらに summaryonly が FALSE の場合は、 返される配列にはキャッシュ内のすべてのエントリについての情報を含むようになります。

返り値

ユーザーキャッシュについてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • total_cache_uptime - ユーザーキャッシュがアクティブになってからの経過秒数。
  • total_item_count - 現在ユーザーキャッシュに入っている要素の数。
  • is_local_cache - メタデータがローカルキャッシュ用のものである場合に true、 グローバルキャッシュ用のものである場合に false。
  • total_hit_count - キャッシュからファイルが取り出された回数。
  • total_miss_count - ファイルがキャッシュに見つからなかった回数。

  • ucache_entries - キャッシュされているアイテムに関する情報を含む配列。

    • key_name - データを保存する際に使うキーの名前。
    • value_type - キーに関連づけて格納する値の型。
    • use_time - ユーザーキャッシュ内でアクセスされてからの経過秒数。
    • last_check - ファイルの変更をチェックされてからの経過秒数。
    • is_session - indicates if the data is a session variable
    • ttl_seconds - データをキャッシュ内に残す残り時間。0 は無制限。
    • age_seconds - データがキャッシュに追加されてからのおよその経過時間。
    • hitcount - キャッシュからファイルが取り出された回数。

例

例1 wincache_ucache_info() の使用

<?php
wincache_ucache_get('green');
wincache_ucache_set('green', 2922);
wincache_ucache_get('green');
wincache_ucache_get('green');
wincache_ucache_get('green');
print_r(wincache_ucache_info());
?>

上の例の出力は以下となります。

Array 
( ["total_cache_uptime"] => int(0)
  ["is_local_cache"] => bool(false)
  ["total_item_count"] => int(1) 
  ["total_hit_count"] => int(3) 
  ["total_miss_count"] => int(1) 
  ["ucache_entries"] => Array(1) 
    ( [1] => Array(6)
      ( 
        ["key_name"] => string(5) "green"
        ["value_type"] => string(4) "long" 
        ["is_session"] => int(0) 
        ["ttl_seconds"] => int(0)
        ["age_seconds"] => int(0)
        ["hitcount"] => int(3) 
       ) 
    ) 
)

参考

wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — ユーザーキャッシュのメモリ使用状況についての情報を取得する

説明

array wincache_ucache_meminfo ( void )

ユーザーキャッシュによるメモリ使用状況についての情報を取得します。

返り値

ユーザーキャッシュのメモリ使用状況についてのメタデータの配列を返します。失敗した場合に FALSE を返します

この関数が返す配列には次の要素が含まれます。

  • memory_total - ユーザーキャッシュ用に確保されたメモリのバイト数。
  • memory_free - ユーザーキャッシュで使える空きメモリのバイト数。
  • num_used_blks - ユーザーキャッシュが使っているメモリブロック数。
  • num_free_blks - ユーザーキャッシュで使える空きメモリブロック数。
  • memory_overhead - ユーザーキャッシュが内部的に使っているメモリのバイト数。

例

例1 wincache_ucache_meminfo() の例

<pre>
<?php
print_r(wincache_ucache_meminfo());
?>
</pre>

上の例の出力は以下となります。

Array 
( 
    [memory_total] => 5242880 
    [memory_free] => 5215056 
    [num_used_blks] => 6 
    [num_free_blks] => 3 
    [memory_overhead] => 176
)

参考

wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする

説明

bool wincache_ucache_set ( mixed $key , mixed $value [, int $ttl = 0 ] )
bool wincache_ucache_set ( array $values [, mixed $unused [, int $ttl = 0 ]] )

変数をユーザーキャッシュに追加します。変数が既にキャッシュに存在する場合はそれを上書きします。 追加あるいは更新された変数は、有効期限に達するか、 wincache_ucache_delete() あるいは wincache_ucache_clear() で削除されるまではキャッシュに残り続けます。

パラメータ

key

変数を格納するときに、この名前のキーを使います。 同じキーで既に変数が格納されているときは、元の値を新しい値で上書きします。 key には name => value のペアの配列を渡すこともできます。 この場合は name がキーとなります。 この形式を使えば複数の値を一度の操作でキャッシュに格納できるので、競合状態になることを防げます。

value

格納したい変数の値。ファイルハンドルのようなリソース型以外のすべてのデータ型をサポートしています。 最初のパラメータが配列の場合は、このパラメータは無視されます。 一般的な指針として、key に配列を渡す場合は value を NULL にしておきましょう。 value がオブジェクト、あるいはオブジェクトを含む配列である場合は、 オブジェクトがシリアライズされます。オブジェクトのシリアライズについての詳細は __sleep() を参照ください。

values

キーと値の連想配列。

ttl

変数のキャッシュ内での生存時間を秒単位で指定します。 ttl で指定した秒数が経過すると、 格納されている変数はキャッシュから削除されます。 このパラメータのデフォルト値は 0 で、これは wincache_ucache_delete() あるいは wincache_ucache_clear() で明示的に削除するまでキャッシュに残り続けることを意味します。

返り値

key が文字列のときは、成功した場合に TRUE、失敗した場合に FALSE を返します。

key が配列のときの返り値は、次のようになります。

  • 配列内のすべての name => value ペアが設定できた場合は、空の配列を返します。
  • 配列内の name => value ペアがひとつも設定できなかった場合は、FALSE を返します。
  • 成功したペアと失敗したペアがある場合は、ユーザーキャッシュへの追加に失敗した name=>value ペアを含む配列を返します。

例

例1 wincache_ucache_set() で key を文字列にする例

<?php
$bar = 'BAR';
var_dump(wincache_ucache_set('foo', $bar));
var_dump(wincache_ucache_get('foo'));
$bar1 = 'BAR1';
var_dump(wincache_ucache_set('foo', $bar1));
var_dump(wincache_ucache_get('foo'));
?>

上の例の出力は以下となります。

bool(true)
string(3) "BAR"
bool(true)
string(3) "BAR1"

例2 wincache_ucache_set() で key を配列にする例

<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>

上の例の出力は以下となります。

array(0) {}
array(0) {}
string(1) "6"

参考

wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — 指定したキーの排他ロックを解放する

説明

bool wincache_unlock ( string $key )

指定したキーに対して、wincache_lock() を使って取得した排他ロックを解放します。 別のプロセスがこのキーに対するロックをブロックされて待機している場合は、 そのプロセスがロックを取得できるようになります。

警告

wincache_lock() および wincache_unlock() を使っていると、FastCGI のようなマルチプロセス環境において PHP スクリプトがデッドロックを引き起こすことがあります。 本当にそれが必要である場合でない限り、これらの関数は使わないようにしましょう。 キャッシュ上でのさまざまな操作の大半は、これらの関数を使う必要のないものです。

パラメータ

key

ロックを解放したいキャッシュ内のキーの名前。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 wincache_unlock() の使用

<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (wincache_lock(“lock_txt_lock”)) { // 排他ロックを確保します
    ftruncate($fp, 0); // ファイルを切り詰めます
    fwrite($fp, "Write something here\n");
    wincache_unlock(“lock_txt_lock”); // ロックを解放します
} else {
    echo "Couldn't get the lock!";
}
fclose($fp);
?>

参考

目次

  • wincache_fcache_fileinfo — ファイルキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_fcache_meminfo — ファイルキャッシュのメモリ使用状況についての情報を取得する
  • wincache_lock — 指定したキーで排他ロックを確保する
  • wincache_ocache_fileinfo — opcode キャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ocache_meminfo — opcode キャッシュのメモリ使用状況についての情報を取得する
  • wincache_refresh_if_changed — キャッシュされたファイルのキャッシュエントリをリフレッシュする
  • wincache_rplist_fileinfo — ファイルパス解決キャッシュについての情報を取得する
  • wincache_rplist_meminfo — ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
  • wincache_scache_info — セッションキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_scache_meminfo — セッションキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_add — 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
  • wincache_ucache_cas — 変数を古い値と比較して新しい値を代入する
  • wincache_ucache_clear — ユーザーキャッシュの中身全体を削除する
  • wincache_ucache_dec — キーに関連づけられた値を減少させる
  • wincache_ucache_delete — 変数をユーザーキャッシュから削除する
  • wincache_ucache_exists — 変数がユーザーキャッシュに存在するかどうかを調べる
  • wincache_ucache_get — ユーザーキャッシュに格納された変数を取得する
  • wincache_ucache_inc — キーに関連づけられた値を増加させる
  • wincache_ucache_info — ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
  • wincache_ucache_meminfo — ユーザーキャッシュのメモリ使用状況についての情報を取得する
  • wincache_ucache_set — 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
  • wincache_unlock — 指定したキーの排他ロックを解放する

Windows でのビルド

目次

要件

WinCache 拡張モジュールのビルドには、以下が必要です。

  1. PHP のソースコード
  2. PHP のビルド環境
  3. WinCache のソースコード

最初のふたつについては、 » Windows での PHP のビルド に書かれている手順に従いましょう。

WinCache のソースコードは、 PECL 拡張モジュールをダウンロードする に書かれている指示に従って取得します。

コンパイルおよびビルド

WinCache を Windows OS 上でコンパイル・ビルドする手順は次のとおりです。

  1. PHP のビルドに使うコマンドプロンプトを開く

  2. PHP ソースのルートフォルダに移動する

  3. 次のコマンドを実行する 

    cscript.exe win32\build\buildconf.js

  4. 次のコマンドを実行する 

    configure.bat --help
    この出力には新しいフラグ --enable-wincache が含まれています。

  5. 次のコマンドを実行する 

    configure.js [all options used to build PHP] --enable-wincache
    --enable-wincache は、WinCache 拡張モジュールを正しくビルドするために必要な唯一の追加オプションです。 このオプションは、WinCache をビルドして PHP の dll にスタティックリンクします。 WinCache 拡張モジュールを単体の DLL とｈしてビルドするには、オプション --enable-wincache=shared を指定します。

  6. 次のコマンドを実行する 

    nmake

ビルドの検証

WinCache が正しくビルドできたことを確かめる手順は次のとおりです。

  1. PHP のバイナリがビルドされたフォルダに移動する

  2. 次のコマンドを実行する 

    php.exe -n -d extension=php_wincache.dll -re wincache
    WinCache が正しくビルドされていれば、このコマンドは WinCache がサポートする INI ディレクティブと関数の一覧を出力します。

Hierarchical Profiler

導入

XHProf is a light-weight hierarchical and instrumentation based profiler. During the data collection phase, it keeps track of call counts and inclusive metrics for arcs in the dynamic callgraph of a program. It computes exclusive metrics in the reporting/post processing phase, such as wall (elapsed) time, CPU time and memory usage. A functions profile can be broken down by callers or callees. XHProf handles recursive functions by detecting cycles in the callgraph at data collection time itself and avoiding the cycles by giving unique depth qualified names for the recursive invocations.

XHProf includes a simple HTML based user interface (written in PHP). The browser based UI for viewing profiler results makes it easy to view results or to share results with peers. A callgraph image view is also supported.

XHProf reports can often be helpful in understanding the structure of the code being executed. The hierarchical nature of the reports can be used to determine, for example, what chain of calls led to a particular function getting called.

XHProf supports ability to compare two runs (a.k.a. "diff" reports) or aggregate data from multiple runs. Diff and aggregate reports, much like single run reports, offer "flat" as well as "hierarchical" views of the profile.

Additional documentation can be found via the » facebook xhprof website.

インストール/設定

目次

要件

Although not required, xhprof includes an interface that's written in PHP. It's used to save and display the profiled data in a usable way, where viewing is done via a web browser. So, a PHP enabled web server will likely make the xhprof experience more useful.

There's also a fork of the GUI interface at » http://github.com/preinheimer/xhprof

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/xhprof

実行時設定

php.ini の設定により動作が変化します。

Xhprof 設定オプション
名前 デフォルト 変更可能 変更履歴
xhprof.output_dir "" PHP_INI_ALL  

以下に設定ディレクティブに関する 簡単な説明を示します。

xhprof.output_dir string

Directory used by the default implementation of the iXHProfRuns interface (namely, the XHProfRuns_Default class) for storing XHProf runs.

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

XHPROF_FLAGS_NO_BUILTINS (integer)
Used to skip all built-in (internal) functions.
XHPROF_FLAGS_CPU (integer)
Used to add CPU profiling information to the output.
XHPROF_FLAGS_MEMORY (integer)
Used to add memory profiling information to the output.

例

例1 Xhprof example with the optional GUI

This example starts and stops the profiler, then uses the bundled GUI interface to save and parse the results. In other words, the code from the extension itself ends at the call to xhprof_disable().

<?php
xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);

for ($i = 0; $i <= 1000; $i++) {
    $a = $i * $i;
}

$xhprof_data = xhprof_disable();

$XHPROF_ROOT = "/tools/xhprof/";
include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_lib.php";
include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_runs.php";

$xhprof_runs = new XHProfRuns_Default();
$run_id = $xhprof_runs->save_run($xhprof_data, "xhprof_testing");

echo "http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";

?>

上の例の出力は、 たとえば以下のようになります。

http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing

Xhprof 関数

xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — Stops xhprof profiler

説明

array xhprof_disable ( void )

Stops the profiler, and returns xhprof data from the run.

パラメータ

この関数にはパラメータはありません。

返り値

An array of xhprof data, from the run.

例

例1 xhprof_disable() example

<?php
xhprof_enable();

$foo = strlen("foo bar");

$xhprof_data = xhprof_disable();

print_r($xhprof_data);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [main()==>strlen] => Array
        (
            [ct] => 1
            [wt] => 279
        )

    [main()==>xhprof_disable] => Array
        (
            [ct] => 1
            [wt] => 9
        )

    [main()] => Array
        (
            [ct] => 1
            [wt] => 610
        )

)

xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — Start xhprof profiler

説明

void xhprof_enable ([ int $flags = 0 [, array $options ]] )

Start xhprof profiling.

パラメータ

flags

Optional flags to add additional information to the profiling. See the XHprof constants for further information about these flags, e.g., XHPROF_FLAGS_MEMORY to enable memory profiling.

options

An array of optional options, namely, the 'ignored_functions' option to pass in functions to be ignored during profiling.

返り値

NULL

変更履歴

バージョン 説明
0.9.2 The optional options parameter was added.

例

例1 xhprof_enable() examples

<?php
// 1. elapsed time + memory + CPU profiling; and ignore built-in (internal) functions
xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

// 2. elapsed time profiling; ignore call_user_func* during profiling
xhprof_enable(
    0,
    array('ignored_functions' =>  array('call_user_func',
                                        'call_user_func_array')));
                                       
// 3. elapsed time + memory profiling; ignore call_user_func* during profiling
xhprof_enable(
    XHPROF_FLAGS_MEMORY,
    array('ignored_functions' =>  array('call_user_func',
                                        'call_user_func_array')));
?>

参考

xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — Stops xhprof sample profiler

説明

array xhprof_sample_disable ( void )

Stops the sample mode xhprof profiler, and

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

An array of xhprof sample data, from the run.

例

例1 xhprof_sample_disable() example

<?php
xhprof_sample_enable();

for ($i = 0; $i <= 10000; $i++) {
    $a = strlen($i);
    $b = $i * $a;
    $c = rand();
}

$xhprof_data = xhprof_sample_disable();

print_r($xhprof_data);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [1272935300.800000] => main()
    [1272935300.900000] => main()
)

xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — Description

説明

void xhprof_sample_enable ( void )

Starts profiling in sample mode, which is a lighter weight version of xhprof_enable(). The sampling interval is 0.1 seconds, and samples record the full function call stack. The main use case is when lower overhead is required when doing performance monitoring and diagnostics.

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

この関数にはパラメータはありません。

返り値

NULL

参考

目次

音声フォーマットの操作

ID3 タグ

導入

これらの関数は、ID3 タグの読み込みや操作を行います。 ID3 タグは MP3 ファイルで使用されており、曲のタイトルや 演奏者、アルバム名、ジャンル、年、トラック番号といった情報が 格納されています。

バージョン 0.2 以降では、ID3 v2.2+ タグのテキストフレームを 抽出できるようになりました。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/id3.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

実行時設定

設定ディレクティブは定義されていません。

リソース型

リソース型は定義されていません。

定義済みの定数

ほとんどの id3 関数は、使用時にタグのバージョンを指定したり、タグの バージョンを結果として返したりします。タグのバージョンを指定するには、 これらの定数を使用してください。

ID3_V1_0 (integer)
ID3_V1_0 は、 ID3 V1.0 タグを利用する場合に用います。このタグには title、artist、album、genre、year および comment といったフィールドが含まれます。
ID3_V1_1 (integer)
ID3_V1_1 は、 ID3 V1.1 タグを利用する場合に用います。このタグには v1.0 タグのすべての情報に加えてトラック番号が含まれます。
ID3_V2_1 (integer)
ID3_V2_1 は、 ID3 V2.1 タグを利用する場合に用います。
ID3_V2_2 (integer)
ID3_V2_2 は、 ID3 V2.2 タグを利用する場合に用います。
ID3_V2_3 (integer)
ID3_V2_3 は、 ID3 V2.3 タグを利用する場合に用います。
ID3_V2_4 (integer)
ID3_V2_4 は、 ID3 V2.4 タグを利用する場合に用います。
ID3_BEST (integer)
ID3_BEST は、 どのバージョンのタグを使用するのかを id3 関数自身に決定させる場合に 用います。

ID3 関数

id3_get_frame_long_name

(PECL id3 >= 0.2)

id3_get_frame_long_name — ID3v2 フレームの長い名前を取得する

説明

string id3_get_frame_long_name ( string $frameId )

id3_get_frame_long_name() は、 ID3v2 フレームの長い名前を返します。

パラメータ

frameId

ID3v2 フレーム。

返り値

フレームの長い名前、あるいはエラー時に FALSE を返します。

例

例1 id3_get_frame_long_name() の例

<?php
$longName = id3_get_frame_long_name("TOLY");
echo $longName;
?>

上の例の出力は以下となります。

Original lyricist(s)/text writer(s)

参考

id3_get_frame_short_name

(PECL id3 >= 0.2)

id3_get_frame_short_name — ID3v2 フレームの短い名前を取得する

説明

string id3_get_frame_short_name ( string $frameId )

id3_get_frame_short_name() は、 ID3v2 フレームの短い名前を返します。

パラメータ

frameId

ID3v2 フレーム。

返り値

フレームの短い名前、あるいはエラー時に FALSE を返します。

id3_get_frame_short_name() が返す値は、 id3_get_tag() の返す配列で用いられます。

例

例1 id3_get_frame_short_name() の例

<?php
$shortName = id3_get_frame_short_name("TOLY");
echo $shortName;
?>

上の例の出力は以下となります。

originalLyricist

参考

id3_get_genre_id

(PECL id3 >= 0.1)

id3_get_genre_id — ジャンルの ID を取得する

説明

int id3_get_genre_id ( string $genre )

id3_get_genre_id() は、ジャンルの ID を返します。

パラメータ

genre

ジャンル名を表す文字列。

返り値

ジャンルの ID あるいはエラー時に FALSE を返します。

例

例1 id3_get_genre_id() の例

<?php
$id = id3_get_genre_id("Alternative");
echo $id;
?>

上の例の出力は以下となります。

20

参考

id3_get_genre_list

(PECL id3 >= 0.1)

id3_get_genre_list — 使用可能なジャンルの一覧を取得する

説明

array id3_get_genre_list ( void )

id3_get_genre_list() は、ID3 タグに格納されている すべてのジャンルを配列で返します。この一覧は Eric Kemp によって作成されたもので、後に WinAmp によって拡張されました。

この関数は、選択可能なジャンルの一覧を利用者に提供するのに便利です。 ID3 タグを更新する際には、ジャンルは 0 から 147 までの整数値で 指定しなければなりません。

返り値

ID3 タグに格納されているすべてのジャンルを含む配列を返します。

例

例1 id3_get_genre_list() の例

<?php
$genres = id3_get_genre_list();
print_r($genres);
?>

上の例の出力は以下となります。

Array
(
    [0] => Blues
    [1] => Classic Rock
    [2] => Country
    [3] => Dance
    [4] => Disco
    [5] => Funk
    [6] => Grunge
    [7] => Hip-Hop
    [8] => Jazz
    [9] => Metal
    [10] => New Age
    [11] => Oldies
    [12] => Other
    [13] => Pop
    [14] => R&B
    [15] => Rap
    [16] => Reggae
    [17] => Rock
    [18] => Techno
    [19] => Industrial
    [20] => Alternative
    [21] => Ska
    [22] => Death Metal
    [23] => Pranks
    [24] => Soundtrack
    [25] => Euro-Techno
    [26] => Ambient
    [27] => Trip-Hop
    [28] => Vocal
    [29] => Jazz+Funk
    [30] => Fusion
    [31] => Trance
    [32] => Classical
    [33] => Instrumental
    [34] => Acid
    [35] => House
    [36] => Game
    [37] => Sound Clip
    [38] => Gospel
    [39] => Noise
    [40] => Alternative Rock
    [41] => Bass
    [42] => Soul
    [43] => Punk
    [44] => Space
    [45] => Meditative
    [46] => Instrumental Pop
    [47] => Instrumental Rock
    [48] => Ethnic
    [49] => Gothic
    [50] => Darkwave
    [51] => Techno-Industrial
    [52] => Electronic
    [53] => Pop-Folk
    [54] => Eurodance
    [55] => Dream
    [56] => Southern Rock
    [57] => Comedy
    [58] => Cult
    [59] => Gangsta
    [60] => Top 40
    [61] => Christian Rap
    [62] => Pop/Funk
    [63] => Jungle
    [64] => Native US
    [65] => Cabaret
    [66] => New Wave
    [67] => Psychadelic
    [68] => Rave
    [69] => Showtunes
    [70] => Trailer
    [71] => Lo-Fi
    [72] => Tribal
    [73] => Acid Punk
    [74] => Acid Jazz
    [75] => Polka
    [76] => Retro
    [77] => Musical
    [78] => Rock & Roll
    [79] => Hard Rock
    [80] => Folk
    [81] => Folk-Rock
    [82] => National Folk
    [83] => Swing
    [84] => Fast Fusion
    [85] => Bebob
    [86] => Latin
    [87] => Revival
    [88] => Celtic
    [89] => Bluegrass
    [90] => Avantgarde
    [91] => Gothic Rock
    [92] => Progressive Rock
    [93] => Psychedelic Rock
    [94] => Symphonic Rock
    [95] => Slow Rock
    [96] => Big Band
    [97] => Chorus
    [98] => Easy Listening
    [99] => Acoustic
    [100] => Humour
    [101] => Speech
    [102] => Chanson
    [103] => Opera
    [104] => Chamber Music
    [105] => Sonata
    [106] => Symphony
    [107] => Booty Bass
    [108] => Primus
    [109] => Porn Groove
    [110] => Satire
    [111] => Slow Jam
    [112] => Club
    [113] => Tango
    [114] => Samba
    [115] => Folklore
    [116] => Ballad
    [117] => Power Ballad
    [118] => Rhytmic Soul
    [119] => Freestyle
    [120] => Duet
    [121] => Punk Rock
    [122] => Drum Solo
    [123] => Acapella
    [124] => Euro-House
    [125] => Dance Hall
    [126] => Goa
    [127] => Drum & Bass
    [128] => Club-House
    [129] => Hardcore
    [130] => Terror
    [131] => Indie
    [132] => BritPop
    [133] => Negerpunk
    [134] => Polsk Punk
    [135] => Beat
    [136] => Christian Gangsta
    [137] => Heavy Metal
    [138] => Black Metal
    [139] => Crossover
    [140] => Contemporary C
    [141] => Christian Rock
    [142] => Merengue
    [143] => Salsa
    [144] => Thrash Metal
    [145] => Anime
    [146] => JPop
    [147] => SynthPop
)

参考

id3_get_genre_name

(PECL id3 >= 0.1)

id3_get_genre_name — ジャンル ID に対応する名前を取得する

説明

string id3_get_genre_name ( int $genre_id )

id3_get_genre_name() は、ジャンル ID に対応する名前を返します。

パラメータ

genre_id

0 から 147 までの整数値。

返り値

名前を文字列で返します。

例

例1 id3_get_genre_name() の例

<?php
$genre = id3_get_genre_name(20);
echo $genre;
?>

上の例の出力は以下となります。

Alternative

参考

id3_get_tag

(PECL id3 >= 0.1)

id3_get_tag — ID3 タグに含まれるすべての情報を取得する

説明

array id3_get_tag ( string $filename [, int $version = ID3_BEST ] )

id3_get_tag() は、指定したファイルの ID3 タグに 含まれるすべての情報を取得するために使用されます。

パラメータ

filename

MP3 ファイルへのパス。

ファイル名のかわりに、ストリームリソースを渡すことも可能です。

version

MP3 ファイルがバージョン 1.x およびバージョン 2.x の両方のタグを 含んでいる場合に、タグのバージョンを指定します。

バージョン 0.2 以降、id3_get_tag() は ID3 タグのバージョン 2.2、2.3 および 2.4 にも対応するようになりました。 これらのタグに関する情報を取得するには、2 番目の引数に ID3_V2_2、ID3_V2_3 あるいは ID3_V2_4 のいずれかの定数を指定します。 ID3 v2.x タグは、ID3 v1.x タグに比べてはるかに多くの情報を MP3 ファイルに含めることが可能です。

返り値

title や artist といったキーを含む連想配列を返します。

genre には 0 から 147 までの整数値が格納されています。 id3_get_genre_name() を使用することで、 この数値をジャンル名に変換することが可能です。

例

例1 id3_get_tag() の例

<?php
$tag = id3_get_tag( "path/to/example.mp3" );
print_r($tag);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [title] => DN-38416
    [artist] => Re:\Legion
    [album] => Reflections
    [year] => 2004
    [genre] => 19
)

例2 id3_get_tag() の例

<?php
$tag = id3_get_tag( "path/to/example2.mp3", ID3_V2_3 );
print_r($tag);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [copyright] => Dirty Mac
    [originalArtist] => Dirty Mac
    [composer] => Marcus Gze
    [artist] => Dirty Mac
    [title] => Little Big Man
    [album] => Demo-Tape
    [track] => 5/12
    [genre] => (17)Rock
    [year] => 2001
)

参考

id3_get_version

(PECL id3 >= 0.1)

id3_get_version — ID3 タグのバージョンを取得する

説明

int id3_get_version ( string $filename )

id3_get_version() は、MP3 ファイル内の ID3 タグのバージョンを取得します。

あるファイルが ID3 v1.1 タグを含んでいるのなら、そのファイルは 常に 1.0 タグも含んでいます。というのも、バージョン 1.1 は単に 1.0 を拡張したものであるからです。

パラメータ

filename

MP3 ファイルへのパス。

ファイル名のかわりに、ストリームリソースを渡すことも可能です。

返り値

MP3 ファイル内の ID3 タグのバージョンを返します。 ID3 v1.x のタグおよび v2.x のタグを同時に保持することも可能なので、 この関数の返す値を利用する際には 定義済みの定数 ID3_V1_0、 ID3_V1_1 および ID3_V2 とのビット比較を行わなければなりません。

例

例1 id3_get_version() の例

<?php
$version = id3_get_version( "path/to/example.mp3" );
if ($version & ID3_V1_0) {
    echo "1.x タグを含んでいます\n";
}
if ($version & ID3_V1_1) {
    echo "1.1 タグを含んでいます\n";
}
if ($version & ID3_V2) {
    echo "2.x タグを含んでいます\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

1.x タグを含んでいます
1.1 タグを含んでいます

参考

id3_remove_tag

(PECL id3 >= 0.1)

id3_remove_tag — 既存の ID3 タグを削除する

説明

bool id3_remove_tag ( string $filename [, int $version = ID3_V1_0 ] )

id3_remove_tag() は、ID3 タグに格納されている 情報を削除するために使用されます。

パラメータ

filename

MP3 ファイルへのパス。

ファイル名のかわりに、ストリームリソースを渡すことも可能です。

version

MP3 ファイルにはバージョン 1.x および 2.x のタグを両方含められるので、 ここでタグのバージョンを指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 id3_remove_tag() の例

<?php
$result = id3_remove_tag( "path/to/example.mp3", ID3_V1_0 );
if ($result === true) {
    echo "タグが正常に削除されました\n";
}
?>

ファイルが書き込み可能であり、かつ 1.0 タグを含んでいる場合は この例の出力は次のようになります。 

タグが正常に削除されました

注意

注意: 現時点では id3_remove_tag() がサポートしているのは バージョン 1.0 および 1.1 のみです。ファイルが 1.1 のタグを 含んでいるときに 1.0 のタグを削除しようとすると、この (1.1 の) タグが削除されます。というのも、v1.1 は単に 1.0 を拡張したものだからです。

参考

id3_set_tag

(PECL id3 >= 0.1)

id3_set_tag — ID3 タグに格納されている情報を更新する

説明

bool id3_set_tag ( string $filename , array $tag [, int $version = ID3_V1_0 ] )

id3_set_tag() は、ID3 タグに格納されている情報を 変更するために使用されます。タグが存在しない場合は、新たに追加されます。

パラメータ

filename

MP3 ファイルへのパス。

ファイル名のかわりに、ストリームリソースを渡すことも可能です。

tag

タグのキーと値を含む連想配列。

連想配列の中で使用できるキーは以下のようになります。

連想配列内のキー
キー とりうる値 使用可能なバージョン
title 最大 30 文字までの文字列 v1.0, v1.1
artist 最大 30 文字までの文字列 v1.0, v1.1
album 最大 30 文字までの文字列 v1.0, v1.1
year 4 桁の数値 v1.0, v1.1
genre 0 から 147 までの整数値 v1.0, v1.1
comment 最大 30 文字 (v1.1 では 28 文字) までの文字列 v1.0, v1.1
track 0 から 255 までの整数値 v1.1

version

MP3 ファイルにはバージョン 1.x および 2.x のタグを両方含められるので、 ここでタグのバージョンを指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 id3_set_tag() の例

<?php
$data = array(
              "title" => "Re:Start",
              "artist" => "Re:\Legion",
              "comment" => "A nice track"
             );
$result = id3_set_tag( "path/to/example.mp3", $data, ID3_V1_0 );
if ($result === true) {
    echo "タグが正常に更新されました\n";
}
?>

ファイルが書き込み可能な場合、 この例の出力は次のようになります。 

タグが正常に更新されました

注意

注意: 現時点では id3_set_tag() がサポートしているのは バージョン 1.0 および 1.1 のみです。

参考

目次

KTaglib

導入

KTaglib は、KDE プロジェクトが Amarok などで使っている tablib ライブラリへのオブジェクト指向のバインディングです。 ID3 タグおよび Ogg タグの読み書きを行います。このライブラリは、音声情報にもアクセスすることができます。 このバインディングは、元となっている C++ の API にしたがって作られていますが、 より PHP らしく扱えるように変更が加えられています。

注意:

現時点では、ktaglib は ID3v1 および ID3v2 タグの読み書きが可能です。

インストール/設定

目次

要件

ktaglib をビルドするには、少なくとも taglib 1.5 以降がインストールされている必要があります。 taglib を取得するには » taglib プロジェクトのページ を参照ください。 Windows 用の DLL は taglib を静的に組み込んでビルドされているので、taglib をインストールする必要はありません。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/ktaglib.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

KTaglib ではクラス定数を使用しています。 ほとんどの定数は、Taglib の列挙値や定数に対応しています。

KTaglib_MPEG_Header::Version1 (integer)
ID3 バージョン 1.0
KTaglib_MPEG_Header::Version2 (integer)
ID3 バージョン 2.0
KTaglib_MPEG_Header::Version2_5 (integer)
ID3 バージョン 2.5
KTaglib_ID3v2_AttachedPictureFrame::Other (integer)
Picture type Other
KTaglib_ID3v2_AttachedPictureFrame::FileIcon (integer)
Picture type FileIcon
KTaglib_ID3v2_AttachedPictureFrame::OtherFileIcon (integer)
Picture type OtherFileIcon
KTaglib_ID3v2_AttachedPictureFrame::FrontCover (integer)
Picture type FrontCover
KTaglib_ID3v2_AttachedPictureFrame::BackCover (integer)
Picture type BackCover
KTaglib_ID3v2_AttachedPictureFrame::LeafletPage (integer)
Picture type LeafletPage
KTaglib_ID3v2_AttachedPictureFrame::Media (integer)
Picture type Media
KTaglib_ID3v2_AttachedPictureFrame::LeadArtist (integer)
Picture type LeadArtist
KTaglib_ID3v2_AttachedPictureFrame::Artist (integer)
Picture type Artist
KTaglib_ID3v2_AttachedPictureFrame::Conductor (integer)
Picture type Condutor
KTaglib_ID3v2_AttachedPictureFrame::Band (integer)
Picture type Band
KTaglib_ID3v2_AttachedPictureFrame::Composer (integer)
Picture type Composer
KTaglib_ID3v2_AttachedPictureFrame::Lyricist (integer)
Picture type Lyricist
KTaglib_ID3v2_AttachedPictureFrame::RecordingLocation (integer)
Picture type RecordingLocation
KTaglib_ID3v2_AttachedPictureFrame::DuringRecording (integer)
Picture type DuringRecording
KTaglib_ID3v2_AttachedPictureFrame::DuringPerformance (integer)
Picture type DuringPerformance
KTaglib_ID3v2_AttachedPictureFrame::MovieScreenCapture (integer)
Picture type MovieScreenCapture
KTaglib_ID3v2_AttachedPictureFrame::ColouredFish (integer)
Picture type ColouredFish
KTaglib_ID3v2_AttachedPictureFrame::Illustration (integer)
Picture type Illustration
Picture type BandLogo

KTaglib_MPEG_File クラス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

MPEG ファイルを表します。MPEG には ID3v1、ID3v2 タグと音声プロパティを含めることができます。

Class synopsis

KTaglib_MPEG_File {
/* メソッド */
public KTaglib_MPEG_File getAudioProperties ( void )
public KTaglib_ID3v1_Tag getID3v1Tag ([ bool $create = false ] )
public KTaglib_ID3v2_Tag getID3v2Tag ([ bool $create = false ] )
}

KTaglib_MPEG_File::__construct

(0.0.1)

KTaglib_MPEG_File::__construct — 新しいファイルをオープンする

説明

public KTaglib_MPEG_File::__construct() ( string $filename )

新しい MPEG ファイルをオープンします。

パラメータ

filename

読み込むファイル。

例

例1 新しい MP3 ファイルのオープンと読み込み

<?php
$mpeg = new KTaglib_MPEG_File('example.mp3');
echo $mpeg->getID3v1Tag()->getTitle();
?>

KTaglib_MPEG_File::getAudioProperties

(0.0.1)

KTaglib_MPEG_File::getAudioProperties — 音声プロパティへのアクセス機能を持つオブジェクトを返す

説明

public KTaglib_MPEG_File KTaglib_MPEG_File::getAudioProperties ( void )

mpeg ファイルの音声プロパティへのアクセス機能を持つオブジェクトを返します。

返り値

KTaglib_MPEG_AudioProperties オブジェクトあるいは false を返します。

KTaglib_MPEG_File::getID3v1Tag

(0.0.1)

KTaglib_MPEG_File::getID3v1Tag — ID3v1 タグを表すオブジェクトを返す

説明

public KTaglib_ID3v1_Tag KTaglib_MPEG_File::getID3v1Tag ([ bool $create = false ] )

ID3v1 タグを表すオブジェクトを返します。 これを使用して、ID3v1 タグに関する情報を取得します。

返り値

KTaglib_MPEG_ID3v1Tag オブジェクト、あるいは ID3v1 タグが存在しない場合に false を返します。

KTaglib_MPEG_File::getID3v2Tag

(0.0.1)

KTaglib_MPEG_File::getID3v2Tag — ID3v2 オブジェクトを返す

説明

public KTaglib_ID3v2_Tag KTaglib_MPEG_File::getID3v2Tag ([ bool $create = false ] )

mpeg ファイルの ID3v2 オブジェクトを返します。ID3v2 タグが存在しない場合は KTaglib_TagNotFoundException がスローされます。

返り値

MPEG ファイルの KTaglib_ID3v2_Tag オブジェクト、あるいは ID3v2 タグが存在しない場合に false を返します。

目次

KTaglib_MPEG_AudioProperties クラス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

MPEG ファイルの音声プロパティ、たとえば長さやビットレート、サンプルレートなどを表します。

KTaglib_MPEG_AudioProperties::getBitrate

(0.0.1)

KTaglib_MPEG_AudioProperties::getBitrate — MPEG ファイルのビットレートを返す

説明

public int KTaglib_MPEG_AudioProperties::getBitrate ( void )

MPEG ファイルのビットレートを返します。

返り値

ビットレートを整数値で返します。

KTaglib_MPEG_AudioProperties::getChannels

(0.0.1)

KTaglib_MPEG_AudioProperties::getChannels — MPEG ファイルのチャンネル数を返す

説明

public int KTaglib_MPEG_AudioProperties::getChannels ( void )

MPEG ファイルのチャンネル数を返します。

返り値

チャンネル数を整数値で返します。

KTaglib_MPEG_AudioProperties::getLayer

(0.0.1)

KTaglib_MPEG_AudioProperties::getLayer — MPEG ファイルのレイヤを返す

説明

public int KTaglib_MPEG_AudioProperties::getLayer ( void )

MPEG ファイルのレイヤ (通常は 3 で、これは MP3 を意味します) を返します。

返り値

レイヤを整数値で返します。

KTaglib_MPEG_AudioProperties::getLength

(0.0.1)

KTaglib_MPEG_AudioProperties::getLength — MPEG ファイルの長さを返す

説明

public int KTaglib_MPEG_AudioProperties::getLength ( void )

MPEG ファイルの長さを返します。

返り値

長さを整数値で返します。

KTaglib_MPEG_AudioProperties::getSampleBitrate

(0.0.1)

KTaglib_MPEG_AudioProperties::getSampleBitrate — MPEG ファイルのサンプルビットレートを返す

説明

public int KTaglib_MPEG_AudioProperties::getSampleBitrate ( void )

MPEG ファイルのサンプルビットレートを返します。

返り値

サンプルビットレートを整数値で返します。

KTaglib_MPEG_AudioProperties::getVersion

(0.0.1)

KTaglib_MPEG_AudioProperties::getVersion — MPEG ファイルのバージョンを返す

説明

public int KTaglib_MPEG_AudioProperties::getVersion ( void )

MPEG ファイルヘッダのバージョンを返します。とりうる値は Tag_MPEG_Header で定義されています (バージョン 1、バージョン 2、バージョン 2.5)。

返り値

バージョンを返します。

KTaglib_MPEG_AudioProperties::isCopyrighted

(0.0.1)

KTaglib_MPEG_AudioProperties::isCopyrighted — MPEG ファイルの著作権保護の状態を返す

説明

public bool KTaglib_MPEG_AudioProperties::isCopyrighted ( void )

MPEG ファイルが著作権で保護されている場合に true を返します。

返り値

MPEG ファイルが著作権で保護されている場合に true を返します。

KTaglib_MPEG_AudioProperties::isOriginal

(0.0.1)

KTaglib_MPEG_AudioProperties::isOriginal — ファイルがオリジナルであるかどうかを返す

説明

public bool KTaglib_MPEG_AudioProperties::isOriginal ( void )

ファイルがオリジナルであるとマークされている場合に true を返します。

返り値

ファイルがオリジナルであるとマークされている場合に true を返します。

KTaglib_MPEG_AudioProperties::isProtectionEnabled

(0.0.1)

KTaglib_MPEG_AudioProperties::isProtectionEnabled — MPEG ファイルの保護機構が有効かどうかを返す

説明

public bool KTaglib_MPEG_AudioProperties::isProtectionEnabled ( void )

(DRM のような) 保護機構がこのファイルで有効になっている場合に true を返します。

返り値

(DRM のような) 保護機構がこのファイルで有効になっている場合に true を返します。

目次

KTaglib_Tag クラス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

ID3v1 あるいは ID3v2 タグの基底クラスです。

Class synopsis

KTaglib_Tag {
/* メソッド */
public string getAlbum ( void )
public string getArtist ( void )
public string getComment ( void )
public string getGenre ( void )
public string getTitle ( void )
public int getTrack ( void )
public int getYear ( void )
public bool isEmpty ( void )
}

KTaglib_Tag::getAlbum

(0.0.1)

KTaglib_Tag::getAlbum — ID3 タグからアルバム文字列を返す

説明

public string KTaglib_Tag::getAlbum ( void )

ID3 タグのアルバム文字列を返します。 このメソッドは、ID3v1 および ID3v2 タグで実装されています。

返り値

アルバム文字列を返します。

KTaglib_Tag::getArtist

(0.0.1)

KTaglib_Tag::getArtist — ID3 タグからアーティスト文字列を返す

説明

public string KTaglib_Tag::getArtist ( void )

ID3 タグのアーティスト文字列を返します。 このメソッドは、ID3v1 および ID3v2 タグで実装されています。

返り値

アーティスト文字列を返します。

KTaglib_Tag::getComment

(0.0.1)

KTaglib_Tag::getComment — ID3 タグからコメントを返す

説明

public string KTaglib_Tag::getComment ( void )

ID3 タグのコメントを返します。 このメソッドは、ID3v1 および ID3v2 タグで実装されています。

返り値

コメント文字列を返します。

KTaglib_Tag::getGenre

(0.0.1)

KTaglib_Tag::getGenre — ID3 タグからジャンルを返す

説明

public string KTaglib_Tag::getGenre ( void )

ID3 タグのジャンルを返します。 このメソッドは、ID3v1 および ID3v2 タグで実装されています。

返り値

ジャンル文字列を返します。

KTaglib_Tag::getTitle

(0.0.1)

KTaglib_Tag::getTitle — ID3 タグからタイトル文字列を返す

説明

public string KTaglib_Tag::getTitle ( void )

ID3 タグのタイトル文字列を返します。 このメソッドは、ID3v1 および ID3v2 タグで実装されています。

返り値

タイトル文字列を返します。

KTaglib_Tag::getTrack

(0.0.1)

KTaglib_Tag::getTrack — ID3 タグからトラック番号を返す

説明

public int KTaglib_Tag::getTrack ( void )

ID3 タグのトラック番号を返します。 このメソッドは、ID3v1 および ID3v2 タグで実装されています。

返り値

トラック番号を整数値で返します。

KTaglib_Tag::getYear

(0.0.1)

KTaglib_Tag::getYear — ID3 タグから年を返す

説明

public int KTaglib_Tag::getYear ( void )

ID3 タグの年を返します。 このメソッドは、ID3v1 および ID3v2 タグで実装されています。

返り値

年を整数値で返します。

KTaglib_Tag::isEmpty

(0.0.1)

KTaglib_Tag::isEmpty — タグが空の場合に true を返す

説明

public bool KTaglib_Tag::isEmpty ( void )

タグが存在するけれども中身が空の場合に true を返します。 このメソッドは、ID3v1 および ID3v2 タグで実装されています。

返り値

タグが空の場合に true、それ以外の場合に false を返します。

目次

KTaglib_ID3v2_Tag クラス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

ID3v2 タグを表します。ID3v2 フレームのリストを提供し、 フレームを追加したり削除したりすることができます。

Class synopsis

extends KTaglib_Tag {
/* メソッド */
public bool addFrame ( KTaglib_ID3v2_Frame $frame )
public array getFrameList ( void )
/* 継承したメソッド */
public string KTaglib_Tag::getAlbum ( void )
public string KTaglib_Tag::getArtist ( void )
public string KTaglib_Tag::getComment ( void )
public string KTaglib_Tag::getGenre ( void )
public string KTaglib_Tag::getTitle ( void )
public int KTaglib_Tag::getTrack ( void )
public int KTaglib_Tag::getYear ( void )
public bool KTaglib_Tag::isEmpty ( void )
}

KTaglib_ID3v2_Tag::addFrame

(0.0.1)

KTaglib_ID3v2_Tag::addFrame — フレームを ID3v2 タグに追加する

説明

public bool KTaglib_ID3v2_Tag::addFrame ( KTaglib_ID3v2_Frame $frame )

フレームを ID3v2 タグに追加します。フレームは、有効な KTaglib_ID3v2_Frame オブジェクトでなければなりません。 タグを保存するには、save 関数を実行する必要があります。

返り値

成功した場合に true、それ以外の場合に false を返します。

KTaglib_ID3v2_Tag::getFrameList

(0.0.1)

KTaglib_ID3v2_Tag::getFrameList — ID3v2 フレームの配列に ID3v2 タグを関連付けたものを返す

説明

public array KTaglib_ID3v2_Tag::getFrameList ( void )

ID3v2 フレームの配列に ID3v2 タグを関連付けたものを返します。

返り値

KTaglib_ID3v2_Frame オブジェクトの配列を返します。

目次

The KTaglib_ID3v2_Frame class

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

ID3v2 フレームの基底クラスです。ID3v2 タグはさまざまに特化されたフレームに分割されます。 フレームによっては複数存在できるものもあります。

Class synopsis

extends KTaglib_Tag {
/* メソッド */
public int getSize ( void )
public string __toString ( void )
/* 継承したメソッド */
public string KTaglib_Tag::getAlbum ( void )
public string KTaglib_Tag::getArtist ( void )
public string KTaglib_Tag::getComment ( void )
public string KTaglib_Tag::getGenre ( void )
public string KTaglib_Tag::getTitle ( void )
public int KTaglib_Tag::getTrack ( void )
public int KTaglib_Tag::getYear ( void )
public bool KTaglib_Tag::isEmpty ( void )
}

KTaglib_ID3v2_Frame::getSize

(0.0.1)

KTaglib_ID3v2_Frame::getSize — フレームのサイズをバイト単位で返す

説明

public int KTaglib_ID3v2_Frame::getSize ( void )

フレームのサイズをバイト単位で返します。 ID3v2 フレームがどういうものなのか、どのように定義されているのかについては id3.org を参照ください。

返り値

フレームのサイズをバイト単位で返します。

KTaglib_ID3v2_Frame::__toString

(0.0.1)

KTaglib_ID3v2_Frame::__toString — フレームの文字列表現を返す

説明

public string KTaglib_ID3v2_Frame::__toString ( void )

フレームの文字列表現を返します。通常は単なるフレーム ID だけでしょうが、さらに情報を含むこともあります。 詳細は ktaglib のドキュメントを参照ください。

返り値

フレームの文字列表現を返します。

目次

KTaglib_ID3v2_AttachedPictureFrame クラス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

画像を保持する ID3v2 フレームを表します。

Class synopsis

extends KTaglib_ID3v2_Frame {
/* メソッド */
public string getDescription ( void )
public string getMimeType ( void )
public int getType ( void )
public bool savePicture ( string $filename )
public string getMimeType ( string $type )
public void setPicture ( string $filename )
public void setType ( int $type )
/* 継承したメソッド */
public int KTaglib_ID3v2_Frame::getSize ( void )
public string KTaglib_ID3v2_Frame::__toString ( void )
public string KTaglib_Tag::getAlbum ( void )
public string KTaglib_Tag::getArtist ( void )
public string KTaglib_Tag::getComment ( void )
public string KTaglib_Tag::getGenre ( void )
public string KTaglib_Tag::getTitle ( void )
public int KTaglib_Tag::getTrack ( void )
public int KTaglib_Tag::getYear ( void )
public bool KTaglib_Tag::isEmpty ( void )
}

KTaglib_ID3v2_AttachedPictureFrame::getDescription

(0.0.1)

KTaglib_ID3v2_AttachedPictureFrame::getDescription — 画像フレーム内の画像の説明を返す

説明

public string KTaglib_ID3v2_AttachedPictureFrame::getDescription ( void )

ID3v2.x フレーム内の画像フレームに添付された説明を返します。

返り値

画像フレーム内の画像の説明を返します。

KTaglib_ID3v2_AttachedPictureFrame::getMimeType

(0.2.0)

KTaglib_ID3v2_AttachedPictureFrame::getMimeType — 画像の mime type を返す

説明

public string KTaglib_ID3v2_AttachedPictureFrame::getMimeType ( void )

添付された画像フレームの画像の mime type を返します。

このメソッドはさまざまな型を返すことに注意しましょう。ID3v2.2 では "image/" 以外ではじまる mime type を返すことがありますが、ID3v2.3 および v2.4 では通常は "image/" で始まります。たとえば、IDv2.3 での返り値が "image/png" なのに対して ID3v2.2 のフレームでは単に "PNG" とだけ返すようになります。

添付画像フレームであっても mime type が設定されているとは限りません。 そのため、空文字列が返されることもありえます。

返り値

添付された画像フレームの画像の mime type を返します。

KTaglib_ID3v2_AttachedPictureFrame::getType

(0.2.0)

KTaglib_ID3v2_AttachedPictureFrame::getType — 画像の型を返す

説明

public int KTaglib_ID3v2_AttachedPictureFrame::getType ( void )

画像の型を返します。

ID3v2 の仕様では、AttachedPictureFrame に画像の型を設定することができます。 たとえば FrontCover や FileIcon といったものです。使用できる型の一覧については KTaglib_ID3v2_AttachedPictureFrame クラスの説明を参照ください。

返り値

画像の型を表す整数値を返します。

KTaglib_ID3v2_AttachedPictureFrame::savePicture

(0.0.1)

KTaglib_ID3v2_AttachedPictureFrame::savePicture — 画像をファイルに保存する

説明

public bool KTaglib_ID3v2_AttachedPictureFrame::savePicture ( string $filename )

添付された画像を指定したファイル名で保存します。

返り値

成功した場合に true、それ以外の場合に false を返します。

KTaglib_ID3v2_AttachedPictureFrame::setMimeType

(0.2.0)

KTaglib_ID3v2_AttachedPictureFrame::setMimeType — 画像の mime type を設定する

説明

public string KTaglib_ID3v2_AttachedPictureFrame::getMimeType ( string $type )

画像の mime type を設定します。たいていの場合は "image/png" あるいは "image/jpeg" となります。

KTaglib_ID3v2_AttachedPictureFrame::setPicture

(0.0.1)

KTaglib_ID3v2_AttachedPictureFrame::setPicture — フレームの画像を、指定したものに設定する

説明

public void KTaglib_ID3v2_AttachedPictureFrame::setPicture ( string $filename )

指定した画像を設定します。画像はファイル名を指定して読み込みます。 対応する file オブジェクトの save メソッドをコールしない限り、 画像は保存されないことに注意しましょう。

返り値

成功した場合に true、それ以外の場合に false を返します。

KTaglib_ID3v2_AttachedPictureFrame::setType

(0.2.0)

KTaglib_ID3v2_AttachedPictureFrame::setType — 画像の型を設定する

説明

public void KTaglib_ID3v2_AttachedPictureFrame::setType ( int $type )

画像の型を設定します。 たとえば FrontCover や FileIcon といったものです。使用できる型とそれに対応する定数の一覧については KTagLib_ID3v2_AttachedPictureFrame クラスの説明を参照ください。

目次

OGG/Vorbis

導入

OGG/Vorbis ファイルフォーマットは » http://www.vorbis.com/ で定義されており、 音質の劣化を最小限に抑えた圧縮オーディオストリームを提供する仕組みです。 この拡張モジュールは、PHP の URL ラッパー を Ogg Vorbis に対応させます。読み込みモードで使用した場合は、以下の表の 6 つの PCM エンコーディングフォーマットのうちひとつを用いて OGG/Vorbis 圧縮データを PCM オーディオに展開します。

インストール/設定

目次

要件

この拡張モジュールは、PHP >= 4.3.0、 » libogg >= 1.0 および » libvorbis >= 1.0 を必要とします。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/oggvorbis

実行時設定

設定ディレクティブは定義されていません。

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

OGG/Vorbis は、以下のフォーマットの PCM エンコーディングをサポートします
定数 定義
OGGVORBIS_PCM_U8 符号なし 8 ビット PCM。
OGGVORBIS_PCM_S8 符号付き 8 ビット PCM。
OGGVORBIS_PCM_U16_LE 符号なし 16 ビット PCM。リトルエンディアンバイトオーダー。
OGGVORBIS_PCM_U16_BE 符号なし 16 ビット PCM。ビッグエンディアンバイトオーダー。
OGGVORBIS_PCM_S16_LE 符号付き 16 ビット PCM。リトルエンディアンバイトオーダー。
OGGVORBIS_PCM_S16_BE 符号付き 16 ビット PCM。ビッグエンディアンバイトオーダー。

Context options

OGG/Vorbis のチューニングオプション
オプション 定義 モード デフォルト
pcm_mode 使用する PCM バイトエンコーディング形式。以下の定数を参照ください。 Read / Write OGGVORBIS_PCM_S16_LE
rate PCM サンプリングレート。Hz 単位。 Write only 44100
bitrate Vorbis 平均ビットレート（ABR）/ 可変ビットレート（VBR）。 bps 単位（ABR）あるいは品質レベル（VBR: 0.0 から 1.0）。 128000 ABR と 0.4 VBR がほぼ同じレベルです。 Write only 128000
channels PCM チャネル数。1 == モノラル、2 == ステレオ。 Write only 2
serialno ファイル内のストリームのシリアル番号。ファイル内で一意である必要が あります。連結したファイル内でシリアル番号が重複してしまう可能性が あるため、エンコードの際には手動で一意の番号を割り当てるよう注意して ください。 Write only Random
comments ファイルについてのコメントの連想配列。 strtoupper($name) . "=$value" 形式に変換されます。 注意: このオプションは、oggvorbis-0.1 では使用できません。 Write only array('ENCODER' => 'PHP/OggVorbis, http://pear.php.net/oggvorbis')

例

目次

ogg:// ラッパーの使用例

例1 OGG/Vorbis ファイルを読み込む

<?php
dl("oggvorbis.so");

/* デフォルトでは、ogg:// は符号付き 16 ビット リトルエンディアンにデコードします。*/
$fp = fopen('ogg://myaudio.ogg', 'r');

/* ファイルの情報を取得します。*/
$metadata = stream_get_meta_data($fp);

/* 最初の曲を調べます（たいていは 1 曲だけですが、
   OGG/Vorbis ファイルは連結が可能です）。*/
$songdata = $metadata['wrapper_data'][0];

echo "OGG/Vorbis file encoded by: {$songdata['vendor']}\n.";
echo "  {$songdata['channels']} channels of {$songdata['rate']}Hz sampling encoded at {$songdata['bitrate_nominal']}bps.\n";
foreach($songdata['comments'] as $comment) {
    echo "  $comment\n";
}

while ($audio_data = fread($fp, 8192)) {
  /* OGG から展開した PCM オーディオについて、なんらかの処理を行います。
     linux システムなら、たとえば /dev/dsp にコピーするなどがよい例でしょう。
     まず最初にデバイスの設定をすることを忘れないようにしましょう。*/
}

fclose($fp);

?>

例2 オーディオファイルを OGG/Vorbis にエンコードする

<?php
dl('oggvorbis.so');

$context = stream_context_create(array('ogg'=>array(
             'pcm_mode' => OGGVORBIS_PCM_S8,  /* 符号付き 8 ビットオーディオ */
             'rate' => 44100,                 /* 44kHz CD クオリティ */
             'bitrate' => 0.5,                /* 中品質の VBR（可変ビットレート） */
             'channels' => 1,                 /* モノラル */
             'serialno' => 12345)));          /* ストリーム内で一意の番号 */

/* ファイルを追記モードでオープンします。これは、
2 番目の OGG ストリームを最初のストリームの後に連結します。*/
$ogg = fopen('ogg://mysong.ogg', 'a', false, $context);

$pcm = fopen('mysample.pcm', 'r');

/* PCM オーディオデータ mysample.pcm を mysong.ogg に圧縮します。*/
stream_copy_to_stream($pcm, $ogg);

fclose($pcm);
fclose($ogg);
?>

OpenAL 音声バインディング

導入

プラットフォームに依存しない音声バインディングです。 » OpenAL ライブラリを必要とします。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/openal.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

実行時設定

設定ディレクティブは定義されていません。

リソース型

この拡張モジュールでは、 Open AL(Device) - openal_device_open() が返すもの、 Open AL(Context) - openal_context_create() が返すもの、 Open AL(Buffer) - openal_buffer_create() が返すもの および Open AL(Source) - openal_source_create() が返すものの 4 種類のリソース型が定義されています。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

ALC_FREQUENCY (integer)
コンテキスト属性
ALC_REFRESH (integer)
コンテキスト属性
ALC_SYNC (integer)
コンテキスト属性
AL_FREQUENCY (integer)
バッファ設定
AL_BITS (integer)
バッファ設定
AL_CHANNELS (integer)
バッファ設定
AL_SIZE (integer)
バッファ設定
AL_BUFFER (integer)
ソース/リスナー 設定 (Integer)
AL_SOURCE_RELATIVE (integer)
ソース/リスナー 設定 (Integer)
AL_SOURCE_STATE (integer)
ソース/リスナー 設定 (Integer)
AL_PITCH (integer)
ソース/リスナー 設定 (Float)
AL_GAIN (integer)
ソース/リスナー 設定 (Float)
AL_MIN_GAIN (integer)
ソース/リスナー 設定 (Float)
AL_MAX_GAIN (integer)
ソース/リスナー 設定 (Float)
AL_MAX_DISTANCE (integer)
ソース/リスナー 設定 (Float)
AL_ROLLOFF_FACTOR (integer)
ソース/リスナー 設定 (Float)
AL_CONE_OUTER_GAIN (integer)
ソース/リスナー 設定 (Float)
AL_CONE_INNER_ANGLE (integer)
ソース/リスナー 設定 (Float)
AL_CONE_OUTER_ANGLE (integer)
ソース/リスナー 設定 (Float)
AL_REFERENCE_DISTANCE (integer)
ソース/リスナー 設定 (Float)
AL_POSITION (integer)
ソース/リスナー 設定 (Float Vector)
AL_VELOCITY (integer)
ソース/リスナー 設定 (Float Vector)
AL_DIRECTION (integer)
ソース/リスナー 設定 (Float Vector)
AL_ORIENTATION (integer)
ソース/リスナー 設定 (Float Vector)
AL_FORMAT_MONO8 (integer)
PCM フォーマット
AL_FORMAT_MONO16 (integer)
PCM フォーマット
AL_FORMAT_STEREO8 (integer)
PCM フォーマット
AL_FORMAT_STEREO16 (integer)
PCM フォーマット
AL_INITIAL (integer)
ソースの状態
AL_PLAYING (integer)
ソースの状態
AL_PAUSED (integer)
ソースの状態
AL_STOPPED (integer)
ソースの状態
AL_LOOPING (integer)
ソースの状態
AL_TRUE (integer)
OpenAL が理解する boolean 値
AL_FALSE (integer)
OpenAL が理解する boolean 値

OpenAL 関数

openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — OpenAL バッファを生成する

説明

resource openal_buffer_create ( void )

返り値

成功した場合に Open AL (バッファ) リソース、失敗した場合に FALSE を返します。

参考

openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — バッファのデータを読み込む

説明

bool openal_buffer_data ( resource $buffer , int $format , string $data , int $freq )

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

format

data のフォーマット。 AL_FORMAT_MONO8、 AL_FORMAT_MONO16、 AL_FORMAT_STEREO8 そして AL_FORMAT_STEREO16 のいずれか。

data

format および freq で指定した、バイナリ音声データブロック。

freq

Hz 単位で指定した data の周波数。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — OpenAL バッファを削除する

説明

bool openal_buffer_destroy ( resource $buffer )

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — OpenAL バッファのプロパティを取得する

説明

int openal_buffer_get ( resource $buffer , int $property )

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

property

特定のプロパティ。 AL_FREQUENCY、 AL_BITS、 AL_CHANNELS そして AL_SIZE のいずれか。

返り値

要求された property の値を整数で返します。 失敗した場合に FALSE を返します。

参考

openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — .wav ファイルをバッファに読み込む

説明

bool openal_buffer_loadwav ( resource $buffer , string $wavfile )

パラメータ

buffer

Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

wavfile

ローカルファイルシステム上の .wav ファイルへのパス。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — 音声処理コンテキストを作成する

説明

resource openal_context_create ( resource $device )

パラメータ

device

Open AL (デバイス) リソース (事前に openal_device_open() で作成したもの)。

返り値

成功した場合に Open AL (コンテキスト) リソース、 失敗した場合に FALSE を返します。

参考

openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — 指定したコンテキストを現在のコンテキストにする

説明

bool openal_context_current ( resource $context )

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — コンテキストを削除する

説明

bool openal_context_destroy ( resource $context )

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — 指定したコンテキストを処理する

説明

bool openal_context_process ( resource $context )

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — 指定したコンテキストをサスペンドする

説明

bool openal_context_suspend ( resource $context )

パラメータ

context

Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — OpenAL デバイスを閉じる

説明

bool openal_device_close ( resource $device )

パラメータ

device

閉じようとしている Open AL (デバイス) リソース (事前に openal_device_open() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — OpenAL 音声レイヤを初期化する

説明

resource openal_device_open ([ string $device_desc ] )

パラメータ

device_desc

device_desc で指定した音声デバイスをオープンします。 device_desc が指定されなかった場合は、 最初に見つかった音声デバイスが使用されます。

返り値

成功した場合に Open AL (デバイス) リソース、 失敗した場合に FALSE を返します。

参考

openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — リスナーのプロパティを取得する

説明

mixed openal_listener_get ( int $property )

パラメータ

property

取得するプロパティ。 AL_GAIN (float)、 AL_POSITION (array(float,float,float))、 AL_VELOCITY (array(float,float,float)) そして AL_ORIENTATION (array(float,float,float)) のいずれか。

返り値

float あるいは float の配列 (どちらか適切なほう) を返します。 失敗した場合に FALSE を返します。

参考

openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — リスナーのプロパティを設定する

説明

bool openal_listener_set ( int $property , mixed $setting )

パラメータ

property

設定するプロパティ。 AL_GAIN (float)、 AL_POSITION (array(float,float,float))、 AL_VELOCITY (array(float,float,float)) そして AL_ORIENTATION (array(float,float,float)) のいずれか。

setting

設定する値。float あるいは float の配列のうち適切なもの。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — ソースリソースを生成する

説明

resource openal_source_create ( void )

返り値

成功した場合に Open AL (ソース) リソース、 失敗した場合に FALSE を返します。

参考

openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — ソースリソースを削除する

説明

bool openal_source_destroy ( resource $source )

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — OpenAL ソースのプロパティを取得する

説明

mixed openal_source_get ( resource $source , int $property )

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

property

取得するプロパティ。 AL_SOURCE_RELATIVE (int)、 AL_SOURCE_STATE (int)、 AL_PITCH (float)、 AL_GAIN (float)、 AL_MIN_GAIN (float)、 AL_MAX_GAIN (float)、 AL_MAX_DISTANCE (float)、 AL_ROLLOFF_FACTOR (float)、 AL_CONE_OUTER_GAIN (float)、 AL_CONE_INNER_ANGLE (float)、 AL_CONE_OUTER_ANGLE (float)、 AL_REFERENCE_DISTANCE (float)、 AL_POSITION (array(float,float,float))、 AL_VELOCITY (array(float,float,float))、 AL_DIRECTION (array(float,float,float)) のいずれか。

返り値

取得したプロパティに関連付けられた型を返します。 失敗した場合に FALSE を返します。

参考

openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pause — ソースを一時停止する

説明

bool openal_source_pause ( resource $source )

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_source_play

(PECL openal >= 0.1.0)

openal_source_play — ソースの再生を開始する

説明

bool openal_source_play ( resource $source )

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — ソースを巻き戻す

説明

bool openal_source_rewind ( resource $source )

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_source_set

(PECL openal >= 0.1.0)

openal_source_set — ソースのプロパティを設定する

説明

bool openal_source_set ( resource $source , int $property , mixed $setting )

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

property

設定するプロパティ。 AL_BUFFER (OpenAL (ソース))、 AL_LOOPING (bool)、 AL_SOURCE_RELATIVE (int)、 AL_SOURCE_STATE (int)、 AL_PITCH (float)、 AL_GAIN (float)、 AL_MIN_GAIN (float)、 AL_MAX_GAIN (float)、 AL_MAX_DISTANCE (float)、 AL_ROLLOFF_FACTOR (float)、 AL_CONE_OUTER_GAIN (float)、 AL_CONE_INNER_ANGLE (float)、 AL_CONE_OUTER_ANGLE (float)、 AL_REFERENCE_DISTANCE (float)、 AL_POSITION (array(float,float,float))、 AL_VELOCITY (array(float,float,float))、 AL_DIRECTION (array(float,float,float)) のいずれか。

setting

指定した property に代入する値。 代入できる値については、property の説明を参照ください。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stop — ソースの再生を停止する

説明

bool openal_source_stop ( resource $source )

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

openal_stream

(PECL openal >= 0.1.0)

openal_stream — ソースのストリーム再生を開始する

説明

resource openal_stream ( resource $source , int $format , int $rate )

パラメータ

source

Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

format

data のフォーマット。 AL_FORMAT_MONO8、 AL_FORMAT_MONO16、 AL_FORMAT_STEREO8 そして AL_FORMAT_STEREO16 のいずれか。

rate

データをストリームに流す際の周波数を Hz 単位で指定します。

返り値

成功した場合にストリームリソースを返します。失敗した場合に FALSE を返します。

参考

目次

認証サービス

Kerberos V

導入

このパッケージは、Kerberos V (ケルベロス バージョン 5) 管理サーバーへのアクセス機能を提供します。 これにより、Kerberos V のプリンシパルやポリシーの 作成・変更・削除が可能となります。

Kerberos についての詳細な情報は、» http://web.mit.edu/kerberos/www/ で得られます。

Kerberos および KADM5 についてのドキュメントは、» http://web.mit.edu/kerberos/www/krb5-1.2/krb5-1.2.8/doc/admin_toc.html にあります。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/kadm5.

注意:

KADM5 のパスを指定せずにこのオプションを使用すると、 PHP は組み込みの KADM5 クライアントライブラリを使用します。 KADM5 を使用するそれ以外のアプリケーションを実行している場合 (たとえば、PHP 4 と PHP 5 を同時に apache モジュールとして動かしたり auth-kadm5 を使用したりといった場合) は、常に KADM5 のパスを --with-kadm5=/path/to/kadm5 のように指定する必要があります。こうすれば PHP は KADM5 がインストールしたクライアントライブラリを用いるようになり、 衝突が回避できます。

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

実行時設定

設定ディレクティブは定義されていません。

リソース型

この拡張モジュールでは KADM5 ハンドルを定義しています。これは kadm5_init_with_password() が返すものです。

定義済み定数

目次

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

属性フラグ用の定数

関数 kadm5_create_principal()、 kadm5_modify_principal() および kadm5_modify_principal() では、ビットを立てることで 特別な属性を指定することができます。以下のような定数が定義されています。

KDC が使用する属性定数
定数
KRB5_KDB_DISALLOW_POSTDATED
KRB5_KDB_DISALLOW_FORWARDABLE
KRB5_KDB_DISALLOW_TGT_BASED
KRB5_KDB_DISALLOW_RENEWABLE
KRB5_KDB_DISALLOW_PROXIABLE
KRB5_KDB_DISALLOW_DUP_SKEY
KRB5_KDB_DISALLOW_ALL_TIX
KRB5_KDB_REQUIRES_PRE_AUTH
KRB5_KDB_REQUIRES_HW_AUTH
KRB5_KDB_REQUIRES_PWCHANGE
KRB5_KDB_DISALLOW_SVR
KRB5_KDB_PWCHANGE_SERVER
KRB5_KDB_SUPPORT_DESMD5
KRB5_KDB_NEW_PRINC

オプション用の定数

関数 kadm5_create_principal()、 kadm5_modify_principal() および kadm5_get_principal() では、プリンシパルの オプションを連想配列形式で指定したり関数の返り値として 受け取ったりできます。連想配列のキーは、以下で定義されている 文字列定数となります。

プリンシパルを作成/変更/取得する際のオプション
定数 型 説明
KADM5_PRINCIPAL long プリンシパルの有効期限を Kerberos タイムスタンプで指定します。
KADM5_PRINC_EXPIRE_TIME long プリンシパルの有効期限を Kerberos タイムスタンプで指定します。
KADM5_LAST_PW_CHANGE long プリンシパルのパスワードが最後に変更された時刻。
KADM5_PW_EXPIRATION long プリンシパルの現在のパスワードの有効期限を Kerberos タイムスタンプで指定します。
KADM5_MAX_LIFE long このプリンシパルに発行された Kerberos チケットの最大の生存時間。
KADM5_MAX_RLIFE long このプリンシパルに発行された Kerberos チケットの最大の 更新可能生存時間。
KADM5_MOD_NAME string 最後にこのプリンシパルを変更した Kerberos プリンシパルの名前。
KADM5_MOD_TIME long このプリンシパルの最終更新時刻を Kerberos タイムスタンプ形式で指定します。
KADM5_KVNO long プリンシパルの現在のキーのバージョン。
KADM5_POLICY string このプリンシパルを制御するポリシーの名前。
KADM5_CLEARPOLICY long 新しいプリンシパルの「デフォルトの」ポリシーには 標準手続きが関連付けられます。 KADM5_CLEARPOLICY は、この挙動を抑制します。
KADM5_LAST_SUCCESS long 最後に AS_REQ が成功したときの KDC 時刻。
KADM5_LAST_FAILED long 最後に AS_REQ が失敗したときの KDC 時刻。
KADM5_FAIL_AUTH_COUNT long AS_REQ が連続して失敗した数。
KADM5_RANDKEY long プリンシパルに対してランダムなパスワードを生成します。 パラメータ password は無視されます。
KADM5_ATTRIBUTES long KDC が使用する属性のビットフィールド。

例

目次

基本的な使用法

この例では、KADM5 データベースに対して 接続・問い合わせ・結果 principal の表示・切断 を行います。

例1 KADM5 拡張モジュールの概要

<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  print "<h1>get_principals</h1>\n";
  $principals = kadm5_get_principals($handle);
  for( $i=0; $i<count($principals); $i++)
      print "$principals[$i]<br>\n";

  print "<h1>get_policies</h1>\n";
  $policies = kadm5_get_policies($handle);
  for( $i=0; $i<count($policies); $i++)
      print "$policies[$i]<br>\n";

  print "<h1>get_principal burbach@GONICUS.LOCAL</h1>\n";

  $options = kadm5_get_principal($handle, "burbach@GONICUS.LOCAL" );
  $keys = array_keys($options);
  for( $i=0; $i<count($keys); $i++) {
    $value = $options[$keys[$i]];
    print "$keys[$i]: $value<br>\n";
  }

  $options = array(KADM5_PRINC_EXPIRE_TIME => 0);
  kadm5_modify_principal($handle, "burbach@GONICUS.LOCAL", $options);

  kadm5_destroy($handle);
?>

KADM5 関数

kadm5_chpass_principal

(PECL kadm5 >= 0.2.3)

kadm5_chpass_principal — プリンシパルのパスワードを変更する

説明

bool kadm5_chpass_principal ( resource $handle , string $principal , string $password )

kadm5_chpass_principal() は、 principal の新しいパスワードを password に設定します。

パラメータ

handle

KADM5 ハンドル。

principal

プリンシパル。

password

新しいパスワード。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 プリンシパルのパスワードを変更する例

<?php

$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

kadm5_chpass_principal($handle, "burbach@GONICUS.LOCAL", "newpassword");

kadm5_destroy($handle);
?>

kadm5_create_principal

(PECL kadm5 >= 0.2.3)

kadm5_create_principal — 指定したパラメータで、kerberos のプリンシパルを作成する

説明

bool kadm5_create_principal ( resource $handle , string $principal [, string $password [, array $options ]] )

指定した password で principal を作成します。

パラメータ

handle

KADM5 ハンドル。

principal

プリンシパル。

password

password を指定しなかったり NULL を指定した場合は、ランダムなキーが生成されます。

options

配列 options にオプションのパラメータを 指定することができます。指定可能なオプションは以下のとおりです。 KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES, KADM5_MAX_LIFE, KADM5_KVNO, KADM5_POLICY, KADM5_CLEARPOLICY, KADM5_MAX_RLIFE.

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 プリンシパルを作成する例

<?php

$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

$attributes = KRB5_KDB_REQUIRES_PRE_AUTH | KRB5_KDB_DISALLOW_PROXIABLE;
$options = array(KADM5_PRINC_EXPIRE_TIME => 0,
                 KADM5_POLICY => "default",
                 KADM5_ATTRIBUTES => $attributes);

kadm5_create_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);

kadm5_destroy($handle);
?>

参考

kadm5_delete_principal

(PECL kadm5 >= 0.2.3)

kadm5_delete_principal — kerberos プリンシパルを削除する

説明

bool kadm5_delete_principal ( resource $handle , string $principal )

Kerberos データベースから principal を削除します。

パラメータ

handle

KADM5 ハンドル。

principal

削除するプリンシパル。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 kadm5_delete_principal() の例

<?php

$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

kadm5_delete_principal($handle, "burbach@GONICUS.LOCAL");

kadm5_destroy($handle);
?>

参考

kadm5_destroy

(PECL kadm5 >= 0.2.3)

kadm5_destroy — 管理サーバーへの接続を閉じ、関連するすべてのリソースを開放する

説明

bool kadm5_destroy ( resource $handle )

管理サーバーへの接続を閉じ、関連するすべてのリソースを開放します。

パラメータ

handle

KADM5 ハンドル。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

  • kadm5_init_with_password() - KADM5 ライブラリへの接続をオープンし、必要なステータス情報を初期化する

kadm5_flush

(PECL kadm5 >= 0.2.3)

kadm5_flush — Kerberos データベースに対するすべての変更を取り消す

説明

bool kadm5_flush ( resource $handle )

Kerberos データベースに対するすべての変更を取り消し、 Kerberos 管理サーバーとの接続はオープンしたままにします。

パラメータ

handle

KADM5 ハンドル。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

kadm5_get_policies

(PECL kadm5 >= 0.2.3)

kadm5_get_policies — Kerberos データベースから、すべてのポリシーを取得する

説明

array kadm5_get_policies ( resource $handle )

ポリシー名を含む配列を取得します。

パラメータ

handle

KADM5 ハンドル。

返り値

成功した場合はポリシーの配列、失敗した場合に FALSE を返します。

例

例1 kadm5_get_policies() の例

<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

print "<h1>get_policies</h1>\n";
foreach (kadm5_get_policies($handle) as $policy) {
    echo "$policy<br />\n";
}

kadm5_destroy($handle);
?>

kadm5_get_principal

(PECL kadm5 >= 0.2.3)

kadm5_get_principal — Kerberos データベースから、プリンシパルのエントリを取得する

説明

array kadm5_get_principal ( resource $handle , string $principal )

Kerberos データベースから、プリンシパルのエントリを取得します。

パラメータ

handle

KADM5 ハンドル。

principal

プリンシパル。

返り値

成功した場合は、以下のキーを含む連想配列を返します。 KADM5_PRINCIPAL、KADM5_PRINC_EXPIRE_TIME、 KADM5_PW_EXPIRATION、KADM5_ATTRIBUTES、KADM5_MAX_LIFE、KADM5_MOD_NAME、 KADM5_MOD_TIME、KADM5_KVNO、KADM5_POLICY、KADM5_MAX_RLIFE、 KADM5_LAST_SUCCESS、KADM5_LAST_FAILED、KADM5_FAIL_AUTH_COUNT 失敗した場合に FALSE を返します。

例

例1 kadm5_get_principal() の例

<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

print "<h1>get_principal burbach@GONICUS.LOCAL</h1>\n";

$options = kadm5_get_principal($handle, "burbach@GONICUS.LOCAL" );

foreach ($options as $key => $value) {
    echo "$key: $value<br />\n";
}

kadm5_destroy($handle);
?>

参考

kadm5_get_principals

(PECL kadm5 >= 0.2.3)

kadm5_get_principals — Kerberos データベースから、すべてのプリンシパルを取得する

説明

array kadm5_get_principals ( resource $handle )

kadm5_get_principals() は、プリンシパルの名前を含む 配列を返します。

パラメータ

handle

KADM5 ハンドル。

返り値

成功した場合はプリンシパルの配列、失敗した場合に FALSE を返します。

例

例1 kadm5_get_principals() の例

<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

print "<h1>get_principals</h1>\n";
foreach (kadm5_get_principals($handle) as $principal) {
    echo "$principal<br />\n";
}

kadm5_destroy($handle);
?>

参考

  • kadm5_get_principal() - Kerberos データベースから、プリンシパルのエントリを取得する

kadm5_init_with_password

(PECL kadm5 >= 0.2.3)

kadm5_init_with_password — KADM5 ライブラリへの接続をオープンし、必要なステータス情報を初期化する

説明

resource kadm5_init_with_password ( string $admin_server , string $realm , string $principal , string $password )

principal および指定した password を使用して KADM5 ライブラリとの接続をオープンし、 admin_server から証明書を取得します。

パラメータ

admin_server

サーバー。

realm

この接続の認証領域を定義します。

principal

プリンシパル。

password

password を省略したり NULL を指定したりすると、 ランダムなキーを生成します。

返り値

成功した場合は KADM5 ハンドル、失敗した場合に FALSE を返します。

例

例1 KADM5 の初期化の例

<?php

$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

$attributes = KRB5_KDB_REQUIRES_PRE_AUTH | KRB5_KDB_DISALLOW_PROXIABLE;
$options = array(KADM5_PRINC_EXPIRE_TIME => 0,
                 KADM5_POLICY => "default",
                 KADM5_ATTRIBUTES => $attributes);

kadm5_create_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);

kadm5_destroy($handle);
?>

注意

注意:

使用後は、kadm5_destroy() で接続を閉じなければなりません。

参考

  • kadm5_destroy() - 管理サーバーへの接続を閉じ、関連するすべてのリソースを開放する

kadm5_modify_principal

(PECL kadm5 >= 0.2.3)

kadm5_modify_principal — kerberos プリンシパルを、指定したパラメータで変更する

説明

bool kadm5_modify_principal ( resource $handle , string $principal , array $options )

指定した options に基づいて principal を変更します。

パラメータ

handle

KADM5 ハンドル。

principal

プリンシパル。

options

オプションのパラメータを、配列 options で指定することができます。指定できるオプションは以下のとおりです。 KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES, KADM5_MAX_LIFE, KADM5_KVNO, KADM5_POLICY, KADM5_CLEARPOLICY, KADM5_MAX_RLIFE. KADM5_FAIL_AUTH_COUNT.

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 プリンシパルの変更の例

<?php

$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

$attributes = KRB5_KDB_REQUIRES_PRE_AUTH;
$options = array(KADM5_PRINC_EXPIRE_TIME => 3451234,
                 KADM5_POLICY => "gonicus",
                 KADM5_ATTRIBUTES => $attributes);

kadm5_modify_principal($handle, "burbach@GONICUS.LOCAL", $options);

kadm5_destroy($handle);
?>

参考

目次

  • kadm5_chpass_principal — プリンシパルのパスワードを変更する
  • kadm5_create_principal — 指定したパラメータで、kerberos のプリンシパルを作成する
  • kadm5_delete_principal — kerberos プリンシパルを削除する
  • kadm5_destroy — 管理サーバーへの接続を閉じ、関連するすべてのリソースを開放する
  • kadm5_flush — Kerberos データベースに対するすべての変更を取り消す
  • kadm5_get_policies — Kerberos データベースから、すべてのポリシーを取得する
  • kadm5_get_principal — Kerberos データベースから、プリンシパルのエントリを取得する
  • kadm5_get_principals — Kerberos データベースから、すべてのプリンシパルを取得する
  • kadm5_init_with_password — KADM5 ライブラリへの接続をオープンし、必要なステータス情報を初期化する
  • kadm5_modify_principal — kerberos プリンシパルを、指定したパラメータで変更する

Radius

導入

このパッケージは、FreeBSD の libradius (Remote Authentication Dial In User Service) をもとにしたものです。 クライアントからの認証や課金を、ネットワーク越しのリモートサーバーに行うことができます。

この PECL モジュールは、Radius 認証 (» RFC 2865) および Radius 課金 (» RFC 2866) を完全にサポートします。 このパッケージは、Unix (FreeBSD および Linux でテストしました) および Windows で使用可能です。

注意:

libradius に関する正確な説明は» ここ にあります。設定ファイルについての詳細な説明は » ここです。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/radius.

この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

実行時設定

設定ディレクティブは定義されていません。

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

RADIUS_ACCESS_REQUEST ()
認証のリクエスト
RADIUS_ACCESS_ACCEPT ()
アクセスが許可されました
RADIUS_ACCESS_REJECT ()
アクセスが拒否されました
RADIUS_ACCOUNTING_REQUEST ()
課金のリクエスト
RADIUS_ACCOUNTING_RESPONSE ()
課金のレスポンス
RADIUS_ACCESS_CHALLENGE ()
アクセスチャレンジ
RADIUS_USER_NAME (string)
ユーザー名
RADIUS_USER_PASSWORD (string)
パスワード
RADIUS_CHAP_PASSWORD (string)
Chap パスワード。 chappass = md5(ident + plaintextpass + challenge)
RADIUS_NAS_IP_ADDRESS (string)
NAS IP アドレス
RADIUS_NAS_PORT (int)
NAS ポート
RADIUS_SERVICE_TYPE (int)

サービスの型、以下のいずれか

  • RADIUS_LOGIN
  • RADIUS_FRAMED
  • RADIUS_CALLBACK_LOGIN
  • RADIUS_CALLBACK_FRAMED
  • RADIUS_OUTBOUND
  • RADIUS_ADMINISTRATIVE
  • RADIUS_NAS_PROMPT
  • RADIUS_AUTHENTICATE_ONLY
  • RADIUS_CALLBACK_NAS_PROMPT

RADIUS_FRAMED_PROTOCOL (int)

フレームのプロトコル、以下のいずれか

  • RADIUS_PPP
  • RADIUS_SLIP
  • RADIUS_ARAP
  • RADIUS_GANDALF
  • RADIUS_XYLOGICS

RADIUS_FRAMED_IP_ADDRESS (int)
IPv4 インターネットのネットワークアドレス
RADIUS_FRAMED_IP_NETMASK (string)
ネットマスク
RADIUS_FRAMED_ROUTING (int)
ルーティング
RADIUS_FILTER_ID (string)
フィルタ ID
RADIUS_FRAMED_MTU (int)
MTU
RADIUS_FRAMED_COMPRESSION (int)

圧縮、以下のいずれか

  • RADIUS_COMP_NONE
  • RADIUS_COMP_VJ
  • RADIUS_COMP_IPXHDR

RADIUS_LOGIN_IP_HOST (string)
ログイン IP ホスト
RADIUS_LOGIN_SERVICE (int)
ログインサービス
RADIUS_LOGIN_TCP_PORT (int)
ログイン TCP ポート
RADIUS_REPLY_MESSAGE (string)
応答メッセージ
RADIUS_CALLBACK_NUMBER (string)
コールバック番号
RADIUS_CALLBACK_ID (string)
コールバック ID
RADIUS_FRAMED_ROUTE (string)
フレームのルート
RADIUS_FRAMED_IPX_NETWORK (string)
フレームの IPX ネットワーク
RADIUS_STATE (string)
状態
RADIUS_CLASS (int)
クラス
RADIUS_VENDOR_SPECIFIC (int)
ベンダ固有の属性
RADIUS_SESSION_TIMEOUT (int)
セッションタイムアウト
RADIUS_IDLE_TIMEOUT (int)
アイドルタイムアウト
RADIUS_TERMINATION_ACTION (int)
停止アクション
RADIUS_CALLED_STATION_ID (int)
呼び出し先ステーション ID
RADIUS_CALLING_STATION_ID (string)
呼び出し元ステーション ID
RADIUS_NAS_IDENTIFIER (int)
NAS ID
RADIUS_PROXY_STATE (int)
Proxy の状態
RADIUS_LOGIN_LAT_SERVICE (int)
ログイン LAT サービス
RADIUS_LOGIN_LAT_NODE (int)
ログイン LAT ノード
RADIUS_LOGIN_LAT_GROUP (int)
ログイン LAT グループ
フレームの Appletalk リンク
RADIUS_FRAMED_APPLETALK_NETWORK (int)
フレームの Appletalk ネットワーク
RADIUS_FRAMED_APPLETALK_ZONE (int)
フレームの Appletalk ゾーン
RADIUS_CHAP_CHALLENGE (string)
チャレンジ
RADIUS_NAS_PORT_TYPE (int)

NAS ポート型、以下のいずれか

  • RADIUS_ASYNC
  • RADIUS_SYNC
  • RADIUS_ISDN_SYNC
  • RADIUS_ISDN_ASYNC_V120
  • RADIUS_ISDN_ASYNC_V110
  • RADIUS_VIRTUAL
  • RADIUS_PIAFS
  • RADIUS_HDLC_CLEAR_CHANNEL
  • RADIUS_X_25
  • RADIUS_X_75
  • RADIUS_G_3_FAX
  • RADIUS_SDSL
  • RADIUS_ADSL_CAP
  • RADIUS_ADSL_DMT
  • RADIUS_IDSL
  • RADIUS_ETHERNET
  • RADIUS_XDSL
  • RADIUS_CABLE
  • RADIUS_WIRELESS_OTHER
  • RADIUS_WIRELESS_IEEE_802_11

RADIUS_PORT_LIMIT (int)
ポートの限界
RADIUS_LOGIN_LAT_PORT (int)
ログイン LAT ポート
RADIUS_CONNECT_INFO (string)
接続の情報
RADIUS_ACCT_STATUS_TYPE (int)

課金状態の型、以下のいずれか

  • RADIUS_START
  • RADIUS_STOP
  • RADIUS_ACCOUNTING_ON
  • RADIUS_ACCOUNTING_OFF

RADIUS_ACCT_DELAY_TIME (int)
課金の遅延時間
RADIUS_ACCT_INPUT_OCTETS (int)
課金の入力バイト数
RADIUS_ACCT_OUTPUT_OCTETS (int)
課金の出力バイト数
RADIUS_ACCT_SESSION_ID (int)
課金のセッション ID
RADIUS_ACCT_AUTHENTIC (int)

課金認証、以下のいずれか

  • RADIUS_AUTH_RADIUS
  • RADIUS_AUTH_LOCAL
  • RADIUS_AUTH_REMOTE

RADIUS_ACCT_SESSION_TIME (int)
課金のセッション時間
RADIUS_ACCT_INPUT_PACKETS (int)
課金の入力パケット
RADIUS_ACCT_OUTPUT_PACKETS (int)
課金の出力パケット
RADIUS_ACCT_TERMINATE_CAUSE (int)

課金終了の原因、以下のいずれか

  • RADIUS_TERM_USER_REQUEST
  • RADIUS_TERM_LOST_CARRIER
  • RADIUS_TERM_LOST_SERVICE
  • RADIUS_TERM_IDLE_TIMEOUT
  • RADIUS_TERM_SESSION_TIMEOUT
  • RADIUS_TERM_ADMIN_RESET
  • RADIUS_TERM_ADMIN_REBOOT
  • RADIUS_TERM_PORT_ERROR
  • RADIUS_TERM_NAS_ERROR
  • RADIUS_TERM_NAS_REQUEST
  • RADIUS_TERM_NAS_REBOOT
  • RADIUS_TERM_PORT_UNNEEDED
  • RADIUS_TERM_PORT_PREEMPTED
  • RADIUS_TERM_PORT_SUSPENDED
  • RADIUS_TERM_SERVICE_UNAVAILABLE
  • RADIUS_TERM_CALLBACK
  • RADIUS_TERM_USER_ERROR
  • RADIUS_TERM_HOST_REQUEST

RADIUS_ACCT_MULTI_SESSION_ID (string)
課金のマルチセッション ID
課金のリンク数
RADIUS_VENDOR_MICROSOFT (int)

Microsoft 固有のベンダ属性 (» RFC 2548)、 以下のいずれか

  • RADIUS_MICROSOFT_MS_CHAP_RESPONSE
  • RADIUS_MICROSOFT_MS_CHAP_ERROR
  • RADIUS_MICROSOFT_MS_CHAP_PW_1
  • RADIUS_MICROSOFT_MS_CHAP_PW_2
  • RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW
  • RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW
  • RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
  • RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
  • RADIUS_MICROSOFT_MS_RAS_VENDOR
  • RADIUS_MICROSOFT_MS_CHAP_DOMAIN
  • RADIUS_MICROSOFT_MS_CHAP_CHALLENGE
  • RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS
  • RADIUS_MICROSOFT_MS_BAP_USAGE
  • RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD
  • RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT
  • RADIUS_MICROSOFT_MS_MPPE_SEND_KEY
  • RADIUS_MICROSOFT_MS_MPPE_RECV_KEY
  • RADIUS_MICROSOFT_MS_RAS_VERSION
  • RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD
  • RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD
  • RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON
  • RADIUS_MICROSOFT_MS_FILTER
  • RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE
  • RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE
  • RADIUS_MICROSOFT_MS_CHAP2_RESPONSE
  • RADIUS_MICROSOFT_MS_CHAP2_SUCCESS
  • RADIUS_MICROSOFT_MS_CHAP2_PW
  • RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER
  • RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER
  • RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER
  • RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER
  • RADIUS_MICROSOFT_MS_ARAP_CHALLENGE

例

どのように使用するの?

  • radius リソースを取得する
  • ライブラリを設定する
  • リクエストを作成する
  • 属性を設定する
  • リクエストを送信する
  • 属性を受け取る
  • radius リソースを閉じる (オプション)
パッケージに含まれている例もごらんください。

このパッケージにはサンプル PHP スクリプトが含まれています。 このスクリプトでは、PAP あるいは CHAP (md5) を使用した radius 認証の 方法を説明しています。Microsoft Radius サーバーを使用して認証を行う 場合は、CHAP (md5) を使用することはできません。Microsoft のサーバーを 使用する場合は、MS-CHAPv1 あるいは MS-CHAPv2 を使用する必要があります。 しかし、正しいデータを生成するために md4、sha1 および des が必要となる こともあり、これは複雑な手順となります。同梱されている例では すべての認証方式を説明しており、そこには MS-CHAPv1 および MS-CHAPv2 も含まれています。MS-CHAP を動作させるためには、拡張モジュール mcrypt および mhash が必要となります。 バージョン 1.2 以降では、mcrypt 拡張モジュールは必要なくなりました。

Radius 関数

連絡先の情報

コメント・バグフィックス・機能拡張・あるいは開発を手伝いたいなどの場合は、 メールを » mbretter@php.net に送ってください。

radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — 課金用の Radius ハンドルを作成する

説明

resource radius_acct_open ( void )

返り値

成功した場合にハンドル、エラー時に FALSE を返します。 この関数が失敗するのは、無効なメモリを使用した場合のみです。

例

例1 radius_acct_open() の例

<?php
$res = radius_acct_open ()
    or die ("ハンドルを作成できませんでした");
print("ハンドルの作成に成功しました");
?>

radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — サーバーを追加する

説明

bool radius_add_server ( resource $radius_handle , string $hostname , int $port , string $secret , int $timeout , int $max_tries )

radius_add_server() は複数回コールされることも ありえます。また、radius_config() とともに 使用されることでしょう。最大で 10 までのサーバーを指定できます。 複数のサーバーが指定されると、有効なレスポンスを受信するか あるいは各サーバーへの接続回数が max_tries をこえるまでラウンドロビン形式でのアクセスを試みます。

パラメータ

radius_handle

hostname

hostname はサーバーのホストを FQDN あるいはドット区切りの IP アドレス形式で指定します。

port

port は、サーバーとの接続に使用する UDP ポートを指定します。0 を指定すると、このライブラリは ネットワークサービスデータベースから radius/udp あるいは radacct/udp サービスを 検索し、見つかったポートを使用します。見つからなかった場合は 標準の Radius ポート、すなわち認証には 1812、 課金には 1813 を使用します。

secret

secret パラメータには、サーバーホストに 対する共有秘密鍵が渡されます。Radius プロトコルは、共有秘密鍵の 最初の 128 バイト以外を無視します。

timeout

timeout パラメータには、サーバーから 応答を受信する際のタイムアウトを秒単位で指定します。

max_tries

結果が返ってこなかった場合に最大何回までリクエストを繰り返すかを max_tries に指定します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 radius_add_server() の例

<?php
if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
    echo 'RadiusError:' . radius_strerror($res). "\n<br>";
    exit;
}
?>

参考

  • radius_config() - 指定した設定ファイルをライブラリに読み込ませる

radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — 認証用の Radius ハンドルを作成する

説明

resource radius_auth_open ( void )

返り値

成功した場合にハンドル、エラー時に FALSE を返します。 この関数が失敗するのは、無効なメモリを使用した場合のみです。

例

例1 radius_auth_open() の例

<?php
$radh = radius_auth_open()
    or die ("ハンドルを作成できませんでした");
echo "ハンドルの作成に成功しました";
?>

radius_close

(PECL radius >= 1.1.0)

radius_close — すべてのリソースを開放する

説明

bool radius_close ( resource $radius_handle )

各リクエストの終了時に PHP がすべてのリソースを開放するので、 この関数をコールする必要はありません。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

radius_config

(PECL radius >= 1.1.0)

radius_config — 指定した設定ファイルをライブラリに読み込ませる

説明

bool radius_config ( resource $radius_handle , string $file )

Radius リクエストを発行する前には、ライブラリが接続可能なサーバーを 知っている必要があります。ライブラリを設定するいちばん簡単な方法は radius_config() をコールすることです。 radius_config() は、ライブラリに » radius.conf 形式のファイルを読み込ませます。

パラメータ

radius_handle

file

設定ファイルへのパスを、引数として radius_config() に渡します。 radius_add_server() をコールすることで、 プログラム上でライブラリの設定をすることも可能です。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — 課金あるいは認証のリクエストを作成する

説明

bool radius_create_request ( resource $radius_handle , int $type )

Radius リクエストには、リクエストの種類を指定するコードおよび 追加情報を指定するゼロ個以上の属性が含まれます。新しいリクエストを 作成するには、radius_create_request() をコールします。

注意: 注意: 属性を設定する前にこの関数をコールする必要があります。

パラメータ

radius_handle

type

RADIUS_ACCESS_REQUEST あるいは RADIUS_ACCOUNTING_REQUEST のいずれか。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 radius_create_request() の例

<?php
if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
    echo 'RadiusError:' . radius_strerror($res). "\n<br />";
    exit;
}
?>

参考

radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — 生データを IP アドレスに変換する

説明

string radius_cvt_addr ( string $data )

例

例1 radius_cvt_addr() の例

<?php
while ($resa = radius_get_attr($res)) {

    if (!is_array($resa)) {
        printf ("属性取得時のエラー: %s\n",  radius_strerror($res));
        exit;
    }

    $attr = $resa['attr'];
    $data = $resa['data'];
    
    switch ($attr) {

    case RADIUS_FRAMED_IP_ADDRESS:
        $ip = radius_cvt_addr($data);
        echo "IP: $ip<br>\n";
        break;

    case RADIUS_FRAMED_IP_NETMASK:
        $mask = radius_cvt_addr($data);
        echo "マスク: $mask<br>\n";
        break;
    }
}
?>

参考

radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_int — 生データを整数に変換する

説明

int radius_cvt_int ( string $data )

例

例1 radius_cvt_int() の例

<?php
while ($resa = radius_get_attr($res)) {

    if (!is_array($resa)) {
        printf ("属性取得時のエラー: %s\n",  radius_strerror($res));
        exit;
    }

    $attr = $resa['attr'];
    $data = $resa['data'];
    
    switch ($attr) {

    case RADIUS_FRAMED_MTU:
        $mtu = radius_cvt_int($data);
        echo "MTU: $mtu<br>\n";
        break;
    }
}
?>

参考

radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_string — 生データを文字列に変換する

説明

string radius_cvt_string ( string $data )

例

例1 radius_cvt_string() の例

<?php
while ($resa = radius_get_attr($res)) {

    if (!is_array($resa)) {
        printf ("属性取得時のエラー: %s\n",  radius_strerror($res));
        exit;
    }

    $attr = $resa['attr'];
    $data = $resa['data'];
    
    switch ($attr) {

    case RADIUS_FILTER_ID:
        $id = radius_cvt_string($data);
        echo "フィルタ ID: $id<br>\n";
        break;
    }
}
?>

参考

radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — 変形されたデータから mppe キーを得る

説明

string radius_demangle_mppe_key ( resource $radius_handle , string $mangled )

MS-CHAPv2 で MPPE を使用している場合には、送信キーおよび受信キーが 変形されます (» RFC 2548 を参照ください)。しかしこの関数は無意味です。なぜなら PHP では PPTP-MPPE は実装されていないし、今後も実装されるとは思えないからです。

返り値

復元したデータ、あるいはエラー時には FALSE を返します。

radius_demangle

(PECL radius >= 1.2.0)

radius_demangle — データを復元する

説明

string radius_demangle ( resource $radius_handle , string $mangled )

セキュリティ上の理由により、(パスワード、MS-CHAPv1 MPPE キーなど) いくつかのデータは変形されます。それを使用する際には事前に復元する 必要があります。

返り値

復元した文字列、あるいはエラー時には FALSE を返します。

radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — 属性を取得する

説明

mixed radius_get_attr ( resource $radius_handle )

Radius リクエストと同様、各レスポンスもゼロ個以上の属性を含んでいます。 radius_send_request() でレスポンスを受け取ったら、 radius_get_attr() を使用して各属性を抽出することが できます。radius_get_attr() がコールされるたびに、 現在のレスポンスから次の属性を取得します。

返り値

属性の型とデータを含む連想配列、あるいは 0 以上の エラー番号を返します。

例

例1 radius_get_attr() の例

<?php
while ($resa = radius_get_attr($res)) {

    if (!is_array($resa)) {
        printf("属性取得エラー: %s\n",  radius_strerror($res));
        exit;
    }

    $attr = $resa['attr'];
    $data = $resa['data'];
    printf("属性を取得:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
}
?>

参考

radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — ベンダ固有の属性を取得する

説明

array radius_get_vendor_attr ( string $data )

radius_get_attr() が RADIUS_VENDOR_SPECIFIC を返す場合に、 ベンダを特定するために radius_get_vendor_attr() をコールします。

返り値

属性の型、ベンダおよびデータを含む連想配列か、エラー時には FALSE を返します。

例

例1 radius_get_vendor_attr() の例

<?php
while ($resa = radius_get_attr($res)) {

    if (!is_array($resa)) {
        printf ("属性取得エラー: %s\n",  radius_strerror($res));
        exit;
    }

    $attr = $resa['attr'];
    $data = $resa['data'];
    printf("属性を取得:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
    if ($attr == RADIUS_VENDOR_SPECIFIC) {

        $resv = radius_get_vendor_attr($data);
        if (is_array($resv)) {
            $vendor = $resv['vendor'];
            $attrv = $resv['attr'];
            $datav = $resv['data'];    
            printf("ベンダ属性を取得:%d %d Bytes %s\n", $attrv, strlen($datav), bin2hex($datav));
        }
        
    }
}
?>

参考

radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — IP アドレス属性を設定する

説明

bool radius_put_addr ( resource $radius_handle , int $type , string $addr )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — バイナリ属性を設定する

説明

bool radius_put_attr ( resource $radius_handle , int $type , string $value )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 radius_put_attr() の例

<?php
mt_srand(time());
$chall = mt_rand();
$chapval = md5(pack('Ca*',1 , 'sepp' . $chall));
$pass = pack('CH*', 1, $chapval);
if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
    echo 'RadiusError:' . radius_strerror($res). "\n<br />";
    exit;
}
?>

参考

radius_put_int

(PECL radius >= 1.1.0)

radius_put_int — 整数属性を設定する

説明

bool radius_put_int ( resource $radius_handle , int $type , int $value )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 radius_put_int() の例

<?php
if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
   echo 'RadiusError:' . radius_strerror($res). "\n<br />";
   exit;
}
?>

参考

radius_put_string

(PECL radius >= 1.1.0)

radius_put_string — 文字列属性を設定する

説明

bool radius_put_string ( resource $radius_handle , int $type , string $value )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 radius_put_string() の例

<?php
if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
    echo 'RadiusError:' . radius_strerror($res). "\n<br />";
    exit;
}
?>

参考

radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — ベンダ固有の IP アドレス属性を設定する

説明

bool radius_put_vendor_addr ( resource $radius_handle , int $vendor , int $type , string $addr )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — ベンダ固有のバイナリ属性を設定する

説明

bool radius_put_vendor_attr ( resource $radius_handle , int $vendor , int $type , string $value )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 radius_put_vendor_attr() の例

<?php
if (!radius_put_vendor_attr($res, RADIUS_VENDOR_MICROSOFT, RAD_MICROSOFT_MS_CHAP_CHALLENGE, $challenge)) {
    echo 'RadiusError:' . radius_strerror($res). "\n<br />";
    exit;
}
?>

参考

radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — ベンダ固有の整数属性を設定する

説明

bool radius_put_vendor_int ( resource $radius_handle , int $vendor , int $type , int $value )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — ベンダ固有の文字列属性を設定する

説明

bool radius_put_vendor_string ( resource $radius_handle , int $vendor , int $type , string $value )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — リクエスト認証子を返す

説明

string radius_request_authenticator ( resource $radius_handle )

パスワードや暗号化キーのような加工されたデータを復元する際には リクエスト認証子が必要となります。

返り値

リクエスト認証子を文字列で返します。エラー時には FALSE を返します。

参考

radius_send_request

(PECL radius >= 1.1.0)

radius_send_request — リクエストを送信し、応答を待つ

説明

int radius_send_request ( resource $radius_handle )

Radius リクエストを作成した後は、 radius_send_request() でそれを送信します。

radius_send_request() 関数は、リクエストを送信して 応答を待ちます。定義されているサーバー間で、必要に応じてラウンドロビン 形式で再試行します。

返り値

有効な応答を受信したら、radius_send_request() は応答の型を示す Radius コードを返します。一般的なコードは RADIUS_ACCESS_ACCEPT、 RADIUS_ACCESS_REJECT あるいは RADIUS_ACCESS_CHALLENGE です。 有効な応答を受信できなかった場合は、 radius_send_request() は FALSE を返します。

参考

radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — 共有秘密鍵を返す

説明

string radius_server_secret ( resource $radius_handle )

パスワードや暗号化キーのような加工されたデータを復元する際の SALT として、共有秘密鍵が必要となります。

返り値

サーバーの共有秘密鍵を文字列で返します。エラー時には FALSE を返します。

radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — エラーメッセージを返す

説明

string radius_strerror ( resource $radius_handle )

Radius 関数が失敗した場合にはエラーメッセージが記録されます。 この関数により、エラーメッセージを取得することが可能となります。

返り値

失敗した radius 関数からのエラーメッセージを文字列で返します。

目次

日付および時刻関連

カレンダー

導入

カレンダー関数は、異なったカレンダーフォーマット間の変換を 簡単に行う関数の集まりです。標準としているのは、ユリウス積算日です。 ユリウス積算日は、紀元前 4713 年 1 月 1 日から数え始めわれています。 カレンダーシステム間の変換を行うには、ユリウス積算日に変換した後 に選択したカレンダーシステムに変換しなければなりません。 ユリウス積算日はユリウス暦とは全く違います! ユリウス積算日の詳細を知りたい場合は、 » http://www.hermetic.ch/cal_stud/jdn.htm を参照ください。 カレンダーシステムに関する情報を知りたい場合は、 » http://www.fourmilab.ch/documents/calendar/ を参照ください。 本説明にはこのページからの引用が含まれています。 このページの内容はこのチュートリアルにも反映/引用されています。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

これらの関数を動作させるには、 --enable-calendar を指定して PHP をコンパイルする必要があります。

Windows 版の PHP には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

実行時設定

設定ディレクティブは定義されていません。

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

CAL_GREGORIAN (integer)
CAL_JULIAN (integer)
CAL_JEWISH (integer)
CAL_FRENCH (integer)
CAL_NUM_CALS (integer)
CAL_DOW_DAYNO (integer)
CAL_DOW_SHORT (integer)
CAL_DOW_LONG (integer)
CAL_MONTH_GREGORIAN_SHORT (integer)
CAL_MONTH_GREGORIAN_LONG (integer)
CAL_MONTH_JULIAN_SHORT (integer)
CAL_MONTH_JULIAN_LONG (integer)
CAL_MONTH_JEWISH (integer)
CAL_MONTH_FRENCH (integer)

以下の定数は、PHP 4.3.0 以降で使用可能です。

CAL_EASTER_DEFAULT (integer)
CAL_EASTER_ROMAN (integer)
CAL_EASTER_ALWAYS_GREGORIAN (integer)
CAL_EASTER_ALWAYS_JULIAN (integer)

以下の定数は、PHP 5.0.0 以降で使用可能です。

CAL_JEWISH_ADD_ALAFIM_GERESH (integer)
CAL_JEWISH_ADD_ALAFIM (integer)
CAL_JEWISH_ADD_GERESHAYIM (integer)

カレンダー 関数

cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5)

cal_days_in_month — 指定した年とカレンダーについて、月の日数を返す

説明

int cal_days_in_month ( int $calendar , int $month , int $year )

この関数は、指定した calendar について year 年 month 月の日数を返します。

パラメータ

calendar

計算に使用するカレンダー。

month

選択したカレンダーにおける月。

year

選択したカレンダーにおける年。

返り値

指定したカレンダーの、その月の日数を返します。

例

例1 cal_days_in_month() の例

<?php
$num = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
echo "2003 年 8 月の日数は $num 日です";
?>

cal_from_jd

(PHP 4 >= 4.1.0, PHP 5)

cal_from_jd — ユリウス積算日からサポートされるカレンダーに変換する

説明

array cal_from_jd ( int $jd , int $calendar )

cal_from_jd() は、 jd で指定したユリウス日を 指定した calendar に変換します。 サポートされる calendar の値は、 CAL_GREGORIAN、 CAL_JULIAN、 CAL_JEWISH および CAL_FRENCH です。

パラメータ

jd

ユリウス日を表す整数値。

calendar

変換するカレンダー。

返り値

カレンダーの情報を含む配列を返します。この配列には、 年、月、日、週、曜日名、月名、"月/日/年" 形式の文字列 などが含まれます。

例

例1 cal_from_jd() の例

<?php
$today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
print_r(cal_from_jd($today, CAL_GREGORIAN));
?>

上の例の出力は以下となります。

Array
(
    [date] => 8/16/2003
    [month] => 8
    [day] => 16
    [year] => 2003
    [dow] => 6
    [abbrevdayname] => Sat
    [dayname] => Saturday
    [abbrevmonth] => Aug
    [monthname] => August
)

参考

  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する
  • jdtofrench() - ユリウス積算日をフランス革命暦(共和暦)に変換する
  • jdtogregorian() - ユリウス積算日をグレゴリウス日に変換する
  • jdtojewish() - ユリウス積算日をユダヤ暦に変換する
  • jdtojulian() - ユリウス積算日をユリウス暦に変換する
  • jdtounix() - ユリウス歴を Unix タイムスタンプに変換する

cal_info

(PHP 4 >= 4.1.0, PHP 5)

cal_info — 特定のカレンダーに関する情報を返す

説明

array cal_info ([ int $calendar = -1 ] )

cal_info() は、指定した calendar についての情報を返します。

カレンダーの情報は配列として返され、その要素は calname、calsymbol、 month、abbrevmonth および maxdaysinmonth となります。 calendar として指定可能なカレンダー名は以下のとおりです。

  • 0 あるいは CAL_GREGORIAN - グレゴリウス暦
  • 1 あるいは CAL_JULIAN - ユリウス暦
  • 2 あるいは CAL_JEWISH - ユダヤ暦
  • 3 あるいは CAL_FRENCH - フランス革命暦

calendar が指定されなかった場合は、 サポートするすべてのカレンダーの情報を配列で返します。

パラメータ

calendar

情報を返したいカレンダー。指定しなかった場合は、 すべてのカレンダーに関する情報を返します。

返り値

変更履歴

バージョン 説明
5.0.0 calendar パラメータが省略可能となり、 省略した場合は "すべてのカレンダー" についての情報を返すようになりました。

例

例1 cal_info() の例

<?php
$info = cal_info(0);
print_r($info);
?>

上の例の出力は以下となります。

Array
(
    [months] => Array
        (
            [1] => January
            [2] => February
            [3] => March
            [4] => April
            [5] => May
            [6] => June
            [7] => July
            [8] => August
            [9] => September
            [10] => October
            [11] => November
            [12] => December
        )

    [abbrevmonths] => Array
        (
            [1] => Jan
            [2] => Feb
            [3] => Mar
            [4] => Apr
            [5] => May
            [6] => Jun
            [7] => Jul
            [8] => Aug
            [9] => Sep
            [10] => Oct
            [11] => Nov
            [12] => Dec
        )

    [maxdaysinmonth] => 31
    [calname] => Gregorian
    [calsymbol] => CAL_GREGORIAN
)

cal_to_jd

(PHP 4 >= 4.1.0, PHP 5)

cal_to_jd — サポートされるカレンダーからユリウス積算日に変換する

説明

int cal_to_jd ( int $calendar , int $month , int $day , int $year )

cal_to_jd() は、指定した calendar の日付からユリウス積算日を計算します。 サポートされる calendar は CAL_GREGORIAN、 CAL_JULIAN、 CAL_JEWISH および CAL_FRENCH です。

パラメータ

calendar

変換元のカレンダー。 CAL_GREGORIAN、 CAL_JULIAN、 CAL_JEWISH あるいは CAL_FRENCH のいずれか。

month

月を表す数値。有効な範囲は calendar に依存します。

day

日を表す数値。有効な範囲は calendar に依存します。

year

年を表す数値。有効な範囲は calendar に依存します。

返り値

ユリウス積算日を返します。

参考

  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する
  • frenchtojd() - フランス革命暦をユリウス積算日に変換する
  • gregoriantojd() - グレゴリウス日をユリウス積算日に変換する
  • jewishtojd() - ユダヤ暦の日付けをユリウス積算日に変換する
  • juliantojd() - ユリウス暦をユリウス積算日に変換する
  • unixtojd() - Unix タイムスタンプをユリウス歴に変換する

easter_date

(PHP 4, PHP 5)

easter_date — 指定した年における復活祭の真夜中のUnix時を得る

説明

int easter_date ([ int $year ] )

指定した年yearにおける復活祭の真夜中のUnix時を返します。

警告

この関数は、年がUnixタイムスタンプの範囲を越える時 (すなわち、1970より前、または2037より後)に警告を発生します。

復活祭の日付は、西暦325年の Nicaea 会議で春分の日の後の 最初の満月の後の日曜日として定められました。 満月とその次の日曜日の日付の計算を簡単にするために 春分の日は常に3月21日になるとして計算されます。 ここで用いるアルゴリズムは、532年頃、Dionysius Exiguus により 導出されたものです。(1753年より前の年に関して)ユリウス暦の元では 月の周期を追うために簡単な19年周期が用いられます。グレゴリウス暦 (1753年以降。この暦は、ClaviusとLiliusにより考案され、 教皇グレゴリウス13世により1582年10月に導入、イギリス及びその植民地に 1752年9月に導入された。) のもとで、二つの補正係数が周期をより正確に作成するために追加されました。

パラメータ

year

1970 から 2037 までの年。

返り値

復活祭の日を Unix タイムスタンプで返します。

変更履歴

バージョン 説明
4.3.0 以降 yearパラメータはオプションとなり 省略された場合には、ローカル時間に基づく現在の年がデフォルトとなります。

例

例1 easter_date() の例

<?php

echo date("M-d-Y", easter_date(1999));        // Apr-04-1999
echo date("M-d-Y", easter_date(2000));        // Apr-23-2000
echo date("M-d-Y", easter_date(2001));        // Apr-15-2001

?>

参考

  • 1970年以前または2037年以降の復活祭の計算に関しては、 easter_days() - 指定した年において、3 月 21 日から復活祭までの日数を得る を参照ください。

easter_days

(PHP 4, PHP 5)

easter_days — 指定した年において、3 月 21 日から復活祭までの日数を得る

説明

int easter_days ([ int $year [, int $method = CAL_EASTER_DEFAULT ]] )

指定した年 year において、3 月 21 日から復活祭までの日数を返します。 year が指定されない場合、現在の年が仮定されます。

この関数は、Unix 時の範囲外(すなわち 1970 年以前または 2037 年以降)の復活祭を 計算するために easter_date() の代わりに使用することが できます。

復活祭の日付は、西暦 325 年の Nicaea の会議で春分の日以降の 最初の満月の後の日曜日として定義されました。 満月とその次の日曜日の日付の計算を簡単にするために 春分の日は常に 3 月 21 日になるとして計算されます。 ここで用いるアルゴリズムは、532 年頃に Dionysius Exiguus により 導出されたものです。(1753 年より前の年に関して)ユリウス暦のもとでは 月の周期を追うために簡単な 19 年周期が用いられます。グレゴリオ暦 (1753 年以降。この暦は Clavius と Lilius により考案され、 教皇グレゴリウス 13 世により 1582 年 10 月に導入、イギリス及びその植民地に 1752 年 9 月に導入された) のもとで、二つの補正係数が周期をより正確に作成するために追加されました。

パラメータ

year

正の数値で表した年。

method

CAL_EASTER_ROMAN に設定すると 1582 年から 1752 年までの復活祭の日付をグレゴリオ暦にもとづいて 計算します。それ以外に使用可能な定数については カレンダー定数を参照ください。

返り値

指定した年 year において、3 月 21 日から復活祭までの日数を返します。

変更履歴

バージョン 説明
4.3.0 以降 year はオプションのパラメータとなり、 もし指定されなかった場合は、地方時にもとづいた現在の年がデフォルトとなります。
4.3.0 以降 method パラメータが追加されました。

例

例1 easter_days() の例

<?php

echo easter_days(1999);        // 14, i.e. April 4
echo easter_days(1492);        // 32, i.e. April 22
echo easter_days(1913);        //  2, i.e. March 23

?>

参考

  • easter_date() - 指定した年における復活祭の真夜中のUnix時を得る

FrenchToJD

(PHP 4, PHP 5)

FrenchToJD — フランス革命暦をユリウス積算日に変換する

説明

int frenchtojd ( int $month , int $day , int $year )

日付けをフランス革命暦からユリウス積算日に変換します。

これらのルーチンは、1から14年まで(グレゴリウス暦の1792年9月22日から 1806年9月22日)日付けのみを変換します。 この期間は、フランス革命暦が使用されていた期間を十分にカバーしています。

パラメータ

month

月を表す、1 (VendĂŠmiaire) から 13 (各年の最後の 5-6 日) までの数字。

day

日を表す、1 から 30 までの数字。

year

年を表す、1 から 14 までの数字。

返り値

フランス革命暦の日付をユリウス積算日になおした結果を整数値で返します。

参考

  • jdtofrench() - ユリウス積算日をフランス革命暦(共和暦)に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する

GregorianToJD

(PHP 4, PHP 5)

GregorianToJD — グレゴリウス日をユリウス積算日に変換する

説明

int gregoriantojd ( int $month , int $day , int $year )

有効なグレゴリウス暦の範囲は紀元前 4714 年から紀元 9999 年までです。

このソフトウェアは日付けを全て紀元前 4714 年にさかのぼることが 出来ますが、この様な使い方は特に意味があるわけではありません。 グレゴリウス暦は 1582 年 10 月 15 日(ユリウス暦では 1582 年 10 月 5 日)まで制定されていませんでした。 この暦は、いくつかの国でもっと後まで受け入れられませんでした。 例えば、イギリスは 1752 年、ロシア(USSR)は 1918 年、ギリシャは 1923 年に 移行しました。 ほとんどのヨーロッパの国々では、グレゴリウス暦の前は ユリウス暦を使用していました。

パラメータ

month

月を表す、1 (January) から 12 (December) までの数字。

day

日を表す、1 から 31 までの数字。

year

年を表す、-4714 から 9999 までの数字。

返り値

指定したグレゴリウス日をユリウス積算日になおした結果を返します。

例

例1 カレンダー関数

<?php
$jd = GregorianToJD(10, 11, 1970);
echo "$jd\n";
$gregorian = JDToGregorian($jd);
echo "$gregorian\n";
?>

参考

  • jdtogregorian() - ユリウス積算日をグレゴリウス日に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する

JDDayOfWeek

(PHP 4, PHP 5)

JDDayOfWeek — 曜日を返す

説明

mixed jddayofweek ( int $julianday [, int $mode = CAL_DOW_DAYNO ] )

曜日を返します。 モードに依存した文字あるいは整数を返す事が出来ます。

パラメータ

julianday

ユリウス積算日を表す整数値。

mode
暦の曜日モード
モード 意味
0 (デフォルト) 整数で曜日番号 (0=Sunday, 1=Monday, 等)を返します。
1 曜日(英グレゴリウス)を含む文字列を返します。
2 曜日の省略形(英グレゴリウス)を含む文字列を返します。

返り値

グレゴリウス暦の曜日を表す数値あるいは文字列を返します。

JDMonthName

(PHP 4, PHP 5)

JDMonthName — 月の名前を返す

説明

string jdmonthname ( int $julianday , int $mode )

月の名前を含んだ文字列を返します。 modeはユリウス積算日をどの暦に変換するか、 どんなタイプの月名を返すかを関数に伝えます。

暦モード
モード 意味 値
0 グレゴリウス暦 - 省略形 Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
1 グレゴリウス暦 January, February, March, April, May, June, July, August, September, October, November, December
2 ユリウス暦 - 省略形 Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
3 ユリウス暦 January, February, March, April, May, June, July, August, September, October, November, December
4 ユダヤ暦 Tishri, Heshvan, Kislev, Tevet, Shevat, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
5 フランス革命暦 Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

パラメータ

jday

変換したいユリウス積算日。

calendar

月名を取得する暦。

返り値

指定したユリウス積算日と calendar にもとづく月名を返します。

JDToFrench

(PHP 4, PHP 5)

JDToFrench — ユリウス積算日をフランス革命暦(共和暦)に変換する

説明

string jdtofrench ( int $juliandaycount )

ユリウス積算日をフランス革命暦に変換します。

パラメータ

julianday

ユリウス積算日を表す整数値。

返り値

フランス革命暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • frenchtojd() - フランス革命暦をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

JDToGregorian

(PHP 4, PHP 5)

JDToGregorian — ユリウス積算日をグレゴリウス日に変換する

説明

string jdtogregorian ( int $julianday )

ユリウス積算日を "月/日/年" の形式でグレゴリウス日を含む文字列に変換します。

パラメータ

julianday

ユリウス積算日を表す整数値。

返り値

グレゴリウス暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • gregoriantojd() - グレゴリウス日をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

jdtojewish

(PHP 4, PHP 5)

jdtojewish — ユリウス積算日をユダヤ暦に変換する

説明

string jdtojewish ( int $juliandaycount [, bool $hebrew = false [, int $fl = 0 ]] )

ユリウス積算日をユダヤ暦に変換します。

パラメータ

julianday

ユリウス積算日を表す整数値。

hebrew

パラメータ hebrew が TRUE に設定されている場合、 ヘブライ語の文字列形式での出力のために fl が使用されます。

fl

使用可能なフォーマットは CAL_JEWISH_ADD_ALAFIM_GERESH、 CAL_JEWISH_ADD_ALAFIM および CAL_JEWISH_ADD_GERESHAYIM です。

返り値

ユダヤ暦の日付を "月/日/年" 形式の文字列で返します。

変更履歴

バージョン 説明
5.0.0 fl パラメータが追加されました。
4.3.0 hebrew パラメータが追加されました。

例

例1 jdtojewish() の例

<?php
echo jdtojewish(gregoriantojd(10, 8, 2002), true,
       CAL_JEWISH_ADD_GERESHAYIM + CAL_JEWISH_ADD_ALAFIM + CAL_JEWISH_ADD_ALAFIM_GERESH); 
?>

参考

  • jewishtojd() - ユダヤ暦の日付けをユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

JDToJulian

(PHP 4, PHP 5)

JDToJulian — ユリウス積算日をユリウス暦に変換する

説明

string jdtojulian ( int $julianday )

ユリウス積算日を "月/日/年" の形式でユリウス暦を含む文字列に変換します。

パラメータ

julianday

ユリウス積算日を表す整数値。

返り値

ユリウス暦の日付を "月/日/年" 形式の文字列で返します。

参考

  • juliantojd() - ユリウス暦をユリウス積算日に変換する
  • cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

jdtounix

(PHP 4, PHP 5)

jdtounix — ユリウス歴を Unix タイムスタンプに変換する

説明

int jdtounix ( int $jday )

この関数は、jday で指定したユリウス歴に 対応する Unix タイムスタンプを返します。 jday が Unix 歴 (グレゴリウス歴で 1970 年と 2037 年の間 または 2440588 <= jday <= 2465342) の範囲外の場合は FALSE を返します。返される時刻は地方時間です (GMT ではありません)。

パラメータ

jday

2440588 から 2465342 までのユリウス積算日。

返り値

指定したユリウス積算日の開始時の Unix タイムスタンプを返します。

参考

  • unixtojd() - Unix タイムスタンプをユリウス歴に変換する

JewishToJD

(PHP 4, PHP 5)

JewishToJD — ユダヤ暦の日付けをユリウス積算日に変換する

説明

int jewishtojd ( int $month , int $day , int $year )

この関数では1年(紀元前3761年)に遡って全ての日々を扱うこと が出来ますが、この様な使い方は特に意味があるわけではありません。 ユダヤ暦は数千年に渡って使われていますが、当初は月の 始まりが決められていませんでいた。新しい月は新月が最初に観測 された日に始まりました。

パラメータ

month

月を表す、1 から 13 までの数値。

day

日を表す、1 から 30 までの数値。

year

年を表す、1 から 9999 までの数値。

返り値

指定したユダヤ暦の日付に対応するユリウス積算日を返します。

参考

  • jdtojewish() - ユリウス積算日をユダヤ暦に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する

JulianToJD

(PHP 4, PHP 5)

JulianToJD — ユリウス暦をユリウス積算日に変換する

説明

int juliantojd ( int $month , int $day , int $year )

ユリウス暦は紀元前 4713 年から紀元 9999 年の範囲で使えます。

この関数は日付けを全て紀元前 4713 年にさかのぼって扱うことが 出来ますが,この様な使い方はあまり意味があるわけではありません。 このカレンダーは紀元前 46 年に作られました、しかし細部は紀元 8 年になるまで、おそらくは 4 世紀になるまで安定しませんでした。 また、年の始まりを一つの文化のものから別の文化のものに変更すること、 つまり、January を最初の月とすることは全く受け入れられませんでした。

警告

覚えておいてほしいのは、現在世界中で使用されているカレンダーは グレゴリウス暦であるということです。この日付をユリウス日に 変換するには、gregoriantojd() が使用可能です。

パラメータ

month

月を表す、1 (for January) から 12 (for December) までの数値。

day

日を表す、1 から 31 までの数値。

year

年を表す、-4713 から 9999 までの数値。

返り値

指定したユリウス暦の日付に対応するユリウス積算日を返します。

参考

  • jdtojulian() - ユリウス積算日をユリウス暦に変換する
  • cal_to_jd() - サポートされるカレンダーからユリウス積算日に変換する

unixtojd

(PHP 4, PHP 5)

unixtojd — Unix タイムスタンプをユリウス歴に変換する

説明

int unixtojd ([ int $timestamp = time() ] )

Unix タイムスタンプ(1970/1/1 からの秒数)timestamp をユリウス歴に変換して返します。timestamp が 指定されない場合は現在の日付が使用されます。

パラメータ

timestamp

変換したい Unix タイムスタンプ。

返り値

ユリウス積算日を表す整数値を返します。

参考

  • jdtounix() - ユリウス歴を Unix タイムスタンプに変換する

目次

  • cal_days_in_month — 指定した年とカレンダーについて、月の日数を返す
  • cal_from_jd — ユリウス積算日からサポートされるカレンダーに変換する
  • cal_info — 特定のカレンダーに関する情報を返す
  • cal_to_jd — サポートされるカレンダーからユリウス積算日に変換する
  • easter_date — 指定した年における復活祭の真夜中のUnix時を得る
  • easter_days — 指定した年において、3 月 21 日から復活祭までの日数を得る
  • FrenchToJD — フランス革命暦をユリウス積算日に変換する
  • GregorianToJD — グレゴリウス日をユリウス積算日に変換する
  • JDDayOfWeek — 曜日を返す
  • JDMonthName — 月の名前を返す
  • JDToFrench — ユリウス積算日をフランス革命暦(共和暦)に変換する
  • JDToGregorian — ユリウス積算日をグレゴリウス日に変換する
  • jdtojewish — ユリウス積算日をユダヤ暦に変換する
  • JDToJulian — ユリウス積算日をユリウス暦に変換する
  • jdtounix — ユリウス歴を Unix タイムスタンプに変換する
  • JewishToJD — ユダヤ暦の日付けをユリウス積算日に変換する
  • JulianToJD — ユリウス暦をユリウス積算日に変換する
  • unixtojd — Unix タイムスタンプをユリウス歴に変換する

日付・時刻

導入

以下の関数により、PHP スクリプトを実行するサーバーから 日付と時間を取得することが可能となります。 多くの異なる方法で日付や時間をフォーマットするために これらの関数を使用することができます。

日付と時刻の情報は内部的には 64 ビット数値で保持されているので、 (負の年も含めて) 考え得る限りのあらゆる日付を扱うことができます。 扱える範囲は、過去およそ2920億年と未来の同じくらいの年です。

注意: これらの関数は、使用するサーバーのロケールの設定に依存していることに注意してください。 これらの関数を使用する際にはサマータイム (例えば、.$date += 7*24*60*60ではなく、 $date = strtotime('+7 days', $date) とする) および閏年を必ず考慮に入れるようにしてください。

注意: この節で参照しているタイムゾーンは、 サポートされるタイムゾーンのリスト で見つけられます。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

注意: 最新のタイムゾーンデータベースの取得

最新バージョンのタイムゾーンデータベースは、PECL の » timezonedb からインストールできます。

注意: PHP 5.1.x における実験的な DateTime サポート

DateTime クラス (とそれに関連する関数) がデフォルトで使用できるようになったのは PHP 5.2.0 からですが、 PHP 5.1.x でも実験的な DateTime サポートを追加することができます。 そのためには、configure/コンパイルの前に CFLAGS=-DEXPERIMENTAL_DATE_SUPPORT=1 フラグを使用します。

実行時設定

php.ini の設定により動作が変化します。

Date/Time Configuration Options
名前 デフォルト 変更可能 変更履歴
date.default_latitude "31.7667" PHP_INI_ALL PHP 5.0.0 以降で利用可能
date.default_longitude "35.2333" PHP_INI_ALL PHP 5.0.0 以降で利用可能
date.sunrise_zenith "90.583333" PHP_INI_ALL PHP 5.0.0 以降で利用可能
date.sunset_zenith "90.583333" PHP_INI_ALL PHP 5.0.0 以降で利用可能
date.timezone "GMT" PHP_INI_ALL PHP 5.1.0 以降で利用可能
PHP_INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

date.default_latitude float

デフォルトの緯度

date.default_longitude float

デフォルトの経度

date.sunrise_zenith float

デフォルトの日出点

date.sunset_zenith float

デフォルトの日没点

date.timezone string

全ての日付/時刻関数で使用されるデフォルトのタイムゾーン。 PHP 5.4.0 より前のバージョンでは、これは環境変数 TZ の値が設定されていない場合にのみ機能していました。 明示的に指定しなかったときにどのタイムゾーンを利用するのかについての優先順位は date_default_timezone_get() のページで解説されています。サポートしているタイムゾーンについては サポートされるタイムゾーンのリスト を参照ください。

注意: 最初の 4 つの設定オプションは現時点で date_sunrise() と date_sunset() でのみ使用されます。

リソース型

リソース型は定義されていません。

定義済み定数

DATE_ 定数 は PHP 5.1.1 以降で定義されており、標準的な日付の書式を表します。 日付フォーマット関数（date() など）で使用します。

以下の定数は PHP 5.1.2 以降に存在し、関数 date_sunrise() および date_sunset() が返す結果の書式を指定します。

SUNFUNCS_RET_TIMESTAMP (integer)
タイムスタンプ
SUNFUNCS_RET_STRING (integer)
時:分 (例: 08:02)
SUNFUNCS_RET_DOUBLE (integer)
時刻を表す浮動小数点値 (例 8.75)

DateTime クラス

(PHP 5 >= 5.2.0)

導入

日付と時刻をあらわします。

クラス概要

DateTime {
/* 定数 */
const string ATOM = "Y-m-d\TH:i:sP" ;
const string COOKIE = "l, d-M-y H:i:s T" ;
const string ISO8601 = "Y-m-d\TH:i:sO" ;
const string RFC822 = "D, d M y H:i:s O" ;
const string RFC850 = "l, d-M-y H:i:s T" ;
const string RFC1036 = "D, d M y H:i:s O" ;
const string RFC1123 = "D, d M Y H:i:s O" ;
const string RFC2822 = "D, d M Y H:i:s O" ;
const string RFC3339 = "Y-m-d\TH:i:sP" ;
const string RSS = "D, d M Y H:i:s O" ;
const string W3C = "Y-m-d\TH:i:sP" ;
/* メソッド */
public __construct ([ string $time = "now" [, DateTimeZone $timezone = NULL ]] )
public DateTime add ( DateInterval $interval )
public static DateTime createFromFormat ( string $format , string $time [, DateTimeZone $timezone ] )
public DateInterval diff ( DateTime $datetime2 [, bool $absolute = false ] )
public string format ( string $format )
public static array getLastErrors ( void )
public int getOffset ( void )
public int getTimestamp ( void )
public DateTimeZone getTimezone ( void )
public DateTime modify ( string $modify )
public static DateTime __set_state ( array $array )
public DateTime setDate ( int $year , int $month , int $day )
public DateTime setISODate ( int $year , int $week [, int $day = 1 ] )
public DateTime setTime ( int $hour , int $minute [, int $second = 0 ] )
public DateTime setTimestamp ( int $unixtimestamp )
public DateTime setTimezone ( DateTimeZone $timezone )
public DateTime sub ( DateInterval $interval )
public DateTime __wakeup ( void )
}

定義済み定数

DateTime::ATOM
DATE_ATOM
Atom (例: 2005-08-15T15:52:01+00:00)
DateTime::COOKIE
DATE_COOKIE
HTTP Cookies (例: Monday, 15-Aug-05 15:52:01 UTC)
DateTime::ISO8601
DATE_ISO8601
ISO-8601 (例: 2005-08-15T15:52:01+0000)
DateTime::RFC822
DATE_RFC822
RFC 822 (例: Mon, 15 Aug 05 15:52:01 +0000)
DateTime::RFC850
DATE_RFC850
RFC 850 (例: Monday, 15-Aug-05 15:52:01 UTC)
DateTime::RFC1036
DATE_RFC1036
RFC 1036 (例: Mon, 15 Aug 05 15:52:01 +0000)
DateTime::RFC1123
DATE_RFC1123
RFC 1123 (例: Mon, 15 Aug 2005 15:52:01 +0000)
DateTime::RFC2822
DATE_RFC2822
RFC 2822 (Mon, 15 Aug 2005 15:52:01 +0000)
DateTime::RFC3339
DATE_RFC3339
DATE_ATOM と同じ (PHP 5.1.3 以降)
DateTime::RSS
DATE_RSS
RSS (Mon, 15 Aug 2005 15:52:01 +0000)
DateTime::W3C
DATE_W3C
World Wide Web Consortium (例: 2005-08-15T15:52:01+00:00)

変更履歴

バージョン 説明
5.2.2 DateTime オブジェクトどうしの 比較演算子 による比較が、期待通りに動作するようになりました。 これより前のバージョンでは、すべての DateTime オブジェクトは (== による比較で) 等しいと見なされていました。

DateTime::add

date_add

(PHP 5 >= 5.3.0)

DateTime::add -- date_add — 年月日時分秒の値を DateTime オブジェクトに加える

説明

オブジェクト指向型

public DateTime DateTime::add ( DateInterval $interval )

手続き型

DateTime date_add ( DateTime $object , DateInterval $interval )

指定した DateInterval オブジェクトを、 指定した DateTime オブジェクトに加えます。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

interval

DateInterval オブジェクト。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に FALSE を返します。

例

例1 DateTime::add() の例

オブジェクト指向型

<?php
$date = new DateTime('2000-01-01');
$date->add(new DateInterval('P10D'));
echo $date->format('Y-m-d') . "\n";
?>

手続き型

<?php
$date = date_create('2000-01-01');
date_add($date, date_interval_create_from_date_string('10 days'));
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2000-01-11

例2 DateTime::add() の別の例

<?php
$date = new DateTime('2000-01-01');
$date->add(new DateInterval('PT10H30S'));
echo $date->format('Y-m-d H:i:s') . "\n";

$date = new DateTime('2000-01-01');
$date->add(new DateInterval('P7Y5M4DT4H3M2S'));
echo $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は以下となります。

2000-01-01 10:00:30
2007-06-05 04:03:02

例3 月を加算するときの注意点

<?php
$date = new DateTime('2000-12-31');
$interval = new DateInterval('P1M');

$date->add($interval);
echo $date->format('Y-m-d') . "\n";

$date->add($interval);
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-01-31
2001-03-03

注意

PHP 5.2 では、かわりに DateTime::modify() を使うことができます。

参考

DateTime::__construct

date_create

(PHP 5 >= 5.2.0)

DateTime::__construct -- date_create — 新しい DateTime オブジェクトを返す

説明

オブジェクト指向型

public DateTime::__construct() ([ string $time = "now" [, DateTimeZone $timezone = NULL ]] )

手続き型

DateTime date_create ([ string $time = "now" [, DateTimeZone $timezone = NULL ]] )

新しい DateTime オブジェクトを返します。

パラメータ

time

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

ここに NULL を指定して $timezone パラメータを使うと、現在時刻を取得できます。

timezone

指定したいタイムゾーンを表す DateTimeZone オブジェクト。

$timezone を省略した場合は、 現在のタイムゾーンを使います。

注意:

$time パラメータが UNIX タイムスタンプ (@946684800 など) であったりタイムゾーンつきで指定した場合 (2010-01-28T15:00:00+02:00 など) は、 $timezone パラメータや現在のタイムゾーンは無視されます。

返り値

新しい DateTime のインスタンスを返します。 手続き型 の場合は、失敗したときに FALSE を返します。

エラー / 例外

エラーがあった場合は Exception を発生させます。

変更履歴

バージョン 説明
5.3.0 無効な日付を指定した場合に例外がスローされるようになりました。 これまではエラーが発生していました。

例

例1 DateTime::__construct() の例

オブジェクト指向型

<?php
try {
    $date = new DateTime('2000-01-01');
} catch (Exception $e) {
    echo $e->getMessage();
    exit(1);
}

echo $date->format('Y-m-d');
?>

手続き型

<?php
$date = date_create('2000-01-01');
if (!$date) {
    $e = date_get_last_errors();
    foreach ($e['errors'] as $error) {
        echo "$error\n";
    }
    exit(1);
}

echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2000-01-01

例2 DateTime::__construct() の複雑な例

<?php
// そのコンピュータのタイムゾーンでの日時の指定
$date = new DateTime('2000-01-01');
echo $date->format('Y-m-d H:i:sP') . "\n";

// 指定したタイムゾーンでの日時の指定
$date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

// そのコンピュータのタイムゾーンでの現在日時
$date = new DateTime();
echo $date->format('Y-m-d H:i:sP') . "\n";

// 指定したタイムゾーンでの現在日時
$date = new DateTime(null, new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

// UNIX タイムスタンプの使用例。結果のタイムゾーンは UTC となることに注意しましょう。
$date = new DateTime('@946684800');
echo $date->format('Y-m-d H:i:sP') . "\n";

// 存在しない値は繰り上がります
$date = new DateTime('2000-02-30');
echo $date->format('Y-m-d H:i:sP') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2000-01-01 00:00:00-05:00
2000-01-01 00:00:00+12:00
2010-04-24 10:24:16-04:00
2010-04-25 02:24:16+12:00
2000-01-01 00:00:00+00:00
2000-03-01 00:00:00-05:00

参考

DateTime::createFromFormat

date_create_from_format

(PHP 5 >= 5.3.0)

DateTime::createFromFormat -- date_create_from_format — 指定した書式でフォーマットした新しい DateTime オブジェクトを返す

説明

オブジェクト指向型

public static DateTime DateTime::createFromFormat ( string $format , string $time [, DateTimeZone $timezone ] )

手続き型

DateTime date_create_from_format ( string $format , string $time [, DateTimeZone $timezone ] )

指定した書式でフォーマットした新しい DateTime オブジェクトを返します。

パラメータ

format

書式を文字列で渡します。以下の書式オプションを参照ください。 大半は、date() で使える文字と同じです。

format パラメータに渡せる文字
format 文字 説明 取りうる値の例
日 --- ---
d および j 2桁の日付。先頭のゼロを含むものと含まないもの 01 から 31 あるいは 1 から 31
D および l 曜日を表す文字列 Mon から Sun あるいは Sunday から Saturday
S 日付の後につける英語の接尾辞。二文字。処理中には無視されます。 st、nd、rd あるいは th
z 年始からの通算日数 (最初は 0) 0 から 365
月 --- ---
F および M 月を表す文字列。January あるいは Sept など January から December あるいは Jan から Dec
m および n 月を表す数値。先頭のゼロを含むものと含まないもの 01 から 12 あるいは 1 から 12
年 --- ---
Y 4 桁の数値で表した年 例: 1999 あるいは 2003
y 2 桁の数値で表した年 例: 99 あるいは 03
時刻 --- ---
a および A 午前および午後 am あるいは pm
g および h 12 時間制での時間。先頭のゼロを含むものと含まないもの 1 から 12 あるいは 01 から 12
G and H 24 時間制での時間。先頭のゼロを含むものと含まないもの 0 から 23 あるいは 00 から 23
i 分。先頭のゼロを含む 00 から 59
s 秒。先頭のゼロを含む 00 から 59
u マイクロ秒 (最大 6 桁) 例: 45, 654321
タイムゾーン --- ---
e、O、 P および T タイムゾーン識別子、UTC からの時差 (時間単位)、 UTC からの時差 (コロン区切りでの時間と分)、そしてタイムゾーンの短縮形 例: UTC、GMT、 Atlantic/Azores あるいは +0200 あるいは +02:00 あるいは EST、MDT
完全な日付/時刻 --- ---
U Unix エポック (January 1 1970 00:00:00 GMT) からの経過秒数 例: 1292177455
空白および区切り --- ---
(空白) 空白 1 文字あるいはタブ 1 文字 例:
# 次の区切り文字のいずれか: ;, :, /, ., ,, -, ( あるいは ) 例: /
;, :, /, ., ,, -, ( あるいは ) 指定した文字 例: -
? ランダムなバイト 例: ^ (UTF-8 文字の場合は複数の ? が必要になるでしょう。この場合、おそらく * を使うと要望が満たせるはずです)
* 次の区切り文字あるいは数字までのランダムなバイト列 例: Y-*-d の中の * は、文字列 2009-aWord-08 の中の aWord にマッチします
! すべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を Unix エポックにリセットする ! がなければ、すべてのフィールドは現在の日時に設定されます。
| まだパースされていないすべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を Unix エポックにリセットする Y-m-d| は、文字列をパースした結果から年月日を設定し 時分秒には 0 を設定します。
+ この文字があると、文字列のそれ以降のデータではエラーが発生せず、 かわりに警告を発生させる それ以降のデータが存在したかどうかを調べるには DateTime::getLastErrors() を使います。

書式文字列の中に解釈不能な文字が含まれていると処理は失敗し、 返り値にはエラーメッセージが付加されます。エラーメッセージを調べるには DateTime::getLastErrors() を使います。

format に文字 ! が含まれない場合は、作成した時刻値のうち format で指定されていない部分を 現在のシステム時刻で初期化します。

format に文字 ! が含まれる場合は、作成した時刻値のうち format で指定されていない部分と ! の左側の部分を Unix エポックの対応する箇所の値で初期化します。

Unix エポックは 1970-01-01 00:00:00 です。

time

時刻を表す文字列。

timezone

指定したいタイムゾーンを表す DateTimeZone オブジェクト。

timezone を省略し、かつ time にタイムゾーンが含まれない場合は、 現在のタイムゾーンを使います。

注意:

time パラメータが UNIX タイムスタンプ (例: 946684800) だったりタイムゾーンを含んでいたり (例: 2010-01-28T15:00:00+02:00) する場合は、 timezone パラメータや現在のタイムゾーンは無視します。

返り値

新しい DateTime のインスタンス、失敗した場合に FALSE を返します。

例

例1 DateTime::createFromFormat() の例

オブジェクト指向型

<?php
$date = DateTime::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');
?>

手続き型

<?php
$date = date_create_from_format('j-M-Y', '15-Feb-2009');
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2009-02-15

例2 DateTime::createFromFormat() の複雑な例

<?php
echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d';
$date = DateTime::createFromFormat($format, '2009-02-15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d H:i:s';
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-!d H:i:s';
$date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = '!d';
$date = DateTime::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Current time: 2010-04-23 10:29:35
Format: Y-m-d; 2009-02-15 10:29:35
Format: Y-m-d H:i:s; 2009-02-15 15:16:17
Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
Format: !d; 1970-01-15 00:00:00

参考

DateTime::diff

date_diff

(PHP 5 >= 5.3.0)

DateTime::diff -- date_diff — ふたつの DateTime オブジェクトの差を返す

説明

オブジェクト指向型

public DateInterval DateTime::diff ( DateTime $datetime2 [, bool $absolute = false ] )

手続き型

DateInterval date_diff ( DateTime $datetime1 , DateTime $datetime2 [, bool $absolute = false ] )

ふたつの DateTime オブジェクトの差を返します。

パラメータ

datetime

比較する日付。

absolute

差の絶対値を返すか否か。

返り値

ふたつの日付の差をあらわす DateInterval オブジェクトを返します。 失敗した場合に FALSE を返します

例

例1 DateTime::diff() の例

オブジェクト指向型

<?php
$datetime1 = new DateTime('2009-10-11');
$datetime2 = new DateTime('2009-10-13');
$interval = $datetime1->diff($datetime2);
echo $interval->format('%R%a days');
?>

手続き型

<?php
$datetime1 = date_create('2009-10-11');
$datetime2 = date_create('2009-10-13');
$interval = date_diff($datetime1, $datetime2);
echo $interval->format('%R%a days');
?>

上の例の出力は以下となります。

+2 days

例2 DateTime オブジェクトの比較

注意:

PHP 5.2.2 以降では、DateTime オブジェクトを 比較演算子 で比較できるようになりました。

<?php
$date1 = new DateTime("now");
$date2 = new DateTime("tomorrow");

var_dump($date1 == $date2);
var_dump($date1 < $date2);
var_dump($date1 > $date2);
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)

参考

DateTime::format

date_format

(PHP 5 >= 5.2.0)

DateTime::format -- date_format — 指定した書式でフォーマットした日付を返す

説明

オブジェクト指向型

public string DateTime::format ( string $format )

手続き型

string date_format ( DateTime $object , string $format )

指定した書式でフォーマットした日付を返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

format

date() が理解できる書式指定文字列。

返り値

成功した場合にフォーマット済みの日付文字列、失敗した場合に FALSE を返します。

例

例1 DateTime::format() の例

オブジェクト指向型

<?php
$date = new DateTime('2000-01-01');
echo $date->format('Y-m-d H:i:s');
?>

手続き型

<?php
$date = date_create('2000-01-01');
echo date_format($date, 'Y-m-d H:i:s');
?>

上の例の出力は以下となります。

2000-01-01 00:00:00

注意

このメソッドはロケールを考慮しません。出力結果はすべて英語となります。

参考

  • date() - ローカルの日付/時刻を書式化する

DateTime::getLastErrors

date_get_last_errors

(PHP 5 >= 5.3.0)

DateTime::getLastErrors -- date_get_last_errors — 警告およびエラーを返す

説明

オブジェクト指向型

public static array DateTime::getLastErrors ( void )

手続き型

array date_get_last_errors ( void )

日付/時刻文字列のパース時に見つかった警告やエラーの配列を返します。

パラメータ

この関数にはパラメータはありません。

返り値

警告やエラーに関する情報を含む配列を返します。

例

例1 DateTime::getLastErrors() の例

オブジェクト指向型

<?php
try {
    $date = new DateTime('asdfasdf');
} catch (Exception $e) {
    // 使用例を出したかっただけ...
    print_r(DateTime::getLastErrors());

    // オブジェクト指向流にやるなら、本来は
    // echo $e->getMessage();
}
?>

手続き型

<?php
$date = date_create('asdfasdf');
print_r(DateTime::getLastErrors());
?>

上の例の出力は以下となります。

Array
(
   [warning_count] => 1
   [warnings] => Array
       (
           [6] => Double timezone specification
       )

   [error_count] => 1
   [errors] => Array
       (
           [0] => The timezone could not be found in the database
       )

)

DateTime::getOffset

date_offset_get

(PHP 5 >= 5.2.0)

DateTime::getOffset -- date_offset_get — タイムゾーンのオフセットを返す

説明

オブジェクト指向型

public int DateTime::getOffset ( void )

手続き型

int date_offset_get ( DateTime $object )

タイムゾーンのオフセットを返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

返り値

成功した場合には UTC からのタイムゾーンオフセット秒数、 失敗した場合に FALSE を返します。

例

例1 DateTime::getOffset() の例

オブジェクト指向型

<?php
$winter = new DateTime('2010-12-21', new DateTimeZone('America/New_York'));
$summer = new DateTime('2008-06-21', new DateTimeZone('America/New_York'));

echo $winter->getOffset() . "\n";
echo $summer->getOffset() . "\n";
?>

手続き型

<?php
$winter = date_create('2010-12-21', timezone_open('America/New_York'));
$summer = date_create('2008-06-21', timezone_open('America/New_York'));

echo date_offset_get($winter) . "\n";
echo date_offset_get($summer) . "\n";
?>

上の例の出力は以下となります。

-18000
-14400

Note: -18000 = -5 hours, -14400 = -4 hours.

DateTime::getTimestamp

date_timestamp_get

(PHP 5 >= 5.3.0)

DateTime::getTimestamp -- date_timestamp_get — Unix タイムスタンプを取得する

説明

オブジェクト指向型

public int DateTime::getTimestamp ( void )

手続き型

int date_timestamp_get ( DateTime $object )

Unix タイムスタンプを取得します。

パラメータ

この関数にはパラメータはありません。

返り値

その日付をあらわす Unix タイムスタンプを返します。

例

例1 DateTime::getTimestamp() の例

オブジェクト指向型

<?php
$date = new DateTime();
echo $date->getTimestamp();
?>

手続き型

<?php
$date = date_create();
echo date_timestamp_get($date);
?>

上の例の出力は、 たとえば以下のようになります。

1272509157

注意

PHP 5.2 では、 DateTime::format() のパラメータに U を使えば同じことができます。

参考

DateTime::getTimezone

date_timezone_get

(PHP 5 >= 5.2.0)

DateTime::getTimezone -- date_timezone_get — 指定した DateTime に関連するタイムゾーンを返す

説明

オブジェクト指向型

public DateTimeZone DateTime::getTimezone ( void )

手続き型

DateTimeZone date_timezone_get ( DateTime $object )

指定した DateTime に関連するタイムゾーンを返します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト

返り値

成功した場合に DateTimeZone オブジェクト、失敗した場合に FALSE を返します。

例

例1 DateTime::getTimezone() の例

オブジェクト指向型

<?php
$date = new DateTime(null, new DateTimeZone('Europe/London'));
$tz = $date->getTimezone();
echo $tz->getName();
?>

手続き型

<?php
$date = date_create(null, timezone_open('Europe/London'));
$tz = date_timezone_get($date);
echo timezone_name_get($tz);
?>

上の例の出力は以下となります。

Europe/London

参考

DateTime::modify

date_modify

(PHP 5 >= 5.2.0)

DateTime::modify -- date_modify — タイムスタンプを変更する

説明

オブジェクト指向型

public DateTime DateTime::modify ( string $modify )

手続き型

DateTime date_modify ( DateTime $object , string $modify )

strtotime() 形式で加算あるいは減算することによって DateTime オブジェクトのタイムスタンプを変更します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

modify

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.3.6 日付/時刻の絶対指定も効果を及ぼすようになりました。 これまでは、相対指定部分だけを用いていました。
5.3.0成功した場合の返り値が NULL から DateTime に変更されました。

例

例1 DateTime::modify() の例

オブジェクト指向型

<?php
$date = new DateTime('2006-12-12');
$date->modify('+1 day');
echo $date->format('Y-m-d');
?>

手続き型

<?php
$date = date_create('2006-12-12');
date_modify($date, '+1 day');
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2006-12-13

例2 月の加減算には注意

<?php
$date = new DateTime('2000-12-31');

$date->modify('+1 month');
echo $date->format('Y-m-d') . "\n";

$date->modify('+1 month');
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-01-31
2001-03-03

参考

DateTime::__set_state

(PHP 5 >= 5.2.0)

DateTime::__set_state — __set_state ハンドラ

説明

public static DateTime DateTime::__set_state ( array $array )

__set_state() を処理します。

パラメータ

array

初期化配列。

返り値

新しい DateTime オブジェクトのインスタンスを返します。

DateTime::setDate

date_date_set

(PHP 5 >= 5.2.0)

DateTime::setDate -- date_date_set — 日付を設定する

説明

オブジェクト指向型

public DateTime DateTime::setDate ( int $year , int $month , int $day )

手続き型

DateTime date_date_set ( DateTime $object , int $year , int $month , int $day )

DateTime オブジェクトの現在の日付をリセットし、別の日付にします。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

year

その日付の年。

month

その日付の月。

day

その日付の日。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.3.0成功した場合の返り値が NULL から DateTime に変更されました。

例

例1 DateTime::setDate() の例

オブジェクト指向型

<?php
$date = new DateTime();
$date->setDate(2001, 2, 3);
echo $date->format('Y-m-d');
?>

手続き型

<?php
$date = date_create();
date_date_set($date, 2001, 2, 3);
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2001-02-03

例2 範囲を超えた値が親の値に加算される例

<?php
$date = new DateTime();

$date->setDate(2001, 2, 28);
echo $date->format('Y-m-d') . "\n";

$date->setDate(2001, 2, 29);
echo $date->format('Y-m-d') . "\n";

$date->setDate(2001, 14, 3);
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-02-28
2001-03-01
2002-02-03

参考

DateTime::setISODate

date_isodate_set

(PHP 5 >= 5.2.0)

DateTime::setISODate -- date_isodate_set — ISO 日付を設定する

説明

オブジェクト指向型

public DateTime DateTime::setISODate ( int $year , int $week [, int $day = 1 ] )

手続き型

DateTime date_isodate_set ( DateTime $object , int $year , int $week [, int $day = 1 ] )

ISO 8601 標準形式、つまり週と日オフセットで日付を設定します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

year

その日付の年。

week

その日付の週。

day

週の最初の日からのオフセット。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.3.0成功した場合の返り値が NULL から DateTime に変更されました。

例

例1 DateTime::setISODate() の例

オブジェクト指向型

<?php
$date = new DateTime();

$date->setISODate(2008, 2);
echo $date->format('Y-m-d') . "\n";

$date->setISODate(2008, 2, 7);
echo $date->format('Y-m-d') . "\n";
?>

手続き型

<?php
$date = date_create();

date_isodate_set($date, 2008, 2);
echo date_format($date, 'Y-m-d') . "\n";

date_isodate_set($date, 2008, 2, 7);
echo date_format($date, 'Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2008-01-07
2008-01-13

例2 範囲を超えた値が親の値に加算される例

<?php
$date = new DateTime();

$date->setISODate(2008, 2, 7);
echo $date->format('Y-m-d') . "\n";

$date->setISODate(2008, 2, 8);
echo $date->format('Y-m-d') . "\n";

$date->setISODate(2008, 53, 7);
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2008-01-13
2008-01-14
2009-01-04

例3 その週が存在する月を探す例

<?php
$date = new DateTime();
$date->setISODate(2008, 14);
echo $date->format('n');
?>

上の例の出力は以下となります。

3

参考

DateTime::setTime

date_time_set

(PHP 5 >= 5.2.0)

DateTime::setTime -- date_time_set — 時刻を設定する

説明

オブジェクト指向型

public DateTime DateTime::setTime ( int $hour , int $minute [, int $second = 0 ] )

手続き型

DateTime date_time_set ( DateTime $object , int $hour , int $minute [, int $second = 0 ] )

DateTime オブジェクトの現在時刻を別の時刻にリセットします。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

hour

その時刻の時。

minute

その時刻の分。

second

その時刻の秒。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.3.0成功した場合の返り値が NULL から DateTime に変更されました。

例

例1 DateTime::setTime() の例

オブジェクト指向型

<?php
$date = new DateTime('2001-01-01');

$date->setTime(14, 55);
echo $date->format('Y-m-d H:i:s') . "\n";

$date->setTime(14, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";
?>

手続き型

<?php
$date = date_create('2001-01-01');

date_time_set($date, 14, 55);
echo date_format($date, 'Y-m-d H:i:s') . "\n";

date_time_set($date, 14, 55, 24);
echo date_format($date, 'Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

2000-01-01 14:55:00
2000-01-01 14:55:24

例2 範囲を超えた値が親の値に加算される例

<?php
$date = new DateTime('2001-01-01');

$date->setTime(14, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";

$date->setTime(14, 55, 65);
echo $date->format('Y-m-d H:i:s') . "\n";

$date->setTime(14, 65, 24);
echo $date->format('Y-m-d H:i:s') . "\n";

$date->setTime(25, 55, 24);
echo $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は以下となります。

2001-01-01 14:55:24
2001-01-01 14:56:05
2001-01-01 15:05:24
2001-01-02 01:55:24

参考

DateTime::setTimestamp

date_timestamp_set

(PHP 5 >= 5.3.0)

DateTime::setTimestamp -- date_timestamp_set — Unix タイムスタンプを用いて日付と時刻を設定する

説明

オブジェクト指向型

public DateTime DateTime::setTimestamp ( int $unixtimestamp )

手続き型

DateTime date_timestamp_set ( DateTime $object , int $unixtimestamp )

Unix タイムスタンプを用いて日付と時刻を設定します。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

unixtimestamp

Unix タイムスタンプ。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に FALSE を返します。

例

例1 DateTime::setTimestamp() の例

オブジェクト指向型

<?php
$date = new DateTime();
echo $date->format('U = Y-m-d H:i:s') . "\n";

$date->setTimestamp(1171502725);
echo $date->format('U = Y-m-d H:i:s') . "\n";
?>

手続き型

<?php
$date = date_create();
echo date_format($date, 'U = Y-m-d H:i:s') . "\n";

date_timestamp_set($date, 1171502725);
echo date_format($date, 'U = Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1272508903 = 2010-04-28 22:41:43
1171502725 = 2007-02-14 20:25:25

注意

PHP 5.2 を使っている場合は、 Unix タイムスタンプ形式を使って新しい DateTime オブジェクトを作る方法もあります。 以下の例を参照ください。

例2 PHP 5.2 における DateTime::setTimestamp() のもうひとつの方法

<?php
$ts = 1171502725;
$date = new DateTime("@$ts");
echo $date->format('U = Y-m-d H:i:s') . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

1171502725 = 2007-02-14 20:25:25

参考

DateTime::setTimezone

date_timezone_set

(PHP 5 >= 5.2.0)

DateTime::setTimezone -- date_timezone_set — DateTime オブジェクトのタイムゾーンを設定する

説明

オブジェクト指向型

public DateTime DateTime::setTimezone ( DateTimeZone $timezone )

手続き型

DateTime date_timezone_set ( DateTime $object , DateTimeZone $timezone )

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

timezone

指定したいタイムゾーンを表す DateTimeZone オブジェクト。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.3.0成功した場合の返り値が NULL から DateTime に変更されました。

例

例1 DateTime::setTimeZone() の例

オブジェクト指向型

<?php
$date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
echo $date->format('Y-m-d H:i:sP') . "\n";

$date->setTimezone(new DateTimeZone('Pacific/Chatham'));
echo $date->format('Y-m-d H:i:sP') . "\n";
?>

手続き型

<?php
$date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
echo date_format($date, 'Y-m-d H:i:sP') . "\n";

date_timezone_set($date, timezone_open('Pacific/Chatham'));
echo date_format($date, 'Y-m-d H:i:sP') . "\n";
?>

上の例の出力は以下となります。

2000-01-01 00:00:00+12:00
2000-01-01 01:45:00+13:45

参考

DateTime::sub

date_sub

(PHP 5 >= 5.3.0)

DateTime::sub -- date_sub — 年月日時分秒の値を DateTime オブジェクトから引く

説明

オブジェクト指向型

public DateTime DateTime::sub ( DateInterval $interval )

手続き型

DateTime date_sub ( DateTime $object , DateInterval $interval )

指定した DateInterval オブジェクトを、 指定した DateTime オブジェクトから引きます。

パラメータ

object

手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。

interval

DateInterval オブジェクト。

返り値

メソッドチェインに使う DateTime オブジェクトを返します。失敗した場合に FALSE を返します。

例

例1 DateTime::sub() の例

オブジェクト指向型

<?php
$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('P10D'));
echo $date->format('Y-m-d') . "\n";
?>

手続き型

<?php
$date = date_create('2000-01-20');
date_sub($date, date_interval_create_from_date_string('10 days'));
echo date_format($date, 'Y-m-d');
?>

上の例の出力は以下となります。

2000-01-10

例2 DateTime::sub() の別の例

<?php
$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('PT10H30S'));
echo $date->format('Y-m-d H:i:s') . "\n";

$date = new DateTime('2000-01-20');
$date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
echo $date->format('Y-m-d H:i:s') . "\n";
?>

上の例の出力は以下となります。

2000-01-19 13:59:30
1992-08-15 19:56:58

例3 月を減算するときの注意点

<?php
$date = new DateTime('2001-04-30');
$interval = new DateInterval('P1M');

$date->sub($interval);
echo $date->format('Y-m-d') . "\n";

$date->sub($interval);
echo $date->format('Y-m-d') . "\n";
?>

上の例の出力は以下となります。

2001-03-30
2001-03-02

注意

PHP 5.2 では、かわりに DateTime::modify() を使うことができます。

参考

DateTime::__wakeup

(PHP 5 >= 5.2.0)

DateTime::__wakeup — __wakeup ハンドラ

説明

public DateTime DateTime::__wakeup ( void )

__wakeup() を処理します。

パラメータ

この関数にはパラメータはありません。

返り値

DateTime オブジェクトを初期化します。

目次

DateTimeZone クラス

(PHP 5 >= 5.2.0)

導入

タイムゾーンをあらわします。

クラス概要

DateTimeZone {
/* 定数 */
const integer AFRICA = 1 ;
const integer AMERICA = 2 ;
const integer ANTARCTICA = 4 ;
const integer ARCTIC = 8 ;
const integer ASIA = 16 ;
const integer ATLANTIC = 32 ;
const integer AUSTRALIA = 64 ;
const integer EUROPE = 128 ;
const integer INDIAN = 256 ;
const integer PACIFIC = 512 ;
const integer UTC = 1024 ;
const integer ALL = 2047 ;
const integer ALL_WITH_BC = 4095 ;
const integer PER_COUNTRY = 4096 ;
/* メソッド */
public __construct ( string $timezone )
public array getLocation ( void )
public string getName ( void )
public int getOffset ( DateTime $datetime )
public array getTransitions ([ int $timestamp_begin [, int $timestamp_end ]] )
public static array listAbbreviations ( void )
public static array listIdentifiers ([ int $what = DateTimeZone::ALL [, string $country = NULL ]] )
}

定義済み定数

DateTimeZone::AFRICA

アフリカのタイムゾーン。

DateTimeZone::AMERICA

アメリカのタイムゾーン。

DateTimeZone::ANTARCTICA

南極のタイムゾーン。

DateTimeZone::ARCTIC

北極のタイムゾーン。

DateTimeZone::ASIA

アジアのタイムゾーン。

DateTimeZone::ATLANTIC

大西洋のタイムゾーン。

DateTimeZone::AUSTRALIA

オーストラリアのタイムゾーン。

DateTimeZone::EUROPE

ヨーロッパのタイムゾーン。

DateTimeZone::INDIAN

インドのタイムゾーン。

DateTimeZone::PACIFIC

太平洋のタイムゾーン。

DateTimeZone::UTC

UTC タイムゾーン。

DateTimeZone::ALL

すべてのタイムゾーン。

DateTimeZone::ALL_WITH_BC

過去との互換性を保つものを含むすべてのタイムゾーン。

DateTimeZone::PER_COUNTRY

国ごとのタイムゾーン。

DateTimeZone::__construct

timezone_open

(PHP 5 >= 5.2.0)

DateTimeZone::__construct -- timezone_open — 新しい DateTimeZone オブジェクトを作成する

説明

オブジェクト指向型

public DateTimeZone::__construct() ( string $timezone )

手続き型

DateTimeZone timezone_open ( string $timezone )

新しい DateTimeZone オブジェクトを作成します。

パラメータ

timezone

いずれかの タイムゾーン。

返り値

成功した場合に DateTimeZone を返します。 手続き型 の場合は、失敗したときに FALSE を返します。

エラー / 例外

このメソッドは、指定したタイムゾーンが無効な形式だった場合に Exception をスローします。

例

例1 DateTimeZone のインスタンスを作成する際のエラー処理

<?php
// エラー処理は、例外をキャッチすることで行います
$timezones = array('Europe/London', 'Mars/Phobos', 'Jupiter/Europa');

foreach ($timezones as $tz) {
    try {
        $mars = new DateTimeZone($tz);
    } catch(Exception $e) {
        echo $e->getMessage() . '<br />';
    }
}
?>

上の例の出力は以下となります。

DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos)
DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Jupiter/Europa)

DateTimeZone::getLocation

timezone_location_get

(PHP 5 >= 5.3.0)

DateTimeZone::getLocation -- timezone_location_get — タイムゾーンの位置情報を返す

説明

オブジェクト指向型

public array DateTimeZone::getLocation ( void )

手続き型

array timezone_location_get ( DateTimeZone $object )

タイムゾーンの位置情報 (国コード、緯度/経度、コメント) を返します。

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

返り値

タイムゾーンについての位置情報を含む配列を返します。

例

例1 DateTimeZone::getLocation() の例

<?php
$tz = new DateTimeZone("Europe/Prague");
print_r($tz->getLocation());
print_r(timezone_location_get($tz));
?>

上の例の出力は以下となります。

Array
(
    [country_code] => CZ
    [latitude] => 50.08333
    [longitude] => 14.43333
    [comments] => 
)
Array
(
    [country_code] => CZ
    [latitude] => 50.08333
    [longitude] => 14.43333
    [comments] => 
)

DateTimeZone::getName

timezone_name_get

(PHP 5 >= 5.2.0)

DateTimeZone::getName -- timezone_name_get — タイムゾーンの名前を返す

説明

オブジェクト指向型

public string DateTimeZone::getName ( void )

手続き型

string timezone_name_get ( DateTimeZone $object )

タイムゾーンの名前を返します。

パラメータ

object

名前を取得したい DateTimeZone。

返り値

タイムゾーン一覧 のタイムゾーン名のひとつを返します。

DateTimeZone::getOffset

timezone_offset_get

(PHP 5 >= 5.2.0)

DateTimeZone::getOffset -- timezone_offset_get — GMT からのタイムゾーンのオフセットを返す

説明

オブジェクト指向型

public int DateTimeZone::getOffset ( DateTime $datetime )

手続き型

int timezone_offset_get ( DateTimeZone $object , DateTime $datetime )

この関数は、datetime パラメータで指定した 日付/時刻 についての GMT へのオフセットを返します。GMT オフセットの計算の際には、 使用する DateTimeZone オブジェクトに含まれるタイムゾーン情報を使用します。

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

datetime

オフセットを計算する 日付/時刻 を含む DateTime。

返り値

成功した場合にタイムゾーンのオフセット秒数、失敗した場合に FALSE を返します。

例

例1 DateTimeZone::getOffset() の例

<?php
// ふたつのタイムゾーンオブジェクトを作成します。ひとつは台北 (台湾)、
// そしてもうひとつは東京 (日本) のものです。
$dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
$dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");

// 同一の Unix タイムスタンプを持つふたつの DateTime オブジェクトを作成します。
// しかしアタッチするタイムゾーンはそれぞれ異なります。
$dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
$dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);

// $dateTimeTaipei オブジェクトに含まれる 日付/時刻 の GMT オフセットを計算します。
// しかし、タイムゾーンの規則は東京のもの ($dateTimeZoneJapan)
// を使用します。
$timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);

// これは int(32400) となります (Sat Sep 8 01:00:00 1951 JST 以降の日付の場合)。
var_dump($timeOffset);
?>

DateTimeZone::getTransitions

timezone_transitions_get

(PHP 5 >= 5.2.0)

DateTimeZone::getTransitions -- timezone_transitions_get — タイムゾーンの変遷を返す

説明

オブジェクト指向型

public array DateTimeZone::getTransitions ([ int $timestamp_begin [, int $timestamp_end ]] )

手続き型

array timezone_transitions_get ( DateTimeZone $object [, int $timestamp_begin [, int $timestamp_end ]] )

パラメータ

object

手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

timestamp_begin

開始時のタイムスタンプ。

timestamp_end

終了時のタイムスタンプ。

返り値

成功した場合にタイムゾーンの遷移を表す連想配列の配列、 失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.3.0 オプションの timestamp_begin および timestamp_end が追加されました。

例

例1 timezone_transitions_get() の例

<?php
$timezone = new DateTimeZone("Europe/London");
$transitions = $timezone->getTransitions();
print_r(array_slice($transitions, 0, 3));
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [ts] => -9223372036854775808
            [time] => -292277022657-01-27T08:29:52+0000
            [offset] => 3600
            [isdst] => 1
            [abbr] => BST
        )

    [1] => Array
        (
            [ts] => -1691964000
            [time] => 1916-05-21T02:00:00+0000
            [offset] => 3600
            [isdst] => 1
            [abbr] => BST
        )

    [2] => Array
        (
            [ts] => -1680472800
            [time] => 1916-10-01T02:00:00+0000
            [offset] => 0
            [isdst] => 
            [abbr] => GMT
        )

)

DateTimeZone::listAbbreviations

timezone_abbreviations_list

(PHP 5 >= 5.2.0)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す

説明

オブジェクト指向型

public static array DateTimeZone::listAbbreviations ( void )

手続き型

array timezone_abbreviations_list ( void )

返り値

成功した場合に配列、失敗した場合に FALSE を返します。

例

例1 timezone_abbreviations_list() の例

<?php
$timezone_abbreviations = DateTimeZone::listAbbreviations();
print_r($timezone_abbreviations["acst"]);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => Array
        (
            [dst] => 1
            [offset] => -14400
            [timezone_id] => America/Porto_Acre
        )

    [1] => Array
        (
            [dst] => 1
            [offset] => -14400
            [timezone_id] => America/Eirunepe
        )

    [2] => Array
        (
            [dst] => 1
            [offset] => -14400
            [timezone_id] => America/Rio_Branco
        )

    [3] => Array
        (
            [dst] => 1
            [offset] => -14400
            [timezone_id] => Brazil/Acre
        )

)

参考

DateTimeZone::listIdentifiers

timezone_identifiers_list

(PHP 5 >= 5.2.0)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — すべてのタイムゾーン識別子を含む配列を返す

説明

オブジェクト指向型

public static array DateTimeZone::listIdentifiers ([ int $what = DateTimeZone::ALL [, string $country = NULL ]] )

手続き型

array timezone_identifiers_list ([ int $what = DateTimeZone::ALL [, string $country = NULL ]] )

パラメータ

what

DateTimeZone のクラス定数のいずれか。

country

2 文字の ISO 3166-1 互換の国コード。

注意: このオプションを使用するのは、what に DateTimeZone::PER_COUNTRY を設定した場合のみです。

返り値

成功した場合に配列、失敗した場合に FALSE を返します。

変更履歴

バージョン 説明
5.3.0 オプションのパラメータ what および country が追加されました。

例

例1 timezone_identifiers_list() の例

<?php
$timezone_identifiers = DateTimeZone::listIdentifiers();
for ($i=0; $i < 5; $i++) {
    echo "$timezone_identifiers[$i]\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmara

参考

目次

DateInterval クラス

(PHP 5 >= 5.3.0)

導入

日付の間隔をあらわします。 格納方式は、固定値 (年、月、日、時など) あるいは相対時刻 (DateTime のコンストラクタがサポートしている書式) となります。

クラス概要

DateInterval {
/* プロパティ */
public integer $y ;
public integer $m ;
public integer $d ;
public integer $h ;
public integer $i ;
public integer $s ;
public integer $invert ;
public mixed $days ;
/* メソッド */
public __construct ( string $interval_spec )
public static DateInterval createFromDateString ( string $time )
public string format ( string $format )
}

プロパティ

y

年。

m

月。

d

日。

h

時間。

i

分。

s

秒。

invert

間隔が反転している場合は 1、そうでない場合は 0。 DateInterval::format() を参照ください。

days

DateTime::diff() の計算における、開始日と終了日の間の日数。 それ以外の場合は days は FALSE となります。

DateInterval::__construct

(PHP 5 >= 5.3.0)

DateInterval::__construct — 新しい DateInterval オブジェクトを作成する

説明

public DateInterval::__construct() ( string $interval_spec )

新しい DateInterval オブジェクトを作成します。

パラメータ

interval_spec

間隔。

最初は P から始まります。これは "period" を表します。 間隔の単位は、整数値の後に間隔指示子をつけて表します。 時間の要素を含む場合は、時間部分の前に文字 T を入れます。

interval_spec の間隔指示子
間隔指示子 説明
Y 年
M 月
D 日
W 週。日付に変換されるので D と組み合わせて使うことはできません。
H 時間
M 分
S 秒

いくつか簡単な例を示しましょう。 P2D は 2 日、 PT2S は 2 秒、そして P6YT5M は 6 年と 5 分を表します。

注意:

複数の単位を指定するときは、 大きな単位を左、小さな単位を右の順に書かなければなりません。 つまり年は月より先、月は日より先、日は分より先などとなります。 1 年と 4 日を表すのは P1Y4D であり、P4D1Y ではありません。

日付と時刻で間隔を指定することもできます。 1 年と 4 日をこの方式で表すと P0001-00-04T00:00:00 のようになります。 しかし、この方式では繰り返し単位以上の値を指定することはできません (たとえば 25 時間などとは指定できません)。

これらのフォーマットは » ISO 8601 duration specification に基づくものです。

例

<?php

$interval = new DateInterval('P2Y4DT6H8M');
var_dump($interval);

?>

上の例の出力は以下となります。

object(DateInterval)#1 (8) {
  ["y"]=>
  int(2)
  ["m"]=>
  int(0)
  ["d"]=>
  int(4)
  ["h"]=>
  int(6)
  ["i"]=>
  int(8)
  ["s"]=>
  int(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
}

参考

DateInterval::createFromDateString

(PHP 5 >= 5.3.0)

DateInterval::createFromDateString — 相対指定文字列から DateInterval を作成する

説明

public static DateInterval DateInterval::createFromDateString ( string $time )

通常の日付パーサを用いて、パースされた相対指定文字列から DateInterval を設定します。

パラメータ

time

相対部分を含む日付。

返り値

成功した場合に、新しい DateInterval のインスタンスを返します。

DateInterval::format

(PHP 5 >= 5.3.0)

DateInterval::format — 間隔をフォーマットする

説明

public string DateInterval::format ( string $format )

間隔をフォーマットします。

パラメータ

format

次の文字を、 format パラメータ文字列に使用することができます。 フォーマット文字は、パーセント記号 (%) で始めなければなりません。
format 文字 説明 値の例
% リテラルとしての % %
Y 年、数値、先頭に 0 を含む 2 桁 01, 03
y 年、数値 1, 3
M 月、数値、先頭に 0 を含む 2 桁 01, 03, 12
m 月、数値 1, 3, 12
D 日、数値、先頭に 0 を含む 2 桁 01, 03, 31
d 日、数値 1, 3, 31
a 総日数 4, 18, 8123
H 時間、数値、先頭に 0 を含む 2 桁 01, 03, 23
h 時間、数値 1, 3, 23
I 分、数値、先頭に 0 を含む 2 桁 01, 03, 59
i 分、数値 1, 3, 59
S 秒、数値、先頭に 0 を含む 2 桁 01, 03, 57
s 秒、数値 1, 3, 57
R 負の値の場合は "-"、正の値の場合は "+" -, +
r 負の値の場合は "-"、正の値の場合は空文字 -,

返り値

フォーマットされた間隔を返します。

注意

注意:

DateInterval::format() メソッドは、 時刻文字列や日付セグメントでの繰り越しを再計算しません。 これは意図的な仕様です。なぜなら "32 days" のようにオーバーフローした値は "1 month and 4 days" から "1 month and 1 day" までのどれとでも解釈可能だからです。

例

例1 DateInterval の例

<?php

$interval = new DateInterval('P2Y4DT6H8M');
echo $interval->format('%d days');

?>

上の例の出力は以下となります。

4 days

例2 DateInterval での繰り越しの例

<?php

$interval = new DateInterval('P32D');
echo $interval->format('%d days');

?>

上の例の出力は以下となります。

32 days

例3 DateInterval および DateTime::diff() での修飾子 %a および %d

<?php

$january = new DateTime('2010-01-01');
$february = new DateTime('2010-02-01');
$interval = $february->diff($january);

// %a は総日数を出力します
echo $interval->format('%a total days')."\n";

// 一方 %d は、月数に含まれない日数のみを出力します
echo $interval->format('%m month, %d days');

?>

上の例の出力は以下となります。

31 total days
1 month, 0 days

目次

DatePeriod クラス

(PHP 5 >= 5.3.0)

導入

日付の期間をあらわします。

クラス概要

DatePeriod implements Traversable {
/* 定数 */
const integer EXCLUDE_START_DATE = 1 ;
/* メソッド */
public __construct ( DateTime $start , DateInterval $interval , int $recurrences [, int $options ] )
public __construct ( DateTime $start , DateInterval $interval , DateTime $end [, int $options ] )
public __construct ( string $isostr [, int $options ] )
}

定義済み定数

DatePeriod::EXCLUDE_START_DATE

開始日を含まない。DatePeriod::__construct() で使用します。

DatePeriod::__construct

(PHP 5 >= 5.3.0)

DatePeriod::__construct — 新しいい DatePeriod オブジェクトを作成する

説明

public DatePeriod::__construct() ( DateTime $start , DateInterval $interval , int $recurrences [, int $options ] )
public DatePeriod::__construct() ( DateTime $start , DateInterval $interval , DateTime $end [, int $options ] )
public DatePeriod::__construct() ( string $isostr [, int $options ] )

新しい DatePeriod オブジェクトを作成します。

パラメータ

start

開始日。

interval

間隔。

recurrences

反復回数。

end

終了日。

isostr

ISO インターバルを含む文字列。

options

DatePeriod::EXCLUDE_START_DATE を設定することができます。

目次

日付・時刻 関数

checkdate

(PHP 4, PHP 5)

checkdate — グレゴリオ暦の日付/時刻の妥当性を確認します

説明

bool checkdate ( int $month , int $day , int $year )

引数で指定された日付の妥当性をチェックします。 各パラメータが適切に指定されている場合に、妥当であると判断されます。

パラメータ

month

月は 1 から 12 の間となります。

day

日は、指定された month の日数の範囲内になります。year がうるう年の場合は、それも考慮されます。

year

年は 1 から 32767 の間となります。

返り値

指定した日付が有効な場合に TRUE、そうでない場合に FALSE を返します。

例

例1 checkdate() の例

<?php
var_dump(checkdate(12, 31, 2000));
var_dump(checkdate(2, 29, 2001));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • strtotime() - 英文形式の日付を Unix タイムスタンプに変換する

date_add

(PHP 5 >= 5.3.0)

date_add — DateTime::add() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::add()

date_create_from_format

(PHP 5 >= 5.3.0)

date_create_from_format — DateTime::createFromFormat() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::createFromFormat()

date_create

(PHP 5 >= 5.2.0)

date_create — DateTime::__construct() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::__construct()

date_date_set

(PHP 5 >= 5.2.0)

date_date_set — DateTime::setDate() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setDate()

date_default_timezone_get

(PHP 5 >= 5.1.0)

date_default_timezone_get — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する

説明

string date_default_timezone_get ( void )

この関数は、デフォルトのタイムゾーンを以下の優先順位で取得して返します。

  • date_default_timezone_set() 関数を使用して 設定したタイムゾーン (もし何か設定されていれば) を読み込む

  • PHP 5.4.0 より前のバージョンのみ: TZ 環境変数 (もし空白でなければ) を読み込む

  • date.timezone ini オプション (設定されていれば) を読み込む

  • PHP 5.4.0 より前のバージョンのみ: ホスト OS に問い合わせる (もし OS がそれに対応しており、許可されていれば)。 これは、タイムゾーンを推測するアルゴリズムを使います。 このアルゴリズムはあらゆる状況で正しく動作するとは限りません。 この段階に到達したときには警告が表示されます。 この推測が正しくなることに期待するのではなく、 date.timezone に正しいタイムゾーンを設定するようにしましょう。

上のすべてが失敗した場合は、 date_default_timezone_get() はデフォルトのタイムゾーンである UTC を返します。

返り値

string を返します。

変更履歴

バージョン 説明
5.4.0 タイムゾーンの判定時に環境変数 TZ を使わなくなりました。
5.4.0 タイムゾーンの判定時に、OS から得られる情報に頼らないようになりました。 推測に基づくタイムゾーンは信頼できないからです。

例

例1 デフォルトのタイムゾーンの取得

<?php
date_default_timezone_set('Europe/London');

if (date_default_timezone_get()) {
    echo 'date_default_timezone_set: ' . date_default_timezone_get() . '<br />';
}

if (ini_get('date.timezone')) {
    echo 'date.timezone: ' . ini_get('date.timezone');
}

?>

上の例の出力は、 たとえば以下のようになります。

date_default_timezone_set: Europe/London
date.timezone: Europe/London

例2 タイムゾーンの短縮名の取得

<?php
date_default_timezone_set('America/Los_Angeles');
echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');
?>

上の例の出力は以下となります。

America/Los_Angeles => America/Los_Angeles => PST

参考

date_default_timezone_set

(PHP 5 >= 5.1.0)

date_default_timezone_set — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する

説明

bool date_default_timezone_set ( string $timezone_identifier )

date_default_timezone_set() は、日付/時刻関数で 使用されるデフォルトタイムゾーンを設定します。

注意:

PHP 5.1.0 以降（日付/時刻 関数が書き直されてから）、タイムゾーンを 正しく設定せずに日付/時刻関数をコールすると E_NOTICE が発生し、またシステムの設定や TZ 環境変数を 使用すると E_WARNING が発生するようになりました。

スクリプト内でこの関数を使用してデフォルトタイムゾーンを設定するかわりに、 INI 設定 date.timezone でデフォルトタイムゾーンを設定することもできます。

パラメータ

timezone_identifier

タイムゾーン ID 。例えば UTC や Europe/Lisbon など。有効な ID の一覧は サポートされるタイムゾーンのリスト にあります。

返り値

この関数は、timezone_identifier が 無効なものである場合に FALSE、それ以外の場合に TRUE を返します。

例

例1 デフォルトのタイムゾーンの取得

<?php
date_default_timezone_set('America/Los_Angeles');

$script_tz = date_default_timezone_get();

if (strcmp($script_tz, ini_get('date.timezone'))){
    echo 'Script timezone differs from ini-set timezone.';
} else {
    echo 'Script timezone and ini-set timezone match.';
}
?>

変更履歴

バージョン 説明
5.3.0 E_STRICT ではなく E_WARNING をスローするようになりました。
5.1.2 timezone_identifier パラメータの内容を 検証するようになりました。

参考

date_diff

(PHP 5 >= 5.3.0)

date_diff — DateTime::diff() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::diff()

date_format

(PHP 5 >= 5.2.0)

date_format — DateTime::format() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::format()

date_get_last_errors

(PHP 5 >= 5.3.0)

date_get_last_errors — DateTime::getLastErrors() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getLastErrors()

date_interval_create_from_date_string

(PHP 5 >= 5.3.0)

date_interval_create_from_date_string — DateInterval::createFromDateString() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateInterval::createFromDateString()

date_interval_format

(PHP 5 >= 5.3.0)

date_interval_format — DateInterval::format() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateInterval::format()

date_isodate_set

(PHP 5 >= 5.2.0)

date_isodate_set — DateTime::setISODate() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setISODate()

date_modify

(PHP 5 >= 5.2.0)

date_modify — DateTime::modify() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::modify()

date_offset_get

(PHP 5 >= 5.2.0)

date_offset_get — DateTime::getOffset() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getOffset()

date_parse_from_format

(PHP 5 >= 5.3.0)

date_parse_from_format — 指定した書式でフォーマットされた日付についての情報を取得する

説明

array date_parse_from_format ( string $format , string $date )

指定した日付についての詳細情報を連想配列で返します。

パラメータ

format

DateTime::createFromFormat() が理解できるフォーマット。

date

日付をあらわす文字列。

返り値

指定した日付についての詳細情報を連想配列で返します。

例

例1 date_parse_from_format() の例

<?php
$date = "6.1.2009 13:00+01:00";
print_r(date_parse_from_format("j.n.Y H:iP", $date));
?>

上の例の出力は以下となります。

Array
(
    [year] => 2009
    [month] => 1
    [day] => 6
    [hour] => 13
    [minute] => 0
    [second] => 0
    [fraction] => 
    [warning_count] => 0
    [warnings] => Array
        (
        )

    [error_count] => 0
    [errors] => Array
        (
        )

    [is_localtime] => 1
    [zone_type] => 1
    [zone] => -60
    [is_dst] => 
)

参考

  • DateTime::createFromFormat() - 指定した書式でフォーマットした新しい DateTime オブジェクトを返す
  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します

date_parse

(PHP 5 >= 5.2.0)

date_parse — 指定した日付に関する詳細な情報を連想配列で返す

説明

array date_parse ( string $date )

パラメータ

date

strtotime() が理解できる書式の日付。

返り値

成功した場合に日付情報を含む配列、失敗した場合に FALSE を返します。

エラー / 例外

日付フォーマットにエラーがある場合は、 'errors' 要素にエラーメッセージが格納されます。

例

例1 date_parse() の例

<?php
print_r(date_parse("2006-12-12 10:00:00.5"));
?>

上の例の出力は以下となります。

Array
(
    [year] => 2006
    [month] => 12
    [day] => 12
    [hour] => 10
    [minute] => 0
    [second] => 0
    [fraction] => 0.5
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] => 
)

参考

  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • getdate() - 日付/時刻情報を取得する

date_sub

(PHP 5 >= 5.3.0)

date_sub — DateTime::sub() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::sub()

date_sun_info

(PHP 5 >= 5.1.2)

date_sun_info — 日の出/日の入り時刻と薄明かり (twilight) の開始/終了時刻の情報を含む配列を返す

説明

array date_sun_info ( int $time , float $latitude , float $longitude )

パラメータ

time

タイムスタンプ。

latitude

緯度を表す度数。

longitude

経度を表す度数。

返り値

成功した場合に配列、失敗した場合に FALSE を返します。

例

例1 date_sun_info() の例

<?php
$sun_info = date_sun_info(strtotime("2006-12-12"), 31.7667, 35.2333);
foreach ($sun_info as $key => $val) {
    echo "$key: " . date("H:i:s", $val) . "\n";
}
?>

上の例の出力は以下となります。

sunrise: 05:52:11
sunset: 15:41:21
transit: 10:46:46
civil_twilight_begin: 05:24:08
civil_twilight_end: 16:09:24
nautical_twilight_begin: 04:52:25
nautical_twilight_end: 16:41:06
astronomical_twilight_begin: 04:21:32
astronomical_twilight_end: 17:12:00

参考

  • date_sunrise() - 指定した日付と場所についての日の出時刻を返す
  • date_sunset() - 指定した日付と場所についての日の入り時刻を返す

date_sunrise

(PHP 5)

date_sunrise — 指定した日付と場所についての日の出時刻を返す

説明

mixed date_sunrise ( int $timestamp [, int $format = SUNFUNCS_RET_STRING [, float $latitude = ini_get("date.default_latitude") [, float $longitude = ini_get("date.default_longitude") [, float $zenith = ini_get("date.sunrise_zenith") [, float $gmt_offset = 0 ]]]]] )

date_sunrise() は、与えられた日付 (timestamp で指定する) と場所についての日の出の時刻を返します。

パラメータ

timestamp

日の出時刻を取得する日の timestamp。

format

format 定数
定数 説明 例
SUNFUNCS_RET_STRING 結果を string で返します。 16:46
SUNFUNCS_RET_DOUBLE 結果を float で返します。 16.78243132
SUNFUNCS_RET_TIMESTAMP 結果を integer (タイムスタンプ) で返します。 1095034606

latitude

デフォルトは北緯で、南緯は負の値で表します。 date.default_latitude も参照ください。

longitude

デフォルトは東経で、西経は負の値で表します。 date.default_longitude も参照ください。

zenith

デフォルトは date.sunrise_zenith です。

gmtoffset

時間単位で指定します。

返り値

日の出時刻を、指定した format で返します。 失敗した場合に FALSE を返します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン 説明
5.1.0

タイムゾーンがおかしい場合に E_STRICT や E_NOTICE が発生するようになりました。

例

例1 date_sunrise() の例

<?php

/* ポルトガル リスボンの日の出時刻を計算する
緯度: 北緯 38.4
経度: 西経 9
天頂 ~= 90
時差: +1 GMT
*/

echo date("D M d Y"). ', sunrise time : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

?>

上の例の出力は、 たとえば以下のようになります。

Mon Dec 20 2004, sunrise time : 08:54

参考

  • date_sunset() - 指定した日付と場所についての日の入り時刻を返す

date_sunset

(PHP 5)

date_sunset — 指定した日付と場所についての日の入り時刻を返す

説明

mixed date_sunset ( int $timestamp [, int $format = SUNFUNCS_RET_STRING [, float $latitude = ini_get("date.default_latitude") [, float $longitude = ini_get("date.default_longitude") [, float $zenith = ini_get("date.sunset_zenith") [, float $gmt_offset = 0 ]]]]] )

date_sunset() は、与えられた日付 (timestamp で指定する) と場所についての日の入り時刻を返します。

パラメータ

timestamp

日の入り時刻を取得する日の timestamp。

format

format 定数
定数 説明 例
SUNFUNCS_RET_STRING 結果を string で返します。 16:46
SUNFUNCS_RET_DOUBLE 結果を float で返します。 16.78243132
SUNFUNCS_RET_TIMESTAMP 結果を integer (タイムスタンプ) で返します。 1095034606

latitude

デフォルトは北緯で、南緯は負の値で表します。 date.default_latitude も参照ください。

longitude

デフォルトは東経で、西経は負の値で表します。 date.default_longitude も参照ください。

zenith

デフォルトは date.sunset_zenith です。

gmtoffset

時間単位で指定します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン 説明
5.1.0

タイムゾーンがおかしい場合に E_STRICT や E_NOTICE が発生するようになりました。

返り値

日の入り時刻を、指定した format で返します。 失敗した場合に FALSE を返します。

例

例1 date_sunset() の例

<?php

/* ポルトガル リスボンの日の入り時刻を計算する
緯度: 北緯 38.4
経度: 西経 9
天頂 ~= 90
時差: +1 GMT
*/

echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

?>

上の例の出力は、 たとえば以下のようになります。

Mon Dec 20 2004, sunset time : 18:13

参考

  • date_sunrise() - 指定した日付と場所についての日の出時刻を返す

date_time_set

(PHP 5 >= 5.2.0)

date_time_set — DateTime::setTime() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTime()

date_timestamp_get

(PHP 5 >= 5.3.0)

date_timestamp_get — DateTime::getTimestamp() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getTimestamp()

date_timestamp_set

(PHP 5 >= 5.3.0)

date_timestamp_set — DateTime::setTimestamp() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTimestamp()

date_timezone_get

(PHP 5 >= 5.2.0)

date_timezone_get — DateTime::getTimezone() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::getTimezone()

date_timezone_set

(PHP 5 >= 5.2.0)

date_timezone_set — DateTime::setTimezone() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTime::setTimezone()

date

(PHP 4, PHP 5)

date — ローカルの日付/時刻を書式化する

説明

string date ( string $format [, int $timestamp = time() ] )

指定された引数 timestamp を、与えられた フォーマット文字列によりフォーマットし、日付文字列を返します。 タイムスタンプが与えられない場合は、現在の時刻が使われます。 つまり timestamp はオプションであり そのデフォルト値は time() の値です。

パラメータ

format

出力される日付文字列の書式。以下のオプションを参照ください。 定義済みの定数 も用意されており、たとえば DATE_RSS はフォーマット文字列 'D, d M Y H:i:s' と同じ意味になります。

以下の文字が format パラメータ文字列として認識されます
format 文字 説明 戻り値の例
日 --- ---
d 日。二桁の数字（先頭にゼロがつく場合も） 01 から 31
D 曜日。3文字のテキスト形式。 Mon から Sun
j 日。先頭にゼロをつけない。 1 から 31
l (小文字の 'L') 曜日。フルスペル形式。 Sunday から Saturday
N ISO-8601 形式の、曜日の数値表現 (PHP 5.1.0 で追加)。 1（月曜日）から 7（日曜日）
S 英語形式の序数を表すサフィックス。2 文字。 st, nd, rd または th。 jと一緒に使用する ことができる。
w 曜日。数値。 0 (日曜)から 6 (土曜)
z 年間の通算日。数字。(ゼロから開始) 0 から 365
週 --- ---
W ISO-8601 月曜日に始まる年単位の週番号 (PHP 4.1.0 で追加) 例: 42 (年の第 42 週目)
月 --- ---
F 月。フルスペルの文字。 January から December
m 月。数字。先頭にゼロをつける。 01 から 12
M 月。3 文字形式。 Jan から Dec
n 月。数字。先頭にゼロをつけない。 1 から 12
t 指定した月の日数。 28 から 31
年 --- ---
L 閏年であるかどうか。 1なら閏年。0なら閏年ではない。
o ISO-8601 形式の年。これは Y ほぼ同じだが、ISO 週番号 （W）が前年あるいは翌年に属する場合がある点で 異なる（PHP 5.1.0 で追加）。 例: 1999 あるいは 2003
Y 年。4 桁の数字。 例: 1999または2003
y 年。2 桁の数字。 例: 99 または 03
時 --- ---
a 午前または午後（小文字） am または pm
A 午前または午後（大文字） AM または PM
B Swatch インターネット時間 000 から 999
g 時。12時間単位。先頭にゼロを付けない。 1 から 12
G 時。24時間単位。先頭にゼロを付けない。 0 から 23
h 時。数字。12 時間単位。 01 から 12
H 時。数字。24 時間単位。 00 から 23
i 分。先頭にゼロをつける。 00 から 59
s 秒。先頭にゼロをつける。 00 から 59
u マイクロ秒 (PHP 5.2.2 で追加)。 例: 654321
タイムゾーン --- ---
e タイムゾーン識別子（PHP 5.1.0 で追加） 例: UTC, GMT, Atlantic/Azores
I (大文字の i) サマータイム中か否か 1ならサマータイム中。 0ならそうではない。
O グリニッジ標準時 (GMT) との時差 例: +0200
P グリニッジ標準時 (GMT) との時差。時間と分をコロンで区切った形式 (PHP 5.1.3 で追加)。 例: +02:00
T タイムゾーンの略称 例: EST, MDT ...
Z タイムゾーンのオフセット秒数。 UTC の西側のタイムゾーン用のオフセットは常に負です。そして、 UTC の東側のオフセットは常に正です。 -43200 から 50400
全ての日付/時刻 --- ---
c ISO 8601 日付 (PHP 5 で追加されました) 2004-02-12T15:19:21+00:00
r » RFC 2822 フォーマットされた日付 例: Thu, 21 Dec 2000 16:01:07 +0200
U Unix Epoch (1970 年 1 月 1 日 0 時 0 分 0 秒) からの秒数 time() も参照

フォーマット文字列中の認識されない文字は、そのまま表示されます。 Z 形式は、 gmdate() で使用した場合、常に 0 を返します。

注意:

この関数が受け付けるのは integer のタイムスタンプだけです。したがって、書式指定文字 u が有用となるのは date_create() で作成したタイムスタンプを用いて date_format() を使用した場合のみです。

timestamp

オプションのパラメータ timestamp は、 integer 型の Unix タイムスタンプです。 timestamp が指定されなかった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

日付を表す文字列を返します。 timestamp に数字以外が使用された場合は FALSE が返され、E_WARNING レベルのエラーが発生します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン 説明
5.1.0 有効なタイムスタンプの範囲は、通常 Fri, 13 Dec 1901 20:45:54 GMT から Tue, 19 Jan 2038 03:14:07 GMT までです (これらの日付は、32 ビット符号付き整数の最小および最大値に 対応します)。 しかし、PHP 5.1 より前のバージョンでは、システム環境によっては (例: Windows) この範囲が 1970 年 1 月 1 日から 2038 年 1 月 19 日 までに制限されます。
5.1.0

タイムゾーンがおかしい場合に E_STRICT や E_NOTICE が発生するようになりました。

5.1.1 PHP 5.1.1 以降、format パラメータで標準的な 日付/時刻フォーマットを指定する際に有用な 定数がいくつか追加されました。

例

例1 date() の例

<?php
// 使用するデフォルトのタイムゾーンを指定します。PHP 5.1 以降で使用可能です。
date_default_timezone_set('UTC');


// 結果は、たとえば Monday のようになります。
echo date("l");

// 結果は、たとえば Monday 8th of August 2005 03:12:46 PM のようになります。
echo date('l jS \of F Y h:i:s A');

// 結果は July 1, 2000 is on a Saturday となります。
echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000));

/* 書式指定パラメータに、定数を使用します。 */
// 結果は、たとえば Mon, 15 Aug 2005 15:12:46 UTC のようになります。
echo date(DATE_RFC822);

// 結果は、たとえば 2000-07-01T00:00:00+00:00 のようになります。
echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
?>

前にバックスラッシュを付けてエスケープすることにより、 フォーマット文字列として認識される文字が展開されることを防止することができます。 バックスラッシュ付きの文字は既に特別なシーケンスであり、 バックスラッシュもエスケープすることが必要となる可能性があります。

例2 date() の文字をエスケープする

<?php
// Wednesday the 15th のように出力
echo date('l \t\h\e jS');
?>

date() と mktime() の両方を用いて、未来または過去の日付を知ることができます。

例3 date() と mktime() の例

<?php
$tomorrow  = mktime(0, 0, 0, date("m")  , date("d")+1, date("Y"));
$lastmonth = mktime(0, 0, 0, date("m")-1, date("d"),   date("Y"));
$nextyear  = mktime(0, 0, 0, date("m"),   date("d"),   date("Y")+1);
?>

注意:

サマータイムがあるため、日付や月の秒数を単純にタイムスタンプに 可減算するよりもより信頼性があります。

date() フォーマットのいくつかの例を示します。 現在の実装で特別な意味がある文字や今後の PHP のバージョンで意味が 割り付けられるであろう文字については、望ましくない結果を避けるために エスケープする必要があることに注意してください。エスケープを する際には、改行文字 \n のような文字を回避するために シングルクォートを使用してください。

例4 date() のフォーマット指定

<?php
// 今日は March 10th, 2001, 5:16:18 pm であり、
// またタイムゾーンは Mountain Standard Time (MST) であるものとします

$today = date("F j, Y, g:i a");                 // March 10, 2001, 5:16 pm
$today = date("m.d.y");                         // 03.10.01
$today = date("j, n, Y");                       // 10, 3, 2001
$today = date("Ymd");                           // 20010310
$today = date('h-i-s, j-m-y, it is w Day');     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
$today = date('\i\t \i\s \t\h\e jS \d\a\y.');   // it is the 10th day.
$today = date("D M j G:i:s T Y");               // Sat Mar 10 17:16:18 MST 2001
$today = date('H:m:s \m \i\s\ \m\o\n\t\h');     // 17:03:18 m is month
$today = date("H:i:s");                         // 17:16:18
?>

他の言語で日付をフォーマットするためには、date() のかわりに setlocale() および strftime() 関数を使用する必要があります。

注意

注意:

日付の文字列表現からタイムスタンプを生成するには、 strtotime() が使用できるでしょう。 さらに、いくつかのデータベースは（MySQL の » UNIX_TIMESTAMP 関数の ような）日付フォーマットからタイムスタンプへの変換関数を有しています。

ヒント

PHP 5.1 以降、$_SERVER['REQUEST_TIME'] によってリクエスト開始時のタイムスタンプが取得できるようになりました。

参考

  • gmdate() - GMT/UTC の日付/時刻を書式化する
  • idate() - ローカルな時刻/日付を整数として整形する
  • getdate() - 日付/時刻情報を取得する
  • getlastmod() - 最終更新時刻を取得する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする
  • time() - 現在の Unix タイムスタンプを返す
  • strtotime() - 英文形式の日付を Unix タイムスタンプに変換する
  • 定義済みの定数

getdate

(PHP 4, PHP 5)

getdate — 日付/時刻情報を取得する

説明

array getdate ([ int $timestamp = time() ] )

timestamp に関する日付情報を有する連想配列を返します。 timestamp が指定されない場合は、現在のローカルな時間に関する情報を返します。

パラメータ

timestamp

オプションのパラメータ timestamp は、 integer 型の Unix タイムスタンプです。 timestamp が指定されなかった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

timestamp に関連する情報を連想配列で返します。 返される連想配列の内容は、次のようになります。

返される連想配列のキー
キー 説明 戻り値の例
"seconds" 秒。数値。 0 から 59
"minutes" 分。数値。 0 から 59
"hours" 時。数値 0 から 23
"mday" 月単位の日。数値 1 から 31
"wday" 曜日。数値。 0 (日曜) から 6 (土曜)
"mon" 月。数値。 1 から 12
"year" 年。4桁の数値。 例: 1999 あるいは 2003
"yday" 年単位の日。数値。 0 から 365
"weekday" 曜日。フルスペルの文字。 Sunday から Saturday
"month" 月。フルスペルの文字。 January から December
0 UNIX時（1970年1月1日）からの秒数。 time()の戻り値と同様。 date()でも使用される。 システムによって違うが、通常は-2147483648 から 2147483647.

例

例1 getdate() の例

<?php
$today = getdate();
print_r($today);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [seconds] => 40
    [minutes] => 58
    [hours]   => 21
    [mday]    => 17
    [wday]    => 2
    [mon]     => 6
    [year]    => 2003
    [yday]    => 167
    [weekday] => Tuesday
    [month]   => June
    [0]       => 1055901520
)

参考

  • date() - ローカルの日付/時刻を書式化する
  • idate() - ローカルな時刻/日付を整数として整形する
  • localtime() - ローカルタイムを得る
  • time() - 現在の Unix タイムスタンプを返す
  • setlocale() - ロケール情報を設定する

gettimeofday

(PHP 4, PHP 5)

gettimeofday — 現在の時間を得る

説明

mixed gettimeofday ([ bool $return_float = false ] )

この関数は、gettimeofday(2) へのインターフェイスです。 この関数は、システムコールから返されたデータを有する連想配列を返します。

パラメータ

return_float

TRUE を指定すると、配列ではなく float で返します。

返り値

デフォルトでは配列を返します。return_float が設定されている場合は float を返します。

配列のキー:

  • "sec" - UNIX エポックからの秒
  • "usec" - マイクロ秒
  • "minuteswest" - グリニッジ基準の分
  • "dsttime" - 夏時間補正の型

変更履歴

バージョン 説明
5.1.0 return_float パラメータが追加されました。

例

例1 gettimeofday() の例

<?php
print_r(gettimeofday());

echo gettimeofday(true);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [sec] => 1073504408
    [usec] => 238215
    [minuteswest] => 0
    [dsttime] => 1
)

1073504408.23910

gmdate

(PHP 4, PHP 5)

gmdate — GMT/UTC の日付/時刻を書式化する

説明

string gmdate ( string $format [, int $timestamp = time() ] )

date() 関数と同じですが、返される時刻が グリニッジ標準時 (GMT) であるところが異なります。

パラメータ

format

出力される文字列の書式。date() 関数の書式オプションを参照ください。

timestamp

オプションのパラメータ timestamp は、 integer 型の Unix タイムスタンプです。 timestamp が指定されなかった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

日付を表す文字列を返します。 timestamp に数字以外が使用された場合は FALSE が返され、E_WARNING レベルのエラーが発生します。

変更履歴

バージョン 説明
5.1.0 有効なタイムスタンプの範囲は、通常 Fri, 13 Dec 1901 20:45:54 GMT から Tue, 19 Jan 2038 03:14:07 GMT までです (これらの日付は、32 ビット符号付き整数の最小および最大値に 対応します)。 しかし、PHP 5.1 より前のバージョンでは、システム環境によっては (例: Windows) この範囲が 1970 年 1 月 1 日から 2038 年 1 月 19 日 までに制限されます。
5.1.1 PHP 5.1.1 以降、format パラメータで標準的な 日付/時刻フォーマットを指定する際に有用な 定数がいくつか追加されました。

例

例1 gmdate() の例

フィンランド (GMT +0200) で実行した場合、一行目の出力は "Jan 01 1998 00:00:00"、二行目の出力は "Dec 31 1997 22:00:00" となります。

<?php
echo date("M d Y H:i:s", mktime(0, 0, 0, 1, 1, 1998));
echo gmdate("M d Y H:i:s", mktime(0, 0, 0, 1, 1, 1998));
?>

参考

  • date() - ローカルの日付/時刻を書式化する
  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • gmmktime() - GMT 日付から Unix タイムスタンプを取得する
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする

gmmktime

(PHP 4, PHP 5)

gmmktime — GMT 日付から Unix タイムスタンプを取得する

説明

int gmmktime ([ int $hour = gmdate("H") [, int $minute = gmdate("i") [, int $second = gmdate("s") [, int $month = gmdate("n") [, int $day = gmdate("j") [, int $year = gmdate("Y") [, int $is_dst = -1 ]]]]]]] )

指定されるパラメータが GMT 日付を表すこと以外は mktime() と同じです。 gmmktime() は内部で mktime() を使用しているので、ローカル時刻として有効な値のみが使用可能です。

mktime() と同様に、 引数は右から順に省略することができます。 省略された引数は、GMT の日付と時刻に従って、現在の値にセットされます。

パラメータ

hour

month、day と year で決まる日付の 0 時から数えた「時」。負の値は、その日の 0 時から前にさかのぼった時間を表します。 23 より大きい値は、その翌日以降の該当する時間を表します。

minute

hour 時 0 分から数えた「分」。 負の値は、その前の時刻を表します。 59 より大きい値は、その次の時間以降の該当する時間を表します。

second

minute 分 0 秒から数えた「秒」。 負の値は、その前の時刻を表します。 59 より大きい値は、その次の分以降の該当する時間を表します。

month

前年末から数えた月数。1 から 12 までの場合は、カレンダーどおりのその年の「月」を表します。 (負の値を含めた) 1 より小さい値は、前年の月を逆順でたどります。 つまり 0 なら 12 月、-1 なら 11 月になるということです。 12 より大きい値は、その翌年以降の該当する月を表します。

day

前月末から数えた日数。1 から 28、29、30、31 (月によって異なる) までの場合は、その月の「日」を表します。 (負の値を含めた) 1 より小さい値は、前月の日を逆順でたどります。 つまり 0 なら前月の末日、-1 ならそのさらに前日になるということです。 その月の日数より大きい値は、翌月以降の該当する日を表します。

year

年

is_dst

常に GMT 日付を表すので、is_dst は結果に影響を及ぼしません。

返り値

Unix タイムスタンプを integer で返します。

変更履歴

バージョン 説明
5.1.0 PHP 5.1.0 で、is_dst パラメータは廃止されました。 その代わりに、新しいタイムゾーン処理機能が使用されます。

例

例1 gmmktime() の基本的な例

<?php
// 出力: July 1, 2000 is on a Friday
echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));
?>

参考

  • mktime() - 日付を Unix のタイムスタンプとして取得する
  • date() - ローカルの日付/時刻を書式化する
  • time() - 現在の Unix タイムスタンプを返す

gmstrftime

(PHP 4, PHP 5)

gmstrftime — ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする

説明

string gmstrftime ( string $format [, int $timestamp = time() ] )

グリニッジ標準時を返すこと以外は、 strftime() と同じ動作をします。例えば、東部標準時 (GMT -0500) で実行した場合、以下の最初の行は "Dec 31 1998 20:00:00" を出力し、二行目は "Jan 01 1999 01:00:00" を出力します。

パラメータ

format

strftime() の説明を参照ください。

timestamp

オプションのパラメータ timestamp は、 integer 型の Unix タイムスタンプです。 timestamp が指定されなかった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

指定した timestamp または timestamp が指定されていない場合に現在のローカル時間を用いて、 指定したフォーマット文字列に基づき文字列をフォーマットして返します。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。

例

例1 gmstrftime() の例

<?php
setlocale(LC_TIME, 'en_US');
echo strftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
echo gmstrftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
?>

参考

  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする

idate

(PHP 5)

idate — ローカルな時刻/日付を整数として整形する

説明

int idate ( string $format [, int $timestamp = time() ] )

指定された引数 timestamp を、 与えられたフォーマット文字列によりフォーマットし、日付数値を返します。 タイムスタンプが与えられない場合は、現在のローカル時刻が使われます。 つまり、timestamp はオプションであり、 そのデフォルト値は time() の値です。

関数 date() と異なり、idate() は format パラメータ中は一文字しか受け取りません。

パラメータ

format

以下の文字が format パラメータ文字列として認識されます
format 文字 説明
B Swatch ビート/インターネット時間
d 月の日
h 時 (12 時間単位)
H 時 (24 時間単位)
i 分
I (大文字の i) 夏時間の適用中は 1、 そうでなければ 0 を返す
L (大文字の l) 閏年なら 1、 そうでなければ 0 を返す
m 月数
s 秒
t 現在の月の日数
U Unix Epoch (January 1 1970 00:00:00 UTC) からの秒数。 これは time() と同じです
w 曜日 (日曜日は 0)
W ISO-8601 形式。月曜日から始まる年単位の週番号
y 年 (1 桁あるいは 2 桁の数値 - 下の「注意」を確認ください)
Y 年 (4 桁)
z 年間の通算日
Z タイムゾーンのオフセット秒数

timestamp

オプションのパラメータ timestamp は、 integer 型の Unix タイムスタンプです。 timestamp が指定されなかった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

整数値を返します。

idate() が返す値の型は常に integer であり、 先頭に "0" がくることはありません。そのため、idate() の返す結果が予想より少ない桁数になることもあります。以下の例を参照ください。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン 説明
5.1.0

タイムゾーンがおかしい場合に E_STRICT や E_NOTICE が発生するようになりました。

例

例1 idate() の例

<?php
$timestamp = strtotime('1st January 2004'); //1072915200

// これは、年を 2 桁で表示します。
// しかし、ここでは年が "0" から始まるので、
// "4" だけが表示されます。
echo idate('y', $timestamp);
?>

参考

  • date() - ローカルの日付/時刻を書式化する
  • getdate() - 日付/時刻情報を取得する
  • time() - 現在の Unix タイムスタンプを返す

localtime

(PHP 4, PHP 5)

localtime — ローカルタイムを得る

説明

array localtime ([ int $timestamp = time() [, bool $is_associative = false ]] )

localtime() 関数は、C 言語の 同名の関数コールにより返される構造体と同じ内容の配列を返します。

パラメータ

timestamp

オプションのパラメータ timestamp は、 integer 型の Unix タイムスタンプです。 timestamp が指定されなかった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

is_associative

FALSE に設定されるか省略された場合は、 配列は通常の数値を添字とした配列として返されます。 TRUE に設定された場合は、 localtime() は C 言語の関数 localtime のコールにより返される構造体の全ての要素を有する連想配列を返します。 この連想配列の各キーの名前は次のようになります。

  • "tm_sec" - 秒 (0 から 59)
  • "tm_min" - 分 (0 から 59)
  • "tm_hour" - 時 (0 から 23)
  • "tm_mday" - 月の日付 (1 から 31)
  • "tm_mon" - 月 (0 (1月) から 11 (12月))
  • "tm_year" - 1900 年からの年数
  • "tm_wday" - 曜日 (0 (日曜日) から 6 (土曜日))
  • "tm_yday" - 年単位の日付 (0 から 365)
  • "tm_isdst" - 夏時間の適用中かどうか 適用中なら正の数、そうでなければ 0、不明なら負の数。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン 説明
5.1.0

タイムゾーンがおかしい場合に E_STRICT や E_NOTICE が発生するようになりました。

例

例1 time() の例

<?php
$localtime = localtime();
$localtime_assoc = localtime(time(), true);
print_r($localtime);
print_r($localtime_assoc);
?>

上の例の出力は、 たとえば以下のようになります。

Array
(
    [0] => 24
    [1] => 3
    [2] => 19
    [3] => 3
    [4] => 3
    [5] => 105
    [6] => 0
    [7] => 92
    [8] => 1
)

Array
(
    [tm_sec] => 24
    [tm_min] => 3
    [tm_hour] => 19
    [tm_mday] => 3
    [tm_mon] => 3
    [tm_year] => 105
    [tm_wday] => 0
    [tm_yday] => 92
    [tm_isdst] => 1
)

参考

  • getdate() - 日付/時刻情報を取得する

microtime

(PHP 4, PHP 5)

microtime — 現在の Unix タイムスタンプをマイクロ秒まで返す

説明

mixed microtime ([ bool $get_as_float = false ] )

microtime() は、現在の Unix タイムスタンプをマイクロ秒単位で返します。 この関数は、gettimeofday() システムコールをサポートする オペレーティングシステムでのみ使用できます。

パラメータ

get_as_float

TRUE を指定すると、microtime() は文字列ではなく float を返すようになります。詳細は、返り値の説明を参照ください。

返り値

デフォルトでは、microtime() は "msec sec" 形式の文字列を返します。ただし、sec は Unix エポック (1970 年 1 月 1 日 0:00:00 GMT) から計算した秒数、msec は sec から経過したマイクロ秒数です。

get_as_float を TRUE に設定すると、microtime() は結果を float で返します。 これは、Unix エポックからの経過秒数をマイクロ秒単位で表したものです。

変更履歴

バージョン 説明
5.0.0 get_as_float パラメータが追加されました。

例

例1 microtime() でタイマスクリプト実行

<?php
/**
 * PHP 5の動作を模擬する簡単な関数
 */
function microtime_float()
{
    list($usec, $sec) = explode(" ", microtime());
    return ((float)$usec + (float)$sec);
}

$time_start = microtime_float();

// しばらくスリープ
usleep(100);

$time_end = microtime_float();
$time = $time_end - $time_start;

echo "Did nothing in $time seconds\n";
?>

例2 PHP 5 におけるタイマスクリプト実行

<?php
$time_start = microtime(true);

// しばらくスリープ
usleep(100);

$time_end = microtime(true);
$time = $time_end - $time_start;

echo "Did nothing in $time seconds\n";
?>

参考

  • time() - 現在の Unix タイムスタンプを返す

mktime

(PHP 4, PHP 5)

mktime — 日付を Unix のタイムスタンプとして取得する

説明

int mktime ([ int $hour = date("H") [, int $minute = date("i") [, int $second = date("s") [, int $month = date("n") [, int $day = date("j") [, int $year = date("Y") [, int $is_dst = -1 ]]]]]]] )

与えられた引数に従って UNIX のタイムスタンプを返します。 このタイムスタンプは、Unix epoch(1970年1月1日00:00:00 GMT)から 指定された時刻までの通算秒を表す長整数です。

引数は右から順に省略することができます。省略された引数は、 ローカルの日付と時刻に従って、現在の値にセットされます。

注意

注意:

PHP 5.1 以降、引数なしでコールすると mktime() は E_STRICT notice を発行するようになりました。かわりに time() 関数を使用しましょう。

パラメータ

hour

month、day と year で決まる日付の 0 時から数えた「時」。負の値は、その日の 0 時から前にさかのぼった時間を表します。 23 より大きい値は、その翌日以降の該当する時間を表します。

minute

hour 時 0 分から数えた「分」。 負の値は、その前の時刻を表します。 59 より大きい値は、その次の時間以降の該当する時間を表します。

second

minute 分 0 秒から数えた「秒」。 負の値は、その前の時刻を表します。 59 より大きい値は、その次の分以降の該当する時間を表します。

month

前年末から数えた月数。1 から 12 までの場合は、カレンダーどおりのその年の「月」を表します。 (負の値を含めた) 1 より小さい値は、前年の月を逆順でたどります。 つまり 0 なら 12 月、-1 なら 11 月になるということです。 12 より大きい値は、その翌年以降の該当する月を表します。

day

前月末から数えた日数。1 から 28、29、30、31 (月によって異なる) までの場合は、その月の「日」を表します。 (負の値を含めた) 1 より小さい値は、前月の日を逆順でたどります。 つまり 0 なら前月の末日、-1 ならそのさらに前日になるということです。 その月の日数より大きい値は、翌月以降の該当する日を表します。

year

年。2 桁または 4 桁の値を指定可能で、 0-69 の間の値は 2000-2069 に、70-100 は 1970-2000 にマップされます。 今日最も一般的なシステム、すなわち time_t が 32 ビットの符号付き整数である システムでは year として有効な範囲は 1901 から 2038 の間です。しかし、PHP 5.1.0 より前のバージョンではこの範囲が 1970 から 2038 に制限されているシステム (たとえば Windows) もありました。

is_dst

このパラメータはサマータイム (DST) の時に1にセットされ、 そうでない時に0、サマータイムであるかどうかが不明である場合に-1 にセットされます。 不明な場合、PHP はサマータイムかどうか推測しようとします。 PHP を実行しているシステムで DST が有効になっている、もしくは is_dst が 1 にセットされている場合、 一部の時刻は有効になりません。 もし DST が有効で例えば 2:00 の場合、2:00 から 3:00 までの全ての時刻は 無効になり、mktime() は不確定な値 (通常は負数) を返します。いくつかのシステム (例えば Solaris 8) は真夜中に DST を有効にしますので、DST が有効なときの 0:30 は前日の 23:30 と評価されます。

注意:

PHP 5.1.0 以降、このパラメータは廃止されました。その結果、 新しいタイムゾーン処理機能がかわりに使用されます。

返り値

mktime() は与えられた引数の Unix タイムスタンプを返します。引数が不正な場合、 この関数は FALSE を返します（PHP 5.1 より前のバージョンでは -1 を返していました）。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン 説明
5.3.0 mktime() は、 is_dst パラメータを使用した場合に E_DEPRECATED をスローするようになりました。
5.1.0 is_dst パラメータは廃止されました。 エラー時には -1 ではなく FALSE を返すようになりました。 年月日がすべてゼロとすることが可能になりました。
5.1.0 引数なしでコールすると、mktime() は E_STRICT notice を発行するようになりました。かわりに time() 関数を使用しましょう。
5.1.0

タイムゾーンがおかしい場合に E_STRICT や E_NOTICE が発生するようになりました。

例

例1 mktime() の基本的な例

<?php
// デフォルトのタイムゾーンを設定します。PHP 5.1 以降で使用可能です
date_default_timezone_set('UTC');

// 出力: July 1, 2000 is on a Saturday
echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000));

// 出力例: 2006-04-05T01:02:03+00:00
echo date('c', mktime(1, 2, 3, 4, 5, 2006));
?>

例2 mktime() の例

mktime() は入力日付の有効性を確認しており、 範囲外の入力を自動的に修正して計算してくれるので便利です。 例えば、以下の各行はいずれも文字列 "Jan-01-1998"を出力します。

<?php
echo date("M-d-Y", mktime(0, 0, 0, 12, 32, 1997));
echo date("M-d-Y", mktime(0, 0, 0, 13, 1, 1997));
echo date("M-d-Y", mktime(0, 0, 0, 1, 1, 1998));
echo date("M-d-Y", mktime(0, 0, 0, 1, 1, 98));
?>

例3 月の末日

指定した月の最後の日は次の月の -1 番目の日ではなく、"0" 番目の日 として表すことが可能です。以下の例はともに文字列"The last day in Feb 2000 is: 29" を出力します。

<?php
$lastday = mktime(0, 0, 0, 3, 0, 2000);
echo strftime("Last day in Feb 2000 is: %d", $lastday);
$lastday = mktime(0, 0, 0, 4, -31, 2000);
echo strftime("Last day in Feb 2000 is: %d", $lastday);
?>

注意

警告

PHP 5.1.0 より前のバージョンでは、負の値のタイムスタンプは Windows の どのバージョンにおいてもサポートされていませんでした。 したがって、年の有効範囲は 1970 年から 2038 年の間のみに限定されていました。

参考

  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • gmmktime() - GMT 日付から Unix タイムスタンプを取得する
  • date() - ローカルの日付/時刻を書式化する
  • time() - 現在の Unix タイムスタンプを返す

strftime

(PHP 4, PHP 5)

strftime — ロケールの設定に基づいてローカルな日付・時間をフォーマットする

説明

string strftime ( string $format [, int $timestamp = time() ] )

ローカルの時刻・日付を、ロケール設定にもとづいてフォーマットします。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。

使用する C ライブラリで、すべての変換指定子がサポートされているとは限りません。 そのような場合、該当する変換指定子は PHP の strftime() ではサポートされません。 また、全てのプラットフォームが負のタイムスタンプをサポートしているわけではないため、 Unix Epoch (1970 年 1 月 1 日）以前の日付を扱えないかもしれません。 つまり、Windows や一部の Linux ディストリビューション、そしてその他のごく一部の オペレーティングシステム上では %e、%T、%R および %D (あるいはこれ以外も) が Jan 1, 1970 より前の日付について動作しないということです。 Windwos システム上でサポートされる変換指定子の概要については、 » MSDN に掲載されています。

パラメータ

format

次の変換指定子が format パラメータ用の文字列として認識されます
format 説明 返り値の例
日 --- ---
%a 短縮された曜日の名前 Sun から Sat
%A 完全な曜日の名前 Sunday から Saturday
%d 10 進数で 2 桁の日付 (先頭のゼロつき) 01 から 31
%e 1 桁の場合は先頭にスペースをいれた日付。 Windows ではそのようには実装されていません。詳細は以下を参照ください。 1 から 31
%j 3 桁で先頭にゼロを含む年間での日付 001 から 366
%u ISO-8601 数値表現であらわした曜日 1 (月曜日) から 7 (土曜日)
%w 数値表現であらわした曜日 0 (日曜日) から 6 (土曜日)
週 --- ---
%U 指定した年の週番号。最初の日曜日を第一週の開始日とする 13 (年間の第 13 週の場合)
%V ISO-8601:1988 で規定された、指定した年の週番号。 週の開始日は月曜日で、第 1 週は少なくとも 4 日はあることになる 01 から 53 (53 は年をまたがる週になります)
%W その年の週番号の数値表現。最初の月曜日を最初の週の初日とする 46 (46 番目の週の場合。開始日は月曜日)
月 --- ---
%b 現在のロケールに基づく短縮された月の名前 Jan から Dec
%B 現在のロケールに基づく完全な月の名前 January から December
%h 現在のロケールに基づく短縮された月の名前 (%b のエイリアス) Jan から Dec
%m 2 桁であらわした月 01 (1 月) から 12 (12 月)
年 --- ---
%C 2 桁であらわした世紀 (年を 100 で割り、整数に丸めたもの) 20 正規の場合は 19
%g 2 桁であらわした年。ISO-8601:1988 標準形式 (%V を参照) 2009 年 1 月 6 日の場合は 09
%G %g の 4 桁完全版 2009 年 1 月 3 日の場合は 2009
%y 2 桁であらわした年 2009 年の場合は 09、1979 年の場合は 79
%Y 4 桁であらわした年 2038
時 --- ---
%H 2 桁であらわした 24 時間制の時間 00 から 23
%I 2 桁であらわした 12 時間制の時間 01 から 12
%l (lower-case 'L') 12 時間制の時間で、1 桁の場合は先頭にスペースをつけたもの 1 から 12
%M 2 桁であらわした分 00 から 59
%p 指定した時刻に応じた大文字の 'AM' あるいは 'PM' 00:31 なら AM、22:23 なら PM
%P 指定した時刻に応じた小文字の 'am' あるいは 'pm' 00:31 なら am、22:23 なら pm
%r "%I:%M:%S %p" と同じ 21:34:17 なら 09:34:17 PM
%R "%H:%M" と同じ 12:35 AM なら 00:35、4:44 PM なら 16:44
%S 2 桁であらわした秒 00 から 59
%T "%H:%M:%S" と同じ 09:34:17 PM なら 21:34:17
%X Preferred time representation based on locale, without the date Example: 03:59:16 or 15:59:16
%z UTC からのオフセットあるいはタイムゾーン略称 (OS に依存) 東海岸時刻なら -0500 あるいは EST
%Z タイムゾーンオフセットあるいは略称のうち %z で返されないもの (OS に依存) 東海岸時刻なら -0500 あるいは EST
タイムスタンプ --- ---
%c 現在のロケールにもとづく日付と時間の表現 2009 年 2 月 5 日 午前 12:45:10 なら Tue Feb 5 00:45:10 2009
%D "%m/%d/%y" と同じ 2009 年 2 月 5 日なら 02/05/09
%F "%Y-%m-%d" と同じ (データベースのタイムスタンプとして一般的) 2009 年 2 月 5 日なら 2009-02-05
%s Unix エポックからのタイムスタンプ (time() 関数と同じ) 1979 年 9 月 10 日午前 08:40:00 なら 305815200
%x 現在のロケールにもとづく日付の表現 (時間は除く) 2009 年 2 月 5 日なら 02/05/09
その他 --- ---
%n 改行文字 ("\n") ---
%t タブ文字 ("\t") ---
%% パーセント文字 ("%") ---

このパラメータの最大長は 1023 文字です。

警告

ISO-9889:1999 に反して、Sun Solaris は日曜日を 1 としています。 そのため、%u はこのマニュアルの説明どおりに機能しないかもしれません。

警告

Windows 限定: %e 修飾子は Windows 版の実装ではサポートされていません。この値を取得するにはかわりに %#d 修飾子を使いましょう。以下の例で、 クロスプラットフォーム対応の関数を書く方法を示します。

警告

Mac OS X 限定: %P 修飾子は Mac OS X 版の実装ではサポートされていません。

timestamp

オプションのパラメータ timestamp は、 integer 型の Unix タイムスタンプです。 timestamp が指定されなかった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

返り値

指定した timestamp または timestamp が指定されていない場合に現在のローカル時間を用いて、 指定したフォーマット文字列に基づき文字列をフォーマットして返します。 月および曜日の名前、およびその他の言語依存の文字列は、 setlocale() で設定された現在のロケールを尊重して表示されます。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

出力内容は元となった C ライブラリに依存するため、サポートしていない変換指定子もあります。 Windows では、対応していない変換指定子を渡すと 5 つの E_WARNING メッセージが出て FALSE を返します。 その他のオペレーティングシステムでは特に E_WARNING メッセージは出ず、 変換指定子が (変換されずに) そのまま出力されます。

変更履歴

バージョン 説明
5.1.0

タイムゾーンがおかしい場合に E_STRICT や E_NOTICE が発生するようになりました。

例

この例は、それぞれのロケールがシステムにインストールされている場合にのみ動作します。

例1 strftime() のロケールの例

<?php
setlocale(LC_TIME, "C");
echo strftime("%A");
setlocale(LC_TIME, "fi_FI");
echo strftime(" in Finnish is %A,");
setlocale(LC_TIME, "fr_FR");
echo strftime(" in French %A and");
setlocale(LC_TIME, "de_DE");
echo strftime(" in German %A.\n");
?>

例2 ISO 8601:1988 の週番号の例

<?php
/*     December 2002 / January 2003
ISOWk  M   Tu  W   Thu F   Sa  Su
----- ----------------------------
51     16  17  18  19  20  21  22
52     23  24  25  26  27  28  29
1      30  31   1   2   3   4   5
2       6   7   8   9  10  11  12
3      13  14  15  16  17  18  19   */

// Outputs: 12/28/2002 - %V,%G,%Y = 52,2002,2002
echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";

// Outputs: 12/30/2002 - %V,%G,%Y = 1,2003,2002
echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";

// Outputs: 1/3/2003 - %V,%G,%Y = 1,2003,2003
echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";

// Outputs: 1/10/2003 - %V,%G,%Y = 2,2003,2003
echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";



/*     December 2004 / January 2005
ISOWk  M   Tu  W   Thu F   Sa  Su
----- ----------------------------
51     13  14  15  16  17  18  19
52     20  21  22  23  24  25  26
53     27  28  29  30  31   1   2
1       3   4   5   6   7   8   9
2      10  11  12  13  14  15  16   */

// Outputs: 12/23/2004 - %V,%G,%Y = 52,2004,2004
echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";

// Outputs: 12/31/2004 - %V,%G,%Y = 53,2004,2004
echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";

// Outputs: 1/2/2005 - %V,%G,%Y = 53,2004,2005
echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";

// Outputs: 1/3/2005 - %V,%G,%Y = 1,2005,2005
echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";

?>

例3 %e 修飾子を使う、クロスプラットフォーム対応の例

<?php

// Jan 1: はこのようになります。'%e%1%' (%%, e, %%, %e, %%)
$format = '%%e%%%e%%';

// Windows かどうかをチェックし、%e 修飾子を
// 適切に置換します
if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
    $format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format);
}

echo strftime($format);
?>

例4 すべての書式の表示

<?php
// 書式についての説明
$strftimeFormats = array(
    'A' => 'A full textual representation of the day',
    'B' => 'Full month name, based on the locale',
    'C' => 'Two digit representation of the century (year divided by 100, truncated to an integer)',
    'D' => 'Same as "%m/%d/%y"',
    'E' => '',
    'F' => 'Same as "%Y-%m-%d"',
    'G' => 'The full four-digit version of %g',
    'H' => 'Two digit representation of the hour in 24-hour format',
    'I' => 'Two digit representation of the hour in 12-hour format',
    'J' => '',
    'K' => '',
    'L' => '',
    'M' => 'Two digit representation of the minute',
    'N' => '',
    'O' => '',
    'P' => 'lower-case "am" or "pm" based on the given time',
    'Q' => '',
    'R' => 'Same as "%H:%M"',
    'S' => 'Two digit representation of the second',
    'T' => 'Same as "%H:%M:%S"',
    'U' => 'Week number of the given year, starting with the first Sunday as the first week',
    'V' => 'ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week',
    'W' => 'A numeric representation of the week of the year, starting with the first Monday as the first week',
    'X' => 'Preferred time representation based on locale, without the date',
    'Y' => 'Four digit representation for the year',
    'Z' => 'The time zone offset/abbreviation option NOT given by %z (depends on operating system)',
    'a' => 'An abbreviated textual representation of the day',
    'b' => 'Abbreviated month name, based on the locale',
    'c' => 'Preferred date and time stamp based on local',
    'd' => 'Two-digit day of the month (with leading zeros)',
    'e' => 'Day of the month, with a space preceding single digits',
    'f' => '',
    'g' => 'Two digit representation of the year going by ISO-8601:1988 standards (see %V)',
    'h' => 'Abbreviated month name, based on the locale (an alias of %b)',
    'i' => '',
    'j' => 'Day of the year, 3 digits with leading zeros',
    'k' => '',
    'l' => 'Hour in 12-hour format, with a space preceeding single digits',
    'm' => 'Two digit representation of the month',
    'n' => 'A newline character ("\n")',
    'o' => '',
    'p' => 'UPPER-CASE "AM" or "PM" based on the given time',
    'q' => '',
    'r' => 'Same as "%I:%M:%S %p"',
    's' => 'Unix Epoch Time timestamp',
    't' => 'A Tab character ("\t")',
    'u' => 'ISO-8601 numeric representation of the day of the week',
    'v' => '',
    'w' => 'Numeric representation of the day of the week',
    'x' => 'Preferred date representation based on locale, without the time',
    'y' => 'Two digit representation of the year',
    'z' => 'Either the time zone offset from UTC or the abbreviation (depends on operating system)',
    '%' => 'A literal percentage character ("%")',
);

// 結果
$strftimeValues = array();

// 書式を評価してエラーを抑制します
foreach($strftimeFormats as $format => $description){
    if (False !== ($value = @strftime("%{$format}"))){
        $strftimeValues[$format] = $value;
    }
}

// 最長の値を探します
$maxValueLength = 2 + max(array_map('strlen', $strftimeValues));

// 既知の書式を表示します
foreach($strftimeValues as $format => $value){
    echo "Known format   : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";
}

// 未知の書式を表示します
foreach(array_diff_key($strftimeFormats, $strftimeValues) as $format => $description){
    echo "Unknown format : '{$format}'   ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";
}
?>

上の例の出力は、 たとえば以下のようになります。

Known format   : 'A' = 'Friday'            ( A full textual representation of the day )
Known format   : 'B' = 'December'          ( Full month name, based on the locale )
Known format   : 'H' = '11'                ( Two digit representation of the hour in 24-hour format )
Known format   : 'I' = '11'                ( Two digit representation of the hour in 12-hour format )
Known format   : 'M' = '24'                ( Two digit representation of the minute )
Known format   : 'S' = '44'                ( Two digit representation of the second )
Known format   : 'U' = '48'                ( Week number of the given year, starting with the first Sunday as the first week )
Known format   : 'W' = '48'                ( A numeric representation of the week of the year, starting with the first Monday as the first week )
Known format   : 'X' = '11:24:44'          ( Preferred time representation based on locale, without the date )
Known format   : 'Y' = '2010'              ( Four digit representation for the year )
Known format   : 'Z' = 'GMT Standard Time' ( The time zone offset/abbreviation option NOT given by %z (depends on operating system) )
Known format   : 'a' = 'Fri'               ( An abbreviated textual representation of the day )
Known format   : 'b' = 'Dec'               ( Abbreviated month name, based on the locale )
Known format   : 'c' = '12/03/10 11:24:44' ( Preferred date and time stamp based on local )
Known format   : 'd' = '03'                ( Two-digit day of the month (with leading zeros) )
Known format   : 'j' = '337'               ( Day of the year, 3 digits with leading zeros )
Known format   : 'm' = '12'                ( Two digit representation of the month )
Known format   : 'p' = 'AM'                ( UPPER-CASE "AM" or "PM" based on the given time )
Known format   : 'w' = '5'                 ( Numeric representation of the day of the week )
Known format   : 'x' = '12/03/10'          ( Preferred date representation based on locale, without the time )
Known format   : 'y' = '10'                ( Two digit representation of the year )
Known format   : 'z' = 'GMT Standard Time' ( Either the time zone offset from UTC or the abbreviation (depends on operating system) )
Known format   : '%' = '%'                 ( A literal percentage character ("%") )
Unknown format : 'C'                       ( Two digit representation of the century (year divided by 100, truncated to an integer) )
Unknown format : 'D'                       ( Same as "%m/%d/%y" )
Unknown format : 'E'
Unknown format : 'F'                       ( Same as "%Y-%m-%d" )
Unknown format : 'G'                       ( The full four-digit version of %g )
Unknown format : 'J'
Unknown format : 'K'
Unknown format : 'L'
Unknown format : 'N'
Unknown format : 'O'
Unknown format : 'P'                       ( lower-case "am" or "pm" based on the given time )
Unknown format : 'Q'
Unknown format : 'R'                       ( Same as "%H:%M" )
Unknown format : 'T'                       ( Same as "%H:%M:%S" )
Unknown format : 'V'                       ( ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week )
Unknown format : 'e'                       ( Day of the month, with a space preceding single digits )
Unknown format : 'f'
Unknown format : 'g'                       ( Two digit representation of the year going by ISO-8601:1988 standards (see %V) )
Unknown format : 'h'                       ( Abbreviated month name, based on the locale (an alias of %b) )
Unknown format : 'i'
Unknown format : 'k'
Unknown format : 'l'                       ( Hour in 12-hour format, with a space preceeding single digits )
Unknown format : 'n'                       ( A newline character ("\n") )
Unknown format : 'o'
Unknown format : 'q'
Unknown format : 'r'                       ( Same as "%I:%M:%S %p" )
Unknown format : 's'                       ( Unix Epoch Time timestamp )
Unknown format : 't'                       ( A Tab character ("\t") )
Unknown format : 'u'                       ( ISO-8601 numeric representation of the day of the week )
Unknown format : 'v'

注意

注意: ISO 8601:1988 week numbers に基づいている %G と %V は、 もしナンバリングシステムが完全に理解されていなければ 期待とは違う結果をもたらします。 このマニュアルの %V の例を参照ください。

参考

strptime

(PHP 5 >= 5.1.0)

strptime — strftime() が生成した日付/時刻をパースする

説明

array strptime ( string $date , string $format )

strptime() は date をパースした結果を配列で返します。エラー時には FALSE を返します。

月名や曜日、そしてその他の言語依存な文字列は setlocale() (LC_TIME) で設定された現在の ロケールを考慮して返します。

パラメータ

date (string)

パースする文字列（例: strftime() の返り値）。

format (string)

date で使用されているフォーマット （例: strftime() で使用されていたものと同じ）。 strftime() で使えるオプションの中には、 strptime() では何の影響を及ぼさないものがあることに注意しましょう。 実際にサポートする範囲がどのようになるのかは、 使っている OS と C ライブラリに依存します。

フォーマットオプションについての詳細は strftime() のページを参照ください。

返り値

成功した場合は配列、失敗した場合に FALSE を返します。

配列で返されるパラメータ
パラメータ 説明
"tm_sec" 分未満の秒数 (0-61)
"tm_min" 時間未満の分数 (0-59)
"tm_hour" 0 時以降の時間数 (0-23)
"tm_mday" 月内の日数 (1-31)
"tm_mon" 1 月から数えた月数 (0-11)
"tm_year" 1900 年以降の年
"tm_wday" 日曜日からの日数 (0-6)
"tm_yday" 1 月 1 日からの日数 (0-365)
"unparsed" date の中で、指定された format で判断できなかった部分

例

例1 strptime() の例

<?php
$format = '%d/%m/%Y %H:%M:%S';
$strf = strftime($format);

echo "$strf\n";

print_r(strptime($strf, $format));
?>

上の例の出力は、 たとえば以下のようになります。

03/10/2004 15:54:19

Array
(
    [tm_sec] => 19
    [tm_min] => 54
    [tm_hour] => 15
    [tm_mday] => 3
    [tm_mon] => 9
    [tm_year] => 104
    [tm_wday] => 0
    [tm_yday] => 276
    [unparsed] =>
)

注意

注意: この関数は Windows 環境にはまだ実装されていません。

注意:

内部では、この関数はシステムの C ライブラリ関数 strptime() をコールしています。 このライブラリ関数は、OS によって挙動が異なることがあります。 date_parse_from_format() はこの問題の影響を受けないので、PHP 5.3.0 以降ではこちらの関数を使うことを推奨します。

注意:

"tm_sec" には、うるう秒も組み込まれています (現在は、年間 2 秒まで)。うるう秒についての詳細な情報は » Wikipedia の記事 を参照ください。

注意:

PHP 5.2.0 より前のバージョンでは、この関数が未定義の挙動をすることがありました。 特に "tm_sec"、"tm_min" および "tm_hour" が未定義の値になることがありました。

参考

  • checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
  • strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする
  • date_parse_from_format() - 指定した書式でフォーマットされた日付についての情報を取得する
  • DateTime::createFromFormat() - 指定した書式でフォーマットした新しい DateTime オブジェクトを返す

strtotime

(PHP 4, PHP 5)

strtotime — 英文形式の日付を Unix タイムスタンプに変換する

説明

int strtotime ( string $time [, int $now = time() ] )

この関数は英語の書式での日付を含む文字列が指定されることを期待しており、 now で与えられたその形式から Unix タイムスタンプ (1970 年 1 月 1 日 00:00:00 UTC からの経過秒数) への変換を試みます。 now が指定されていない場合は現在日時に変換します。

この関数の各パラメータでは、パラメータ内でタイムゾーンを指定しない限りはデフォルトのタイムゾーンを使います。 意図的にそうする場合は別として、パラメータごとにタイムゾーンを変えてしまったりしないように気をつけましょう。 デフォルトのタイムゾーンを定義する方法については date_default_timezone_get() を参照ください。

パラメータ

time

日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

now

返される値を計算するために使用されるタイムスタンプ。

返り値

成功時はタイムスタンプ、そうでなければ FALSE を返します。 PHP 5.1.0 以前ではこの関数は失敗時に -1 を返します。

エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に E_NOTICE を発生させます。また、システム設定のタイムゾーンあるいは環境変数 TZ を使用した場合には E_STRICT あるいは E_WARNING を発生させます。 date_default_timezone_set() も参照ください。

変更履歴

バージョン 説明
5.3.0 PHP 5.3.0 より前のバージョンでは、24:00 は無効なフォーマットとされており strtotime() は FALSE を返していました。
5.2.7 5.2.7 より前の PHP 5 では、「ある月の何回目の何曜日」 を取得するときにもしその月の初日がその曜日だった場合、 タイムスタンプが間違って一週間追加されてしまっていました。 これは 5.2.7 以降のバージョンでは修正されています。
5.1.0 失敗時に -1 の代わりに FALSE を返すようになりました。
5.1.0

タイムゾーンがおかしい場合に E_STRICT や E_NOTICE が発生するようになりました。

5.0.2 5.0.2 までの PHP 5 では、"now" やその他の相対時刻は誤って当日の真夜中から計算されます。 他のバージョンでは、これは正しく現在時刻から計算されます。
5.0.0 マイクロ秒も受け付けるようになりましたが、指定してもそれは無視されます。
4.4.0 バージョン 4.4.0 より前の PHP では、"next" が誤って +2 として計算されます。これを解決するには、代わりに "+1" を使用します。

例

例1 A strtotime() の例

<?php
echo strtotime("now"), "\n";
echo strtotime("10 September 2000"), "\n";
echo strtotime("+1 day"), "\n";
echo strtotime("+1 week"), "\n";
echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
echo strtotime("next Thursday"), "\n";
echo strtotime("last Monday"), "\n";
?>

例2 失敗のチェック

<?php
$str = 'Not Good';

// PHP 5.1.0 以前では、false の代わりに -1 と比較する
if (($timestamp = strtotime($str)) === false) {
    echo "The string ($str) is bogus";
} else {
    echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
}
?>

注意

注意:

年を 2 桁の数値で指定した場合、その値が 00-69 なら 2000-2069 に、 70-99 なら 1970-1999 にそれぞれ変換されます。 32 ビットシステム上での相違点 (2038-01-19 03:14:07 までの日付しか表せない) については以下の注意を参照ください。

注意:

タイムスタンプの有効な範囲は、通常、Fri, 13 Dec 1901 20:45:54 UTC から Tue, 19 Jan 2038 03:14:07 UTC までです (これらは、32 ビット符号付整数の最大及び最小に一致します)。 さらに全てのプラットフォームが負のタイムスタンプをサポートしている わけではありませんので、日付の範囲は Unix エポック以前にはならないかも知れません。 これは、例えば Windows やいくつかの Linux ディストリビューション、 いくつかの他のオペレーティングシステムでは 1970 年 1 月 1 日以前の日付では動作しない事を意味しています。 PHP 5.1.0 以降のバージョンでは、この制限はなくなっています。

64 ビット版の PHP では、タイムスタンプの有効範囲は事実上無制限です。 というのも、64 ビットでは過去側も未来側も約 2930 億年を表せるからです。

注意:

m/d/y あるいは d-m-y といった書式の曖昧さを解決する際には、区切り文字を利用します。スラッシュ (/) で区切られている場合はアメリカ風の m/d/y と見なし、ダッシュ (-) あるいはドット (.) で区切られている場合はヨーロッパ風の d-m-y であると見なします。

このような曖昧さを避けるためにも、ISO 8601 形式 (YYYY-MM-DD) を使うか、可能であれば DateTime::createFromFormat() を使うことを推奨します。

注意:

この関数を使って日付の足し算や引き算を行うことはおすすめできません。 PHP 5.3 以降なら DateTime::add() や DateTime::sub() を、そして PHP 5.2 なら DateTime::modify() を使いましょう。

参考

time

(PHP 4, PHP 5)

time — 現在の Unix タイムスタンプを返す

説明

int time ( void )

現在時刻を Unix エポック (1970 年 1 月 1 日 00:00:00 GMT) からの通算秒として返します。

例

例1 time() の例

<?php
$nextWeek = time() + (7 * 24 * 60 * 60);
                   // 7 日 * 24 時間 * 60 分 * 60 秒
echo 'Now:       '. date('Y-m-d') ."\n";
echo 'Next Week: '. date('Y-m-d', $nextWeek) ."\n";
// あるいは strtotime() を使用します
echo 'Next Week: '. date('Y-m-d', strtotime('+1 week')) ."\n";
?>

上の例の出力は、 たとえば以下のようになります。

Now:       2005-03-30
Next Week: 2005-04-06
Next Week: 2005-04-06

注意

ヒント

PHP 5.1 以降、$_SERVER['REQUEST_TIME'] によってリクエスト開始時のタイムスタンプが取得できるようになりました。

参考

  • date() - ローカルの日付/時刻を書式化する
  • microtime() - 現在の Unix タイムスタンプをマイクロ秒まで返す

timezone_abbreviations_list

(PHP 5 >= 5.2.0)

timezone_abbreviations_list — DateTimeZone::listAbbreviations() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::listAbbreviations()

timezone_identifiers_list

(PHP 5 >= 5.2.0)

timezone_identifiers_list — DateTimeZone::listIdentifiers() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::listIdentifiers()

timezone_location_get

(PHP 5 >= 5.3.0)

timezone_location_get — DateTimeZone::getLocation() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getLocation()

timezone_name_from_abbr

(PHP 5 >= 5.1.3)

timezone_name_from_abbr — 略称からタイムゾーン名を返す

説明

string timezone_name_from_abbr ( string $abbr [, int $gmtOffset = -1 [, int $isdst = -1 ]] )

パラメータ

abbr

タイムゾーンの略称。

gmtOffset

GMT からのオフセット秒数。デフォルトは -1 で、 この場合は abbr に対応するタイムゾーンのうち最初に見つかったものを返します。 それ以外の場合は指定したオフセットを探し、 そこで見つからなかった場合には 他のオフセットも含めて最初に見つかったものを返します。

isdst

夏時間のインジケータ。デフォルトは -1 で、 タイムゾーンが夏時間を持っているかどうかは考慮せずに検索します。 この値を 1 にすると、gmtOffset は夏時間を考慮したオフセットと見なします。 0 の場合は、gmtOffset は夏時間を考慮しないオフセットと見なします。 abbr が存在しない場合、 タイムゾーンの検索は gmtOffset と isdst だけで行います。

返り値

成功した場合にタイムゾーン名、失敗した場合に FALSE を返します。

例

例1 timezone_name_from_abbr() の例

<?php
echo timezone_name_from_abbr("CET") . "\n";
echo timezone_name_from_abbr("", 3600, 0) . "\n";
?>

上の例の出力は、 たとえば以下のようになります。

Europe/Berlin
Europe/Paris

参考

timezone_name_get

(PHP 5 >= 5.2.0)

timezone_name_get — DateTimeZone::getName() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getName()

timezone_offset_get

(PHP 5 >= 5.2.0)

timezone_offset_get — DateTimeZone::getOffset() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getOffset()

timezone_open

(PHP 5 >= 5.2.0)

timezone_open — DateTimeZone::__construct() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::__construct()

timezone_transitions_get

(PHP 5 >= 5.2.0)

timezone_transitions_get — DateTimeZone::getTransitions() のエイリアス

説明

この関数は次の関数のエイリアスです。 DateTimeZone::getTransitions()

timezone_version_get

(PHP 5 >= 5.3.0)

timezone_version_get — timezonedb のバージョンを取得する

説明

string timezone_version_get ( void )

timezonedb の現在のバージョンを返します。

返り値

文字列を返します。

例

例1 timezonedb のバージョンの取得

<?php
echo timezone_version_get();
?>

上の例の出力は、 たとえば以下のようになります。

2009.7

目次

サポートする日付と時刻の書式

目次

この節では strtotime(), DateTime および date_create() が解釈可能な全ての書式について説明します。 これらの書式はセクションごとにグループ分けされています。 たいていの場合、一つの日付・時刻文字列の中で異なるセクションの書式を併用することができます。 それぞれの書式について、説明と一緒に1個以上の例を示してあります。 シングルクォートで囲まれたフォーマットは大文字小文字を同一視します ('t' は t とも T とも書けます)。 ダブルクォートで囲まれたフォーマットは大文字小文字を同一視しません ("T" は T としか書けません)。

時刻の書式

シンボル一覧
シンボル 書式 例
frac . [0-9]+ ".21342", ".85"
hh "0"?[1-9] | "1"[0-2] "04", "7", "12"
HH [01][0-9] | "2"[0-4] "04", "7", "19"
meridian [AaPp] .? [Mm] .? [\0\t ] "A.m.", "pM", "am."
MM [0-5][0-9] "00", "12", "59"
II [0-5][0-9] "00", "12", "59"
space [ \t]  
tz "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ "CEST", "Europe/Amsterdam", "America/Indiana/Knox"
tzcorrection "GMT"? [+-] hh ":"? MM? "+0400", "GMT-07:00", "-07:00"
12時間制の表記
説明 書式 例
時、午前/午後 hh space? meridian "4 am", "5PM"
時、分、午前/午後 hh [.:] MM space? meridian "4:08 am", "7:19P.M."
時、分、秒、午前/午後 hh [.:] MM [.:] II space? meridian "4:08:37 am", "7:19:19P.M."
MS SQL (時、分、秒、端数、午前/午後), PHP 5.3 以降で利用可能 hh ":" MM ":" II [.:] [0-9]+ meridian "4:08:39:12313am"
24時間制の表記
説明 書式 例
時、分 't'? HH [.:] MM "04:08", "19.19", "T23:43"
時、分（コロンなし） 't'? HH MM "0408", "t1919", "T2343"
時、分、秒 't'? HH [.:] MM [.:] II "04.08.37", "t19:19:19"
時、分、秒（コロンなし） 't'? HH MM II "040837", "T191919"
時、分、秒、タイムゾーン 't'? HH [.:] MM [.:] II space? ( tzcorrection | tz ) "040837CEST", "T191919-0700"
時、分、秒、端数 't'? HH [.:] MM [.:] II frac "04.08.37.81412", "19:19:19.532453"
タイムゾーン tz | tzcorrection "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00"

日付の書式

シンボル一覧
シンボル 書式 例
daysuf "st" | "nd" | "rd" | "th"  
dd ([0-2]?[0-9] | "3"[01]) daysuf? "7th", "22nd", "31"
DD "0" [0-9] | [1-2][0-9] | "3" [01] "07", "31"
m 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" | "VII" | "VIII" | "IX" | "X" | "XI" | "XII"  
M 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec'  
mm "0"? [0-9] | "1"[0-2] "0", "04", "7", "12"
MM "0" [0-9] | "1"[0-2] "00", "04", "07", "12"
y [0-9]{1,4} "00", "78", "08", "8", "2008"
yy [0-9]{2} "00", "08", "78"
YY [0-9]{4} "2000", "2008", "1978"
各国ごとの表記法
説明 書式 例
アメリカ式の月、日 mm "/" dd "5/12", "10/27"
アメリカ式の月、日、年 mm "/" dd "/" y "12/22/78", "1/17/2006", "1/17/6"
スラッシュで区切られた、4桁の年、月、日 YY "/" mm "/" dd "2008/6/30", "1978/12/22"
4桁の年、月 (GNU) YY "-" mm "2008-6", "2008-06", "1978-12"
ハイフンで区切られた、年、月、日 y "-" mm "-" dd "2008-6-30", "78-12-22", "8-6-21"
ドットかタブかハイフンで区切られた、日、月、4桁の年 dd [.\t-] mm [.-] YY "30-6-2008", "22.12\t1978"
ドットかタブで区切られた、日、月、2桁の年 dd [.\t] mm "." yy "30.6.08", "22\t12\t78"
日、月の文字表記、年 dd ([ \t.-])* m ([ \t.-])* y "30-June 2008", "22DEC78", "14 III 1879"
月の文字表記、4桁の年 (日は1日にリセットされる) m ([ \t.-])* YY "June 2008", "DEC1978", "March 1879"
4桁の年、月の文字表記 (日は1日にリセットされる) YY ([ \t.-])* m "2008 June", "1978-XII", "1879.MArCH"
月の文字表記、日、年 m ([ .\t-])* dd [,.stndrh\t ]+ y "July 1st, 2008", "April 17, 1790", "May.9,78"
月の文字表記、日 m ([ .\t-])* dd [,.stndrh\t ]* "July 1st,", "Apr 17", "May.9"
日、月の文字表記 d ([ .\t-])* m "1 July", "17 Apr", "9.May"
月の省略形、日、年 M "-" DD "-" y "May-09-78", "Apr-17-1790"
年、月の省略形、日 y "-" M "-" DD "78-Dec-22", "1814-MAY-17"
年 (年だけの指定) YY "1978", "2008"
月の文字表記 (月だけの指定) m "March", "jun", "DEC"
ISO 8601 に準拠した表記法
説明 書式 例
年、月、日の8桁 YY MM DD "15810726", "19780417", "18140517"
スラッシュで区切られた、4桁の年、月、日 YY "/" MM "/" DD "2008/06/30", "1978/12/22"
ハイフンで区切られた、2桁の年、月、日 yy "-" MM "-" DD "08-06-30", "78-12-22"
符号つきまたは符号なしの4桁の年、月、日 [+-]? YY "-" MM "-" DD "-0002-07-26", "+1978-04-17", "1814-05-17"

注意:

シンボル y または yy を含む書式について、 100未満の年は特別な扱いになります。年が0から69までの間だった場合、 2000を足した数になります。 また、年が70から99までの間だった場合、1900を足した数になります。 つまり、"00-01-01" は "2000-01-01" と解釈されます。

注意:

書式「ドットかタブで区切られた、日、月、2桁の年」 (dd [.\t] mm "." yy) は年が61から99の間のときだけ機能します。 この範囲外の年を与えた場合には 時刻の書式 の "HH [.:] MM [.:] SS" が優先されます。

注意:

書式「年 (年だけの指定)」は、時刻の指定が先に出現している場合のみ機能します。 そうでない場合、指定された4桁は HH MM とみなされます。

注意:

シンボル dd と DD について、 オーバーフローやアンダーフローすることができます。 つまり、 0 日は先月の最終日の意味になりますし、 オーバーフローすると翌月に繰り越しになります。 このルールにより、"2008-08-00" は "2008-07-31" と同一になり、 "2008-06-31" は "2008-07-01" と同一になります ( 6 月は 30 日までしかないので)。

また、シンボル mm と MM についても 0 を用いてアンダーフローすることができます。 0 月は前年の 12 月を意味します。 たとえば "2008-00-22" は "2007-12-22" と同一です。

もしこれらを併用し、日も月もアンダーフローした場合は次のようになります。 "2008-00-00" は、まず "2007-12-00" へと変換され、 さらに "2007-11-30" へと変換されます。 文字列 "0000-00-00" についても同様に "-0001-11-30" へと変形されます。 (ISO 8601 における -1 年は、予測的グレゴリオ暦 (proleptic Gregorian calendar) で言うところの紀元前 2 年になります。)

複合的な書式

シンボル一覧
シンボル 書式 例
DD "0" [0-9] | [1-2][0-9] | "3" [01] "02", "12", "31"
doy "00"[1-9] | "0"[1-9][0-9] | [1-2][0-9][0-9] | "3"[0-5][0-9] | "36"[0-6] "36"[0-6] "000", "012", "366"
frac . [0-9]+ ".21342", ".85"
hh "0"?[1-9] | "1"[0-2] "04", "7", "12"
HH [01][0-9] | "2"[0-4] "04", "7", "19"
meridian [AaPp] .? [Mm] .? [\0\t ] "A.m.", "pM", "am."
ii [0-5][0-9] "04", "8", "59"
II [0-5][0-9] "04", "08", "59"
M 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec'  
MM [0-5][0-9] "00", "12", "59"
space [ \t]  
ss [0-5][0-9] "04", "8", "59"
SS [0-5][0-9] "04", "08", "59"
W "0"[1-9] | [1-4][0-9] | "5"[0-3] "05", "17", "53"
tzcorrection "GMT"? [+-] hh ":"? MM? "+0400", "GMT-07:00", "-07:00"
YY [0-9]{4} "2000", "2008", "1978"
標準仕様/アプリケーションごとの表記法
説明 書式 例
Common Log Format dd "/" M "/" YY : HH ":" II ":" SS space tzcorrection "10/Oct/2000:13:55:36 -0700"
EXIF YY ":" MM ":" DD " " HH ":" II ":" SS "2008:08:07 18:11:31"
ISO の年、 ISO の週番号 YY "-"? "W" W "2008W27", "2008-W28"
ISO の年、 ISO の週番号、 ISO の曜日番号 YY "-"? "W" W "-"? [0-7] "2008W273", "2008-W28-3"
MySQL YY "-" MM "-" DD " " HH ":" II ":" SS "2008-08-07 18:11:31"
PostgreSQL: 年、日番号 YY "."? doy "2008.197", "2008197"
SOAP YY "-" MM "-" DD "T" HH ":" II ":" SS frac tzcorrection? "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00"
Unix タイムスタンプ "@" "-"? [0-9]+ "@1215282385"
XMLRPC YY MM DD "T" hh ":" II ":" SS "20080701T22:38:07", "20080701T9:38:07"
XMLRPC (短縮形) YY MM DD 't' hh II SS "20080701t223807", "20080701T093807"
WDDX YY "-" mm "-" dd "T" hh ":" ii ":" ss "2008-7-1T9:3:37"

注意:

書式「 ISO の年、 ISO の週番号」と 「 ISO の年、 ISO の週番号、 ISO の曜日番号」で使われている "W" は大文字小文字を同一視しません。大文字の "W" だけが利用できます。

「 SOAP 」、「 XMRPC 」および「 WDDX 」の各書式中の "T" は大文字小文字を同一視しません。大文字の "T" だけが利用できます。

書式「 Unix タイムスタンプ 」は、タイムゾーンを UTC に設定します。

（訳注）書式「 Common Log Format 」は、 Apache ログにおける時刻の書式です。

（訳注）書式「 ISO の年、 ISO の週番号」と 「 ISO の年、 ISO の週番号、 ISO の曜日番号」は、 ISO 8601で規定されている表記法です。 定義上、週が前年あるいは翌年に属すことがあるので注意してください。 たとえば、 ISO 8601 の定義では 2010 年の第 1 週は 1 月 3 日から 1 月 9 日までとなり、 2010 年の 1 月 1 日と 1 月 2 日は 2009 年の第 53 週に属します。

相対的な書式

シンボル一覧
シンボル 書式
dayname 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun'
daytext 'weekday' | 'weekdays'
number [+-]?[0-9]+
ordinal 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this'
reltext 'next' | 'last' | 'previous' | 'this'
space [ \t]+
unit (('sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | daytext
日付に基づいた表記
書式 説明 例
'yesterday' 昨日の00:00:00 "yesterday 14:00"
'midnight' 時刻を00:00:00にします  
'today' 時刻を00:00:00にします  
'now' 今 - 単に無視されます  
'noon' 時刻を12:00:00にします "yesterday noon"
'tomorrow' 明日の00:00:00  
'back of' hour 指定された時の15分前 "back of 7pm", "back of 15"
'front of' hour 指定された時の15分後 "front of 5am", "front of 23"
'first day' ' of'? 現在月の最初の日にします。 この書式に続けて月名を指定する使いかたが最適です。 "first day of January 2008"
'last day' ' of'? 現在月の最後の日にします。 この書式に続いて月名を指定する使いかたが最適です。 "last day of next month"
ordinal space dayname space 'of' 現在月のx番目の曜日を計算します。 "first sat of July 2008"
'last' space dayname space 'of' 現在月の 最後の 曜日を計算します。 "last sat of July 2008"
number space? (unit | 'week') 値を数値で指定するような、相対的な時間指定を処理します。 "+5 weeks", "12 day", "-7 weekdays"
ordinal space unit 値を英単語で指定するような、相対的な時間指定を処理します。 "fifth day", "second month"
'ago' 直前に指定された相対的な時間指定について、正負反転します。 "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago ago"
dayname 現在からみて次にやってくる、指定された曜日にします。 "Monday"
reltext space 'week' 特別な書式 "weekday + last/this/next week" を処理します。 "Monday next week"

注意:

相対的な記述は、相対的でない記述の 後で 処理されます。 このため、 "+1 week july 2008" と "july 2008 +1 week" とは同一になります。

ただし、 "yesterday"、 "midnight"、 "today"、 "noon" そして "tomorrow" はこのルールの例外です。 つまり、 "tomorrow 11:00" と "11:00 tomorrow" は異なります。 たとえば、今日が2008年7月23日だとしましょう。 このときの1つ目の結果は "2008-07-24 11:00" ですが、 2つ目の方は "2008-07-24 00:00" となります。 このような結果になる理由は、 これら5つの記述が現在時刻に直接影響するためです。

注意:

日付/時刻文字列中の曜日指定が現在の曜日と同じ場合は、 以下の点に注意してください。 この場合、日付文字列中の曜日は、曜日を明示的に指定しなかった場合に 日付文字列の相対的でない部分から計算される曜日と同一ではありますが、 指定しなくても同じというわけではありません。

  1. "dayname" は、 日付を進め ません 。 (例: "Wed July 23rd, 2008" は "2008-07-23" の意味です。)
  2. "number dayname" は、 日付を進めません 。 (例: "1 wednesday july 23rd, 2008" は "2008-07-23" の意味です。)
  3. "number week dayname" は、 指定された週を加算しますが、 さらに日付を進めることはしません。 この場合、"number week" と "dayname" は 2 つの別個のブロックとなります。 (例: "+1 week wednesday july 23rd, 2008" は "2008-07-30" の意味です。)
  4. "ordinal dayname" は、日付を別の日まで進めます。 (例: "first wednesday july 23rd, 2008" は "2008-07-30" の意味です。)
  5. "number week ordinal dayname" は、まず指定された週を加算し、 それから日付を別の日まで進めます。 この場合、 "number week" と "ordinal dayname" は2つの別個のブロックとなります。 (例: "+1 week first wednesday july 23rd, 2008" は "2008-08-06" の意味です。)
  6. "ordinal dayname 'of' " は日付を進め ません 。 (例: "first wednesday of july 23rd, 2008" は "2008-07-02" の意味です。 なぜなら、'of'を含む一連の語群 'first wednesday of july' が 相対的な書式として処理されることで 日付を同月の '1' 日にリセットしてしまい、'23rd' は無視されてしまうのです。)

また、書式 "ordinal space dayname space 'of' " と "'last' space dayname space 'of' " に含まれる "of" は少々特別扱いなので、注意してください。

  1. 日付を指定月の1日にします。
  2. "ordinal dayname 'of' " は日付を進め ません 。 (例: "first tuesday of july 2008" は "2008-07-01" の意味です。)
  3. "ordinal dayname " は日付を進め ます 。 (例: "first tuesday july 2008" は "2008-07-08" の意味です。上記の項番4を参照。)
  4. "'last' dayname 'of' " は、 指定された曜日（dayname）の同月最後の日を返します。 (例: "last wed of july 2008" は "2008-07-30" の意味です。)
  5. "'last' dayname" は、 現在日付からみて直前の、指定された曜日（dayname）を返します。 (例: "last wed july 2008" は "2008-06-25" の意味です。 まず "july 2008" を処理して現在日付を "2008-07-01" とみなし、 次に "last wed" により直前の水曜日、つまり "2008-06-25" へと移動します。)

注意:

月数を相対指定すると、その途中に経過する月の日数を使って結果を算出します。 たとえば "+2 month 2011-11-30" の結果は "2012-01-30" となります。 11 月の日数は 30 日、12 月の日数は 31 日なので、 その合計である 61 日後となるわけです。

サポートされるタイムゾーンのリスト

目次

これは、PHP がサポートしているタイムゾーンの完全なリストです。例えば date_default_timezone_set() などで使用します。

注意: 最新バージョンのタイムゾーンデータベースは、PECL の » timezonedb からインストールできます。

注意: このリストの元になっているのは、タイムゾーンデータベース バージョン 2012.3.

アフリカ

アフリカ
Africa/Abidjan Africa/Accra Africa/Addis_Ababa Africa/Algiers Africa/Asmara
Africa/Asmera Africa/Bamako Africa/Bangui Africa/Banjul Africa/Bissau
Africa/Blantyre Africa/Brazzaville Africa/Bujumbura Africa/Cairo Africa/Casablanca
Africa/Ceuta Africa/Conakry Africa/Dakar Africa/Dar_es_Salaam Africa/Djibouti
Africa/Douala Africa/El_Aaiun Africa/Freetown Africa/Gaborone Africa/Harare
Africa/Johannesburg Africa/Juba Africa/Kampala Africa/Khartoum Africa/Kigali
Africa/Kinshasa Africa/Lagos Africa/Libreville Africa/Lome Africa/Luanda
Africa/Lubumbashi Africa/Lusaka Africa/Malabo Africa/Maputo Africa/Maseru
Africa/Mbabane Africa/Mogadishu Africa/Monrovia Africa/Nairobi Africa/Ndjamena
Africa/Niamey Africa/Nouakchott Africa/Ouagadougou Africa/Porto-Novo Africa/Sao_Tome
Africa/Timbuktu Africa/Tripoli Africa/Tunis Africa/Windhoek  

アメリカ

アメリカ
America/Adak America/Anchorage America/Anguilla America/Antigua America/Araguaina
America/Argentina/Buenos_Aires America/Argentina/Catamarca America/Argentina/ComodRivadavia America/Argentina/Cordoba America/Argentina/Jujuy
America/Argentina/La_Rioja America/Argentina/Mendoza America/Argentina/Rio_Gallegos America/Argentina/Salta America/Argentina/San_Juan
America/Argentina/San_Luis America/Argentina/Tucuman America/Argentina/Ushuaia America/Aruba America/Asuncion
America/Atikokan America/Atka America/Bahia America/Bahia_Banderas America/Barbados
America/Belem America/Belize America/Blanc-Sablon America/Boa_Vista America/Bogota
America/Boise America/Buenos_Aires America/Cambridge_Bay America/Campo_Grande America/Cancun
America/Caracas America/Catamarca America/Cayenne America/Cayman America/Chicago
America/Chihuahua America/Coral_Harbour America/Cordoba America/Costa_Rica America/Creston
America/Cuiaba America/Curacao America/Danmarkshavn America/Dawson America/Dawson_Creek
America/Denver America/Detroit America/Dominica America/Edmonton America/Eirunepe
America/El_Salvador America/Ensenada America/Fort_Wayne America/Fortaleza America/Glace_Bay
America/Godthab America/Goose_Bay America/Grand_Turk America/Grenada America/Guadeloupe
America/Guatemala America/Guayaquil America/Guyana America/Halifax America/Havana
America/Hermosillo America/Indiana/Indianapolis America/Indiana/Knox America/Indiana/Marengo America/Indiana/Petersburg
America/Indiana/Tell_City America/Indiana/Vevay America/Indiana/Vincennes America/Indiana/Winamac America/Indianapolis
America/Inuvik America/Iqaluit America/Jamaica America/Jujuy America/Juneau
America/Kentucky/Louisville America/Kentucky/Monticello America/Knox_IN America/Kralendijk America/La_Paz
America/Lima America/Los_Angeles America/Louisville America/Lower_Princes America/Maceio
America/Managua America/Manaus America/Marigot America/Martinique America/Matamoros
America/Mazatlan America/Mendoza America/Menominee America/Merida America/Metlakatla
America/Mexico_City America/Miquelon America/Moncton America/Monterrey America/Montevideo
America/Montreal America/Montserrat America/Nassau America/New_York America/Nipigon
America/Nome America/Noronha America/North_Dakota/Beulah America/North_Dakota/Center America/North_Dakota/New_Salem
America/Ojinaga America/Panama America/Pangnirtung America/Paramaribo America/Phoenix
America/Port-au-Prince America/Port_of_Spain America/Porto_Acre America/Porto_Velho America/Puerto_Rico
America/Rainy_River America/Rankin_Inlet America/Recife America/Regina America/Resolute
America/Rio_Branco America/Rosario America/Santa_Isabel America/Santarem America/Santiago
America/Santo_Domingo America/Sao_Paulo America/Scoresbysund America/Shiprock America/Sitka
America/St_Barthelemy America/St_Johns America/St_Kitts America/St_Lucia America/St_Thomas
America/St_Vincent America/Swift_Current America/Tegucigalpa America/Thule America/Thunder_Bay
America/Tijuana America/Toronto America/Tortola America/Vancouver America/Virgin
America/Whitehorse America/Winnipeg America/Yakutat America/Yellowknife  

南極

南極
Antarctica/Casey Antarctica/Davis Antarctica/DumontDUrville Antarctica/Macquarie Antarctica/Mawson
Antarctica/McMurdo Antarctica/Palmer Antarctica/Rothera Antarctica/South_Pole Antarctica/Syowa
Antarctica/Vostok        

北極

北極
Arctic/Longyearbyen

アジア

アジア
Asia/Aden Asia/Almaty Asia/Amman Asia/Anadyr Asia/Aqtau
Asia/Aqtobe Asia/Ashgabat Asia/Ashkhabad Asia/Baghdad Asia/Bahrain
Asia/Baku Asia/Bangkok Asia/Beirut Asia/Bishkek Asia/Brunei
Asia/Calcutta Asia/Choibalsan Asia/Chongqing Asia/Chungking Asia/Colombo
Asia/Dacca Asia/Damascus Asia/Dhaka Asia/Dili Asia/Dubai
Asia/Dushanbe Asia/Gaza Asia/Harbin Asia/Hebron Asia/Ho_Chi_Minh
Asia/Hong_Kong Asia/Hovd Asia/Irkutsk Asia/Istanbul Asia/Jakarta
Asia/Jayapura Asia/Jerusalem Asia/Kabul Asia/Kamchatka Asia/Karachi
Asia/Kashgar Asia/Kathmandu Asia/Katmandu Asia/Kolkata Asia/Krasnoyarsk
Asia/Kuala_Lumpur Asia/Kuching Asia/Kuwait Asia/Macao Asia/Macau
Asia/Magadan Asia/Makassar Asia/Manila Asia/Muscat Asia/Nicosia
Asia/Novokuznetsk Asia/Novosibirsk Asia/Omsk Asia/Oral Asia/Phnom_Penh
Asia/Pontianak Asia/Pyongyang Asia/Qatar Asia/Qyzylorda Asia/Rangoon
Asia/Riyadh Asia/Saigon Asia/Sakhalin Asia/Samarkand Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tashkent Asia/Tbilisi
Asia/Tehran Asia/Tel_Aviv Asia/Thimbu Asia/Thimphu Asia/Tokyo
Asia/Ujung_Pandang Asia/Ulaanbaatar Asia/Ulan_Bator Asia/Urumqi Asia/Vientiane
Asia/Vladivostok Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan  

大西洋

大西洋
Atlantic/Azores Atlantic/Bermuda Atlantic/Canary Atlantic/Cape_Verde Atlantic/Faeroe
Atlantic/Faroe Atlantic/Jan_Mayen Atlantic/Madeira Atlantic/Reykjavik Atlantic/South_Georgia
Atlantic/St_Helena Atlantic/Stanley      

オーストラリア

オーストラリア
Australia/ACT Australia/Adelaide Australia/Brisbane Australia/Broken_Hill Australia/Canberra
Australia/Currie Australia/Darwin Australia/Eucla Australia/Hobart Australia/LHI
Australia/Lindeman Australia/Lord_Howe Australia/Melbourne Australia/North Australia/NSW
Australia/Perth Australia/Queensland Australia/South Australia/Sydney Australia/Tasmania
Australia/Victoria Australia/West Australia/Yancowinna    

ヨーロッパ

ヨーロッパ
Europe/Amsterdam Europe/Andorra Europe/Athens Europe/Belfast Europe/Belgrade
Europe/Berlin Europe/Bratislava Europe/Brussels Europe/Bucharest Europe/Budapest
Europe/Chisinau Europe/Copenhagen Europe/Dublin Europe/Gibraltar Europe/Guernsey
Europe/Helsinki Europe/Isle_of_Man Europe/Istanbul Europe/Jersey Europe/Kaliningrad
Europe/Kiev Europe/Lisbon Europe/Ljubljana Europe/London Europe/Luxembourg
Europe/Madrid Europe/Malta Europe/Mariehamn Europe/Minsk Europe/Monaco
Europe/Moscow Europe/Nicosia Europe/Oslo Europe/Paris Europe/Podgorica
Europe/Prague Europe/Riga Europe/Rome Europe/Samara Europe/San_Marino
Europe/Sarajevo Europe/Simferopol Europe/Skopje Europe/Sofia Europe/Stockholm
Europe/Tallinn Europe/Tirane Europe/Tiraspol Europe/Uzhgorod Europe/Vaduz
Europe/Vatican Europe/Vienna Europe/Vilnius Europe/Volgograd Europe/Warsaw
Europe/Zagreb Europe/Zaporozhye Europe/Zurich    

インド

インド
Indian/Antananarivo Indian/Chagos Indian/Christmas Indian/Cocos Indian/Comoro
Indian/Kerguelen Indian/Mahe Indian/Maldives Indian/Mauritius Indian/Mayotte
Indian/Reunion        

太平洋

太平洋
Pacific/Apia Pacific/Auckland Pacific/Chatham Pacific/Chuuk Pacific/Easter
Pacific/Efate Pacific/Enderbury Pacific/Fakaofo Pacific/Fiji Pacific/Funafuti
Pacific/Galapagos Pacific/Gambier Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu
Pacific/Johnston Pacific/Kiritimati Pacific/Kosrae Pacific/Kwajalein Pacific/Majuro
Pacific/Marquesas Pacific/Midway Pacific/Nauru Pacific/Niue Pacific/Norfolk
Pacific/Noumea Pacific/Pago_Pago Pacific/Palau Pacific/Pitcairn Pacific/Pohnpei
Pacific/Ponape Pacific/Port_Moresby Pacific/Rarotonga Pacific/Saipan Pacific/Samoa
Pacific/Tahiti Pacific/Tarawa Pacific/Tongatapu Pacific/Truk Pacific/Wake
Pacific/Wallis Pacific/Yap      

その他

その他
Brazil/Acre Brazil/DeNoronha Brazil/East Brazil/West Canada/Atlantic
Canada/Central Canada/East-Saskatchewan Canada/Eastern Canada/Mountain Canada/Newfoundland
Canada/Pacific Canada/Saskatchewan Canada/Yukon CET Chile/Continental
Chile/EasterIsland CST6CDT Cuba EET Egypt
Eire EST EST5EDT Etc/GMT Etc/GMT+0
Etc/GMT+1 Etc/GMT+10 Etc/GMT+11 Etc/GMT+12 Etc/GMT+2
Etc/GMT+3 Etc/GMT+4 Etc/GMT+5 Etc/GMT+6 Etc/GMT+7
Etc/GMT+8 Etc/GMT+9 Etc/GMT-0 Etc/GMT-1 Etc/GMT-10
Etc/GMT-11 Etc/GMT-12 Etc/GMT-13 Etc/GMT-14 Etc/GMT-2
Etc/GMT-3 Etc/GMT-4 Etc/GMT-5 Etc/GMT-6 Etc/GMT-7
Etc/GMT-8 Etc/GMT-9 Etc/GMT0 Etc/Greenwich Etc/UCT
Etc/Universal Etc/UTC Etc/Zulu Factory GB
GB-Eire GMT GMT+0 GMT-0 GMT0
Greenwich Hongkong HST Iceland Iran
Israel Jamaica Japan Kwajalein Libya
MET Mexico/BajaNorte Mexico/BajaSur Mexico/General MST
MST7MDT Navajo NZ NZ-CHAT Poland
Portugal PRC PST8PDT ROC ROK
Singapore Turkey UCT Universal US/Alaska
US/Aleutian US/Arizona US/Central US/East-Indiana US/Eastern
US/Hawaii US/Indiana-Starke US/Michigan US/Mountain US/Pacific
US/Pacific-New US/Samoa UTC W-SU WET
Zulu        
警告

ここに挙げられているタイムゾーン (UTC 以外のもの) は使用しないでください。 これらは過去のバージョンとの互換性のためにのみ残されています。

コマンドライン関連

Ncurses 端末画面制御

導入

ncurses (new curses) は、System V Rel 4.0(及びそれ以前)の curses の フリーなソフトウエアエミュレーションです。ncurses は terminfo 型式を 使用し、パッド、カラー、複数のハイライト、フォーム文字、 ファンクションキーマッピングをサポートします。 このライブラリは対話的なものであるため、 Web アプリケーションを作成する際にはほとんど使用されませんが、 コマンドラインから PHP を使用 するスクリプトを書く際には有用です。

使用できる機能、たとえば色などは、使用している端末に依存します。 ncurses_has_colors() や ncurses_can_change_color()、 ncurses_has_ic() といった関数でこれらの機能について調べることができます。

注意:

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 5.3.0.

ncurses は以下のプラットフォームで利用可能です。

  • AIX
  • BeOS
  • BSD 系 (FreeBSD, NetBSD, OpenBSD)
  • Cygwin
  • Digital Unix (aka OSF1)
  • GNU/Linux
  • HPUX
  • IRIX64
  • Mac OS X
  • OS/2
  • QNX
  • SCO OpenServer
  • Solaris
  • Tru64

インストール/設定

目次

要件

ncurses ライブラリおよびヘッダファイルが必要です。最新のバージョンを » ftp://ftp.gnu.org/pub/gnu/ncurses/ あるいは他の GNU ミラーサイトからダウンロードしてください。

インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/ncurses.

ワイドキャラクタ CRT 画面処理 (ncursesw) のサポートは、PECL 拡張モジュールのバージョン 1.0.1 で追加されました。

実行時設定

設定ディレクティブは定義されていません。

リソース型

この拡張モジュールではウィンドウ、パネルおよびパッドリソースを定義しています。

定義済み定数

目次

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

エラーコード

エラー時に、ncurese 関数は -1 を返します。 関数によっては、成功した場合に 0 を返すものがあります。 実際の返り値については、ドキュメントの対応するページを参照ください。

カラー

ncurses カラー定数
定数 意味
NCURSES_COLOR_BLACK 色なし(黒)
NCURSES_COLOR_WHITE 白
NCURSES_COLOR_RED 赤 - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_GREEN 緑 - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_YELLOW 黄 - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_BLUE 青 - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_CYAN シアン - 端末がカラーモードの場合のみサポート
NCURSES_COLOR_MAGENTA マゼンタ - 端末がカラーモードの場合のみサポート

キー

ncurses キー定数
定数 意味
NCURSES_KEY_F0 - NCURSES_KEY_F64 ファンクションキー F1 - F64
NCURSES_KEY_DOWN 下矢印
NCURSES_KEY_UP 上矢印
NCURSES_KEY_LEFT 左矢印
NCURSES_KEY_RIGHT 右矢印
NCURSES_KEY_HOME ホームキー(upward+左矢印)
NCURSES_KEY_BACKSPACE バックスペース
NCURSES_KEY_DL 行削除
NCURSES_KEY_IL 行挿入
NCURSES_KEY_DC 文字削除
NCURSES_KEY_IC 文字挿入あるいは挿入モード移行
NCURSES_KEY_EIC 文字挿入モード終了
NCURSES_KEY_CLEAR 画面消去
NCURSES_KEY_EOS 画面最下部までを消去
NCURSES_KEY_EOL 行末までを消去
NCURSES_KEY_SF 1 行スクロール
NCURSES_KEY_SR 1 行逆スクロール
NCURSES_KEY_NPAGE 次ページ
NCURSES_KEY_PPAGE 前ページ
NCURSES_KEY_STAB タブ
NCURSES_KEY_CTAB タブ消去
NCURSES_KEY_CATAB 全タブ消去
NCURSES_KEY_SRESET ソフト(部分)リセット
NCURSES_KEY_RESET リセットあるいはハードリセット
NCURSES_KEY_PRINT 印刷
NCURSES_KEY_LL 左下
NCURSES_KEY_A1 キーパッドの左上
NCURSES_KEY_A3 キーパッドの右上
NCURSES_KEY_B2 キーパッドの中央
NCURSES_KEY_C1 キーパッドの左下
NCURSES_KEY_C3 キーパッドの右下
NCURSES_KEY_BTAB バックタブ
NCURSES_KEY_BEG 先頭
NCURSES_KEY_CANCEL キャンセル
NCURSES_KEY_CLOSE 閉じる
NCURSES_KEY_COMMAND cmd (コマンド)
NCURSES_KEY_COPY コピー
NCURSES_KEY_CREATE 作成
NCURSES_KEY_END 行末
NCURSES_KEY_EXIT 終了
NCURSES_KEY_FIND 検索
NCURSES_KEY_HELP ヘルプ
NCURSES_KEY_MARK マーク
NCURSES_KEY_MESSAGE メッセージ
NCURSES_KEY_MOVE 移動
NCURSES_KEY_NEXT 次
NCURSES_KEY_OPEN オープン
NCURSES_KEY_OPTIONS オプション
NCURSES_KEY_PREVIOUS 前
NCURSES_KEY_REDO やり直し
NCURSES_KEY_REFERENCE ref (参照)
NCURSES_KEY_REFRESH リフレッシュ
NCURSES_KEY_REPLACE 置換
NCURSES_KEY_RESTART 再起動
NCURSES_KEY_RESUME 再開
NCURSES_KEY_SAVE 保存
NCURSES_KEY_SBEG shiftet beg (beginning)
NCURSES_KEY_SCANCEL shift + キャンセル
NCURSES_KEY_SCOMMAND shift + command
NCURSES_KEY_SCOPY shift + コピー
NCURSES_KEY_SCREATE shift + create
NCURSES_KEY_SDC shift + 文字削除
NCURSES_KEY_SDL shift + 行削除
NCURSES_KEY_SELECT 選択
NCURSES_KEY_SEND shift + end
NCURSES_KEY_SEOL shift + 行末
NCURSES_KEY_SEXIT shift + exit
NCURSES_KEY_SFIND shift + 検索
NCURSES_KEY_SHELP shift + ヘルプ
NCURSES_KEY_SHOME shift + ホーム
NCURSES_KEY_SIC shift + input
NCURSES_KEY_SLEFT shift + 左矢印
NCURSES_KEY_SMESSAGE shift + メッセージ
NCURSES_KEY_SMOVE shift + 移動
NCURSES_KEY_SNEXT shift + 次
NCURSES_KEY_SOPTIONS shift + オプション
NCURSES_KEY_SPREVIOUS shift + 前
NCURSES_KEY_SPRINT shift + 印刷
NCURSES_KEY_SREDO shift + やり直し
NCURSES_KEY_SREPLACE shift + 置換
NCURSES_KEY_SRIGHT shift + 右矢印
NCURSES_KEY_SRSUME shift + 再開
NCURSES_KEY_SSAVE shift + 保存
NCURSES_KEY_SSUSPEND shift + サスペンド
NCURSES_KEY_UNDO 元に戻す
NCURSES_KEY_MOUSE マウスイベントが発生
NCURSES_KEY_MAX 最大のキーの値

マウス

マウス定数
定数 意味
NCURSES_BUTTON1_RELEASED - NCURSES_BUTTON4_RELEASED ボタン (1-4) が離された
NCURSES_BUTTON1_PRESSED - NCURSES_BUTTON4_PRESSED ボタン (1-4) が押された
NCURSES_BUTTON1_CLICKED - NCURSES_BUTTON4_CLICKED ボタン (1-4) がクリックされた
NCURSES_BUTTON1_DOUBLE_CLICKED - NCURSES_BUTTON4_DOUBLE_CLICKED ボタン (1-4) がダブルクリックされた
NCURSES_BUTTON1_TRIPLE_CLICKED - NCURSES_BUTTON4_TRIPLE_CLICKED ボタン (1-4) がトリプルクリックされた
NCURSES_BUTTON_CTRL クリック中に ctrl が押された
NCURSES_BUTTON_SHIFT クリック中に shift が押された
NCURSES_BUTTON_ALT クリック中に alt が押された
NCURSES_ALL_MOUSE_EVENTS すべてのマウスイベントを報告する
NCURSES_REPORT_MOUSE_POSITION マウスの位置を報告する

Ncurses 関数

ncurses_addch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addch — 現在の位置に文字を追加し、カーソルを進める

説明

int ncurses_addch ( int $ch )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ch

ncurses_addchnstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addchnstr — 現在の位置に指定した長さの属性付き文字列を追加する

説明

int ncurses_addchnstr ( string $s , int $n )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

n

ncurses_addchstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addchstr — 現在の位置に属性付き文字列を追加する

説明

int ncurses_addchstr ( string $s )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

ncurses_addnstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addnstr — 現在の位置に、指定した長さの文字列を追加する

説明

int ncurses_addnstr ( string $s , int $n )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

s

n

ncurses_addstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_addstr — 現在の位置にテキストを出力する

説明

int ncurses_addstr ( string $text )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

ncurses_assume_default_colors

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_assume_default_colors — カラー 0 のデフォルト色を定義する

説明

int ncurses_assume_default_colors ( int $fg , int $bg )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fg

bg

ncurses_attroff

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_attroff — 指定した属性を無効とする

説明

int ncurses_attroff ( int $attributes )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attributes

ncurses_attron

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_attron — 指定した属性を有効にする

説明

int ncurses_attron ( int $attributes )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attributes

ncurses_attrset

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_attrset — 指定した属性を設定する

説明

int ncurses_attrset ( int $attributes )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attributes

ncurses_baudrate

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_baudrate — 端末のボーレートを返す

説明

int ncurses_baudrate ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_beep

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_beep — 端末のビープを鳴らす

説明

int ncurses_beep ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_beep() は、耳に聞こえる警告(ベル) を送信ます。送信できなかった場合は画面をフラッシュします。

参考

  • ncurses_flash() - 端末画面をフラッシュする(ビジュアルベル)

ncurses_bkgd

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_bkgd — 端末画面の背景属性を設定する

説明

int ncurses_bkgd ( int $attrchar )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attrchar

ncurses_bkgdset

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_bkgdset — 画面背景を制御する

説明

void ncurses_bkgdset ( int $attrchar )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

attrchar

ncurses_border

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_border — 属性付きの文字で画面周囲に境界を描画する

説明

int ncurses_border ( int $left , int $right , int $top , int $bottom , int $tl_corner , int $tr_corner , int $bl_corner , int $br_corner )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

指定した線と角を、メインウィンドウの周りに描画します。

サブウィンドウの周りに境界を描画するには ncurses_wborder() を使用してください!

パラメータ

各パラメータに 0 を指定すると描画を行い、1 を指定すると描画しません。

left

right

top

bottom

tl_corner

左上隅。

tr_corner

右上隅。

bl_corner

左下隅。

br_corner

右下隅。

参考

  • ncurses_wborder() - 属性文字を使用してウィンドウの周囲に線を描画する

ncurses_bottom_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_bottom_panel — パネルをスタックの最下部に移動する

説明

int ncurses_bottom_panel ( resource $panel )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

ncurses_can_change_color

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_can_change_color — 端末の色を変更可能かどうか確認する

説明

bool ncurses_can_change_color ( void )

端末が色を扱えるかどうか、そしてプログラマが ncurses_init_color() で色を変更できるかどうかを返します。 この関数をコールする前に、ncurses を ncurses_init() で初期化しておく必要があります。

パラメータ

この関数にはパラメータはありません。

返り値

プログラマが色定義を変更できる場合に TRUE、それ以外の場合に FALSE を返します。

参考

ncurses_cbreak

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_cbreak — 入力のバッファリングを変更する

説明

bool ncurses_cbreak ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_cbreak() は、行のバッファリングと 文字の処理(文字が影響を受けない割り込みやフロー制御)を無効にし、 ユーザーが入力した文字をすぐにプログラムに渡します。

返り値

TRUE を返します。エラーが発生した場合は NCURSES_ERR を返します。

参考

ncurses_clear

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_clear — スクリーンをクリアする

説明

bool ncurses_clear ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

空白を設定せず 完全に画面を消去します。

注意: ncurses_clear() は空白を設定せずに 画面を消去します。つまり、現在の背景の状態が残されるということです。 空白文字で画面を消去するには ncurses_erase() を使用します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

ncurses_clrtobot

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_clrtobot — 現在位置から最下部までスクリーンをクリアする

説明

bool ncurses_clrtobot ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_clrtobot() は、カーソル位置から 画面の最下部までのすべての行を消去し、空白で埋めます。 ncurses_clrtobot() で作成される空白には 現在の背景設定が使用されます。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

ncurses_clrtoeol

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_clrtoeol — 現在位置から行末までスクリーンをクリアする

説明

bool ncurses_clrtoeol ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_clrtoeol() は、カーソル位置から 行末までを消去し、空白で埋めます。 ncurses_clrtoeol() で作成される空白には 現在の背景設定が使用されます。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

ncurses_color_content

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_color_content — 色の RGB 値を取得する

説明

int ncurses_color_content ( int $color , int &$r , int &$g , int &$b )

指定した色定義から赤、緑、青の各コンポーネントを取得します。 この関数をコールする前に、端末の色機能を ncurses_start_color() で初期化しておく必要があります。

パラメータ

color

情報を取得したい色の番号。定義済みの色定数のいずれかとなるでしょう。

r

赤コンポーネントの値への参照。 返される値は 0 から 1000 までの値となります。

g

緑コンポーネントの値への参照。 返される値は 0 から 1000 までの値となります。

b

青コンポーネントの値への参照。 返される値は 0 から 1000 までの値となります。

返り値

関数が成功した場合は -1、 ncurses や端末の色機能の初期化ができていない場合は 0 を返します。

参考

ncurses_color_set

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_color_set — 前景/背景色を設定する

説明

int ncurses_color_set ( int $pair )

アクティブな前景色と背景色を設定します。 この関数のあとに書いたすべての文字は、指定した色となります。 この関数を使用するには、端末の色がサポートされていてかつ ncurses_start_color() で事前に初期化されている必要があります。

ncurses は、色ペアを使って前景色と背景色の両方を指定します。 色ペアを定義するには ncurses_init_pair() を使用します。

パラメータ

pair

アクティブな色として設定したい、前景色と背景色の色ペア。

返り値

成功した場合に -1、失敗した場合に 0 を返します。

例

例1 指定した色で文字列を画面に書き込む

<?php
ncurses_init();

// 端末が色をサポートしている場合に、初期化してアクティブな色を設定します
if (ncurses_has_colors()) {
    ncurses_start_color();
    ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
    ncurses_color_set(1);
}

// 指定した位置に文字列を書き込みます
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");

// 出力をフラッシュします
ncurses_refresh();

ncurses_end();
?>

参考

ncurses_curs_set

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_curs_set — カーソル状態を設定する

説明

int ncurses_curs_set ( int $visibility )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

visibility

ncurses_def_prog_mode

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_def_prog_mode — 端末(プログラム)モードを保存する

説明

bool ncurses_def_prog_mode ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_reset_prog_mode() で使用するために (curses 内の)プログラムの現在の端末モードを保存します。

返り値

成功した場合に FALSE、それ以外の場合に TRUE を返します。

参考

ncurses_def_shell_mode

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_def_shell_mode — 端末(シェル)モードを保存する

説明

bool ncurses_def_shell_mode ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_reset_shell_mode() で使用するために (curses 内でない)シェルの現在の端末モードを保存します。

返り値

成功した場合に FALSE、それ以外の場合に TRUE を返します。

参考

ncurses_define_key

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_define_key — キーコードを定義する

説明

int ncurses_define_key ( string $definition , int $keycode )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

definition

keycode

ncurses_del_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_del_panel — パネルをスタックから取り除き、削除する (しかし、関連付けられているウィンドウは削除しない)

説明

bool ncurses_del_panel ( resource $panel )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

ncurses_delay_output

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_delay_output — パディング文字を用いて端末出力を遅延させる

説明

int ncurses_delay_output ( int $milliseconds )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

milliseconds

ncurses_delch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_delch — 現在位置の文字を削除し、残った部分を左に移動する

説明

bool ncurses_delch ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

カーソルがある位置の文字を削除します。 同じ行でカーソルの右側にある文字が左側にひとつづつ移動し、 その行の最後の文字があった場所は空白で埋められます。 カーソルの位置は変わりません。

返り値

成功した場合に FALSE、 それ以外の場合に TRUE を返します。

参考

ncurses_deleteln

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_deleteln — 現在位置の行を削除し、残りの部分を上に上げる

説明

bool ncurses_deleteln ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

カーソル位置の行を削除します。 現在の行より下の行は 1 行ずつ上に移動します。 ウィンドウの最下行はクリアされます。カーソルの位置は変わりません。

返り値

成功した場合に FALSE、それ以外の場合に TRUE を返します。

参考

  • ncurses_delch() - 現在位置の文字を削除し、残った部分を左に移動する

ncurses_delwin

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_delwin — ncurses ウインドウを削除する

説明

bool ncurses_delwin ( resource $window )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_doupdate

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_doupdate — 準備中の全ての出力を書き込み、端末をリフレッシュする

説明

bool ncurses_doupdate ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

仮想スクリーンと物理スクリーンを比較し、 物理スクリーンを更新します。リフレッシュを何度もコールするよりも、 この方法のほうが効率的です。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

ncurses_echo

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_echo — キーボード入力のエコーを有効とする

説明

bool ncurses_echo ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

エコーモードを有効にします。 ユーザーがタイプした文字がすべて ncurses_getch() によってエコーされます。

返り値

成功した場合に FALSE、何らかのエラーが発生した場合に TRUE を返します。

参考

  • エコーモードを無効にするには ncurses_noecho() - キーボード入力エコーを無効にする を使用します。

ncurses_echochar

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_echochar — リフレッシュを行いつつ 1 文字出力する

説明

int ncurses_echochar ( int $character )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

character

ncurses_end

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_end — ncurses を終了し、画面を消去する

説明

int ncurses_end ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_erase

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_erase — 端末画面を消去する

説明

bool ncurses_erase ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末の画面を空白で埋めます。

作成された空白の背景処理は、ncurses_bkgd() で設定したものとなります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

ncurses_erasechar

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_erasechar — 現在の erase 文字を返す

説明

string ncurses_erasechar ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の erase 文字を返します。

返り値

現在の erase 文字を文字列で返します。

参考

ncurses_filter

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_filter — iniscr() および newterm() の LINES を 1 に設定する

説明

void ncurses_filter ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_flash

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_flash — 端末画面をフラッシュする(ビジュアルベル)

説明

bool ncurses_flash ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

画面をフラッシュします。 もしそれができなかった場合は、音声の警告(ベル)を送信します。

返り値

成功した場合に FALSE、そうでない場合に TRUE を返します。

参考

ncurses_flushinp

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_flushinp — キーボード入力バッファをフラッシュする

説明

bool ncurses_flushinp ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

タイプされた内容のうち、 まだプログラムで読み込まれていないものををすべて捨てます。

返り値

成功した場合に FALSE、それ以外の場合に TRUE を返します。

ncurses_getch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_getch — キーボードから 1 文字読み込む

説明

int ncurses_getch ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_getmaxyx

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_getmaxyx — ウィンドウの大きさを返す

説明

void ncurses_getmaxyx ( resource $window , int &$y , int &$x )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

指定したウィンドウ window の水平方向・垂直方向の大きさを取得します。

変数は参照渡しとする必要があり、 ユーザーが端末の大きさを変更した際にこの変数が更新されます。

パラメータ

window

調べるウィンドウ。

y

ウィンドウの高さが設定されます。

x

ウィンドウの幅が設定されます。

返り値

値を返しません。

ncurses_getmouse

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_getmouse — マウスイベントを読みこむ

説明

bool ncurses_getmouse ( array &$mevent )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_getmouse() は、 キューからマウスイベントを読み込みます。

パラメータ

mevent

イベントのオプションを指定します。 これは配列への参照として渡されます(以下の例を参照ください)。

成功した場合、以下のキーを持つ連想配列が返されます。

  • "id" : 複数デバイスを識別する ID。

  • "x" : 画面上の相対的な x 位置(文字単位)。

  • "y" : 画面上の相対的な y 位置(文字単位)。

  • "z" : 現在はサポートされていません。

  • "mmask" : マウスアクション。

返り値

指定したウィンドウでマウスイベントが実際に見える場合に FALSE、そうでない場合に TRUE を返します。

例

例1 ncurses_getmouse() の例

<?php
switch (ncurses_getch()){
  case NCURSES_KEY_MOUSE:
    if (!ncurses_getmouse($mevent)){
      if ($mevent["mmask"] & NCURSES_MOUSE_BUTTON1_PRESSED){
        $mouse_x = $mevent["x"]; // マウスの位置を保存します
        $mouse_y = $mevent["y"];
      }
    }
  break;

  default:
    /* .... */
}
?>

参考

ncurses_getyx

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_getyx — ウィンドウ内の現在のカーソル位置を返す

説明

void ncurses_getyx ( resource $window , int &$y , int &$x )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

y

x

ncurses_halfdelay

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_halfdelay — 端末をハーフディレイモードにする

説明

int ncurses_halfdelay ( int $tenth )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

tenth

ncurses_has_colors

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_has_colors — カラー端末かどうか確認する

説明

bool ncurses_has_colors ( void )

端末がカラー表示機能を持つかどうかを調べます。 この関数を使用すると、端末に依存しないプログラムを書くことができます。 この関数をコールする前に、 ncurses_init() で ncurses を初期化しておく必要があります。

パラメータ

この関数にはパラメータはありません。

返り値

端末がカラー表示機能を持っている場合に TRUE、持っていない場合に FALSE を返します。

例

例1 指定した色で文字列を画面に書き込む

<?php
ncurses_init();

// 端末が色をサポートしている場合に、初期化してアクティブな色を設定します
if (ncurses_has_colors()) {
    ncurses_start_color();
    ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
    ncurses_color_set(1);
}

// 指定した位置に文字列を書き込みます
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");

// 出力をフラッシュします
ncurses_refresh();

ncurses_end();
?>

参考

ncurses_has_ic

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_has_ic — 挿入/削除機能の有無を確認する

説明

bool ncurses_has_ic ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末が挿入/削除機能を持つかどうかを調べます。

返り値

端末が挿入/削除機能を持つ場合に TRUE、それ以外の場合に FALSE を返します。

参考

ncurses_has_il

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_has_il — 行挿入/削除機能の有無を確認する

説明

bool ncurses_has_il ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末が行挿入/削除機能を持つかどうかを調べます。

返り値

端末が行挿入/削除機能を持つ場合に TRUE、それ以外の場合に FALSE を返します。

参考

ncurses_has_key

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_has_key — 端末キーボードにおいてファンクションキーの有無を調べる

説明

int ncurses_has_key ( int $keycode )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

keycode

ncurses_hide_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_hide_panel — パネルをスタックから取り除き、見えなくする

説明

int ncurses_hide_panel ( resource $panel )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

ncurses_hline

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_hline — 現在位置に属性付きの文字を用いて最大 n 文字長の線を水平に描画する

説明

int ncurses_hline ( int $charattr , int $n )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

charattr

n

ncurses_inch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_inch — 現在位置の文字と属性を取得する

説明

string ncurses_inch ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在位置の文字を返します。

返り値

文字を返します。

ncurses_init_color

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_init_color — 端末の色を定義する

説明

int ncurses_init_color ( int $color , int $r , int $g , int $b )

指定した色を定義/再定義します。この関数がコールされると、 画面上に存在するその色の部分が即時に新しい定義に変わります。

色機能が端末でサポートされており、かつこの関数をコールする前に ncurses_start_color() で初期化されている必要があります。 さらに、端末が色の変更機能を持っている必要があります。これを調べるには ncurses_can_change_color() を使用します。

パラメータ

color

再定義したい色の番号。定義済みの色定数のいずれかとなるでしょう。

r

赤コンポーネントの値。 0 から 1000 までの値となります。

g

緑コンポーネントの値。 0 から 1000 までの値となります。

b

青コンポーネントの値。 0 から 1000 までの値となります。

返り値

関数が成功した場合は -1、 ncurses や端末の色機能の初期化ができていない場合、 端末に色の変更機能がない場合は 0 を返します。

参考

ncurses_init_pair

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_init_pair — 色ペアを定義する

説明

int ncurses_init_pair ( int $pair , int $fg , int $bg )

前景色と背景色の色ペアを定義/再定義します。 色ペアが事前に初期化されている場合は、 画面が再描画されて即時に新しい定義が反映されます。

この関数をコールする前に、 ncurses_start_color() で色機能を初期化しておく必要があります。 最初の色ペア (色ペア 0) はデフォルトで黒地に白となっていますが、 ncurses_assume_default_colors() で変更することも可能です。

パラメータ

pair

定義したい色ペアの番号。

fg

色ペアの前景色。 定義済みの色 のいずれか、あるいは端末に色変更機能がある場合に ncurses_init_color() で定義したものとなります。

bg

色ペアの背景色。 定義済みの色 のいずれか、あるいは端末に色変更機能がある場合に ncurses_init_color() で定義したものとなります。

返り値

関数が成功した場合は -1、 ncurses や端末の色機能の初期化ができていない場合は 0 を返します。

注意

既存の色で色ペアを定義する際には、色の変更機能は不要であることに注意しましょう。 この機能が必要となるのは、色自体の定義 (赤、緑、青コンポーネント) を ncurses_init_color() で変更したい場合です。

例

例1 指定した色で文字列を画面に書き込む

<?php
ncurses_init();

// 端末が色をサポートしている場合に、初期化してアクティブな色を設定します
if (ncurses_has_colors()) {
    ncurses_start_color();
    ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
    ncurses_color_set(1);
}

// 指定した位置に文字列を書き込みます
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");

// 出力をフラッシュします
ncurses_refresh();

ncurses_end();
?>

参考

ncurses_init

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_init — ncurses を初期化する

説明

void ncurses_init ( void )

ncurses インターフェイスを初期化します。 必ず、その他の ncurses 関数の前に使用する必要があります。

プログラムを終了する前に、必ず ncurses_end() をコールしなければならないことに注意しましょう。 そうしないと、端末を適切な非ビジュアルモードに戻すことができません。

パラメータ

この関数にはパラメータはありません。

返り値

値を返しません。

参考

ncurses_insch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_insch — 文字を挿入し、現在位置にある文字を含む残りの行を移動する

説明

int ncurses_insch ( int $character )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

character

ncurses_insdelln

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_insdelln — 現在の行の後に複数の行を挿入し、スクロールダウンする (負の数を指定すると削除し、スクロールアップする)

説明

int ncurses_insdelln ( int $count )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

count

ncurses_insertln

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_insertln — 行を挿入し、残りの部分をスクロールダウンする

説明

int ncurses_insertln ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の行の上に新しい行を挿入します。いちばん下の行は失われます。

ncurses_insstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_insstr — 現在位置に文字列を挿入し、残りの行を右に移動する

説明

int ncurses_insstr ( string $text )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

ncurses_instr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_instr — 端末画面から文字列を読み込む

説明

int ncurses_instr ( string &$buffer )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の位置から行末までを読み込み、その文字数を返します。

パラメータ

buffer

読み込んだ文字列。文字の属性は削除されます。

返り値

文字の数を返します。

ncurses_isendwin

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_isendwin — Ncurses が endwin モードの場合、通常の画面出力が実行可能

説明

bool ncurses_isendwin ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses が endwin モードであるかどうかを調べます。

返り値

ncurses_end() がコールされた後に 続けて ncurses_wrefresh() がコールされていない場合に TRUE、それ以外の場合に FALSE を返します。

参考

ncurses_keyok

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_keyok — キーコードを有効または無効にする

説明

int ncurses_keyok ( int $keycode , bool $enable )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

keycode

enable

ncurses_keypad

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_keypad — キーパッドを on あるいは off にする

説明

int ncurses_keypad ( resource $window , bool $bf )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

bf

ncurses_killchar

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_killchar — 現在の行削除文字を返す

説明

string ncurses_killchar ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の行削除文字を返します。

返り値

現在の行削除文字を返します。

参考

ncurses_longname

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_longname — 端末の説明を返す

説明

string ncurses_longname ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末の詳細な説明を返します。

返り値

端末の詳細な説明を返します。 説明は、最大 128 文字までで切り詰められます。 エラー時には NULL を返します。

参考

ncurses_meta

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_meta — 8 ビットのメタキー情報を有効/無効にする

説明

int ncurses_meta ( resource $window , bool $8bit )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

8bit

ncurses_mouse_trafo

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mouse_trafo — 座標を変換する

説明

bool ncurses_mouse_trafo ( int &$y , int &$x , bool $toscreen )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

toscreen

ncurses_mouseinterval

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mouseinterval — マウスボタンクリックのタイムアウトを設定する

説明

int ncurses_mouseinterval ( int $milliseconds )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

milliseconds

ncurses_mousemask

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mousemask — マウスオプションを設定する

説明

int ncurses_mousemask ( int $newmask , int &$oldmask )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

報告されるマウスイベントを設定します。デフォルトでは、 どのマウスイベントについても報告されません。

マウスイベントは、ncurses_wgetch() 入力ストリーム内では NCURSES_KEY_MOUSE で表されます。 イベントデータを読み込んでキューからイベントを取り出すには、 ncurses_getmouse() をコールします。

パラメータ

newmask

マウスマスクオプションには、以下の定義済み定数が指定可能です。

  • NCURSES_BUTTON1_PRESSED

  • NCURSES_BUTTON1_RELEASED

  • NCURSES_BUTTON1_CLICKED

  • NCURSES_BUTTON1_DOUBLE_CLICKED

  • NCURSES_BUTTON1_TRIPLE_CLICKED

  • NCURSES_BUTTON2_PRESSED

  • NCURSES_BUTTON2_RELEASED

  • NCURSES_BUTTON2_CLICKED

  • NCURSES_BUTTON2_DOUBLE_CLICKED

  • NCURSES_BUTTON2_TRIPLE_CLICKED

  • NCURSES_BUTTON3_PRESSED

  • NCURSES_BUTTON3_RELEASED

  • NCURSES_BUTTON3_CLICKED

  • NCURSES_BUTTON3_DOUBLE_CLICKED

  • NCURSES_BUTTON3_TRIPLE_CLICKED

  • NCURSES_BUTTON4_PRESSED

  • NCURSES_BUTTON4_RELEASED

  • NCURSES_BUTTON4_CLICKED

  • NCURSES_BUTTON4_DOUBLE_CLICKED

  • NCURSES_BUTTON4_TRIPLE_CLICKED

  • NCURSES_BUTTON_SHIFT>

  • NCURSES_BUTTON_CTRL

  • NCURSES_BUTTON_ALT

  • NCURSES_ALL_MOUSE_EVENTS

  • NCURSES_REPORT_MOUSE_POSITION

副作用として、newmask にゼロを設定すると マウスポインタを消去します。ゼロ以外の値を設定すると マウスポインタが表示されます。

oldmask

以前のマウスイベントマスクの値が設定されます。

返り値

newmask が指定するイベントを報告することが できるマスクを返します。失敗した場合は 0 を返します。

例

例1 ncurses_mousemask() の例

<?php
$newmask = NCURSES_BUTTON1_CLICKED + NCURSES_BUTTON1_RELEASED;
$mask = ncurses_mousemask($newmask, $oldmask);
if ($mask & $newmask){
    printf("All specified mouse options will be supported\n");
}
?>

参考

ncurses_move_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_move_panel — 左上が [startx, starty] となるようにパネルを移動する

説明

int ncurses_move_panel ( resource $panel , int $startx , int $starty )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

startx

starty

ncurses_move

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_move — 出力位置を移動する

説明

int ncurses_move ( int $y , int $x )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

ncurses_mvaddch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddch — 現在位置を移動し、文字を追加する

説明

int ncurses_mvaddch ( int $y , int $x , int $c )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

c

ncurses_mvaddchnstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddchnstr — 位置を移動し、指定長の属性付きの文字列を追加する

説明

int ncurses_mvaddchnstr ( int $y , int $x , string $s , int $n )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

s

n

ncurses_mvaddchstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddchstr — 位置を移動し、属性付きの文字列を追加する

説明

int ncurses_mvaddchstr ( int $y , int $x , string $s )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

s

ncurses_mvaddnstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddnstr — 位置を移動し、指定長の文字列を追加する

説明

int ncurses_mvaddnstr ( int $y , int $x , string $s , int $n )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

s

n

ncurses_mvaddstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvaddstr — 位置を移動し、文字列を追加する

説明

int ncurses_mvaddstr ( int $y , int $x , string $s )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

s

ncurses_mvcur

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvcur — 直ちにカーソルを移動する

説明

int ncurses_mvcur ( int $old_y , int $old_x , int $new_y , int $new_x )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

old_y

old_x

new_y

new_x

ncurses_mvdelch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvdelch — 位置を移動し、文字を削除、行の残りを左シフトする

説明

int ncurses_mvdelch ( int $y , int $x )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

ncurses_mvgetch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvgetch — 位置を移動し、新しい位置で文字を得る

説明

int ncurses_mvgetch ( int $y , int $x )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

ncurses_mvhline

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvhline — 位置を新しく設定し、属性付きの文字を用いて最大n文字の水平線を描画

説明

int ncurses_mvhline ( int $y , int $x , int $attrchar , int $n )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

attrchar

n

ncurses_mvinch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvinch — 位置を移動し、新しい位置の属性付きの文字を取得する

説明

int ncurses_mvinch ( int $y , int $x )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

ncurses_mvvline

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvvline — 位置を新しく設定し、属性付きの文字を用いて最大 n 文字の垂直線を描画する

説明

int ncurses_mvvline ( int $y , int $x , int $attrchar , int $n )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

y

x

attrchar

n

ncurses_mvwaddstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_mvwaddstr — ウインドウの新規位置に文字列を追加する

説明

int ncurses_mvwaddstr ( resource $window , int $y , int $x , string $text )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

y

x

text

ncurses_napms

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_napms — スリープ

説明

int ncurses_napms ( int $milliseconds )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

milliseconds

ncurses_new_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_new_panel — 新しいパネルを作成し、それをウィンドウに関連づける

説明

resource ncurses_new_panel ( resource $window )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_newpad

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_newpad — 新しいパッド (window) を作成する

説明

resource ncurses_newpad ( int $rows , int $cols )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

rows

cols

ncurses_newwin

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_newwin — 新規ウインドウを作成する

説明

resource ncurses_newwin ( int $rows , int $cols , int $y , int $x )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

描画要素を入れるための新しいウィンドウを作成します。

端末の大きさはそれぞれ異なりいろいろな値をとる可能性があるので、 ウィンドウを追加する際には ncurses_getmaxyx() を使用して使用可能な領域を調べることを忘れないようにしましょう。

パラメータ

rows

行の数。

cols

列の数。

y

原点の y 座標。

x

原点の x 座標。

返り値

新しいウィンドウのリソース ID を返します。

ncurses_nl

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_nl — 改行と復改/ラインフィードを変換する

説明

bool ncurses_nl ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_nocbreak

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_nocbreak — 端末を cooked モードに変更する

説明

bool ncurses_nocbreak ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末を通常モード (cooked モード) に戻します。モードが継承されている場合、端末の 書記モードは cbreak モードであったりそうでなかったりするかもしれません。 そのため、プログラムでは ncurses_cbreak() および ncurses_nocbreak() を明示的にコールすべきです。

返り値

何らかのエラーが発生した場合に TRUE、 それ以外の場合に FALSE を返します。

参考

ncurses_noecho

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_noecho — キーボード入力エコーを無効にする

説明

bool ncurses_noecho ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ユーザーが入力した文字のエコーを無効にします。

返り値

何らかのエラーが発生した場合に TRUE、 それ以外の場合に FALSE を返します。

参考

ncurses_nonl

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_nonl — 改行と復改/ラインフィードを変換しない

説明

bool ncurses_nonl ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_noqiflush

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_noqiflush — シグナル文字のフラッシュを無効とする

説明

void ncurses_noqiflush ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_noraw

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_noraw — 端末を raw モード以外に変更する

説明

bool ncurses_noraw ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末を raw モード以外に変更します。row モードは cbreak モードと似ており、 タイプされた文字はすぐにプログラムへ渡されます。違う点は、 raw モードの場合は 中断 (interrupt)、終了 (quit)、停止 (suspend) およびフロー制御文字もそのまま渡され、シグナルは発生しないということです。

返り値

何らかのエラーが発生した場合に TRUE、 それ以外の場合に FALSE を返します。

参考

ncurses_pair_content

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_pair_content — 色ペアの前景色と背景色を取得する

説明

int ncurses_pair_content ( int $pair , int &$f , int &$b )

指定した色ペアの前景色と背景色を取得します。この関数をコールする前に、 ncurses_start_color() で端末の色機能を初期化しておく必要があります。

パラメータ

pair

情報を取得したい色ペアの番号。

f

色ペアの前景色への参照。返される情報は、 定義済みの色 を指す色番号か、端末が色の変更機能をサポートしている場合に ncurses_init_color() で定義した色となります。

b

色ペアの背景色への参照。返される情報は、 定義済みの色 を指す色番号か、端末が色の変更機能をサポートしている場合に ncurses_init_color() で定義した色となります。

返り値

関数が成功した場合は -1、 ncurses や端末の色機能の初期化ができていない場合は 0 を返します。

参考

ncurses_panel_above

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_panel_above — パネルの上のパネルを返す

説明

resource ncurses_panel_above ( resource $panel )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

返り値

パネルが null の場合は、スタックの最下部のパネルを返します。

ncurses_panel_below

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_panel_below — パネルの下のパネルを返す

説明

resource ncurses_panel_below ( resource $panel )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

パラメータ

パネルが null の場合は、スタックの最上部のパネルを返します。

ncurses_panel_window

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_panel_window — パネルに関連付けられたウィンドウを返す

説明

resource ncurses_panel_window ( resource $panel )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

ncurses_pnoutrefresh

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_pnoutrefresh — パッドから仮想画面にリージョンをコピーする

説明

int ncurses_pnoutrefresh ( resource $pad , int $pminrow , int $pmincol , int $sminrow , int $smincol , int $smaxrow , int $smaxcol )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

pad

pminrow

pmincol

sminrow

smincol

smaxrow

smaxcol

ncurses_prefresh

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_prefresh — パッドから仮想画面にリージョンをコピーする

説明

int ncurses_prefresh ( resource $pad , int $pminrow , int $pmincol , int $sminrow , int $smincol , int $smaxrow , int $smaxcol )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

pad

pminrow

pmincol

sminrow

smincol

smaxrow

smaxcol

ncurses_putp

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_putp — パディング情報を文字列に適用し、それを出力する

説明

int ncurses_putp ( string $text )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

ncurses_qiflush

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_qiflush — シグナル文字のフラッシュを有効とする

説明

void ncurses_qiflush ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_raw

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_raw — 端末を raw モードに変更する

説明

bool ncurses_raw ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

端末を raw モードに変更します。row モードは cbreak モードと似ており、 タイプされた文字はすぐにプログラムへ渡されます。違う点は、raw モードの場合は 中断 (interrupt)、終了 (quit)、停止 (suspend) およびフロー制御文字もそのまま渡され、シグナルは発生しないということです。

返り値

何らかのエラーが発生した場合に TRUE、 それ以外の場合に FALSE を返します。

参考

ncurses_refresh

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_refresh — 画面をリフレッシュする

説明

int ncurses_refresh ( int $ch )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

ch

ncurses_replace_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_replace_panel — パネルに関連付けられたウィンドウを置き換える

説明

int ncurses_replace_panel ( resource $panel , resource $window )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

window

ncurses_reset_prog_mode

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_reset_prog_mode — def_prog_mode で保存したプログラムモードをリセットする

説明

int ncurses_reset_prog_mode ( void )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_reset_shell_mode

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_reset_shell_mode — def_shell_mode で保存したシェルモードをリセットする

説明

int ncurses_reset_shell_mode ( void )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_resetty

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_resetty — 保存した端末モードに復帰する

説明

bool ncurses_resetty ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

事前に ncurses_savetty() をコールすることによって保存しておいた端末モードを復元します。

返り値

常に FALSE を返します。

参考

ncurses_savetty

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_savetty — 端末の状態を保存する

説明

bool ncurses_savetty ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在の端末の状態を保存します。 保存された状態は、関数 ncurses_resetty() によって復元することが可能です。

返り値

常に FALSE を返します。

参考

ncurses_scr_dump

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scr_dump — 画面の内容をファイルにダンプする

説明

int ncurses_scr_dump ( string $filename )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

ncurses_scr_init

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scr_init — ファイルダンプから画面を初期化する

説明

int ncurses_scr_init ( string $filename )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

ncurses_scr_restore

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scr_restore — ファイルダンプから画面を復帰する

説明

int ncurses_scr_restore ( string $filename )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

ncurses_scr_set

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scr_set — ファイルダンプから画面を継承する

説明

int ncurses_scr_set ( string $filename )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

filename

ncurses_scrl

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_scrl — 現在位置を変更せずに画面の内容をスクロールアップまたはダウンする

説明

int ncurses_scrl ( int $count )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

count

ncurses_show_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_show_panel — 不可視のパネルをスタックの最上部に置き、見えるようにする

説明

int ncurses_show_panel ( resource $panel )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

ncurses_slk_attr

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_attr — 現在のソフトラベルキー属性を返す

説明

int ncurses_slk_attr ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

現在のソフトラベルキー属性を返します。

返り値

属性を整数値で返します。

ncurses_slk_attroff

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_attroff — ソフトファンクションキーラベルの指定した属性を無効にする

説明

int ncurses_slk_attroff ( int $intarg )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

ncurses_slk_attron

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_attron — ソフトファンクションキーラベルの指定した属性を有効にする

説明

int ncurses_slk_attron ( int $intarg )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

ncurses_slk_attrset

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_attrset — ソフトファンクションキーラベルに、指定した属性を設定する

説明

int ncurses_slk_attrset ( int $intarg )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

ncurses_slk_clear

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_clear — 画面からソフトラベルをクリアする

説明

bool ncurses_slk_clear ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

関数 ncurses_slk_clear() は、 画面からソフトラベルキーを消去します。

返り値

エラー時に TRUE、 それ以外の場合に FALSE を返します。

ncurses_slk_color

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_color — ソフトラベルキーの色を設定する

説明

int ncurses_slk_color ( int $intarg )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

ncurses_slk_init

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_init — ソフトラベルキー関数を初期化する

説明

bool ncurses_slk_init ( int $format )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ソフトラベルキー関数を初期化します。

この関数は、必ず ncurses_init() あるいは ncurses_newwin() がコールされる前にコールする必要があります。

パラメータ

format

ncurses_init() が、 最終的にソフトラベルをエミュレートするために stdscr からの線を使用する場合、 このパラメータで画面上でのラベルの配置方法を指定します。

0 にするとラベルを 3-2-3 形式に配置し、1 にすると 4-4 形式に配置します。 また 2 にすると PC 風の 4-4-4 形式に配置しますが、それに加えて インデックスラインが作成されます。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

ncurses_slk_noutrefresh

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_noutrefresh — 仮想画面にソフトラベルキーをコピーする

説明

bool ncurses_slk_noutrefresh ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_slk_refresh

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_refresh — ソフトラベルキーを画面にコピーする

説明

int ncurses_slk_refresh ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ソフトラベルキーを仮想画面から実際の画面にコピーします。

ncurses_slk_restore

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_restore — ソフトラベルキーを復帰する

説明

int ncurses_slk_restore ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

ncurses_slk_clear() が実行された後に ソフトラベルキーを復元します。

ncurses_slk_set

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_set — ファンクションキーラベルを設定する

説明

bool ncurses_slk_set ( int $labelnr , string $label , int $format )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

labelnr

label

format

ncurses_slk_touch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_slk_touch — ncurses_slk_noutrefresh を実行する際に強制的に出力する

説明

int ncurses_slk_touch ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

次に ncurses_slk_noutrefresh() が実行された際に すべてのソフトラベルを強制的に出力するようにします。

ncurses_standend

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_standend — 'standout' 属性の使用を停止する

説明

int ncurses_standend ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_standout

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_standout — 'standout' 属性の使用を開始する

説明

int ncurses_standout ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_start_color

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_start_color — 色機能を初期化する

説明

int ncurses_start_color ( void )

ncurses の色機能を初期化します。この関数は、 ncurses_init() をコールした後で その他の色操作関数をコールする前に実行する必要があります。 ncurses_init() の直後に実行するのがよいでしょう。

パラメータ

この関数にはパラメータはありません。

返り値

成功した場合に 0、 色テーブルの割り当てに失敗した場合や ncurses が初期化されていない場合に -1 を返します。

例

例1 指定した色で文字列を画面に書き込む

<?php
ncurses_init();

// 端末が色をサポートしている場合に、初期化してアクティブな色を設定します
if (ncurses_has_colors()) {
    ncurses_start_color();
    ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
    ncurses_color_set(1);
}

// 指定した位置に文字列を書き込みます
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");

// 出力をフラッシュします
ncurses_refresh();

ncurses_end();
?>

参考

ncurses_termattrs

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_termattrs — 端末でサポートされる全ての属性フラグの論理和を返す

説明

bool ncurses_termattrs ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_termname

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_termname — 端末の(簡略)名を返す

説明

string ncurses_termname ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

Returns terminals shortname.

返り値

端末の簡略名を返します。 簡略名は最大 14 文字で切り詰められます。エラー時には NULL を返します。

参考

ncurses_timeout

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_timeout — 特別なキーシーケンスのタイムアウトを設定する

説明

void ncurses_timeout ( int $millisec )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

millisec

ncurses_top_panel

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_top_panel — 可視パネルをスタックの最上部に移動する

説明

int ncurses_top_panel ( resource $panel )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

panel

ncurses_typeahead

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_typeahead — typeahead 確認用に別のファイル記述子を指定する

説明

int ncurses_typeahead ( int $fd )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

fd

ncurses_ungetch

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_ungetch — 入力ストリームに 1 文字戻す

説明

int ncurses_ungetch ( int $keycode )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

keycode

ncurses_ungetmouse

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_ungetmouse — マウスイベントをキューにプッシュする

説明

bool ncurses_ungetmouse ( array $mevent )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

キューに KEY_MOUSE イベントをプッシュし、このイベントを、mevent で指定した状態・画面上の位置座標と関連付けます。

パラメータ

mevent

イベントのオプションを指定する連想配列。

  • "id" : 複数デバイスを識別する ID。

  • "x" : 画面上の相対的な x 位置(文字単位)。

  • "y" : 画面上の相対的な y 位置(文字単位)。

  • "z" : 現在はサポートされていません。

  • "mmask" : マウスアクション

返り値

成功した場合に FALSE、それ以外の場合に TRUE を返します。

参考

ncurses_update_panels

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_update_panels — 仮想画面を再描画し、スタック内のパネルとの関係を反映させる

説明

void ncurses_update_panels ( void )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_use_default_colors

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_use_default_colors — 端末のデフォルト色をカラー ID -1 に割り付ける

説明

bool ncurses_use_default_colors ( void )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ncurses_use_env

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_use_env — 端末の大きさに関する環境情報の使用を制御する

説明

void ncurses_use_env ( bool $flag )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

flag

ncurses_use_extended_names

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_use_extended_names — terminfo 記述において拡張名の使用を制御する

説明

int ncurses_use_extended_names ( bool $flag )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

flag

ncurses_vidattr

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_vidattr — video attribute モードで、端末上に文字列を表示する

説明

int ncurses_vidattr ( int $intarg )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

intarg

ncurses_vline

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_vline — 現在位置に最大 n 文字の属性付きの文字を用いて垂直線を描画する

説明

int ncurses_vline ( int $charattr , int $n )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

charattr

n

ncurses_waddch

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_waddch — ウィンドウ内の現在位置に文字を追加し、カーソルを進める

説明

int ncurses_waddch ( resource $window , int $ch )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ch

ncurses_waddstr

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_waddstr — ウィンドウ内の現在位置にテキストを出力する

説明

int ncurses_waddstr ( resource $window , string $str [, int $n ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

str

n

ncurses_wattroff

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wattroff — ウィンドウの属性をオフにする

説明

int ncurses_wattroff ( resource $window , int $attrs )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

attrs

ncurses_wattron

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wattron — ウィンドウの属性をオンにする

説明

int ncurses_wattron ( resource $window , int $attrs )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

attrs

ncurses_wattrset

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wattrset — ウィンドウの属性を設定する

説明

int ncurses_wattrset ( resource $window , int $attrs )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

attrs

ncurses_wborder

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wborder — 属性文字を使用してウィンドウの周囲に線を描画する

説明

int ncurses_wborder ( resource $window , int $left , int $right , int $top , int $bottom , int $tl_corner , int $tr_corner , int $bl_corner , int $br_corner )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

window で指定したウィンドウの周囲を指定した線と角で囲みます。

メインウィンドウの周囲を囲むには、ncurses_border() を使用します。

パラメータ

各パラメータに 0 を渡すとその部分を描画し、1 を渡すと描画しません。

window

操作するウィンドウ。

left

right

top

bottom

tl_corner

左上隅。

tr_corner

右上隅。

bl_corner

左下隅。

br_corner

右下隅。

参考

  • ncurses_border() - 属性付きの文字で画面周囲に境界を描画する

ncurses_wclear

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wclear — ウィンドウをクリアする

説明

int ncurses_wclear ( resource $window )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_wcolor_set

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wcolor_set — ウィンドウの色の組み合わせを設定する

説明

int ncurses_wcolor_set ( resource $window , int $color_pair )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

color_pair

ncurses_werase

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_werase — ウィンドウを消去する

説明

int ncurses_werase ( resource $window )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_wgetch

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wgetch — キーボート (ウィンドウ) から文字を読み込む

説明

int ncurses_wgetch ( resource $window )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_whline

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_whline — 指定した属性文字を用いて、最大 n 文字分の長さの水平線を ウィンドウに描画する

説明

int ncurses_whline ( resource $window , int $charattr , int $n )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

charattr

n

ncurses_wmouse_trafo

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wmouse_trafo — ウィンドウ/標準画面の座標系を変換する

説明

bool ncurses_wmouse_trafo ( resource $window , int &$y , int &$x , bool $toscreen )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

x

y

toscreen

ncurses_wmove

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wmove — ウィンドウの出力位置を移動する

説明

int ncurses_wmove ( resource $window , int $y , int $x )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

y

x

ncurses_wnoutrefresh

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wnoutrefresh — ウィンドウを仮想画面にコピーする

説明

int ncurses_wnoutrefresh ( resource $window )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_wrefresh

(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wrefresh — 端末画面のウインドウをリフレッシュする

説明

int ncurses_wrefresh ( resource $window )
警告

この関数は、 実験的 なものです。この関数の動作・ 名前・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 この関数は自己責任で使用してください。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_wstandend

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wstandend — ウィンドウの standout モードを終了する

説明

int ncurses_wstandend ( resource $window )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_wstandout

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wstandout — ウィンドウの standout モードに入る

説明

int ncurses_wstandout ( resource $window )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

ncurses_wvline

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)

ncurses_wvline — 指定した属性文字を用いて、最大 n 文字分の長さの垂直線を ウィンドウに描画する

説明

int ncurses_wvline ( resource $window , int $charattr , int $n )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

window

charattr

n

目次

Newt

導入

これは RedHat Newt ライブラリのための PHP 拡張モジュールで、 ユーザーに優しいアプリケーションを作成するための、ターミナルベースの ウィンドウやウィジェットのライブラリです。 PHP でこの拡張モジュールを有効にすることで Newt ウィジェットが使用可能に なります。この中にはウィンドウやボタン・チェックボックス・ラジオボタン・ ラベル・エディットボックス・スクロールバー・テキストエリア・スケールなどが 含まれます。この拡張モジュールの使用方法は、もとの C 言語用の API と非常によく似ています。

インストール/設定

目次

要件

このモジュールは RedHat Newt ライブラリの関数を使用します。 libnewt バージョン >= 0.51.0 が必要です。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/newt.

PHP 4 の場合、この PECL 拡張モジュール のソースは、PHP のソースの ext/ ディレクトリ、または 上の PECL リンクで入手可能です。 これらの関数を使用するには、--with-newt[=DIR] オプションを使用し、newt サポートを有効にした上で CGI あるいは CLI 版の PHP を コンパイルする必要があります。

注意:

この拡張モジュールは、Windows プラットフォームでは使用できません。

この拡張モジュールをコンパイルするには、curses ライブラリおよび slang ライブラリも必要です。 これらのライブラリの場所を指定するには、以下の設定オプションを 使用します。 --with-curses-dir=/path/to/libcurses --with-slang-dir=/path/to/libslang

実行時設定

設定ディレクティブは定義されていません。

リソース型

この拡張モジュールは 2 つのリソース型 "newt component" および "newt grid" を使用します。

リソース型 "newt component" は関数から返されるもので、一般的な newt ウィジェット（例: newt_button()）を作成します。

リソース型 "newt grid" はコンポーネントの特別なリンク ID で、これは newt グリッドファクトリ関数（例: newt_create_grid()） によって返されます。

定義済み定数

目次

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Newt フォームの終了原因

Newt フォームの終了原因
定数 意味
NEWT_EXIT_HOTKEY newt_form_add_hot_key() で定義したホットキーが押されました
NEWT_EXIT_COMPONENT 何らかのコンポーネントがフォームを終了させました
NEWT_EXIT_FDREADY newt_form_watch_fd() で指定したファイル記述子の 読み込みあるいは書き込みの準備が完了しました
NEWT_EXIT_TIMER newt_form_set_timer() で指定した時間が 経過しました

Newt 色セット

Newt 色セット
定数 意味
NEWT_COLORSET_ROOT  
NEWT_COLORSET_BORDER  
NEWT_COLORSET_WINDOW  
NEWT_COLORSET_SHADOW  
NEWT_COLORSET_TITLE  
NEWT_COLORSET_BUTTON  
NEWT_COLORSET_ACTBUTTON  
NEWT_COLORSET_CHECKBOX  
NEWT_COLORSET_ACTCHECKBOX  
NEWT_COLORSET_ENTRY  
NEWT_COLORSET_LABEL  
NEWT_COLORSET_LISTBOX  
NEWT_COLORSET_ACTLISTBOX  
NEWT_COLORSET_TEXTBOX  
NEWT_COLORSET_ACTTEXTBOX  
NEWT_COLORSET_HELPLINE  
NEWT_COLORSET_ROOTTEXT  
NEWT_COLORSET_EMPTYSCALE  
NEWT_COLORSET_FULLSCALE  
NEWT_COLORSET_DISENTRY  
NEWT_COLORSET_COMPACTBUTTON  
NEWT_COLORSET_ACTSELLISTBOX  
NEWT_COLORSET_SELLISTBOX  

Newt 引数のフラグ

Newt 引数のフラグ
定数 意味
NEWT_ARG_LAST  
NEWT_ARG_APPEND  

Newt フラグの状態

Newt フラグの状態
定数 意味
NEWT_FLAGS_SET  
NEWT_FLAGS_RESET  
NEWT_FLAGS_TOGGLE  

Newt コンポーネントのフラグ

Newt コンポーネントのフラグ
定数 意味
NEWT_FLAG_RETURNEXIT コンポーネントがアクティブになった際にフォームを終了します
NEWT_FLAG_HIDDEN コンポーネントは非表示です
NEWT_FLAG_SCROLL コンポーネントはスクロール可能です
NEWT_FLAG_DISABLED コンポーネントは使用不能です
NEWT_FLAG_BORDER  
NEWT_FLAG_WRAP テキストを折り返します
NEWT_FLAG_NOF12 F12 を押してもフォームを終了しません
NEWT_FLAG_MULTIPLE  
NEWT_FLAG_SELECTED コンポーネントは選択されています
NEWT_FLAG_CHECKBOX コンポーネントはチェックボックスです
NEWT_FLAG_PASSWORD 入力コンポーネントはパスワード入力欄です
NEWT_FLAG_SHOWCURSOR カーソルを表示します

ファイル識別子のフラグ

ファイル識別子のフラグ
定数 意味
NEWT_FD_READ  
NEWT_FD_WRITE  
NEWT_FD_EXCEPT  

チェックボックスツリーのフラグ

チェックボックスツリーのフラグ
定数 意味
NEWT_CHECKBOXTREE_UNSELECTABLE  
NEWT_CHECKBOXTREE_HIDE_BOX  
NEWT_CHECKBOXTREE_COLLAPSED  
NEWT_CHECKBOXTREE_EXPANDED  
NEWT_CHECKBOXTREE_UNSELECTED  
NEWT_CHECKBOXTREE_SELECTED  

入力フラグ

入力フラグ
定数 意味
NEWT_ENTRY_SCROLL  
NEWT_ENTRY_HIDDEN  
NEWT_ENTRY_RETURNEXIT  
NEWT_ENTRY_DISABLED  

リストボックスのフラグ

リストボックスのフラグ
定数 意味
NEWT_LISTBOX_RETURNEXIT  

テキストボックスのフラグ

テキストボックスのフラグ
定数 意味
NEWT_TEXTBOX_WRAP テキストボックスのテキストを折り返します
NEWT_TEXTBOX_SCROLL テキストボックスのテキストをスクロールします

フォームのフラグ

フォームのフラグ
定数 意味
NEWT_FORM_NOF12 F12 を押しても終了しません

Newt キー

Newt キー
定数 意味
NEWT_KEY_TAB  
NEWT_KEY_ENTER  
NEWT_KEY_SUSPEND  
NEWT_KEY_ESCAPE  
NEWT_KEY_RETURN  
NEWT_KEY_EXTRA_BASE  
NEWT_KEY_UP  
NEWT_KEY_DOWN  
NEWT_KEY_LEFT  
NEWT_KEY_RIGHT  
NEWT_KEY_BKSPC  
NEWT_KEY_DELETE  
NEWT_KEY_HOME  
NEWT_KEY_END  
NEWT_KEY_UNTAB  
NEWT_KEY_PGUP  
NEWT_KEY_PGDN  
NEWT_KEY_INSERT  
NEWT_KEY_F1  
NEWT_KEY_F2  
NEWT_KEY_F3  
NEWT_KEY_F4  
NEWT_KEY_F5  
NEWT_KEY_F6  
NEWT_KEY_F7  
NEWT_KEY_F8  
NEWT_KEY_F9  
NEWT_KEY_F10  
NEWT_KEY_F11  
NEWT_KEY_F12  
NEWT_KEY_RESIZE  

Newt アンカー

Newt アンカー
定数 意味
NEWT_ANCHOR_LEFT  
NEWT_ANCHOR_RIGHT  
NEWT_ANCHOR_TOP  
NEWT_ANCHOR_BOTTOM  

グリッドのフラグ

グリッドのフラグ
定数 意味
NEWT_GRID_FLAG_GROWX  
NEWT_GRID_FLAG_GROWY  
NEWT_GRID_EMPTY  
NEWT_GRID_COMPONENT  
NEWT_GRID_SUBGRID  

例

目次

基本的な使用法

この例は、RedHat の 'setup' ユーティリティダイアログを PHP に移植したもので、 テキストモードで動作します。

例1 Newt の使用例

<?php
newt_init ();
newt_cls ();

newt_draw_root_text (0, 0, "Test Mode Setup Utility 1.12");
newt_push_help_line (null);
newt_draw_root_text (-30, 0, "(c) 1999-2002 RedHat, Inc");

newt_get_screen_size ($rows, $cols);

newt_open_window ($rows/2-17, $cols/2-10, 34, 17, "Choose a Tool");

$form = newt_form ();

$list = newt_listbox (3, 2, 10);

foreach (array (
    "Authentication configuration",
    "Firewall configuration",
    "Mouse configuration",
    "Network configuration",
    "Printer configuration",
    "System services") as $l_item)
{
    newt_listbox_add_entry ($list, $l_item, $l_item);
}

$b1 = newt_button (5, 12, "Run Tool");
$b2 = newt_button (21, 12, "Quit");

newt_form_add_component ($form, $list);
newt_form_add_components ($form, array($b1, $b2));

newt_refresh ();
newt_run_form ($form);

newt_pop_window ();
newt_pop_help_line ();
newt_finished ();
newt_form_destroy ($form);
?>

Newt 関数

newt_bell

(PECL newt >= 0.1)

newt_bell — ビープ音を端末に送信する

説明

void newt_bell ( void )

この関数は、端末にビープ音を送信します。

注意:

端末の設定により、この音が聞こえることも聞こえないこともあります。

返り値

値を返しません。

newt_button_bar

(PECL newt >= 0.1)

newt_button_bar — 作成したボタンを含むグリッドを返す

説明

resource newt_button_bar ( array &$buttons )

この関数は、作成したボタンを含むグリッドを返します。

パラメータ

buttons

返り値

作成したボタンを含むグリッドを返します。

newt_button

(PECL newt >= 0.1)

newt_button — 新しいボタンを作成する

説明

resource newt_button ( int $left , int $top , string $text )

新しいボタンを作成します。

パラメータ

left

ボタンの X 座標。

top

ボタンの Y 座標。

text

ボタンに表示するテキスト。

返り値

作成したボタンコンポーネントへのリソースリンク、あるいはエラー時に FALSE を返します。

例

例1 newt_button() の例

<?php

$form = newt_form();

$ok_button = newt_button(5, 12, "Run Tool");
    
newt_form_add_component($form, $ok_button);

?>

参考

newt_centered_window

(PECL newt >= 0.1)

newt_centered_window — 画面の中央に指定したサイズのウィンドウをオープンする

説明

int newt_centered_window ( int $width , int $height [, string $title ] )

画面の中央に、指定したサイズのウィンドウをオープンします。

パラメータ

width

ウィンドウの幅。

height

ウィンドウの高さ。

title

ウィンドウのタイトル。

返り値

未定義です。

参考

newt_checkbox_get_value

(PECL newt >= 0.1)

newt_checkbox_get_value — チェックボックスリソースの値を取得する

説明

string newt_checkbox_get_value ( resource $checkbox )

この関数は、シーケンス内の文字を返します。 これは、チェックボックスの現在の値を表します。

パラメータ

checkbox

返り値

チェックボックスの値を表す文字を返します。

newt_checkbox_set_flags

(PECL newt >= 0.1)

newt_checkbox_set_flags — チェックボックスリソースを設定する

説明

void newt_checkbox_set_flags ( resource $checkbox , int $flags , int $sense )

この関数は、チェックボックスリソースのさまざまなフラグを設定します。

パラメータ

checkbox

flags

sense

返り値

値を返しません。

newt_checkbox_set_value

(PECL newt >= 0.1)

newt_checkbox_set_value — チェックボックスの値を設定する

説明

void newt_checkbox_set_value ( resource $checkbox , string $value )

この関数は、チェックボックスリソースの現在の値を設定します。

パラメータ

checkbox

value

返り値

値を返しません。

newt_checkbox_tree_add_item

(PECL newt >= 0.1)

newt_checkbox_tree_add_item — 新しいアイテムをチェックボックスツリーに追加する

説明

void newt_checkbox_tree_add_item ( resource $checkboxtree , string $text , mixed $data , int $flags , int $index [, int $... ] )

この関数は、新しいアイテムをチェックボックスツリーに追加します。

パラメータ

checkboxtree

text

data

flags

index

返り値

値を返しません。

newt_checkbox_tree_find_item

(PECL newt >= 0.1)

newt_checkbox_tree_find_item — チェックボックスツリーのアイテムを探す

説明

array newt_checkbox_tree_find_item ( resource $checkboxtree , mixed $data )

データを指定して、チェックボックスツリーのアイテムを探します。

パラメータ

checkboxtree

data

返り値

チェックボックスツリーアイテムリソースを返します。 見つからなかった場合は NULL を返します。

newt_checkbox_tree_get_current

(PECL newt >= 0.1)

newt_checkbox_tree_get_current — チェックボックスツリーの選択されているアイテムを返す

説明

mixed newt_checkbox_tree_get_current ( resource $checkboxtree )

このメソッドは、チェックボックスツリーの選択されているアイテムを返します。

パラメータ

checkboxtree

返り値

現在の (選択されている) チェックボックスツリーアイテムを返します。

newt_checkbox_tree_get_entry_value

(PECL newt >= 0.1)

newt_checkbox_tree_get_entry_value —

説明

string newt_checkbox_tree_get_entry_value ( resource $checkboxtree , mixed $data )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

checkboxtree

data

返り値

newt_checkbox_tree_get_multi_selection

(PECL newt >= 0.1)

newt_checkbox_tree_get_multi_selection —

説明

array newt_checkbox_tree_get_multi_selection ( resource $checkboxtree , string $seqnum )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

checkboxtree

seqnum

返り値

newt_checkbox_tree_get_selection

(PECL newt >= 0.1)

newt_checkbox_tree_get_selection —

説明

array newt_checkbox_tree_get_selection ( resource $checkboxtree )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

checkboxtree

返り値

newt_checkbox_tree_multi

(PECL newt >= 0.1)

newt_checkbox_tree_multi —

説明

resource newt_checkbox_tree_multi ( int $left , int $top , int $height , string $seq [, int $flags ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

height

seq

flags

返り値

newt_checkbox_tree_set_current

(PECL newt >= 0.1)

newt_checkbox_tree_set_current —

説明

void newt_checkbox_tree_set_current ( resource $checkboxtree , mixed $data )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

checkboxtree

data

返り値

値を返しません。

newt_checkbox_tree_set_entry_value

(PECL newt >= 0.1)

newt_checkbox_tree_set_entry_value —

説明

void newt_checkbox_tree_set_entry_value ( resource $checkboxtree , mixed $data , string $value )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

checkboxtree

data

value

返り値

値を返しません。

newt_checkbox_tree_set_entry

(PECL newt >= 0.1)

newt_checkbox_tree_set_entry —

説明

void newt_checkbox_tree_set_entry ( resource $checkboxtree , mixed $data , string $text )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

checkboxtree

data

text

返り値

値を返しません。

newt_checkbox_tree_set_width

(PECL newt >= 0.1)

newt_checkbox_tree_set_width —

説明

void newt_checkbox_tree_set_width ( resource $checkbox_tree , int $width )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

checkbox_tree

width

返り値

値を返しません。

newt_checkbox_tree

(PECL newt >= 0.1)

newt_checkbox_tree —

説明

resource newt_checkbox_tree ( int $left , int $top , int $height [, int $flags ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

height

flags

返り値

newt_checkbox

(PECL newt >= 0.1)

newt_checkbox —

説明

resource newt_checkbox ( int $left , int $top , string $text , string $def_value [, string $seq ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

text

def_value

seq

返り値

newt_clear_key_buffer

(PECL newt >= 0.1)

newt_clear_key_buffer — 追加の入力を待たずに、端末の入力バッファの内容をクリアする

説明

void newt_clear_key_buffer ( void )

追加の入力を待たずに、端末の入力バッファの内容をクリアします。

返り値

値を返しません。

参考

newt_cls

(PECL newt >= 0.1)

newt_cls —

説明

void newt_cls ( void )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

返り値

値を返しません。

newt_compact_button

(PECL newt >= 0.1)

newt_compact_button —

説明

resource newt_compact_button ( int $left , int $top , string $text )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

text

返り値

newt_component_add_callback

(PECL newt >= 0.1)

newt_component_add_callback —

説明

void newt_component_add_callback ( resource $component , mixed $func_name , mixed $data )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

component

func_name

data

返り値

値を返しません。

newt_component_takes_focus

(PECL newt >= 0.1)

newt_component_takes_focus —

説明

void newt_component_takes_focus ( resource $component , bool $takes_focus )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

component

takes_focus

返り値

値を返しません。

newt_create_grid

(PECL newt >= 0.1)

newt_create_grid —

説明

resource newt_create_grid ( int $cols , int $rows )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

cols

rows

返り値

newt_cursor_off

(PECL newt >= 0.1)

newt_cursor_off —

説明

void newt_cursor_off ( void )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

返り値

値を返しません。

newt_cursor_on

(PECL newt >= 0.1)

newt_cursor_on —

説明

void newt_cursor_on ( void )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

返り値

値を返しません。

newt_delay

(PECL newt >= 0.1)

newt_delay —

説明

void newt_delay ( int $microseconds )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

microseconds

返り値

値を返しません。

newt_draw_form

(PECL newt >= 0.1)

newt_draw_form —

説明

void newt_draw_form ( resource $form )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

form

返り値

値を返しません。

newt_draw_root_text

(PECL newt >= 0.1)

newt_draw_root_text — 指定した位置に文字列を表示する

説明

void newt_draw_root_text ( int $left , int $top , string $text )

指定した位置に文字列を表示します。

パラメータ

left

カラム番号。

注意:

left が負の数の場合、画面の反対側から位置が計算されます。

top

行番号。

注意:

top が負の数の場合、画面の反対側から位置が計算されます。

text

表示する文字列。

返り値

値を返しません。

例

例1 newt_draw_root_text() の例

このコードは、画面の両側の隅にタイトルを表示します。

<?php
 newt_init();
 newt_cls();

 newt_draw_root_text (2, 0, "Some root text");
 newt_refresh();
 sleep(1);

 newt_draw_root_text (-30, 0, "Root text in the other corner");
 newt_refresh();
 sleep(1);

 newt_finished();
?>

参考

newt_entry_get_value

(PECL newt >= 0.1)

newt_entry_get_value —

説明

string newt_entry_get_value ( resource $entry )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

entry

返り値

newt_entry_set_filter

(PECL newt >= 0.1)

newt_entry_set_filter —

説明

void newt_entry_set_filter ( resource $entry , callable $filter , mixed $data )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

entry

filter

data

返り値

値を返しません。

newt_entry_set_flags

(PECL newt >= 0.1)

newt_entry_set_flags —

説明

void newt_entry_set_flags ( resource $entry , int $flags , int $sense )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

entry

flags

sense

返り値

値を返しません。

newt_entry_set

(PECL newt >= 0.1)

newt_entry_set —

説明

void newt_entry_set ( resource $entry , string $value [, bool $cursor_at_end ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

entry

value

cursor_at_end

返り値

値を返しません。

newt_entry

(PECL newt >= 0.1)

newt_entry —

説明

resource newt_entry ( int $left , int $top , int $width [, string $init_value [, int $flags ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

width

init_value

flags

返り値

newt_finished

(PECL newt >= 0.1)

newt_finished — newt インターフェイスを終了する

説明

int newt_finished ( void )

newt インターフェイスを終了します。プログラムが終了する際にこの関数を コールします。

返り値

成功した場合に 1、失敗した場合に 0 を返します。

参考

newt_form_add_component

(PECL newt >= 0.1)

newt_form_add_component — フォームにコンポーネントを追加する

説明

void newt_form_add_component ( resource $form , resource $component )

form にコンポーネントを追加します。

パラメータ

form

コンポーネントを追加するフォーム。

component

フォームに追加するコンポーネント。

返り値

値を返しません。

例

例1 newt_form_add_component() の例

<?php
$form = newt_form();

$options = array("Authentication configuration", "Firewall configuration",
"Mouse configuration", "Network configuration", "Printer configuration",
"System services");

$list = newt_listbox(3, 2, 10);

foreach ($options as $l_item) {
    newt_listbox_add_entry($list, $l_item, $l_item);
}

newt_form_add_component($form, $list);
?>

参考

newt_form_add_components

(PECL newt >= 0.1)

newt_form_add_components — フォームに複数のコンポーネントを追加する

説明

void newt_form_add_components ( resource $form , array $components )

form に複数のコンポーネントを追加します。

パラメータ

form

コンポーネントを追加するフォーム。

components

フォームに追加するコンポーネントの配列。

返り値

値を返しません。

例

例1 newt_form_add_components() の例

<?php
$form = newt_form();

$b1 = newt_button(5, 12, "Run Tool");
$b2 = newt_button(21, 12, "Quit");

newt_form_add_components($form, array($b1, $b2));
?>

参考

newt_form_add_hot_key

(PECL newt >= 0.1)

newt_form_add_hot_key —

説明

void newt_form_add_hot_key ( resource $form , int $key )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

form

key

返り値

値を返しません。

newt_form_destroy

(PECL newt >= 0.1)

newt_form_destroy — フォームを破壊する

説明

void newt_form_destroy ( resource $form )

この関数は、フォームおよびそこに追加されたすべてのコンポーネント (サブフォーム上のコンポーネントも含みます)が使用しているメモリ リソースを開放します。いちどフォームが破壊されると、フォーム上の コンポーネントは使用できなくなります。

パラメータ

form

破壊されるフォームコンポーネント。

返り値

値を返しません。

参考

newt_form_get_current

(PECL newt >= 0.1)

newt_form_get_current —

説明

resource newt_form_get_current ( resource $form )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

form

返り値

newt_form_run

(PECL newt >= 0.1)

newt_form_run — フォームを実行する

説明

void newt_form_run ( resource $form , array &$exit_struct )

この関数は、引数で渡したフォームを実行します。

パラメータ

form

フォームコンポーネント。

exit_struct

フォームコンポーネントを実行した後の情報を返すために使用する 配列。キーと値については以下の表で示します。

Form の終了情報の構造
インデックスのキー 値の型 説明
reason integer フォームが終了した理由。とりうる値については ここ で定義しています。
watch resource newt_form_watch_fd() で指定したリソースリンク。
キー 整数 ホットキー
component resource フォームを終了させたコンポーネント。

返り値

値を返しません。

参考

newt_form_set_background

(PECL newt >= 0.1)

newt_form_set_background —

説明

void newt_form_set_background ( resource $from , int $background )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

from

background

返り値

値を返しません。

newt_form_set_height

(PECL newt >= 0.1)

newt_form_set_height —

説明

void newt_form_set_height ( resource $form , int $height )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

form

height

返り値

値を返しません。

newt_form_set_size

(PECL newt >= 0.1)

newt_form_set_size —

説明

void newt_form_set_size ( resource $form )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

form

返り値

値を返しません。

newt_form_set_timer

(PECL newt >= 0.1)

newt_form_set_timer —

説明

void newt_form_set_timer ( resource $form , int $milliseconds )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

form

milliseconds

返り値

値を返しません。

newt_form_set_width

(PECL newt >= 0.1)

newt_form_set_width —

説明

void newt_form_set_width ( resource $form , int $width )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

form

width

返り値

値を返しません。

newt_form_watch_fd

(PECL newt >= 0.1)

newt_form_watch_fd —

説明

void newt_form_watch_fd ( resource $form , resource $stream [, int $flags ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

form

stream

flags

返り値

値を返しません。

newt_form

(PECL newt >= 0.1)

newt_form — フォームを作成する

説明

resource newt_form ([ resource $vert_bar [, string $help [, int $flags ]]] )

新しいフォームを作成します。

パラメータ

vert_bar

フォームに関連付けられる垂直スクロールバー。

help

ヘルプ文字列。

flags

さまざまなフラグ。

返り値

作成されたフォームコンポーネントのリソースリンク、 あるいはエラー時に FALSE を返します。

例

例1 newt_form() の例

"Quit" ボタンを表示し、それが押されるとアプリケーションを 終了させます。

<?php
newt_init();
newt_cls();

$myform = newt_form();
$button = newt_button (5, 12, "Quit");

newt_form_add_component ($myform, $button);
newt_refresh ();
newt_run_form ($myform);

newt_finished ();
newt_form_destroy ($myform);
?>

参考

newt_get_screen_size

(PECL newt >= 0.1)

newt_get_screen_size — 参照で渡された引数に、現在の端末の大きさを格納する

説明

void newt_get_screen_size ( int &$cols , int &$rows )

参照で渡された引数に、現在の端末の大きさを格納します。

パラメータ

cols

端末のカラム数。

rows

端末の行数。

返り値

値を返しません。

例

例1 newt_get_screen_size() の例

このコードは、端末の画面の大きさを表示します。

<?php
 newt_init();
 newt_get_screen_size (&$cols, &$rows);
 newt_finished();

 print "端末のサイズは {$cols}x{$rows} です。\n";
?>

上の例の出力は以下となります。

端末のサイズは 138x47 です。

newt_grid_add_components_to_form

(PECL newt >= 0.1)

newt_grid_add_components_to_form —

説明

void newt_grid_add_components_to_form ( resource $grid , resource $form , bool $recurse )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

grid

form

recurse

返り値

値を返しません。

newt_grid_basic_window

(PECL newt >= 0.1)

newt_grid_basic_window —

説明

resource newt_grid_basic_window ( resource $text , resource $middle , resource $buttons )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

middle

buttons

返り値

newt_grid_free

(PECL newt >= 0.1)

newt_grid_free —

説明

void newt_grid_free ( resource $grid , bool $recurse )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

grid

recurse

返り値

値を返しません。

newt_grid_get_size

(PECL newt >= 0.1)

newt_grid_get_size —

説明

void newt_grid_get_size ( resouce $grid , int &$width , int &$height )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

grid

width

height

返り値

値を返しません。

newt_grid_h_close_stacked

(PECL newt >= 0.1)

newt_grid_h_close_stacked —

説明

resource newt_grid_h_close_stacked ( int $element1_type , resource $element1 [, int $... [, resource $... ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

element1_type

element1

返り値

newt_grid_h_stacked

(PECL newt >= 0.1)

newt_grid_h_stacked —

説明

resource newt_grid_h_stacked ( int $element1_type , resource $element1 [, int $... [, resource $... ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

element1_type

element1

返り値

newt_grid_place

(PECL newt >= 0.1)

newt_grid_place —

説明

void newt_grid_place ( resource $grid , int $left , int $top )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

grid

left

top

返り値

値を返しません。

newt_grid_set_field

(PECL newt >= 0.1)

newt_grid_set_field —

説明

void newt_grid_set_field ( resource $grid , int $col , int $row , int $type , resource $val , int $pad_left , int $pad_top , int $pad_right , int $pad_bottom , int $anchor [, int $flags ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

grid

col

row

type

val

pad_left

pad_top

pad_right

pad_bottom

anchor

flags

返り値

値を返しません。

newt_grid_simple_window

(PECL newt >= 0.1)

newt_grid_simple_window —

説明

resource newt_grid_simple_window ( resource $text , resource $middle , resource $buttons )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

middle

buttons

返り値

newt_grid_v_close_stacked

(PECL newt >= 0.1)

newt_grid_v_close_stacked —

説明

resource newt_grid_v_close_stacked ( int $element1_type , resource $element1 [, int $... [, resource $... ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

element1_type

element1

返り値

newt_grid_v_stacked

(PECL newt >= 0.1)

newt_grid_v_stacked —

説明

resource newt_grid_v_stacked ( int $element1_type , resource $element1 [, int $... [, resource $... ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

element1_type

element1

返り値

newt_grid_wrapped_window_at

(PECL newt >= 0.1)

newt_grid_wrapped_window_at —

説明

void newt_grid_wrapped_window_at ( resource $grid , string $title , int $left , int $top )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

grid

title

left

top

返り値

値を返しません。

newt_grid_wrapped_window

(PECL newt >= 0.1)

newt_grid_wrapped_window —

説明

void newt_grid_wrapped_window ( resource $grid , string $title )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

grid

title

返り値

値を返しません。

newt_init

(PECL newt >= 0.1)

newt_init — newt を初期化する

説明

int newt_init ( void )

newt インターフェイスを初期化します。この関数は、他の newt 関数の前に コールする必要があります。

返り値

成功した場合に 1、失敗した場合に 0 を返します。

参考

newt_label_set_text

(PECL newt >= 0.1)

newt_label_set_text —

説明

void newt_label_set_text ( resource $label , string $text )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

label

text

返り値

値を返しません。

newt_label

(PECL newt >= 0.1)

newt_label —

説明

resource newt_label ( int $left , int $top , string $text )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

text

返り値

newt_listbox_append_entry

(PECL newt >= 0.1)

newt_listbox_append_entry —

説明

void newt_listbox_append_entry ( resource $listbox , string $text , mixed $data )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

text

data

返り値

値を返しません。

newt_listbox_clear_selection

(PECL newt >= 0.1)

newt_listbox_clear_selection —

説明

void newt_listbox_clear_selection ( resource $listbox )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

返り値

値を返しません。

newt_listbox_clear

(PECL newt >= 0.1)

newt_listbox_clear —

説明

void newt_listbox_clear ( resource $listobx )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listobx

返り値

値を返しません。

newt_listbox_delete_entry

(PECL newt >= 0.1)

newt_listbox_delete_entry —

説明

void newt_listbox_delete_entry ( resource $listbox , mixed $key )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

key

返り値

値を返しません。

newt_listbox_get_current

(PECL newt >= 0.1)

newt_listbox_get_current —

説明

string newt_listbox_get_current ( resource $listbox )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

返り値

newt_listbox_get_selection

(PECL newt >= 0.1)

newt_listbox_get_selection —

説明

array newt_listbox_get_selection ( resource $listbox )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

返り値

newt_listbox_insert_entry

(PECL newt >= 0.1)

newt_listbox_insert_entry —

説明

void newt_listbox_insert_entry ( resource $listbox , string $text , mixed $data , mixed $key )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

text

data

key

返り値

値を返しません。

newt_listbox_item_count

(PECL newt >= 0.1)

newt_listbox_item_count —

説明

int newt_listbox_item_count ( resource $listbox )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

返り値

newt_listbox_select_item

(PECL newt >= 0.1)

newt_listbox_select_item —

説明

void newt_listbox_select_item ( resource $listbox , mixed $key , int $sense )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

key

sense

返り値

値を返しません。

newt_listbox_set_current_by_key

(PECL newt >= 0.1)

newt_listbox_set_current_by_key —

説明

void newt_listbox_set_current_by_key ( resource $listbox , mixed $key )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

key

返り値

値を返しません。

newt_listbox_set_current

(PECL newt >= 0.1)

newt_listbox_set_current —

説明

void newt_listbox_set_current ( resource $listbox , int $num )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

num

返り値

値を返しません。

newt_listbox_set_data

(PECL newt >= 0.1)

newt_listbox_set_data —

説明

void newt_listbox_set_data ( resource $listbox , int $num , mixed $data )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

num

data

返り値

値を返しません。

newt_listbox_set_entry

(PECL newt >= 0.1)

newt_listbox_set_entry —

説明

void newt_listbox_set_entry ( resource $listbox , int $num , string $text )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

num

text

返り値

値を返しません。

newt_listbox_set_width

(PECL newt >= 0.1)

newt_listbox_set_width —

説明

void newt_listbox_set_width ( resource $listbox , int $width )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

listbox

width

返り値

値を返しません。

newt_listbox

(PECL newt >= 0.1)

newt_listbox —

説明

resource newt_listbox ( int $left , int $top , int $height [, int $flags ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

height

flags

返り値

newt_listitem_get_data

(PECL newt >= 0.1)

newt_listitem_get_data —

説明

mixed newt_listitem_get_data ( resource $item )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

item

返り値

newt_listitem_set

(PECL newt >= 0.1)

newt_listitem_set —

説明

void newt_listitem_set ( resource $item , string $text )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

item

text

返り値

値を返しません。

newt_listitem

(PECL newt >= 0.1)

newt_listitem —

説明

resource newt_listitem ( int $left , int $top , string $text , bool $is_default , resouce $prev_item , mixed $data [, int $flags ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

text

is_default

prev_item

data

flags

返り値

newt_open_window

(PECL newt >= 0.1)

newt_open_window — 指定したサイズと位置でウィンドウをオープンする

説明

int newt_open_window ( int $left , int $top , int $width , int $height [, string $title ] )

指定したサイズと位置でウィンドウをオープンします。

パラメータ

left

ウィンドウの左上隅の位置(カラム番号)。

top

ウィンドウの左上隅の位置(行番号)。

width

ウィンドウの幅。

height

ウィンドウの高さ。

title

ウィンドウのタイトル。

返り値

成功した場合に 1、失敗した場合に 0 を返します。

参考

newt_pop_help_line

(PECL newt >= 0.1)

newt_pop_help_line — 現在のヘルプ行をスタックの内容で置き換える

説明

void newt_pop_help_line ( void )

現在のヘルプ行を、スタックの内容で置き換えます。

注意:

newt_push_help_line() をコールした回数をこえて newt_pop_help_line() をコールしないようにすることが 重要です。

返り値

値を返しません。

参考

newt_pop_window

(PECL newt >= 0.1)

newt_pop_window — トップウィンドウを画面から消去する

説明

void newt_pop_window ( void )

トップウィンドウを画面から消去し、ウィンドウが覆っていた部分を 再描画します。

返り値

値を返しません。

参考

newt_push_help_line

(PECL newt >= 0.1)

newt_push_help_line — 現在のヘルプ行をスタックに保存し、新しい行を表示する

説明

void newt_push_help_line ([ string $text ] )

現在のヘルプ行をスタックに保存し、新しい行を表示します。

パラメータ

text

新しいヘルプメッセージ。

注意:

指定しなかった場合、ヘルプ行はクリアされます。

返り値

値を返しません。

参考

newt_radio_get_current

(PECL newt >= 0.1)

newt_radio_get_current —

説明

resource newt_radio_get_current ( resource $set_member )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

set_member

返り値

newt_radiobutton

(PECL newt >= 0.1)

newt_radiobutton —

説明

resource newt_radiobutton ( int $left , int $top , string $text , bool $is_default [, resource $prev_button ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

text

is_default

prev_button

返り値

newt_redraw_help_line

(PECL newt >= 0.1)

newt_redraw_help_line —

説明

void newt_redraw_help_line ( void )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

返り値

値を返しません。

newt_reflow_text

(PECL newt >= 0.1)

newt_reflow_text —

説明

string newt_reflow_text ( string $text , int $width , int $flex_down , int $flex_up , int &$actual_width , int &$actual_height )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

text

width

flex_down

flex_up

actual_width

actual_height

返り値

newt_refresh

(PECL newt >= 0.1)

newt_refresh — 画面の変更された部分を更新する

説明

void newt_refresh ( void )

パフォーマンスを向上させるため、newt は必要時にしか画面を更新しません。 それはプログラムが端末への書き込みを行った場合とは限りません。 変更した部分を即時に更新させるようにするために、この関数をコールします。

返り値

値を返しません。

newt_resize_screen

(PECL newt >= 0.1)

newt_resize_screen —

説明

void newt_resize_screen ([ bool $redraw ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

redraw

返り値

値を返しません。

newt_resume

(PECL newt >= 0.1)

newt_resume — newt_suspend() をコールした後に newt インターフェイスの使用を再開する

説明

void newt_resume ( void )

newt_suspend() をコールした後に newt インターフェイスの使用を再開します。

返り値

値を返しません。

参考

  • newt_suspend() - 端末を元の状態に戻すよう、newt に通知する

newt_run_form

(PECL newt >= 0.1)

newt_run_form — フォームを実行する

説明

resource newt_run_form ( resource $form )

この関数は、引数で渡したフォームを実行します。

パラメータ

form

フォームコンポーネント。

返り値

フォームの実行を停止させたコンポーネントを返します。

注意:

この関数は、newt の通常の名前付け規則に当てはまらないことに注意 しましょう。これは古いインターフェイスであり、すべてのフォームで 動作するわけではありません。これは、昔のアプリケーションのために だけ newt に残されています。しかし、この関数のインターフェイスは newt_form_run() よりシンプルであるため、 結果としていまだに頻繁に利用されています。 アプリケーションが終了した際には、フォームおよびそこに含まれる すべてのコンポーネントは破壊されます。

参考

newt_scale_set

(PECL newt >= 0.1)

newt_scale_set —

説明

void newt_scale_set ( resource $scale , int $amount )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

scale

amount

返り値

値を返しません。

newt_scale

(PECL newt >= 0.1)

newt_scale —

説明

resource newt_scale ( int $left , int $top , int $width , int $full_value )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

width

full_value

返り値

newt_scrollbar_set

(PECL newt >= 0.1)

newt_scrollbar_set —

説明

void newt_scrollbar_set ( resource $scrollbar , int $where , int $total )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

scrollbar

where

total

返り値

値を返しません。

newt_set_help_callback

(PECL newt >= 0.1)

newt_set_help_callback —

説明

void newt_set_help_callback ( mixed $function )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

function

返り値

値を返しません。

newt_set_suspend_callback

(PECL newt >= 0.1)

newt_set_suspend_callback — ユーザーがサスペンドキーを押した際に起動するコールバック関数を設定する

説明

void newt_set_suspend_callback ( callable $function , mixed $data )

ユーザーがサスペンドキー（通常は ^Z）を押した際に起動するコールバック関数を 設定します。コールバックが登録されていない場合、サスペンドのキー入力は 無視されます。

パラメータ

function

ひとつの引数 data を受け取るコールバック関数。

data

コールバック関数に渡されるデータ。

返り値

値を返しません。

参考

  • newt_suspend() - 端末を元の状態に戻すよう、newt に通知する
  • newt_resume() - newt_suspend をコールした後に newt インターフェイスの使用を再開する

newt_suspend

(PECL newt >= 0.1)

newt_suspend — 端末を元の状態に戻すよう、newt に通知する

説明

void newt_suspend ( void )

端末を元の状態に戻すよう、newt に通知します。いったん実行されると、 (自分自身に SIGTSTP を送信する・子プログラムをフォークするなどの方法で) アプリケーションが自分自身でサスペンドすることが可能となります。

返り値

値を返しません。

参考

  • newt_resume() - newt_suspend をコールした後に newt インターフェイスの使用を再開する

newt_textbox_get_num_lines

(PECL newt >= 0.1)

newt_textbox_get_num_lines —

説明

int newt_textbox_get_num_lines ( resource $textbox )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

textbox

返り値

newt_textbox_reflowed

(PECL newt >= 0.1)

newt_textbox_reflowed —

説明

resource newt_textbox_reflowed ( int $left , int $top , char $*text , int $width , int $flex_down , int $flex_up [, int $flags ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

*text

width

flex_down

flex_up

flags

返り値

newt_textbox_set_height

(PECL newt >= 0.1)

newt_textbox_set_height —

説明

void newt_textbox_set_height ( resource $textbox , int $height )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

textbox

height

返り値

値を返しません。

newt_textbox_set_text

(PECL newt >= 0.1)

newt_textbox_set_text —

説明

void newt_textbox_set_text ( resource $textbox , string $text )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

textbox

text

返り値

値を返しません。

newt_textbox

(PECL newt >= 0.1)

newt_textbox —

説明

resource newt_textbox ( int $left , int $top , int $width , int $height [, int $flags ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

width

height

flags

返り値

newt_vertical_scrollbar

(PECL newt >= 0.1)

newt_vertical_scrollbar —

説明

resource newt_vertical_scrollbar ( int $left , int $top , int $height [, int $normal_colorset [, int $thumb_colorset ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

left

top

height

normal_colorset

thumb_colorset

返り値

newt_wait_for_key

(PECL newt >= 0.1)

newt_wait_for_key — キーが押されるまで結果を返さない

説明

void newt_wait_for_key ( void )

この関数は、キーが押されるまで結果を返しません。 キー入力は無視されます。もし端末のバッファにキー入力が格納されている場合は、 この関数はその内容を捨てて結果をすぐに返します。

返り値

値を返しません。

参考

  • newt_clear_key_buffer() - 追加の入力を待たずに、端末の入力バッファの内容をクリアする

newt_win_choice

(PECL newt >= 0.1)

newt_win_choice —

説明

int newt_win_choice ( string $title , string $button1_text , string $button2_text , string $format [, mixed $args [, mixed $... ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

title

button1_text

button2_text

format

args

返り値

newt_win_entries

(PECL newt >= 0.1)

newt_win_entries —

説明

int newt_win_entries ( string $title , string $text , int $suggested_width , int $flex_down , int $flex_up , int $data_width , array &$items , string $button1 [, string $... ] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

title

text

suggested_width

flex_down

flex_up

data_width

items

button1

button2

返り値

例

例1 newt_win_entries() の例

<?php

newt_init();
newt_cls();

$entries[] = array('text' => 'First name:', 'value' => &$f_name);
$entries[] = array('text' => 'Last name:',  'value' => &$l_name);

$rc = newt_win_entries("User information", "Please enter your credentials:", 50, 7, 7, 30, $entries, "Ok", "Back");
newt_finished ();

if ($rc != 2) {
    echo "Your name is: $f_name $l_name\n";
}
?>

newt_win_menu

(PECL newt >= 0.1)

newt_win_menu —

説明

int newt_win_menu ( string $title , string $text , int $suggestedWidth , int $flexDown , int $flexUp , int $maxListHeight , array $items , int &$listItem [, string $button1 [, string $... ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

title

text

suggestedWidth

flexDown

flexUp

maxListHeight

items

listItem

button1

返り値

値を返しません。

newt_win_message

(PECL newt >= 0.1)

newt_win_message —

説明

void newt_win_message ( string $title , string $button_text , string $format [, mixed $args [, mixed $... ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

title

button_text

format

args

返り値

値を返しません。

newt_win_messagev

(PECL newt >= 0.1)

newt_win_messagev —

説明

void newt_win_messagev ( string $title , string $button_text , string $format , array $args )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

title

button_text

format

args

返り値

値を返しません。

newt_win_ternary

(PECL newt >= 0.1)

newt_win_ternary —

説明

int newt_win_ternary ( string $title , string $button1_text , string $button2_text , string $button3_text , string $format [, mixed $args [, mixed $... ]] )
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パラメータ

title

Its description

button1_text

Its description

button2_text

Its description

button3_text

Its description

format

Its description

args

Its description

返り値

What the function returns, first on success, then on failure. See also the &return.success; entity

目次

GNU Readline

導入

readline 関数群は、GNU Readline ライブラリへの インターフェイスを実装したものです。これらの関数は、コマンドラインの 編集機能を提供します。一例をあげると、Bash において文字を挿入したり コマンド履歴を走査したりする際に、矢印キーを使用することを 可能にしているものです。 このライブラリは対話的なものであるため、Web アプリケーションで 使用されることはほとんどないでしょう。しかし、 コマンドライン から PHP を使用するスクリプトを書く際には有用です。

注意: この拡張モジュールは Windows 環境では利用できません。

インストール/設定

目次

要件

readline 関数を使用するには、libreadline をインストールすることが 必要です。libreadline は、» http://cnswww.cns.cwru.edu/~chet/readline/rltop.html にある GNU Readline プロジェクトのホームページから入手可能です。このライブラリは、Bash の 作者でもある Chet Ramey により管理されています。

この関数を libeditライブラリで使用することも可能です。これは readline ライブラリの代替品で、非 GPL です。 libeditライブラリは BSD ライセンスで配布され、 » http://www.thrysoee.dk/editline/ から入手可能です。

インストール手順

この関数を使用するには、readline サポートを有効にして CGI 版または CLI 版の PHP をコンパイルする必要があります。PHP の configure に --with-readline[=DIR] を指定する必要が あります。readline の代替品である libedit を使用したい場合、PHP の configure に --with-libedit[=DIR] を指定してください。

実行時設定

php.ini の設定により動作が変化します。

Readline 設定オプション
名前 デフォルト 変更可能 変更履歴
cli.pager "" PHP_INI_ALL PHP 5.4.0 以降で使用可能。
cli.prompt "\\b \\> " PHP_INI_ALL PHP 5.4.0 以降で使用可能。

以下に設定ディレクティブに関する 簡単な説明を示します。

cli.pager string

コマンドライン の出力を表示する外部ツール。

cli.prompt string

コマンドラインのプロンプト。

リソース型

リソース型は定義されていません。

定義済み定数

定数は定義されていません。

Readline 関数

readline_add_history

(PHP 4, PHP 5)

readline_add_history — ヒストリに 1 行追加する

説明

bool readline_add_history ( string $line )

この関数は、コマンドラインヒストリに 1 行追加します。

パラメータ

line

ヒストリに追加する行。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

readline_callback_handler_install

(PHP 5 >= 5.1.0)

readline_callback_handler_install — readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す

説明

bool readline_callback_handler_install ( string $prompt , callable $callback )

readline コールバックインターフェイスを設定し、プロンプト prompt を表示して入力を受け取ります。 コールバック関数 callback はひとつのパラメータを とり、そこにはユーザーの入力内容が格納されます。一度登録したコールバック インターフェイスを削除せずもういちどこの関数をコールした場合、もとの インターフェイスは自動的に上書きされます。

コールバック機能は stream_select() と組み合わせると 有用です。これは readline() とは異なり、 IO とユーザーの入力を交互に取り扱います。

パラメータ

prompt

確認メッセージ。

callback

callback 関数が受け取るパラメータはひとつで、 ユーザーから返された入力です。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

例

例1 Readline コールバックインターフェイスの例

<?php
function rl_callback($ret)
{
    global $c, $prompting;

    echo "You entered: $ret\n";
    $c++;

    if ($c > 10) {
        $prompting = false;
        readline_callback_handler_remove();
    } else {
        readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
    }
}

$c = 1;
$prompting = true;

readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');

while ($prompting) {
    $w = NULL;
    $e = NULL;
    $n = stream_select($r = array(STDIN), $w, $e, null);
    if ($n && in_array(STDIN, $r)) {
        // read a character, will call the callback when a newline is entered
        readline_callback_read_char();
    }
}

echo "Prompting disabled. All done.\n";
?>

参考

  • readline_callback_handler_remove() - インストールされたハンドラを削除し、端末の設定をもとに戻す
  • readline_callback_read_char() - 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する
  • stream_select() - select() システムコールと同等の操作を、 ストリームの配列に対して tv_sec と tv_usec で指定されたタイムアウト時間をもって行う

readline_callback_handler_remove

(PHP 5 >= 5.1.0)

readline_callback_handler_remove — インストールされたハンドラを削除し、端末の設定をもとに戻す

説明

bool readline_callback_handler_remove ( void )

インストールされたハンドラを削除し、端末の設定をもとに戻します。

返り値

インストールされたコールバックが削除できた場合に TRUE、 削除するハンドラが見つからなかった場合に FALSE を返します。

例

readline コールバックインターフェイスの使用方法についての例は readline_callback_handler_install() を参照ください。

参考

  • readline_callback_handler_install() - readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
  • readline_callback_read_char() - 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

readline_callback_read_char

(PHP 5 >= 5.1.0)

readline_callback_read_char — 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

説明

void readline_callback_read_char ( void )

ユーザーが入力した文字を読み込みます。改行を受け取ると、この関数は readline_callback_handler_install() で インストールされた readline コールバックインターフェイスに対して 入力待ちを通知します。

返り値

値を返しません。

例

readline コールバックインターフェイスの使用方法についての例は readline_callback_handler_install() を参照ください。

参考

readline_clear_history

(PHP 4, PHP 5)

readline_clear_history — ヒストリをクリアする

説明

bool readline_clear_history ( void )

この関数はコマンドラインヒストリ全体をクリアします。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

readline_completion_function

(PHP 4, PHP 5)

readline_completion_function — 補完関数を登録する

説明

bool readline_completion_function ( callable $function )

この関数は補完用の関数を登録します。 これは、Bash を使用している際に、タブキーを 押して得られるのと同様の機能です。

パラメータ

function

コマンドラインの一部を入力とし、 マッチする可能性がある文字列の配列を返す 既存の関数の名前を指定する必要があります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

readline_info

(PHP 4, PHP 5)

readline_info — 種々の readline の内部変数を取得/設定する

説明

mixed readline_info ([ string $varname [, string $newvalue ]] )

さまざまな readline の内部変数の取得あるいは設定を行います。

パラメータ

varname

変数の名前。

newvalue

指定した場合は、これがその設定の新しい値となります。

返り値

パラメータを指定しないでコールした場合、この関数は readline が使用する すべての設定の値を配列で返します。要素の添字は次のようになります。 done, end, erase_empty_line, library_version, line_buffer, mark, pending_input, point, prompt, readline_name, terminal_name

ひとつあるいはふたつのパラメータを指定してコールした場合は、 元の値が返されます。

readline_list_history

(PHP 4, PHP 5)

readline_list_history — ヒストリを一覧表示する

説明

array readline_list_history ( void )

コマンドラインヒストリ全体を取得します。

返り値

コマンドラインヒストリ全体の配列を返します。 各要素にはゼロから始まる整数の添字が付加されています。

readline_on_new_line

(PHP 5 >= 5.1.0)

readline_on_new_line — カーソルが新しい行に移動したことを readline に通知する

説明

void readline_on_new_line ( void )

readline に、カーソルが新しい行に移動したことを通知します。

返り値

値を返しません。

readline_read_history

(PHP 4, PHP 5)

readline_read_history — ヒストリを読み込む

説明

bool readline_read_history ([ string $filename ] )

この関数は、コマンドヒストリをファイルから読み込みます。

パラメータ

filename

コマンドヒストリを含むファイルへのパス。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

readline_redisplay

(PHP 5 >= 5.1.0)

readline_redisplay — 画面を再描画する

説明

void readline_redisplay ( void )

画面の再描画を readline に依頼します。

返り値

値を返しません。

readline_write_history

(PHP 4, PHP 5)

readline_write_history — ヒストリを書きこむ

説明

bool readline_write_history ([ string $filename ] )

この関数はコマンドヒストリをファイルに書き込みます。

パラメータ

filename

保存するファイルへのパス。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

readline

(PHP 4, PHP 5)

readline — 一行読み込む

説明

string readline ([ string $prompt ] )

ユーザーからの入力を一行読み込みます。 この行を readline_add_history(). を用いてヒストリに追加する必要があります。

パラメータ

prompt

ユーザーに示す確認文字列を指定します。

返り値

ユーザーから取得した文字列を一つだけ返します。 返り値の最後の改行は取り除かれます。

例

例1 readline() の例

<?php
// ユーザーから 3 回コマンドを取得
for ($i=0; $i < 3; $i++) {
        $line = readline("Command: ");
        readline_add_history($line);
}

// ヒストリをダンプ
print_r(readline_list_history());

// 変数をダンプ
print_r(readline_info());
?>

目次

圧縮およびアーカイブ

Bzip2

導入

bzip2関数は、bzip2 (.bz2) 圧縮されたファイルを透過的に読み書きするために使用します。

インストール/設定

目次

要件

このモジュールは、Julian Seward により作成された » bzip2ライブラリの関数を使用しています。 このモジュールは、bzip2/libbzip2 のバージョン >= 1.0.x を必要とします。

インストール手順

PHP の bzip2 サポートはデフォルトでは有効となっていません。 bzip2 サポートを有効とするには、PHP をコンパイルする際に設定オプション --with-bz2[=DIR] を使用する必要があります。

実行時設定

設定ディレクティブは定義されていません。

リソース型

この拡張モジュールは、リソース型として処理を行う bz2 ファイルを指すファイルポインタを定義します。

定義済み定数

定数は定義されていません。

例

この例は、テンポラリファイルをオープンし、テスト用の文字列を書き込みます。 この後、このファイルの内容を出力します。

例1 簡単な bzip2 の例

<?php

$filename = "/tmp/testfile.bz2";
$str = "This is a test string.\n";

// 書き込み用にオープン
$bz = bzopen($filename, "w");

// ファイルに文字列を書き込む
bzwrite($bz, $str);

// ファイルを閉じる
bzclose($bz);

// 読み込み用にファイルをオープン
$bz = bzopen($filename, "r");

// 10文字読み込む
echo bzread($bz, 10);

// ファイルの終端まで出力(または次の1024文字)し、閉じる
echo bzread($bz);

bzclose($bz);

?>

Bzip2 関数

bzclose

(PHP 4 >= 4.0.4, PHP 5)

bzclose — bzip2 ファイルを閉じる

説明

int bzclose ( resource $bz )

与えられた bzip2 ファイルポインタを閉じます。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

  • bzopen() - bzip2 圧縮されたファイルをオープンする

bzcompress

(PHP 4 >= 4.0.4, PHP 5)

bzcompress — 文字列をbzip2形式のデータに圧縮する

説明

mixed bzcompress ( string $source [, int $blocksize = 4 [, int $workfactor = 0 ]] )

bzcompress() は、与えられた文字列を圧縮し、 bzip2 形式のデータとして返します。

パラメータ

source

圧縮する文字列

blocksize

圧縮時のブロック長を指定します。 1 から 9 の数とする必要があります。この場合、9 の圧縮度が最大ですが、リソースの消費量も最大となります。

workfactor

繰り返しが多い、最悪の入力データの場合の圧縮処理の動作を制御します。 この値は、0 から 250 までとなり、0 は特別な場合です。

workfactor によらず、 生成される出力は同じになります。

返り値

圧縮された文字列、もしくはエラー時はエラー数

例

例1 データの圧縮

<?php
$str = "sample data";
$bzstr = bzcompress($str, 9);
echo $bzstr;
?>

参考

bzdecompress

(PHP 4 >= 4.0.4, PHP 5)

bzdecompress — bzip2 形式のデータを解凍する

説明

mixed bzdecompress ( string $source [, int $small = 0 ] )

bzdecompress() は、bzip2 形式のデータを含む文字列を解凍します。

パラメータ

source

解凍する文字列

small

TRUE の場合、よりメモリの消 費量が少ない (所要メモリは最大2300K程度まで少なくなります) 別の圧縮アルゴリズムが使用されますが、速度は約半分になってしまいます。

この機能に関する詳細については、» bzip2 ドキュメント を参照ください。

返り値

解凍された文字列列、もしくはエラー時はエラー数

例

例1 文字列を解凍する

<?php
$start_str = "This is not an honest face?";
$bzstr = bzcompress($start_str);

echo "Compressed String: ";
echo $bzstr;
echo "\n<br />\n";

$str = bzdecompress($bzstr);
echo "Decompressed String: ";
echo $str;
echo "\n<br />\n";
?>

参考

  • bzcompress() - 文字列をbzip2形式のデータに圧縮する

bzerrno

(PHP 4 >= 4.0.4, PHP 5)

bzerrno — bzip2 エラー番号を返す

説明

int bzerrno ( resource $bz )

与えられたファイルポインタから返された bzip2 エラーのエラー番号を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

整数としてのエラー番号を返します。

参考

  • bzerror() - bzip2 エラー番号とエラー文字列を配列で返す
  • bzerrstr() - bzip2 エラー文字列を返す

bzerror

(PHP 4 >= 4.0.4, PHP 5)

bzerror — bzip2 エラー番号とエラー文字列を配列で返す

説明

array bzerror ( resource $bz )

与えられたファイルポインタから返された bzip2 エラーのエラー番号とエラー文字列を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

errno エントリにエラーコード、errstr エントリにエラーメッセージを持つ連想配列を返します。

例

例1 bzerror() の例

<?php
$error = bzerror($bz);

echo $error["errno"];
echo $error["errstr"];
?>

参考

bzerrstr

(PHP 4 >= 4.0.4, PHP 5)

bzerrstr — bzip2 エラー文字列を返す

説明

string bzerrstr ( resource $bz )

与えられたファイルポインタから返された bzip2 エラーのエラーの文字列を返します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

エラーメッセージを含む文字列を返します。

参考

  • bzerrno() - bzip2 エラー番号を返す
  • bzerror() - bzip2 エラー番号とエラー文字列を配列で返す

bzflush

(PHP 4 >= 4.0.4, PHP 5)

bzflush — 全てのバッファリングされたデータを強制的に書き込む

説明

int bzflush ( resource $bz )

バッファリングされた全ての bzip2 データをファイルポインタ bz に書き込みます。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

参考

  • bzread() - バイナリ対応の bzip2 ファイル読み込み
  • bzwrite() - バイナリ対応の bzip2 ファイルへの書き込み

bzopen

(PHP 4 >= 4.0.4, PHP 5)

bzopen — bzip2 圧縮されたファイルをオープンする

説明

resource bzopen ( string $filename , string $mode )

bzopen() は、 bzip2 (.bz2) ファイルを読み書き用にオープンします。

パラメータ

filename

オープンするファイル名

mode

fopen() 関数と同様ですが、 'r' (読み込み) と 'w' (書き込み) だけをサポートしています。 それ以外を指定すると bzopen は FALSE を返します。

返り値

オープンできなかった場合、bzopen() は FALSE を返します。それ以外の場合は、 新規にオープンされたファイルへのポインタが返されます。

例

例1 bzopen() の例

<?php

$file = "/tmp/foo.bz2";
$bz = bzopen($file, "r") or die("Couldn't open $file for reading");

bzclose($bz);

?>

参考

bzread

(PHP 4 >= 4.0.4, PHP 5)

bzread — バイナリ対応の bzip2 ファイル読み込み

説明

string bzread ( resource $bz [, int $length = 1024 ] )

bzread() は、与えられた bzip2 ファイルポインタから読み込みます。

読み込みは、(圧縮前の状態で) length バイトが読み込まれたか、EOF に達したかのどちらか最初に来た方で終了します。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

length

指定されない場合、bzread() は一度に (圧縮前の状態で) 1024バイト読み込みます。 最大で 8192 バイト (圧縮前) までを一度に読み込みます。

返り値

非圧縮データ、もしくはエラー時に FALSE を返します。

例

例1 bzread() の例

<?php

$file = "/tmp/foo.bz2";
$bz = bzopen($file, "r") or die("Couldn't open $file");

$decompressed_file = '';
while (!feof($bz)) {
  $decompressed_file .= bzread($bz, 4096);
}
bzclose($bz);

echo "The contents of $file are: <br />\n";
echo $decompressed_file;

?>

参考

  • bzwrite() - バイナリ対応の bzip2 ファイルへの書き込み
  • feof() - ファイルポインタがファイル終端に達しているかどうか調べる
  • bzopen() - bzip2 圧縮されたファイルをオープンする

bzwrite

(PHP 4 >= 4.0.4, PHP 5)

bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

説明

int bzwrite ( resource $bz , string $data [, int $length ] )

bzwrite() は、文字列を与えられた bzip2 ファイルストリームに書き込みます。

パラメータ

bz

ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

data

書き込むデータ

length

指定した場合、 (圧縮前の) length バイト分の書き込みが終ったか、 data の終端に達したかで書き込みは終了します。

返り値

書き込んだバイト数、もしくはエラー時に FALSE を返します。

例

例1 bzwrite() の例

<?php
$str = "uncompressed data";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>

参考

  • bzread() - バイナリ対応の bzip2 ファイル読み込み
  • bzopen() - bzip2 圧縮されたファイルをオープンする

目次

  • bzclose — bzip2 ファイルを閉じる
  • bzcompress — 文字列をbzip2形式のデータに圧縮する
  • bzdecompress — bzip2 形式のデータを解凍する
  • bzerrno — bzip2 エラー番号を返す
  • bzerror — bzip2 エラー番号とエラー文字列を配列で返す
  • bzerrstr — bzip2 エラー文字列を返す
  • bzflush — 全てのバッファリングされたデータを強制的に書き込む
  • bzopen — bzip2 圧縮されたファイルをオープンする
  • bzread — バイナリ対応の bzip2 ファイル読み込み
  • bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

LZF

導入

LZF は非常に高速な圧縮アルゴリズムで、わずかな速度の低下と引き換えに スペースを節約したい場合に適しています。 コンパイル時に速度もしくはスペースのどちらを優先して最適化を行うかを 選択することができます。この拡張モジュールは、Marc Lehmann による » liblzf ライブラリを用いて操作を行います。

インストール/設定

目次

要件

外部ライブラリを必要としません。

インストール手順

この » PECL 拡張 モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » http://pecl.php.net/package/lzf.

これらの関数を使用するには、--with-lzf[=DIR] オプションを指定して PHP を lzf サポートつきでコンパイルする必要があります。 --enable-lzf-better-compression を指定して、 圧縮速度より圧縮率を優先するよう LZF を設定することも可能です。

Windows ユーザーは、php.ini で php_lzf.dll を有効にすることでこれらの関数を使用可能です。 この PECL 拡張モジュールの DLL は、現在存在しません。 Windows でのビルド も参照ください

実行時設定

設定ディレクティブは定義されていません。

リソース型

リソース型は定義されていません。

定義済み定数

定数は定義されていません。

LZF 関数

lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — LZF 圧縮を行う

説明

string lzf_compress ( string $data )

lzf_compress() は、指定された arg を LZF 符号化方式で圧縮します。

パラメータ

data

圧縮するデータ。

返り値

圧縮されたデータを返します。エラー時には FALSE を返します。

参考

lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — LZF 圧縮を伸長する

説明

string lzf_decompress ( string $data )

lzf_decompress() は、lzf で符号化された文字列を含む data を伸長します。

パラメータ

data

圧縮されたデータ。

返り値

伸長したデータを返します。エラー時には FALSE を返します。

参考

lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する

説明

int lzf_optimized_for ( void )

LZF 拡張モジュールが圧縮時に使用した最適化指定を取得します。

返り値

LZF が速度に最適化されている場合に 1、圧縮率に最適化されている場合に 0 を返します。

目次

Phar

導入

phar 拡張モジュールは、PHP アプリケーション全体をひとつの "phar" (PHP Archive) ファイルにまとめてしまい、配布やインストールを容易にするためのものです。 それだけでなく、phar 拡張モジュールではファイルフォーマットを抽象化する機能も提供しており、 tar 形式や zip 形式のファイルを PharData クラスで扱うことができます。ちょうど PDO がさまざまなデータベースへの統一インターフェイスを用意しているのと同じようなものです。 PDO では異なるデータベース間の変換はできませんが、 phar では tar、zip、phar ファイルフォーマット間の変換がコード 1 行だけでできてしまいます。 例として Phar::convertToExecutable() を参照ください。

Phar って何? Phar アーカイブは、複数のファイルをひとつにまとめるための便利な仕組みです。 Phar アーカイブを使用すれば、PHP のアプリケーションをひとつのファイルとして配布できるようになります。 また、それをディスク上に展開しなくてもそのまま実行できるのです。 さらに、他のファイルと同様に PHP から phar アーカイブを実行することができます。 コマンドラインとウェブサーバー経由のどちらでも実行可能です。 phar は、いわば PHP アプリケーションにおける thumb drive のようなものです。

Phar はこの機能を実装するために ストリームラッパー を使用しています。通常は、PHP スクリプトから外部のファイルを使用するには include を用います。

例1 外部ファイルの使用

<?php
 include '/path/to/external/file.php';
 ?>

PHP は、実際には /path/to/external/file.php をストリームラッパー file:///path/to/external/file.php とみなし、 内部的にはファイルストリームラッパーのストリーム関数でローカルファイルにアクセスしています。

Phar アーカイブ /path/to/myphar.phar の中に含まれるファイル file.php を使用する場合に構文は、 先ほどの file:// 構文と似ています。

例2 Phar アーカイブ内のファイルの使用

<?php
 include 'phar:///path/to/myphar.phar/file.php';
 ?>

実際のところ、phar アーカイブは外部ディスクと同様に扱うことができます。 fopen() 系の関数や opendir()、そして mkdir() 系の関数を使用して、 phar アーカイブ内のファイルの読み書きや新しいファイルの作成が可能です。 これにより、完全な PHP アプリケーションを単一のファイルで配布して そのままの形式で直接実行できるようになるのです。

Phar アーカイブのもっとも一般的な使用法は、 完全なアプリケーションをひとつのファイルにまとめて配布することです。 たとえば、PHP に同梱されている PEAR インストーラは phar アーカイブとして配布されています。 このような形式の phar アーカイブを使用するには、 コマンドラインあるいはウェブサーバーからアーカイブを実行します。

Phar アーカイブの配布形式は tar アーカイブか zip アーカイブ、あるいは専用の phar 独自ファイルフォーマットのいずれかとなります。 それぞれの形式には利点と欠点があります。 tar 形式や zip 形式は、他のツールからでも内容を読んだり展開したりできるという利点がありますが、 それを実行する環境にも phar 拡張モジュールが必要となります。 phar 独自フォーマットは phar 拡張モジュール独自の形式です。 phar 拡張モジュールか PEAR パッケージ » PHP_Archive にしか作成できません。しかし、この形式で作成したアプリケーションは phar 拡張モジュールのない環境でも動作するという利点があります。

言い換えると、phar 拡張モジュールが無効になっている環境でも phar アーカイブを実行できるということです。 しかし、phar アーカイブ内の個別のファイルにアクセスするには、 (PHP_Archive で作成したものでない限り) phar 拡張モジュールが必要です。

phar 拡張モジュールには、tar ファイルを zip 形式や phar 形式に変換する機能もあります。

例3 phar 形式から tar 形式への phar アーカイブの変換

<?php
 $phar = new Phar('myphar.phar');
 $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // myphar.phar.tar.gz を作成します
 ?>

phar には、特定のファイルあるいはアーカイブ全体を gzip あるいは bzip2 で圧縮する機能があります。 また、アーカイブの整合性を md5()、 sha1()、sha256() あるいは sha512() シグネチャで自動的に検証します。

最後に、phar 拡張モジュールはセキュリティにも注意を払っており、 実行可能な phar アーカイブへの書き込みアクセスはデフォルトで無効にしています。 phar アーカイブを作成したり変更したりするには、php.ini の設定 phar.readonly をシステムレベルで無効にする必要があります。 通常の、実行可能属性がない tar アーカイブや zip アーカイブは、常に PharData クラスで作成、変更することができます。

アプリケーションを配布したい場合は Phar アーカイブのつくりかた を読みましょう。phar がサポートする各形式の違いをより詳しく知りたい場合は Phar、Tar そして Zip を読みましょう。

phar 形式のアプリケーションを使用したい場合は Phar アーカイブの使いかた が参考となるでしょう。

phar という単語は PHP と Archive を組み合わせたもので、 Java 開発者ならおなじみの jar (Java Archive) を参考にしています。

Phar アーカイブの実装は PEAR の » PHP_Archive パッケージに基づいています。実装の詳細は同じですが、 Phar 拡張モジュールのほうがずっと強力です。 さらに、Phar 拡張モジュールで作成した PHP アプリケーションは ほとんどの場合は何も修正せずに動かすことができます。 PHP_Archive で作った phar アーカイブは、 動かす前に多少手を入れなければならないことがよくあります。

インストール/設定

目次

要件

Phar を使用するには PHP 5.2.0 以降が必要です。また、 Phar ファイルの中身に対して配列形式でアクセスしたり順に処理したりするには SPL 拡張モジュールが PHP に組み込まれている必要があります。 phar ストリームを使用するには、 これは不要です。

オプションとして、zlib 拡張モジュールおよび bzip2 拡張モジュールを有効にしておくと、 圧縮された phar をサポートすることができます。 さらに、OpenSSL の署名を使用するには、OpenSSL 拡張モジュールを有効にする必要があります。

zlib.deflate ストリームフィルタのバグのせいで、gzip 圧縮形式あるいは bzip2 圧縮形式の phar アーカイブが切り詰められてしまう可能性があることに注意しましょう。 このバグは PHP 5.2.6 以降で修正されます。

インストール手順

PHP 5.3.0 以降 Phar 拡張モジュールは組み込みとなりました。 それより前のバージョンの PHP では PECL 拡張モジュールとしてインストールできます。 » PECL の Phar のページ には詳しい情報や過去の歴史があります。

Windows ユーザーがこの拡張モジュールを使うには、php.ini に php_phar.dll を含めなければなりません。

実行時設定

php.ini の設定により動作が変化します。

ファイルシステムおよびストリームの設定オプション
名前 デフォルト 変更可能 変更履歴
phar.readonly "1" PHP_INI_ALL  
phar.require_hash "1" PHP_INI_ALL  
phar.extract_list "" PHP_INI_ALL phar 1.1.0 から 1.2.3 で使用可能、2.0.0 で削除
phar.cache_list "" PHP_INI_SYSTEM phar 2.0.0 以降で使用可能

以下に設定ディレクティブに関する 簡単な説明を示します。

phar.readonly boolean

このオプションを使用すると、phar ストリームや Phar オブジェクトによる Phar アーカイブの作成や変更ができなくなります。 この設定は、実運用環境では常に有効にしておくべきです。 phar 拡張モジュールのこの機能は、 サーバー上に他のセキュリティ上の脆弱性があった場合に php ベースのウィルスを直接作成されてしまうことにつながります。

注意:

この設定は、セキュリティ上の理由により php.ini でしか解除できません。 phar.readonly を php.ini で無効にした場合は、 ユーザーがスクリプト内で phar.readonly の有効/無効を切りかえることができます。 phar.readonly を php.ini で有効にした場合は、 スクリプト内でこれを "再度有効にする" ことはできますが、無効にすることはできません。

phar.require_hash boolean

このオプションを使用すると、署名つき (現在サポートしているのは MD5、SHA1、SHA256 および SHA512) の Phar アーカイブのみをオープンするようになります。 署名を含まない Phar アーカイブの処理はできません。

注意:

この設定は、セキュリティ上の理由により php.ini でしか解除できません。 phar.require_hash を php.ini で無効にした場合は、 ユーザーがスクリプト内で phar.require_hash の有効/無効を切りかえることができます。 phar.require_hash を php.ini で有効にした場合は、 スクリプト内でこれを "再度有効にする" ことはできますが、無効にすることはできません。

この設定は、 PharData クラスで通常の tar ファイルを読み込む際には影響を及ぼしません。

phar.extract_list string

この INI 設定は phar 2.0.0 で削除されました。

phar アーカイブへのフルパスあるいはそのエイリアスと、 展開されたファイルの場所との関連付けを行います。 パラメータの書式は name=archive,name2=archive2 のようになります。 phar ファイルをディスクに展開して、 展開したファイル群へのマッパーとして phar を扱えるようになります。 これを行うのは、たとえばパフォーマンスを向上させたい場合や phar のデバッグを行いたい場合などです。

例1 phar.extract_list の使用例

php.ini で、次のように記述します
phar.extract_list = archive=/full/path/to/archive/,arch2=/full/path/to/arch2
<?php
include "phar://archive/content.php";
include "phar://arch2/foo.php";
?>

phar.cache_list string

この INI 設定は phar 2.0.0 で追加されました。

phar アーカイブをウェブサーバーの起動時に事前にパースさせるようにします。 これによりパフォーマンスが向上し、 ディスク上に配置した伝統的なファイルに近い速度で実行することができます。

例2 phar.cache_list の使用例

php.ini (windows):
phar.cache_list =C:\path\to\phar1.phar;C:\path\to\phar2.phar
php.ini (unix):
phar.cache_list =/path/to/phar1.phar:/path/to/phar2.phar

リソース型

Phar 拡張モジュールで使用するリソースは phar ストリームで、これにより、phar 内のファイルへの透過的なアクセスが可能となります。 Phar ファイルフォーマットについての説明 も参照ください。

定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Phar 圧縮定数
定数 値 説明
Phar::NONE (integer) 0x00000000 圧縮しない
Phar::COMPRESSED (integer) 0x0000F000 そのファイルが既に何らかの形式で圧縮されているかどうかを表すフラグとして用いるビットマスク
Phar::GZ (integer) 0x00001000 zlib (gzip) 圧縮
Phar::BZ2 (integer) 0x00002000 bzip2 圧縮
Phar ファイル形式定数
定数 値 説明
Phar::SAME (integer) 0 同じファイル形式を維持する
Phar::PHAR (integer) 1 phar ファイル形式
Phar::TAR (integer) 2 tar ファイル形式
Phar::ZIP (integer) 3 zip ファイル形式
Phar 署名定数
定数 値 説明
Phar::MD5 (integer) 0x0001 md5 ハッシュアルゴリズムでの署名
Phar::SHA1 (integer) 0x0002 sha1 ハッシュアルゴリズムでの署名
Phar::SHA256 (integer) 0x0003 sha256 ハッシュアルゴリズムでの署名 (hash 拡張モジュールが必要)
Phar::SHA512 (integer) 0x0004 sha512 ハッシュアルゴリズムでの署名 (hash 拡張モジュールが必要)
Phar::OPENSSL (integer) 0x0010 OpenSSL 公開鍵/秘密鍵 ペアでの署名。真の意味での非対称鍵による署名。
Phar webPhar mime オーバーライド定数
定数 値 説明
Phar::PHP (integer) 1 Phar::webPhar() の mimeoverrides パラメータに対して、その拡張子を PHP ファイルとしてパースするよう指示する
Phar::PHPS (integer) 2 Phar::webPhar() の mimeoverrides パラメータに対して、その拡張子を PHP ファイルとしてパースして highlight_file() を通すよう指示する

Phar アーカイブの使用法

目次

Phar アーカイブの使用法: 導入

Phar アーカイブは Java の JAR アーカイブと似た概念のものですが、 PHP アプリケーションで使用する際に必要な機能をより柔軟に使用できるよう改良しています。 Phar アーカイブを使用すると、PHP アプリケーションやライブラリを ひとつのファイルにまとめて配布できるようになります。 Phar アーカイブ形式のアプリケーションは、その他の PHP アプリケーションとまったく同様に扱えます。 

php coolapplication.phar

Phar アーカイブ形式のライブラリを使用する方法も、 その他の通常の PHP ライブラリとまったく同じです。

<?php
include 'coollibrary.phar';
?>

phar ストリームラッパーは phar 拡張モジュールの要となるものです。 詳細については こちら で説明します。このストリームラッパーを使用すると、 phar 内の個々のファイルに対して fopen() や opendir() といった標準のファイル操作関数を使用でき、 まるで通常のファイルシステム上にあるのと同じような感覚でアクセスできます。 phar ストリームラッパーは、 ファイルやディレクトリに対する読み書き操作をすべてサポートしています。

<?php
include 'phar://coollibrary.phar/internal/file.php';
header('Content-type: image/jpeg');
// phar にアクセスするには、フルパスあるいはエイリアスを使用します
echo file_get_contents('phar:///fullpath/to/coollibrary.phar/images/wow.jpg');
?>

Phar クラスでは、 ファイルへのアクセスや phar アーカイブ作成用により高度な機能も実装しています。 Phar クラスについての説明は こちら をご覧ください。

<?php
try {
    // 既存の phar をオープンします
    $p = new Phar('coollibrary.phar', 0);
    // Phar は SPL の DirectoryIterator クラスを継承しています
    foreach (new RecursiveIteratorIterator($p) as $file) {
        // $file は PharFileInfo クラスで、これは SplFileInfo を継承しています
        echo $file->getFileName() . "\n";
        echo file_get_contents($file->getPathName()) . "\n"; // 内容を表示します
    }
    if (isset($p['internal/file.php'])) {
        var_dump($p['internal/file.php']->getMetadata());
    }

    // 新しい phar の作成 - php.ini で phar.readonly を 0 にしておく必要があります。
    // phar.readonly は、セキュリティ上の理由によってデフォルトで有効になっています。
    // 実際の運用サーバーでは、決して Phar を作成する必要はないはずで、
    // 単に実行できるだけでよいはずです。
    if (Phar::canWrite()) {
        $p = new Phar('newphar.tar.phar', 0, 'newphar.tar.phar');
        // tar 形式の phar アーカイブを作成し、gzip で圧縮します (.tar.gz)
        $p = $p->convertToExecutable(Phar::TAR, Phar::GZ);

        // トランザクションの作成 - newphar.phar には、
        // stopBuffering() がコールされるまで (一時的なストレージが必要となっても) なにも書き込まれません
        $p->startBuffering();
        // すべてのファイルを /path/to/project に追加し、プレフィックス "project" で phar に保存します
        $p->buildFromIterator(new RecursiveIteratorIterator(new DirectoryIterator('/path/to/project')), '/path/to/');

        // 配列形式の API で新しいファイルを追加します
        $p['file1.txt'] = 'Information';
        $fp = fopen('hugefile.dat', 'rb');
        // すべてのデータをストリームからコピーします
        $p['data/hugefile.dat'] = $fp;

        if (Phar::canCompress(Phar::GZ)) {
            $p['data/hugefile.dat']->compress(Phar::GZ);
        }

        $p['images/wow.jpg'] = file_get_contents('images/wow.jpg');
        // ファイルのメタデータには任意の値を保存できます
        $p['images/wow.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
        $p['index.php'] = file_get_contents('index.php');
        $p->setMetadata(array('bootstrap' => 'index.php'));

        // phar アーカイブをディスクに保存します
        $p->stopBuffering();
    }
} catch (Exception $e) {
    echo 'Phar をオープンできません: ', $e;
}
?>

さらに、phar ファイルの中身の検証を行うこともできます。対称型ハッシュアルゴリズム (MD5、SHA1、SHA256、そしてもし ext/hash が有効ならさらに SHA512) のいずれか、 あるいは OpenSSL を使用した非対称公開鍵/秘密鍵ペアによる署名 (Phar 2.0.0 の新機能) のいずれかを使用します。OpenSSL による署名を使用するには、 まず公開鍵/秘密鍵のペアを作成し、秘密鍵を使用して Phar::setSignatureAlgorithm() で署名を行います。 公開キーによる展開はこのようなコードで行います。

<?php
$public = openssl_get_publickey(file_get_contents('private.pem'));
$pkey = '';
openssl_pkey_export($public, $pkey);
?>
公開鍵は phar アーカイブと同じ場所、名前でなければなりません。つまり、phar アーカイブの保存先が /path/to/my.phar の場合は公開鍵を /path/to/my.phar.pubkey としなければなりません。 そうしないと、OpenSSL 署名の検証ができなくなります。

バージョン 2.0.0 以降、Phar には 3 つの静的メソッド Phar::webPhar()、 Phar::mungServer() そして Phar::interceptFileFuncs() が追加されました。これは、通常のファイルシステム用あるいはウェブアプリケーション用の PHP アプリケーションのパッケージを作成する際に重要となります。 Phar::webPhar() は、HTTP のコールを phar アーカイブ内の特定の場所に転送するフロントコントローラを実装します。 Phar::mungServer() は $_SERVER 配列の中身をうまく変更して アプリケーションでその値を使えるようにします。 Phar::interceptFileFuncs() は、 fopen() や file_get_contents()、opendir() そしてすべての stat 系関数 (file_exists()、is_readable() など) のコールを Phar が横取りして、相対パスを phar アーカイブ内の適切な位置に変換するようにします。

たとえば、あの有名な phpMyAdmin を phar アーカイブにすることを考えてみましょう。 必要なのは、こんな単純なスクリプトだけです。あとは、 ユーザー名とパスワードを変更してウェブサーバー上から phpMyAdmin.phar.tar.php にアクセスするだけで利用できます。

<?php
@unlink('phpMyAdmin.phar.tar.php');
copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
$a = new Phar('phpMyAdmin.phar.tar.php');
$a->startBuffering();
$a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
/* サーバーの設定 */
$i = 0;

/* Server localhost (config:root) [1] */
$i++;
$cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
$cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
$cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
$cfg[\'Servers\'][$i][\'compress\'] = false;
$cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
$cfg[\'Servers\'][$i][\'user\'] = \'root\';
$cfg[\'Servers\'][$i][\'password\'] = \'\';


/* サーバーの設定はここまで */
if (strpos(PHP_OS, \'WIN\') !== false) {
    $cfg[\'UploadDir\'] = getcwd();
} else {
    $cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
    @mkdir(\'/tmp/pharphpmyadmin\');
    @chmod(\'/tmp/pharphpmyadmin\', 0777);
}';
$a->setStub('<?php
Phar::interceptFileFuncs();
Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
echo "phpMyAdmin is intended to be executed from a web browser\n";
exit -1;
__HALT_COMPILER();
');
$a->stopBuffering();
?>

Phar アーカイブの使用法: phar ストリームラッパー

Phar ストリームラッパーは、fopen() による読み込みや 書き込み (追記は除く)、unlink()、stat()、 fstat()、fseek()、rename() そしてディレクトリに対する opendir() といった機能に完全に対応しています。 バージョン 2.0.0 以降では rmdir() や mkdir() にも対応します。

Phar アーカイブ内の各ファイルの圧縮やファイル単位のメタデータの操作も、 ストリーム上で可能です。

<?php
$context = stream_context_create(array('phar' =>
                                    array('compress' => Phar::GZ)),
                                    array('metadata' => array('user' => 'cellog')));
file_put_contents('phar://my.phar/somefile.php', 0, $context);
?>

phar ストリームラッパーは、 リモートファイルを操作することはできません。つまり、INI 設定 allow_url_fopen および allow_url_include が無効になっている場合でも使用できます。

ストリーム操作だけで新しい phar アーカイブをゼロから作成することも可能ですが、 そんな場合は Phar クラスの組み込み機能を使用するほうが便利です。 ストリームラッパーが有用なのは、読み込み専用の操作を行う場合です。

Phar アーカイブの使用法: Phar クラスおよび PharData クラス

Phar クラスは Phar アーカイブの読み込みや操作をサポートしています。 また RecursiveDirectoryIterator クラスを継承しているため、順次処理も可能です。 ArrayAccess インターフェイスをサポートしているので、 Phar アーカイブ内のファイルに対して、 それがまるで連想配列であるかのようにアクセスすることができます。

PharData クラスは Phar を継承したもので、実行可能でない (データ) tar アーカイブおよび zip アーカイブなら php.ini で phar.readonly=1 であっても作成/変更できるようになります。 このクラスでは PharData::setAlias() と PharData::setStub() は使用不可能になっています。というのもエイリアスやスタブというのは 実行可能な phar アーカイブに独特の概念だからです。

注意すべき点は、Phar アーカイブを作成する際には Phar のコンストラクタに フルパスを渡さなければならないということです。 相対パスでは初期化に失敗します。

$p が、次のように作成した Phar オブジェクトであるとしましょう。

<?php
$p = new Phar('/path/to/myphar.phar', 0, 'myphar.phar');
?>

空の Phar アーカイブが /path/to/myphar.phar に作成されます。もし /path/to/myphar.phar が既に存在する場合は、それを再度オープンします。 リテラル myphar.phar は、エイリアスを表します。 これを用いると、URL で /path/to/myphar.phar を参照する際に次のようにできます。

<?php
// これらのふたつの file_get_contents() コールが同等となるのは、
// /path/to/myphar.phar のマニフェストでエイリアス "myphar.phar"
// が明示的に指定されている場合か、先ほどの例のように
// Phar オブジェクトを初期化した場合です。
$f = file_get_contents('phar:///path/to/myphar.phar/whatever.txt');
$f = file_get_contents('phar://myphar.phar/whatever.txt');
?>

新しく作成した Phar オブジェクト $p に対して、次のような処理が可能となります。

  • $a = $p['file.php'] とすると、 phar://myphar.phar/file.php の中身を参照する PharFileInfo クラスが作成されます。
  • $p['file.php'] = $v とすると、 myphar.phar の中に新しいファイル (phar://myphar.phar/file.php) を作成するか、あるいは同名のファイルを上書きします。 $v には、文字列あるいはファイルポインタのいずれかを指定できます。 ファイルポインタを指定した場合は、その中身全体をもとにして新しいファイルを作成します。 $p->addFromString('file.php', $v) は、 機能的に上と同じであることに注意しましょう。また、ファイルの中身を $p->addFile('/path/to/file.php', 'file.php') で追加することもできます。最後に、空のディレクトリを作成するには $p->addEmptyDir('empty') とします。
  • isset($p['file.php']) とすると、phar://myphar.phar/file.php が myphar.phar の中に存在するかどうかがわかります。
  • unset($p['file.php']) とすると、 phar://myphar.phar/file.php を myphar.phar から削除します。

さらに、Phar 固有のメタデータにアクセスするためには Phar オブジェクトを使用することが唯一の方法となります。そのためには Phar::getMetadata() を使用します。また、Phar アーカイブの PHP ローダスタブを設定したり取得したりするための唯一の方法が Phar::getStub() および Phar::setStub() です。 また、Phar アーカイブ全体の圧縮を行うには Phar クラスが必要となります。

Phar オブジェクトの全機能の一覧については、以下で説明します。

PharFileInfo クラスは SplFileInfo クラスを継承しており、Phar 内のファイルについての Phar 固有の情報 (圧縮情報やメタデータなど) を扱うためのメソッドが追加されています。

Phar アーカイブの作成

目次

Phar アーカイブの作成: 導入

そのうちにきちんと書きます。今のところは、とりあえず Phar アーカイブの使用法 を読んでおいてください。

まず最初のとっかかりとしては Phar::buildFromIterator() を読むといいでしょう。そして、アーカイブで使用できる ファイル形式 の詳細を確認します。 phar アーカイブを作成するには、スタブについてきちんと理解しておくことが大切です。 そのためには Phar::setStub() と Phar::createDefaultStub() を調べるといいでしょう。 ウェブアプリケーションを配布しようと考えているのなら、 Phar::webPhar() と Phar::mungServer() について調べてみましょう。 アーカイブ内のファイルにアクセスするアプリケーションを作成する場合は Phar::interceptFileFuncs() の使用を検討しましょう。

phar って、tar や zip とは何が違うの?

目次

Phar アーカイブの原料のうち、ファイル形式に依存しないもの

すべての Phar アーカイブは、三つあるいは四つの部分から構成されています。

  1. スタブ

  2. 内容を説明するマニフェスト

  3. ファイルの内容

  4. [オプション] Phar の整合性を検証するためのシグネチャ (phar 形式の場合のみ)

Phar ファイルのスタブ

Phar のスタブは、単純な PHP ファイルです。必要最小限のスタブは、次のようになります。

<?php __HALT_COMPILER();

スタブには、少なくとも __HALT_COMPILER(); トークンが必要です。 典型的なスタブは、次のように読み込み機能を含んでいます。

<?php
Phar::mapPhar();
include 'phar://myphar.phar/index.php';
__HALT_COMPILER();

Phar スタブの内容には特に制限はありません。唯一の制約は、最後が __HALT_COMPILER(); でなければならないということです。 PHP の終了タグ 

?>
は含めても含めなくてもかまいません。 しかし、; と終了タグ 
?>
 の間にはひとつ以上の空白を含めてはいけません。 もしそうしてしまうと、phar 拡張モジュールは その Phar アーカイブのマニフェストを処理できなくなります。

tar 形式あるいは zip 形式の phar アーカイブでは、スタブは .phar/stub.php というファイルに保存されます。 phar 形式の phar アーカイブのデフォルトのスタブには 約 7k のコードが含まれており、このコードが phar の展開と実行を行います。 詳細は Phar::createDefaultStub() を参照ください。

tar 形式あるいは zip 形式の phar アーカイブにおける phar エイリアスの保存先は .phar/alias.txt で、これはプレーンテキスト形式となります。

Phar 形式と Tar 形式、Zip 形式の徹底比較

phar 拡張モジュールがサポートする 3 つのファイル形式って、何がどう違うのでしょう? その答えを次の表にまとめました。

機能マトリックス: Phar vs. Tar vs. Zip
機能 Phar Tar Zip
一般的なファイル形式 No Yes Yes
Phar 拡張モジュールなしでの実行 [1] Yes No No
ファイル単位での圧縮 Yes No Yes
アーカイブ全体の圧縮 Yes Yes No
アーカイブ全体のシグネチャによる検証 Yes Yes Yes (PHP 5.3.1+)
ウェブアプリケーションへの対応 Yes Yes Yes
ファイルごとのメタデータ Yes Yes Yes
アーカイブ単位のメタデータ Yes Yes Yes
アーカイブの作成/変更 [2] Yes Yes Yes
すべてのストリームラッパー関数への対応 Yes Yes Yes
phar.readonly=1 の場合でも作成/変更が可能 [3] No Yes Yes

ヒント

[1] Phar 拡張モジュールが使用できない環境で Phar アーカイブの中身に PHP からアクセスする場合は、その スタブ を使用します。ここに phar アーカイブの中身を展開するコードが含まれています。 phar 拡張モジュールが見つからない場合は、 Phar::createDefaultStub() で作成したスタブが phar アーカイブを展開し、テンポラリディレクトリ内でそれを実行します。

ヒント

[2] 書き込みアクセスを行うには、php.ini あるいはコマンドラインで phar.readonly を無効にする必要があります。

ヒント

[3] tar および zip 形式のアーカイブでファイル名に .phar がつかない、かつ実行スタブ .phar/stub.php を含まないファイルは phar.readonly=1 でも作成できます。

Tar 形式の phar アーカイブ

tar 形式のアーカイブは、より近代的な USTAR フォーマットを使用しています。 tar 形式のファイルヘッダは、zip 形式よりも効率的にアクセスできるよう設計されています。 また、phar ファイルフォーマットともほぼ同じくらいに効率的です。 phar アーカイブ内のファイル名は、フルパスで 255 バイトまでという制限があります。 tar 形式の phar アーカイブでは、アーカイブ内のファイルの数に制限はありません。 このアーカイブは gzip や bzip2 で圧縮することができ、 そのまま Phar 拡張モジュールで実行できます。

アーカイブ全体を圧縮するには Phar::compress() を使用します。 アーカイブ全体の圧縮を解くには Phar::decompress() を使用します。

Zip 形式の phar アーカイブ

zip 形式のアーカイブは、zip ファイル形式に組み込まれているいくつかの機能に対応しています。 ファイルごとのメタデータやアーカイブ全体のメタデータを、 文字列にシリアル化して zip ファイルのコメントや zip アーカイブのコメントとして格納することができます。 また、既存の zip コメントも文字列として読み込むことができます。 zlib 圧縮ではファイル単位の圧縮の読み書き、 そして bzip2 圧縮ではファイル単位の圧縮の読み込みに対応しています。 zip 形式の phar アーカイブでは、アーカイブ内のファイルの数に制限はありません。 空のディレクトリを zip アーカイブに保存する際には、最後にスラッシュをつけた my/directory/ のような形式のファイルとなります。

Phar ファイルフォーマット

phar ファイル形式は スタブ/マニフェスト/コンテンツ/シグネチャ で構成されており、phar アーカイブ内に何が含まれているのかについての重要な情報は マニフェスト に格納されます。

Phar マニフェストは高度に最適化された書式で、 ファイル単位で圧縮やパーミッションの情報を指定することができ、 さらにファイルのユーザーやグループなど、独自に定義したメタデータも含めることができます。 1 バイトをこえる大きさの値はリトルエンディアン形式のバイト順で保存されます。 ただし API バージョンだけは例外です。これは 3 ニブルのデータですが、 歴史的な理由によりビッグエンディアン形式のバイト順で保存されます。

未使用のフラグはすべて将来の使用に備えて予約されています。 したがって、独自の情報を保存するためにそれを使用してはいけません。 特定のファイルについて独自の情報を保存するには、 ファイル単位のメタデータ機能を使用します。

Phar アーカイブマニフェストの基本的なファイルフォーマットは、次のようになります。

グローバル Phar マニフェスト書式
バイト数 説明
4 バイト マニフェスト全体のバイト長 (最大 1 MB)。
4 バイト Phar 内のファイル数。
2 バイト Phar マニフェストの API バージョン (現在は 1.0.0)。
4 バイト グローバルな Phar ビットマップフラグ。
4 バイト Phar のエイリアスの長さ。
?? Phar のエイリアス (先ほどの長さに基づきます)。
4 バイト Phar のメタデータの長さ (存在しない場合は 0)。
?? シリアライズ化された Phar メタデータ。serialize() 形式で格納される。
最低でも 24 * エントリ数ぶんのバイト 各ファイルのエントリ

グローバルな Phar ビットマップフラグ

これが、Phar 拡張モジュールが現在 Phar フラットビットマップとして認識するフラグです。

認識するビットマップ値
値 説明
0x00010000 設定されている場合、この Phar には検証用シグネチャが含まれます。
0x00001000 設定されている場合、この Phar には zlib 圧縮されたファイルが少なくともひとつ含まれます。
0x00002000 設定されている場合、この Phar には bzip 圧縮されたファイルが少なくともひとつ含まれます。

Phar マニフェストのファイルエントリの定義

マニフェスト内の各ファイルについて、次のような情報が含まれます。

Phar マニフェストのファイルエントリ
バイト数 説明
4 バイト ファイル名の長さを表すバイト数。
?? ファイル名 (先ほど指定した長さになります)。
4 バイト 圧縮前のファイルサイズを表すバイト数。
4 バイト ファイルの Unix タイムスタンプ。
4 バイト 圧縮後のファイルサイズを表すバイト数。
4 バイト 圧縮前のファイルの CRC32 チェックサム。
4 バイト ファイル固有のビットマップフラグ。
4 バイト シリアライズされたファイルのメタデータの長さ (存在しない場合は 0)。
?? シリアライズされたファイルのメタデータ。serialize() の形式で格納される。

API バージョン 1.1.1 では、空のディレクトリの最後にスラッシュをつけて my/directory/ のような形式で保存されることに注意しましょう。

ファイル固有のビットマップ値として認識される値は次のとおりです。

認識されるビットマップ値
値 説明
0x000001FF これらのビットは、ファイルの特定のパーミッションを定義するために予約されています。 このパーミッションは fstat() で用いられ、 ファイルを展開する際に特定のパーミッションを指定することができます。
0x00001000 設定されている場合、このファイルは zlib で圧縮されています。
0x00002000 設定されている場合、このファイルは bzip で圧縮されています。

Phar のシグネチャの書式

シグネチャを含む Phar は、常にシグネチャを保持しています。 シグネチャの場所は、 ローダ、マニフェスト、実際のファイルの内容に続く Phar アーカイブの最後の部分です。 現在サポートしているシグネチャのフォーマットは MD5 および SHA1 の二種類です。

シグネチャのフォーマット
バイト長 説明
16 あるいは 20 バイト 実際のシグネチャ。SHA1 の場合は 20 バイト、 MD5 の場合は 16 バイト、 SHA256 の場合は 32 バイト、 そして SHA512 の場合は 64 バイトとなります。
4 バイト シグネチャのフラグ。0x0001 は MD5 シグネチャ、そして 0x0002 は SHA1 シグネチャ、 0x0004 は SHA256 シグネチャ、 0x0008 は SHA512 シグネチャを表します。 SHA256 および SHA512 は、API バージョン 1.1.0 以降で対応します。
4 バイト GBMB という固定値で、 シグネチャが存在することを表します。

Phar クラス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

Phar クラスは、phar アーカイブへのアクセスや作成のための高レベルインターフェイスを提供します。

クラス概要

Phar extends RecursiveDirectoryIterator implements Countable , ArrayAccess {
/* プロパティ */
/* メソッド */
void addEmptyDir ( string $dirname )
void addFile ( string $file [, string $localname ] )
void addFromString ( string $localname , string $contents )
string apiVersion ( void )
array buildFromDirectory ( string $base_dir [, string $regex ] )
array buildFromIterator ( Iterator $iter [, string $base_directory ] )
bool canCompress ([ int $type = 0 ] )
bool canWrite ( void )
object compress ( int $compression [, string $extension ] )
bool compressAllFilesBZIP2 ( void )
bool compressAllFilesGZ ( void )
void compressFiles ( int $compression )
__construct ( string $fname [, int $flags [, string $alias ]] )
PharData convertToData ([ int $format = 9021976 [, int $compression = 9021976 [, string $extension ]]] )
Phar convertToExecutable ([ int $format = 9021976 [, int $compression = 9021976 [, string $extension ]]] )
bool copy ( string $oldfile , string $newfile )
int count ( void )
string createDefaultStub ([ string $indexfile [, string $webindexfile ]] )
object decompress ([ string $extension ] )
bool decompressFiles ( void )
bool delMetadata ( void )
bool delete ( string $entry )
bool extractTo ( string $pathto [, string|array $files [, bool $overwrite = false ]] )
mixed getMetadata ( void )
bool getModified ( void )
array getSignature ( void )
string getStub ( void )
array getSupportedCompression ( void )
array getSupportedSignatures ( void )
string getVersion ( void )
bool hasMetadata ( void )
void interceptFileFuncs ( void )
bool isBuffering ( void )
mixed isCompressed ( void )
bool isFileFormat ( int $format )
bool isValidPharFilename ( string $filename [, bool $executable = true ] )
bool isWritable ( void )
bool loadPhar ( string $filename [, string $alias ] )
bool mapPhar ([ string $alias [, int $dataoffset = 0 ]] )
void mount ( string $pharpath , string $externalpath )
void mungServer ( array $munglist )
bool offsetExists ( string $offset )
int offsetGet ( string $offset )
void offsetSet ( string $offset , string $value )
bool offsetUnset ( string $offset )
string running ([ bool $retphar = true ] )
bool setAlias ( string $alias )
bool setDefaultStub ([ string $index [, string $webindex ]] )
void setMetadata ( mixed $metadata )
void setSignatureAlgorithm ( int $sigtype [, string $privatekey ] )
bool setStub ( string $stub )
void startBuffering ( void )
void stopBuffering ( void )
bool uncompressAllFiles ( void )
bool unlinkArchive ( string $archive )
void webPhar ([ string $alias [, string $index = "index.php" [, string $f404 [, array $mimetypes [, array $rewrites ]]]]] )
}

Phar::addEmptyDir

(Unknown)

Phar::addEmptyDir — 空のディレクトリを phar アーカイブに追加する

説明

void Phar::addEmptyDir ( string $dirname )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用すると、空のディレクトリが dirname に作成されます。このメソッドは ZipArchive::addEmptyDir() と同じようなものです。

パラメータ

dirname

phar アーカイブ内に作成する空のディレクトリの名前。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 Phar::addEmptyDir() の例

<?php
try {
    $a = new Phar('/path/to/phar.phar');

    $a->addEmptyDir('/full/path/to/file');
    // できあがったファイルを確認します
    $b = $a['full/path/to/file']->isDir();
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • PharData::addEmptyDir() - 空のディレクトリを tar/zip アーカイブに追加する
  • Phar::addFile() - ファイルシステム上のファイルを phar アーカイブに追加する
  • Phar::addFromString() - ファイルシステム上のファイルを phar アーカイブに追加する

Phar::addFile

(Unknown)

Phar::addFile — ファイルシステム上のファイルを phar アーカイブに追加する

説明

void Phar::addFile ( string $file [, string $localname ] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用すると、任意のファイルあるいは URL を phar アーカイブに追加することができます。 オプションの 2 番目のパラメータ localname を指定すると、 ファイルはその名前でアーカイブ内に格納されます。指定しなかった場合は、 file パラメータをアーカイブ内のパスとして使用します。 URL を使用する場合は、localname を指定しないと例外がスローされます。 このメソッドは ZipArchive::addFile() と同じようなものです。

パラメータ

file

phar アーカイブに追加したいディスク上のファイルへのフルパスあるいは相対パス。

localname

ファイルをアーカイブ内に格納するときのパス。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 Phar::addFile() の例

<?php
try {
    $a = new Phar('/path/to/phar.phar');

    $a->addFile('/full/path/to/file');
    // 格納したファイルを確認します
    $b = $a['full/path/to/file']->getContent();

    $a->addFile('/full/path/to/file', 'my/file.txt');
    $c = $a['my/file.txt']->getContent();

    // URL の使用例
    $a->addFile('http://www.example.com', 'example.html');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • PharData::addFile() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • Phar::addFromString() - ファイルシステム上のファイルを phar アーカイブに追加する
  • Phar::addEmptyDir() - 空のディレクトリを phar アーカイブに追加する

Phar::addFromString

(Unknown)

Phar::addFromString — ファイルシステム上のファイルを phar アーカイブに追加する

説明

void Phar::addFromString ( string $localname , string $contents )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用すると、任意の文字列を phar アーカイブに追加することができます。 アーカイブ内のファイル名は localname で指定したものとなります。 このメソッドは ZipArchive::addFromString() と同じようなものです。

パラメータ

localname

ファイルをアーカイブ内に格納するときのパス。

contents

ファイルに保存する内容。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 Phar::addFromString() の例

<?php
try {
    $a = new Phar('/path/to/phar.phar');

    $a->addFromString('path/to/file.txt', 'my simple file');
    $b = $a['path/to/file.txt']->getContent();

    // 大きなファイル用にストリームハンドルから追加するには offsetSet() を使用します
    $c = fopen('/path/to/hugefile.bin');
    $a['largefile.bin'] = $c;
    fclose($c);
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::offsetSet() - 内部ファイルに、外部ファイルの内容を設定する
  • PharData::addFromString() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • Phar::addFile() - ファイルシステム上のファイルを phar アーカイブに追加する
  • Phar::addEmptyDir() - 空のディレクトリを phar アーカイブに追加する

Phar::apiVersion

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::apiVersion — API のバージョンを返す

説明

string Phar::apiVersion ( void )

phar ファイルフォーマットの API バージョンを返します。 phar を作成する際にこのバージョンが使用されます。 Phar 拡張モジュールが読み込みをサポートしているのは、 バージョン 1.0.0 以降の API です。 SHA-256 や SHA-512 を使用するには API バージョン 1.1.0 以降が、 そして空のディレクトリを格納するには API バージョン 1.1.1 以降が必要です。

パラメータ

返り値

API のバージョンを、"1.0.0" のような文字列で返します。

例

例1 Phar::apiVersion() の例

<?php
echo Phar::apiVersion();
?>

上の例の出力は以下となります。

1.1.1

Phar::buildFromDirectory

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::buildFromDirectory — ディレクトリ内のファイルから phar を作成する

説明

array Phar::buildFromDirectory ( string $base_dir [, string $regex ] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

ディレクトリの中身をもとに phar アーカイブを作成します。 オプションの 2 番目のパラメータで正規表現 (pcre) を指定すると、特定のファイルを除外することができます。 正規表現にマッチするすべてのファイルがアーカイブに含められ、 それ以外のファイルは除外されます。より詳細に制御するには Phar::buildFromIterator() を使用します。

パラメータ

base_dir

アーカイブに追加するすべてのファイルを含むディレクトリへの フルパスあるいは相対パス。

regex

オプションで指定する pcre 正規表現。 これを使用してファイル一覧をフィルタリングします。 正規表現にマッチするファイルパスのみがアーカイブに追加されます。

返り値

Phar::buildFromDirectory() は、連想配列を返します。これは、 ファイルの内部パスをファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、内部ディレクトリイテレータのインスタンスの作成に失敗したときに BadMethodCallException をスローします。 また、phar アーカイブの保存時にエラーが発生した場合は PharException をスローします。

例

例1 Phar::buildFromDirectory() の例

<?php
// "project.phar" というエイリアスで作成します
$phar = new Phar('project.phar', 0, 'project.phar');
// project 内のすべてのファイルを追加します
$phar->buildFromDirectory(dirname(__FILE__) . '/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));

$phar2 = new Phar('project2.phar', 0, 'project2.phar');
// project 内のファイルのうち、php ファイルだけを追加します
$phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
$phar2->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

参考

Phar::buildFromIterator

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::buildFromIterator — イテレータから phar アーカイブを作成する

説明

array Phar::buildFromIterator ( Iterator $iter [, string $base_directory ] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブをイテレータから作成します。 サポートするイテレータは二種類で、 phar 内のファイル名とディスク上の実際のファイル名を対応させたものか、あるいは DirectoryIterator のように SplFileInfo オブジェクトを返すものです。 SplFileInfo オブジェクトを返すイテレータの場合は、2 番目のパラメータが必要となります。

パラメータ

iter

phar ファイルと実際の場所の関連を返すイテレータ、 あるいは SplFileInfo オブジェクトを返すイテレータ。

base_directory

SplFileInfo オブジェクトを返すイテレータを指定した際、 phar アーカイブへの追加時にフルパスから取り除く部分。

返り値

Phar::buildFromIterator() は連想配列を返します。 これは、ファイルの内部パスとファイルシステム上のフルパスを対応させたものです。

例

例1 SplFileInfo を使用した Phar::buildFromIterator() の例

ほとんどの phar アーカイブは、実際のディレクトリ構造を反映した形式になっています。 このような場合は 2 番目の方式が最適です。 たとえば、次のようなディレクトリ構成のファイルを含む phar アーカイブを作成してみることにしましょう。 

/path/to/project/
                 config/
                        dist.xml
                        debug.xml
                 lib/
                     file1.php
                     file2.php
                 src/
                     processthing.php
                 www/
                     index.php
                 cli/
                     index.php

次のコードを使用すると、これらのファイルを phar アーカイブ "project.phar" に追加します。

<?php
// "project.phar" というエイリアスで作成します
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new RecursiveDirectoryIterator('/path/to/project')),
    '/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

これで、ファイル project.phar はすぐに使えるようになります。 Phar::buildFromIterator() は圧縮やメタデータの設定を行いません。 これらは phar アーカイブを作成した後で行うことができます。

興味深いことに、Phar::buildFromIterator() を使用して既存の phar アーカイブの中身をコピーすることもできます。 というのも Phar オブジェクトは DirectoryIterator を継承しているからです。

<?php
// "project.phar" というエイリアスで作成します
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new Phar('/path/to/anotherphar.phar')),
    'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

例2 その他のイテレータを使用した Phar::buildFromIterator() の例

それ以外の形式のイテレータでは、 key => value の対応を返すものを使用できます。たとえば ArrayIterator などです。

<?php
// "project.phar" というエイリアスで作成します
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
    new ArrayIterator(
     array(
        'internal/file.php' => dirname(__FILE__) . '/somefile.php',
        'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
     )));
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

エラー / 例外

このメソッドは、イテレータが間違った値 (たとえば文字列キーではなく整数キーなど) を返した場合に UnexpectedValueException を返します。また、SplFileInfo 型のイテレータを渡したときに base_directory を指定しなかった場合は BadMethodCallException を、 phar アーカイブの保存時にエラーが発生した場合は PharException を返します。

参考

Phar::canCompress

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::canCompress — phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す

説明

bool Phar::canCompress ([ int $type = 0 ] )

これは、圧縮されたファイルを含む phar を読み込む前に、 圧縮が可能かどうかを調べるために使用します。

パラメータ

type

Phar::GZ あるいは Phar::BZ2 のいずれかを指定し、指定した圧縮アルゴリズムでの圧縮が可能かどうかを調べます。

返り値

圧縮/展開 が可能な場合に TRUE、そうでない場合に FALSE を返します。

例

例1 Phar::canCompress() の例

<?php
if (Phar::canCompress()) {
    echo file_get_contents('phar://compressedphar.phar/internal/file.txt');
} else {
    echo '圧縮はできません';
}
?>

参考

Phar::canWrite

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::canWrite — phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す

説明

bool Phar::canWrite ( void )

この静的メソッドは、書き込みアクセスが php.ini の phar.readonly で無効にされているかどうかを調べます。

パラメータ

返り値

書き込みが可能な場合に TRUE、そうでない場合に FALSE を返します。

例

例1 Phar::canWrite() の例

<?php
if (Phar::canWrite()) {
    file_put_contents('phar://myphar.phar/file.txt', 'hi there');
}
?>

参考

Phar::compress

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::compress — Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

説明

object Phar::compress ( int $compression [, string $extension ] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式あるいは phar 形式の phar アーカイブの場合は、 このメソッドはアーカイブ全体を gzip あるいは bzip2 で圧縮します。 できあがったファイルは gunzip/bunzip コマンドで処理することもできますし、 Phar 拡張モジュールで直接透過的に使用することもできます。

zip 形式の phar アーカイブの場合は、このメソッドは失敗して例外が発生します。 gzip で圧縮するためには zlib 拡張モジュールが、そして bzip2 で圧縮するためには bzip2 拡張モジュールが有効になっていなければなりません。 この関数は phar の内容を変更するので、使用するには INI 設定 phar.readonly が off になっていなければなりません。

さらに、このメソッドは自動的にアーカイブの名前を変更し、 .gz あるいは .bz2 を追加します。Phar::NONE を渡して圧縮を解除した場合は拡張子も削除します。 もうひとつの方法として、ファイルの拡張子を 2 番目のパラメータで指定することもできます。

パラメータ

compression

圧縮を行う場合には Phar::GZ あるいは Phar::BZ2、圧縮を解除する場合には Phar::NONE を指定します。

extension

デフォルトでは、phar 形式のアーカイブを圧縮する際の拡張子は .phar.gz あるいは .phar.bz2 となり、tar 形式のアーカイブを圧縮する際の拡張子は .phar.tar.gz あるいは .phar.tar.bz2 となります。伸長の際は、デフォルトの拡張子は .phar および .phar.tar となります。

返り値

Phar オブジェクトを返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 Phar::compress() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // /path/to/my.phar.gz にコピーします
$p2 = $p->compress(Phar::BZ2); // /path/to/my.phar.bz2 にコピーします
$p3 = $p2->compress(Phar::NONE); // 例外: /path/to/my.phar は既に存在します
?>

参考

Phar::compressAllFilesBZIP2

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::compressAllFilesBZIP2 — 現在の Phar アーカイブ内のすべてのファイルを Bzip2 で圧縮する

説明

bool Phar::compressAllFilesBZIP2 ( void )

注意:

このメソッドは、phar 拡張モジュールバージョン 2.0.0 で削除されました。 今後は Phar::compress()、 Phar::decompress()、Phar::compressFiles() および Phar::decompressFiles() をご利用ください。

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドは、Phar アーカイブ内のすべてのファイルを bzip2 で圧縮します。この機能を使用するには bzip2 拡張モジュールが有効になっていなければなりません。 また、すでに gzip で圧縮されているファイルを処理するためには、 まず gzip を伸張してから bzip2 で再圧縮するため、 zlib 拡張モジュールが有効になっていなければなりません。 この関数は phar の内容を変更するので、使用するには INI 設定 phar.readonly が off になっていなければなりません。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、bzip2 拡張モジュールが使用できない場合、あるいは gzip で圧縮されたファイルがあるのに zlib 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 Phar::compressAllFilesBZIP2() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressedBZIP2());
    var_dump($file->isCompressedGZ());
}
$p->compressAllFilesBZIP2();
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressedBZIP2());
    var_dump($file->isCompressedGZ());
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)
string(10) "myfile.txt"
bool(true)
bool(true)
bool(false)
string(11) "myfile2.txt"
bool(true)
bool(true)
bool(false)

参考

Phar::compressAllFilesGZ

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::compressAllFilesGZ — 現在の Phar アーカイブ内のすべてのファイルを Gzip で圧縮する

説明

bool Phar::compressAllFilesGZ ( void )

注意:

このメソッドは、phar 拡張モジュールバージョン 2.0.0 で削除されました。 今後は Phar::compress()、 Phar::decompress()、Phar::compressFiles() および Phar::decompressFiles() をご利用ください。

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式の phar アーカイブの場合は、このメソッドはアーカイブ全体を gzip で圧縮します。 できあがったファイルは gunzip コマンドで処理することもできますし、 Phar 拡張モジュールで直接透過的に使用することもできます。

zip 形式あるいは phar 形式の phar アーカイブの場合は、このメソッドは Phar アーカイブ内のすべてのファイルを gzip で圧縮します。 この機能を使用するには zlib 拡張モジュールが有効になっていなければなりません。 また、すでに bzip2 で圧縮されているファイルを処理するためには、 まず bzip2 を伸張してから gzip で再圧縮するため、 bzip2 拡張モジュールが有効になっていなければなりません。 この関数は phar の内容を変更するので、使用するには INI 設定 phar.readonly が off になっていなければなりません。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが使用できない場合、あるいは bzip2 で圧縮されたファイルがあるのに bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 Phar::compressAllFilesGZ() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressedBZIP2());
    var_dump($file->isCompressedGZ());
}
$p->compressAllFilesGZ();
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressedBZIP2());
    var_dump($file->isCompressedGZ());
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)
string(10) "myfile.txt"
bool(true)
bool(false)
bool(true)
string(11) "myfile2.txt"
bool(true)
bool(false)
bool(true)

参考

Phar::compressFiles

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::compressFiles — 現在の Phar アーカイブ内のすべてのファイルを圧縮する

説明

void Phar::compressFiles ( int $compression )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 Phar::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式および phar 形式の phar アーカイブでは、 このメソッドは Phar アーカイブ内のすべてのファイルを指定した方式で圧縮します。 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。さらに、 もし既に bzip2/zlib で圧縮されているファイルがある場合は、 いったんその圧縮を解除するために対応する拡張モジュールが必要となります。 この関数は phar の内容を変更するので、使用するためには INI 設定 phar.readonly が off になっている必要があります。

パラメータ

compression

圧縮を行う場合は Phar::GZ あるいは Phar::BZ2、圧縮を解除するためには Phar::NONE のいずれかを指定しなければなりません。

返り値

値を返しません。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが有効でない場合、 あるいは既に bzip2 圧縮されているファイルがあるのに bzip2 拡張モジュールが有効でない場合に BadMethodCallException をスローします。

例

例1 Phar::compressFiles() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)
string(10) "myfile.txt"
int(4096)
bool(false)
bool(true)
string(11) "myfile2.txt"
int(4096)
bool(false)
bool(true)

参考

Phar::__construct

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::__construct — Phar アーカイブオブジェクトを作成する

説明

Phar::__construct ( string $fname [, int $flags [, string $alias ]] )

パラメータ

fname

既存の Phar アーカイブ、あるいは作成したいアーカイブへのパス。

flags

親クラス RecursiveDirectoryIterator に渡すフラグ。

alias

ストリーム機能をコールする場合に Phar アーカイブが参照するエイリアス。

エラー / 例外

二度コールされた場合に BadMethodCallException、 phar アーカイブがオープンできなかった場合に UnexpectedValueException がスローされます。

例

例1 Phar::__construct() の例

<?php
try {
    $p = new Phar('/path/to/my.phar', FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::KEY_AS_FILENAME,
                  'my.phar');
} catch (UnexpectedValueException $e) {
    die('my.phar をオープンできません');
} catch (BadMethodCallException $e) {
    echo 'これはありえません';
}
// これは動作します
echo file_get_contents('phar://my.phar/example.txt');
// これも動作します
echo file_get_contents('phar:///path/to/my.phar/example.txt');
?>

Phar::convertToData

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

説明

PharData Phar::convertToData ([ int $format = 9021976 [, int $compression = 9021976 [, string $extension ]]] )

このメソッドは、実行可能な phar アーカイブを tar あるいは zip ファイルに変換します。 tar あるいは zip を実行可能ではない形式にするため、 phar スタブおよび phar エイリアスファイルはアーカイブから削除されます。

何も変更しなかった場合、もしアーカイブが phar 形式ならこのメソッドは BadMethodCallException をスローします。 tar あるいは zip 形式のアーカイブの場合は、 このメソッドはアーカイブを実行可能でない形式に変換します。

成功した場合は、このメソッドはディスク上に新しいアーカイブを作成して PharData オブジェクトを返します。 古いアーカイブは削除されずディスク上に残るので、 処理を終えたら手動で削除する必要があります。

パラメータ

format

これは Phar::TAR あるいは Phar::ZIP のいずれかとなります。 NULL を指定すると、現在のファイル形式をそのまま保持します。

compression

アーカイブ全体の圧縮を行わない場合は Phar::NONE、 zlib による圧縮の場合は Phar::GZ、そして bzip による圧縮の場合は Phar::BZ2 のいずれかを指定します。

extension

このパラメータは、変換後のアーカイブのデフォルトのファイル拡張子を変更します。 実行可能でない tar や zip アーカイブのファイル名としては .phar は使用できないことに注意しましょう。

tar 形式の phar アーカイブの場合、デフォルトの拡張子は圧縮形式によって .tar、.tar.gz、 .tar.bz2 のいずれかとなります。 zip 形式のアーカイブの場合、デフォルトの拡張子は .zip となります。

返り値

このメソッドは、成功した場合に PharData オブジェクトを返します。失敗した場合は例外をスローします。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、phar 作成中に何らかの問題が発生した場合に PharException をスローします。

例

例1 Phar::convertToData() の例

Phar::convertToData() の使用法です。

<?php
try {
    $tarphar = new Phar('myphar.phar.tar');
    // myphar.phar.tar は削除 *されない* ことに注意しましょう
    // 実行可能ではない tar 形式に変換し
    // myphar.tar を作成します
    $tar = $tarphar->convertToData();
    // 実行可能でない zip 形式に変換し myphar.zip を作成します
    $zip = $tarphar->convertToData(Phar::ZIP);
    // myphar.tbz を作成します
    $tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
    // myphar.phar.tgz を作成します
    $phar = $tarphar->convertToData(Phar::PHAR); // 例外をスローします
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

Phar::convertToExecutable

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::convertToExecutable — phar アーカイブを実行可能な別の phar アーカイブ形式に変換する

説明

Phar Phar::convertToExecutable ([ int $format = 9021976 [, int $compression = 9021976 [, string $extension ]]] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドは、phar アーカイブを別のファイル形式に変換します。 たとえば、zip 形式の実行可能な phar アーカイブあるいは phar 形式の実行可能な phar アーカイブから tar 形式の実行可能な phar アーカイブを作成することができます。 さらに、tar あるいは phar 形式のアーカイブについてはアーカイブ全体を圧縮することもできます。

何も変更しなかった場合、このメソッドは BadMethodCallException をスローします。

成功した場合は、このメソッドはディスク上に新しいアーカイブを作成して Phar オブジェクトを返します。 古いアーカイブは削除されずディスク上に残るので、 処理を終えたら手動で削除する必要があります。

パラメータ

format

これは Phar::PHAR、Phar::TAR あるいは Phar::ZIP のいずれかとなります。 NULL を指定すると、現在のファイル形式をそのまま保持します。

compression

アーカイブ全体の圧縮を行わない場合は Phar::NONE、 zlib による圧縮の場合は Phar::GZ、そして bzip による圧縮の場合は Phar::BZ2 のいずれかを指定します。

extension

このパラメータは、変換後のアーカイブのデフォルトのファイル拡張子を変更します。 実行可能でない tar や zip アーカイブのファイル名としては .phar は使用できないことに注意しましょう。

phar 形式のアーカイブに変換する場合、デフォルトの拡張子は圧縮形式によって .phar、.phar.gz あるいは .phar.bz2 のいずれかとなります。tar 形式のアーカイブの場合、デフォルトの拡張子は .phar.tar、.phar.tar.gz および .phar.tar.bz2 です。zip 形式のアーカイブの場合、 デフォルトの拡張子は .phar.zip となります。

返り値

このメソッドは、成功した場合に Phar オブジェクトを返します。失敗した場合は例外をスローします。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、書き込みサポートが無効な場合に UnexpectedValueException、 phar 作成中に何らかの問題が発生した場合に PharException をスローします。

例

例1 Phar::convertToExecutable() の例

Phar::convertToExecutable() の使用例です。

<?php
try {
    $tarphar = new Phar('myphar.phar.tar');
    // phar ファイル形式に変換します
    // myphar.phar.tar は削除 *されない* ことに注意しましょう
    $phar = $tarphar->convertToExecutable(Phar::PHAR); // myphar.phar を作成します
    $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    // myphar.phar.tgz を作成します
    $compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

Phar::copy

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

説明

bool Phar::copy ( string $oldfile , string $newfile )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブ内のファイルを、そのアーカイブ内で別の新しいファイルとしてコピーします。 これは、phar ストリームラッパーでの copy() と同等の操作をオブジェクト指向で行うものです。

パラメータ

oldfile

newfile

返り値

成功した場合に TRUE を返します。しかし、より安全を期すなら try/catch ブロック内で使用して例外がスローされないことを確認するといいでしょう。

エラー / 例外

コピー元のファイルが存在しない、コピー先のファイルが既に存在する、 書き込みアクセスが無効になっている、どちらかのファイルのオープンに失敗した、 あるいはコピー元のファイルの読み込みに失敗した場合に UnexpectedValueException をスローします。 変更内容の phar への書き込みに失敗した場合は PharException をスローします。

例

例1 Phar::copy() の例

この例は、Phar::copy() の使用法のほかに それと同等の操作をストリームラッパーで行う方法を示すものです。 これらの方式の最大の違いはエラー処理です。 Phar のすべてのメソッドは例外をスローしますが、ストリームラッパーの場合は trigger_error() を使用します。

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar['a'] = 'hi';
    $phar->copy('a', 'b');
    echo $phar['b']; // 出力は "hi"
} catch (Exception $e) {
    // エラー処理
}

// 上のコードと同等の処理をストリームラッパーで行う例。
// エラー時には例外ではなく E_WARNINGS が発生します
copy('phar://myphar.phar/a', 'phar//myphar.phar/c');
echo file_get_contents('phar://myphar.phar/c'); // 出力は "hi"
?>

Phar::count

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::count — Phar アーカイブ内のエントリ (ファイル) の数を返す

説明

int Phar::count ( void )

パラメータ

返り値

この phar ファイルに含まれるファイルの数を返します。 存在しない場合は 0 (数字のゼロ) を返します。

例

例1 Phar::count() の例

<?php
// 存在しないことを確実にしておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
} catch (Exception $e) {
    echo 'phar を作成できません', $e;
}
echo 'phar のエントリ数は ' . $p->count() . " です\n";
$p['file.txt'] = 'hi';
echo 'phar のエントリ数は ' . $p->count() . " です\n";
?>

上の例の出力は以下となります。

phar のエントリ数は 0 です
phar のエントリ数は 1 です

Phar::createDefaultStub

(Unknown)

Phar::createDefaultStub — phar ファイルフォーマット用のスタブを作成する

説明

string Phar::createDefaultStub ([ string $indexfile [, string $webindexfile ]] )

このメソッドは、phar ファイル形式のスタブを作成するためのもので、 tar 形式や zip 形式の phar アーカイブでは使用しません。

PHP でかかれた起動ローダー (スタブ) を含む Phar アーカイブを PHP から実行するには、次のようにそれをインクルードするか、

<?php
include 'myphar.phar';
?>
あるいは単に実行します。 
php myphar.phar

このメソッドは、phar アーカイブの起動時に実行するスタブ用のメソッドを作成します。 さらに、phar アーカイブをコマンドラインやウェブサーバーから実行する際には別のファイルを指定することもできます。 ローダースタブは Phar::interceptFileFuncs() もコールでき、PHP のアプリケーションからファイルシステムを簡単に扱えるようになります。 phar 拡張モジュールが存在しない場合は、 ローダースタブが phar アーカイブの内容を一時ディレクトリに展開し、 そのファイルを操作します。 シャットダウン関数が、この一時ファイル群を削除します。

返り値

独自の起動ローダー (スタブ) を文字列で返します。 これを用いて作成した Phar アーカイブは、 Phar 拡張モジュールが有効になっていない環境でも実行することができます。

エラー / 例外

パラメータの長さが 400 バイトをこえる場合に UnexpectedValueException をスローします。

例

例1 Phar::createDefaultStub() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
    // エラー処理
}
?>

参考

  • Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する
  • Phar::getStub() - Phar アーカイブの PHP ローダーあるいは起動スタブを返す

Phar::decompress

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::decompress — Phar アーカイブ全体の圧縮を解除する

説明

object Phar::decompress ([ string $extension ] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式あるいは phar 形式の phar アーカイブの場合は、 このメソッドはアーカイブ全体の圧縮を解除します。

zip 形式の phar アーカイブの場合は、このメソッドは失敗して例外が発生します。 gzip で圧縮されたファイルの圧縮を解除するためには zlib 拡張モジュールが、そして bzip2 で圧縮されたファイルの圧縮を解除するためには bzip2 拡張モジュールが有効になっていなければなりません。 この関数は phar の内容を変更するので、使用するには INI 設定 phar.readonly が off になっていなければなりません。

さらに、このメソッドは自動的にアーカイブの拡張子を変更し、 phar アーカイブなら .phar、 tar 形式のアーカイブなら .phar.tar をデフォルトで追加します。 もうひとつの方法として、ファイルの拡張子を 2 番目のパラメータで指定することもできます。

パラメータ

extension

圧縮を解除する場合、デフォルトのファイル拡張子は .phar および .phar.tar です。 このパラメータを使用すると、別の拡張子を指定することができます。 実行可能な phar アーカイブは、ファイル名に必ず .phar を含まなければならないことに注意しましょう。

返り値

Phar オブジェクトを返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 Phar::decompress() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar.gz');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p3 = $p2->decompress(); // /path/to/my.phar を作成します
?>

参考

Phar::decompressFiles

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::decompressFiles — 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

説明

bool Phar::decompressFiles ( void )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 Phar::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式および phar 形式の phar アーカイブでは、 このメソッドは Phar アーカイブ内のすべてのファイルの圧縮を解除します。 もし bzip2/zlib で圧縮されているファイルがある場合は、 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。 この関数は phar の内容を変更するので、使用するためには INI 設定 phar.readonly が off になっている必要があります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが有効でない場合、 あるいは既に bzip2 圧縮されているファイルがあるのに bzip2 拡張モジュールが有効でない場合に BadMethodCallException をスローします。

例

例1 Phar::decompressFiles() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
int(4096)
bool(false)
bool(true)
string(11) "myfile2.txt"
int(4096)
bool(false)
bool(true)
string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)

参考

Phar::delMetadata

(PHP >= 5.3.0, PECL phar >= 1.2.0)

Phar::delMetadata — phar のグローバルメタデータを削除する

説明

bool Phar::delMetadata ( void )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar のグローバルメタデータを削除します。

パラメータ

返り値

成功した場合に TRUE を返します。しかし、より安全を期すなら try/catch ブロック内で使用して例外がスローされないことを確認するといいでしょう。

エラー / 例外

変更をディスクに書き戻す際にエラーが発生した場合は PharException をスローします。

例

例1 Phar::delMetaData() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    var_dump($phar->getMetadata());
    $phar->setMetadata("hi there");
    var_dump($phar->getMetadata());
    $phar->delMetadata();
    var_dump($phar->getMetadata());
} catch (Exception $e) {
    // エラー処理
}
?>

上の例の出力は以下となります。

NULL
string(8) "hi there"
NULL

参考

Phar::delete

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::delete — phar アーカイブ内のファイルを削除する

説明

bool Phar::delete ( string $entry )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

アーカイブ内のファイルを削除します。 これは、ストリームラッパー上で unlink() をコールするのと同じ意味です。以下に例を示します。

パラメータ

entry

削除したいファイルの、アーカイブ内でのパス。

返り値

成功した場合に TRUE を返します。 しかし、例外がスローされているかどうかを確認したうえで 例外がなければ成功とみなすほうがいいでしょう。

エラー / 例外

変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 Phar::delete() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->delete('unlink/me.php');
    // これは以下と同じ意味です
    unlink('phar://myphar.phar/unlink/me.php');
} catch (Exception $e) {
    // エラー処理
}
?>

参考

Phar::extractTo

(Unknown)

Phar::extractTo — phar アーカイブの内容をディレクトリに展開する

説明

bool Phar::extractTo ( string $pathto [, string|array $files [, bool $overwrite = false ]] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブ内のすべてのファイルをディスクに展開します。 展開されたファイルやディレクトリは、アーカイブに保存されたときのパーミッションを維持しています。 オプションのパラメータを使用すると、どのファイルを展開するかを制御したり 既存のファイルを上書きするかどうかを指定したりすることができます。 2 番目のパラメータ files には、 展開したいファイルやディレクトリの名前、あるいはその配列を指定します。 デフォルトでは、このメソッドは既存のファイルを上書きしません。 3 番目のパラメータを true にすると既存のファイルを上書きさせることができます。 このメソッドは ZipArchive::extractTo() と同じようなものです。

パラメータ

pathto

アーカイブ内のファイルへのパス。

files

展開したいファイル名/ディレクトリ名、あるいはその配列。

overwrite

TRUE にすると既存のファイルを上書きします。

返り値

成功した場合に TRUE を返します。 しかし、例外がスローされているかどうかを確認したうえで 例外がなければ成功とみなすほうがいいでしょう。

エラー / 例外

変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 Phar::extractTo() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->extractTo('/full/path'); // すべてのファイルを展開します
    $phar->extractTo('/another/path', 'file.txt'); // file.txt のみを展開します
    $phar->extractTo('/this/path',
        array('file1.txt', 'file2.txt')); // 2 つのファイルだけを展開します
    $phar->extractTo('/third/path', null, true); // すべてのファイルを展開し、上書きします
} catch (Exception $e) {
    // エラー処理
}
?>

参考

Phar::getMetadata

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::getMetadata — phar アーカイブのメタデータを返す

説明

mixed Phar::getMetadata ( void )

アーカイブのメタデータを取得します。メタデータは、PHP の任意の変数をシリアライズしたものです。

パラメータ

パラメータはありません。

返り値

Phar アーカイブのメタデータとして保存されている、シリアライズ可能な任意の PHP 変数を返します。 メタデータが保存されていない場合は NULL を返します。

例

例1 Phar::getMetadata() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['file.php'] = '<?php echo "hello";';
    $p->setMetadata(array('bootstrap' => 'file.php'));
    var_dump($p->getMetadata());
} catch (Exception $e) {
    echo 'phar を変更できません:', $e;
}
?>

上の例の出力は以下となります。

array(1) {
  ["bootstrap"]=>
  string(8) "file.php"
}

参考

Phar::getModified

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::getModified — phar が変更されているかどうかを返す

説明

bool Phar::getModified ( void )

このメソッドを使用すると、phar 内のファイルが 削除されたり変更されたりしているかどうかを判断できます。

パラメータ

パラメータはありません。

返り値

オープンした後でファイルが変更されている場合に TRUE、 そうでない場合に FALSE を返します。

Phar::getSignature

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::getSignature — Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す

説明

array Phar::getSignature ( void )

phar アーカイブの検証用シグネチャを、 十六進文字列で返します。

パラメータ

返り値

開いているアーカイブのシグネチャを配列で返します。 キー hash にはシグネチャ自体を、そしてキー hash_type には MD5、SHA-1、 SHA-256、SHA-512 あるいは OpenSSL を格納します。 このシグネチャは phar の中身全体から計算したハッシュで、 アーカイブの整合性を検証する際に使用します。 INI 設定 phar.require_hash が true の場合は、すべての実行可能な phar が有効なシグネチャを持っている必要があります。

Phar::getStub

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::getStub — Phar アーカイブの PHP ローダーあるいは起動スタブを返す

説明

string Phar::getStub ( void )

Phar アーカイブには、ブートストラップローダー (あるいは スタブ) というものが含まれています。これは PHP で書かれており、 そのアーカイブを PHP から実行したときに最初に実行されます。 たとえば次のようにインクルードしたり、

<?php
include 'myphar.phar';
?>
あるいは単純に実行したりなどした場合です。 
php myphar.phar

返り値

現在の Phar アーカイブの起動用ローダー (スタブ) の内容を文字列で返します。

エラー / 例外

スタブを Phar アーカイブから読み込めない場合に RuntimeException をスローします。

例

例1 Phar::getStub() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
echo $p->getStub();
echo "==NEXT==\n";
$p->setStub("<?php
function __autoload($class)
{
    include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER(); ?>");
echo $p->getStub();
?>

上の例の出力は以下となります。

<?php __HALT_COMPILER(); ?>
==NEXT==
<?php
function __autoload($class)
{
    include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER(); ?>

参考

Phar::getSupportedCompression

(PHP >= 5.3.0, PECL phar >= 1.2.0)

Phar::getSupportedCompression — サポートする圧縮アルゴリズムの配列を返す

説明

array Phar::getSupportedCompression ( void )

パラメータ

パラメータはありません。

返り値

Phar::GZ あるいは Phar::BZ2 を含む配列を返します。 これは、zlib 拡張モジュールと bz2 拡張モジュールが使用可能かどうかによって決まります。

参考

Phar::getSupportedSignatures

(PHP >= 5.3.0, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — サポートするシグネチャ型の配列を返す

説明

array Phar::getSupportedSignatures ( void )

サポートするシグネチャ型の配列を返します。

パラメータ

パラメータはありません。

返り値

MD5、SHA-1、 SHA-256、SHA-512 あるいは OpenSSL を含む配列を返します。

参考

Phar::getVersion

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::getVersion — Phar アーカイブのバージョン情報を返す

説明

string Phar::getVersion ( void )

オープンした Phar アーカイブの API バージョンを返します。

パラメータ

返り値

オープンしたアーカイブの API バージョンを返します。 これは、読み込んだ phar 拡張モジュールが新しい phar を作成する際に使用する API バージョンとは異なります。各 Phar アーカイブは、 マニフェスト内に API バージョンをハードコードして保持しています。 詳細は Phar ファイルフォーマット のドキュメントを参照ください。

参考

Phar::hasMetadata

(PHP >= 5.3.0, PECL phar >= 1.2.0)

Phar::hasMetadata — ファイルがグローバルなメタデータを持つかどうかを返す

説明

bool Phar::hasMetadata ( void )

ファイルがグローバルなメタデータを持っているかどうかを返します。

パラメータ

パラメータはありません。

返り値

メタデータが設定されている場合に TRUE、されていない場合に FALSE を返します。

例

例1 Phar::hasMetadata() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    var_dump($phar->hasMetadata());
    $phar->setMetadata(array('thing' => 'hi'));
    var_dump($phar->hasMetadata());
    $phar->delMetadata();
    var_dump($phar->hasMetadata());
} catch (Exception $e) {
    // エラー処理
}
?>

上の例の出力は以下となります。

bool(false)
bool(true)
bool(false)

参考

Phar::interceptFileFuncs

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::interceptFileFuncs — fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

説明

void Phar::interceptFileFuncs ( void )

fopen() や readfile()、 file_get_contents()、opendir() などの stat 関連の関数をすべて phar に横取りさせます。 phar アーカイブ内で相対パスを指定してこれらの関数がコールされると、 それが phar アーカイブ内のファイルへのアクセスに変更されます。 絶対パスの場合は、ファイルシステム上の外部ファイルを指すものとみなされます。

この関数を使用すると、ハードディスク上で動作するように作られている PHP アプリケーションを phar アプリケーションにまとめられるようになります。

パラメータ

パラメータはありません。

返り値

例

例1 Phar::interceptFileFuncs() の例

<?php
Phar::interceptFileFuncs();
include 'phar://' . __FILE__ . '/file.php';
?>

phar ファイルの場所が /path/to/myphar.phar で、その中に file.php と file2.txt が存在するものとします。 file.php にこのようなコードが含まれていた場合、

例2 Phar::interceptFileFuncs() の例

<?php
echo file_get_contents('file2.txt');
?>

通常は、PHP はカレントディレクトリの file2.txt を探します。カレントディレクトリの場所は、file.php と同じ場所かあるいは コマンドラインで実行した際のカレントディレクトリとなります。 Phar::interceptFileFuncs() を使用した場合は、 PHP はカレントディレクトリを phar:///path/to/myphar.phar/ とみなし、上のコードの場合は phar:///path/to/myphar.phar/file2.txt をオープンします。

Phar::isBuffering

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::isBuffering — Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

説明

bool Phar::isBuffering ( void )

このメソッドを使用すると、その Phar が変更を即時にディスクに書き込むのか それとも Phar::stopBuffering() をコールしないと変更が保存されないのかがわかります。

Phar の書き込みバッファリングはアーカイブ単位で処理されます。 Phar アーカイブ foo.phar でバッファリングが有効であったとしても、それは Phar アーカイブ bar.phar の変更には影響しません。

返り値

書込み操作がバッファリングされる場合に TRUE、それ以外の場合に FALSE を返します。

例

例1 Phar::isBuffering() の例

<?php
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p2 = new Phar('existingphar.phar');
$p['file1.txt'] = 'hi';
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>
=2=
<?php
$p->startBuffering();
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
$p->stopBuffering();
?>
=3=
<?php
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>

上の例の出力は以下となります。

bool(false)
bool(false)
=2=
bool(true)
bool(false)
=3=
bool(false)
bool(false)

参考

  • Phar::startBuffering() - Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない
  • Phar::stopBuffering() - Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

Phar::isCompressed

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::isCompressed — phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す

説明

mixed Phar::isCompressed ( void )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返します。 zip 形式の phar アーカイブはファイル単位で圧縮することができません。 そのため、zip 形式の phar アーカイブを調べたときはこのメソッドは常に FALSE を返します。

パラメータ

パラメータはありません。

返り値

Phar::GZ、Phar::BZ2 あるいは FALSE を返します。

例

例1 Phar::isCompressed() の例

<?php
try {
    $phar1 = new Phar('myphar.zip.phar');
    var_dump($phar1->isCompressed());
    $phar2 = new Phar('myuncompressed.tar.phar');
    var_dump($phar2->isCompressed());
    $phar2->compressAllFilesGZ();
    var_dump($phar2->isCompressed() == Phar::GZ);
} catch (Exception $e) {
}
?>

上の例の出力は以下となります。

bool(false)
bool(false)
bool(true)

参考

Phar::isFileFormat

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::isFileFormat — phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す

説明

bool Phar::isFileFormat ( int $format )

パラメータ

format

Phar::PHAR、Phar::TAR あるいは Phar::ZIP で、アーカイブの形式を指定します。

返り値

phar アーカイブのファイル形式がパラメータで指定したものと一致する場合に TRUE を返します。

エラー / 例外

パラメータで指定した内容が既知の形式でない場合に PharException をスローします。

参考

Phar::isValidPharFilename

(PHP >= 5.3.0, PECL phar >= 1.2.0)

Phar::isValidPharFilename — 指定したファイル名が正しい形式の phar ファイルかどうかを返す

説明

bool Phar::isValidPharFilename ( string $filename [, bool $executable = true ] )

指定したファイル名のファイルが、phar 拡張モジュールで利用できる 正しい形式の phar ファイルであるかどうかを返します。 これは、phar アーカイブを実際に開く前にそのファイルを確認する際に使用します。 これで、 無効なファイルを指定したときに当然発生するであろう例外の処理を省略することができます。

パラメータ

filename

まだ作成されていない phar アーカイブの名前あるいはフルパス。

executable

このパラメータは、指定した名前のファイルを phar の実行可能アーカイブとして扱うかデータのみの非実行可能アーカイブとして扱うかを指定します。

返り値

正しい形式のファイルである場合に TRUE、そうでない場合に FALSE を返します。

Phar::isWritable

(Unknown)

Phar::isWritable — phar アーカイブが変更可能な場合に true を返す

説明

bool Phar::isWritable ( void )

このメソッドは、phar.readonly が 0 かつディスク上の実際の phar アーカイブが読み取り専用でない場合に TRUE を返します。

パラメータ

パラメータはありません。

返り値

phar アーカイブが変更可能な場合に TRUE を返します。

参考

  • Phar::canWrite() - phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
  • PharData::isWritable() - tar/zip アーカイブが変更可能な場合に true を返す

Phar::loadPhar

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::loadPhar — 任意の phar アーカイブを、エイリアスを指定して読み込む

説明

bool Phar::loadPhar ( string $filename [, string $alias ] )

これを使用して、外部の Phar アーカイブの内容を読み込むことができます。 phar へのエイリアスを指定することで、その後 phar を使用する場合に短い名前を使用できるので便利です。 また、データのみが含まれており、実行したり インクルードしたりする必要のない PHP スクリプトからなる Phar アーカイブを読み込む際にも便利です。

パラメータ

filename

オープンする phar アーカイブへの完全パスあるいは相対パス。

alias

この phar アーカイブをさす際に使用するエイリアス。 多くの場合は phar アーカイブ内で明示的なエイリアスを指定しており、 このような場合に新しいエイリアスを指定すると、 PharException がスローされます。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

すでに明示的なエイリアスを持っている phar アーカイブに対してエイリアスを渡すと、 PharException がスローされます。

例

例1 Phar::loadPhar() の例

Phar::loadPhar を使用すると、任意の場所にある外部の Phar アーカイブを読み込めます。 一方 Phar::mapPhar は Phar ローダのスタブ内で使用します。

<?php
try {
    Phar::loadPhar('/path/to/phar.phar', 'my.phar');
    echo file_get_contents('phar://my.phar/file.txt');
} catch (PharException $e) {
    echo $e;
}
?>

参考

  • Phar::mapPhar() - 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する

Phar::mapPhar

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::mapPhar — 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する

説明

bool Phar::mapPhar ([ string $alias [, int $dataoffset = 0 ]] )

この静的メソッドは、直接実行されたときや 他のスクリプトからインクルードされたときに Phar アーカイブのローダスタブ内で使用され、 phar を初期化します。

パラメータ

alias

このアーカイブを参照する際にフルパスのかわりに使用する、 phar:// 形式の URL。

dataoffset

未使用。PEAR の PHP_Archive との互換性のために用意しています。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

PHP から直接コールされなかった場合、 ソースファイル内に __HALT_COMPILER(); トークンがなかった場合、 あるいはファイルを読み込みモードでオープンできなかった場合に PharException をスローします。

例

例1 Phar::mapPhar() の例

mapPhar は、phar のローダスタブ内でのみ使用します。 外部の phar をメモリに読み込むには、loadPhar を使用します。

mapPhar を使用する Phar ローダスタブの例は、このようになります。

<?php
function __autoload($class)
{
    include 'phar://me.phar/' . str_replace('_', '/', $class) . '.php';
}
try {
    Phar::mapPhar('me.phar');
    include 'phar://me.phar/startup.php';
} catch (PharException $e) {
    echo $e->getMessage();
    die('Phar を初期化できません');
}
__HALT_COMPILER();

参考

  • Phar::loadPhar() - 任意の phar アーカイブを、エイリアスを指定して読み込む

Phar::mount

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::mount — 外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする

説明

void Phar::mount ( string $pharpath , string $externalpath )

Unix のファイルシステムで外部のデバイスをディレクトリツリー上にマウントできるのと同様に、 Phar::mount() を使用すると 外部のファイルやディレクトリをあたかもアーカイブ内にあるかのように参照することができるようになります。 これを使用すると、外部の設定ファイルをアーカイブ内にあるかのように扱うなどの高度な抽象化が可能となります。

パラメータ

pharpath

マウントする場所として使用する phar アーカイブ内のパス。 これは phar アーカイブ内の相対パスでなければならず、また、 既に存在するパスを指定することはできません。

externalpath

phar アーカイブ内にマウントしたい外部ファイルあるいはディレクトリのパスあるいは URL。

返り値

返り値はありません。失敗した場合は PharException をスローします。

エラー / 例外

パスのマウント時に問題が発生した場合は PharException をスローします。

例

例1 Phar::mount() の例

次の例は、外部の設定ファイルをまるでそれが phar アーカイブ内のパス上にあるかのように扱うものです。

まず、phar アーカイブ内のコードを示します。

<?php
$configuration = simplexml_load_string(file_get_contents(
    Phar::running(false) . '/config.xml'));
?>

次は、設定ファイルをマウントする外部コードです。

<?php
// まずは、抽象化した config.xml
// と実際のディスク上のファイルを関連づけます
Phar::mount('phar://config.xml', '/home/example/config.xml');
// アプリケーションを実行します
include '/path/to/archive.phar';
?>

もうひとつの方法として、コードを phar アーカイブのスタブ内に置くというものがあります。 これは、ユーザーが設定ファイルを指定しなかった場合にデフォルトの設定ファイルを使用する例です。

<?php
// まずは、抽象化した config.xml
// と実際のディスク上のファイルを関連づけます
if (defined('EXTERNAL_CONFIG')) {
    Phar::mount('config.xml', EXTERNAL_CONFIG);
    if (file_exists(__DIR__ . '/extra_config.xml')) {
        Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
    }
} else {
    Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
    Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
}
// アプリケーションを実行します
include 'phar://' . __FILE__ . '/index.php';
__HALT_COMPILER();
?>

...and the code externally to load this phar archive:

<?php
define('EXTERNAL_CONFIG', '/home/example/config.xml');
// アプリケーションを実行します
include '/path/to/archive.phar';
?>

Phar::mungServer

(Unknown)

Phar::mungServer — 最大 4 つまでの $_SERVER 変数を実行時に変更させる

説明

void Phar::mungServer ( array $munglist )

Phar::mungServer() は、 phar アーカイブのスタブ内でのみ使用します。

最大 4 つまでの $_SERVER 変数を指定し、 実行時に変更させます。phar の実行時に変更できる変数は REQUEST_URI、PHP_SELF、 SCRIPT_NAME そして SCRIPT_FILENAME です。

このメソッド自身は何も行いません。これが効力を発揮するのは Phar::webPhar() と組み合わせた場合で PHP ファイルがリクエストされた場合のみです。 PATH_INFO と PATH_TRANSLATED は常に変更されていることに注意しましょう。

変更前の元の値は、SERVER 配列の中で PHAR_ をつけた名前で保持されます。たとえば SCRIPT_NAME の場合は 変更前の値は PHAR_SCRIPT_NAME となります。

パラメータ

munglist

REQUEST_URI、PHP_SELF、 SCRIPT_NAME および SCRIPT_FILENAME を含む配列。その他の値を指定した場合は例外が発生します。また Phar::mungServer() は大文字小文字を区別します。

返り値

値を返しません。

エラー / 例外

渡したデータに何らかの問題があった場合は UnexpectedValueException をスローします。

例

例1 Phar::mungServer() の例

<?php
// スタブのサンプル
Phar::mungServer(array('REQUEST_URI'));
Phar::webPhar();
__HALT_COMPILER();
?>

参考

  • Phar::webPhar() - ウェブベースの phar で使用するフロントコントローラ
  • Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

Phar::offsetExists

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::offsetExists — ファイルが phar 内に存在するかどうかを調べる

説明

bool Phar::offsetExists ( string $offset )

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。

offsetExists() は、isset() がコールされる際にはいつもコールされます。

パラメータ

offset

Phar 内で探すファイル名 (相対パス)。

返り値

ファイルが phar 内に存在する場合に TRUE、しない場合に FALSE を返します。

例

例1 Phar::offsetExists() の例

<?php
$p = new Phar(dirname(__FILE__) . '/my.phar', 0, 'my.phar');
$p['firstfile.txt'] = 'first file';
$p['secondfile.txt'] = 'second file';
// 以下の行では、offsetExists() が間接的にコールされます
var_dump(isset($p['firstfile.txt']));
var_dump(isset($p['nothere.txt']));
?>

上の例の出力は以下となります。

bool(true)
bool(false)

参考

Phar::offsetGet

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::offsetGet — 指定したファイルの PharFileInfo オブジェクトを取得する

説明

int Phar::offsetGet ( string $offset )

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 Phar::offsetGet() を使用して、Phar アーカイブからファイルを取得します。

パラメータ

offset

Phar 内で探すファイル名 (相対パス)。

返り値

PharFileInfo オブジェクトを返します。 これを使用して、ファイルの内容を順に処理したりファイルの情報を取得したりします。

エラー / 例外

そのファイルが Phar アーカイブ内に存在しない場合に、このメソッドは BadMethodCallException をスローします。

例

例1 Phar::offsetGet() の例

ArrayAccess インターフェイスを実装した他のクラスと同様、 Phar::offsetGet() は [] 演算子を使用した場合に自動的にコールされます。

<?php
$p = new Phar(dirname(__FILE__) . '/myphar.phar', 0, 'myphar.phar');
$p['exists.txt'] = "file exists\n";
try {
    // 自動的に offsetGet() をコールします
    echo $p['exists.txt'];
    echo $p['doesnotexist.txt'];
} catch (BadMethodCallException $e) {
    echo $e;
}
?>

上の例の出力は以下となります。

file exists
Entry doesnotexist.txt does not exist

参考

Phar::offsetSet

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::offsetSet — 内部ファイルに、外部ファイルの内容を設定する

説明

void Phar::offsetSet ( string $offset , string $value )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetSet を使用して、Phar アーカイブの既存ファイルの変更や 新しいファイルの追加を行います。

パラメータ

offset

Phar 内で変更するファイル名 (相対パス)。

value

ファイルの内容。

返り値

値を返しません。

エラー / 例外

phar.readonly に 1 の場合は BadMethodCallException がスローされます。 Phar の変更ができるのは phar.readonly が 0 のときだけだからです。Phar アーカイブへの変更をディスクに書き込む際に何らかのエラーが発生すると PharException がスローされます。

例

例1 Phar::offsetSet() の例

offsetSet は直接使用してはいけません。 配列に [] 演算子でアクセスする際に使用されます。

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
try {
    // offsetSet がコールされます
    $p['file.txt'] = 'Hi there';
} catch (Exception $e) {
    echo 'ファイルを変更できません: ', $e;
}
?>

参考

Phar::offsetUnset

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::offsetUnset — ファイルを phar から削除する

説明

bool Phar::offsetUnset ( string $offset )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

これは ArrayAccess インターフェイスを実装したものです。 これにより、Phar アーカイブの内容に対して配列形式の角括弧を使用したアクセスが可能となります。 offsetUnset を使用して、既存のファイルを削除します。また unset() が使用された場合にもコールされます。

パラメータ

offset

Phar 内で変更するファイル名 (相対パス)。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

phar.readonly に 1 の場合は BadMethodCallException がスローされます。 Phar の変更ができるのは phar.readonly が 0 のときだけだからです。Phar アーカイブへの変更をディスクに書き込む際に何らかのエラーが発生すると PharException をスローします。

例

例1 Phar::offsetUnset() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
try {
    // offsetUnset がコールされ、file.txt が my.phar から削除されます
    unset($p['file.txt']);
} catch (Exception $e) {
    echo 'file.txt を削除できません: ', $e;
}
?>

参考

Phar::running

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::running — 現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す

説明

string Phar::running ([ bool $retphar = true ] )

実行中の phar アーカイブのフルパスを返します。これはマジック定数 __FILE__ のような使い方を想定したもので、 実行中の phar アーカイブの内部でのみ有効です。

アーカイブ内のスタブでは、Phar::running() は "" を返します。現在実行中の phar にスタブ内からアクセスするには、 単純に __FILE__ を使用します。

パラメータ

retphar

FALSE の場合は phar アーカイブのディスク上でのフルパスを返します。 TRUE の場合は完全な phar URL を返します。

返り値

ファイル名が正しい形式の場合にファイル名、それ以外の場合に空文字列を返します。

例

例1 Phar::running() の例

次の例では、phar アーカイブが /path/to/phar/my.phar にあるものとします。

<?php
$a = Phar::running(); // $a は "phar:///path/to/my.phar"
$b = Phar::running(false); // $b は "/path/to/my.phar"
?>

Phar::setAlias

(PHP >= 5.3.0, PECL phar >= 1.2.1)

Phar::setAlias — Phar アーカイブのエイリアスを設定する

説明

bool Phar::setAlias ( string $alias )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

Phar アーカイブのエイリアスを設定し、そのアーカイブのエイリアスとして書き込みます。 エイリアスは phar アーカイブで内部的に使用するもので、 phar ストリームラッパーがアーカイブ内のファイルにアクセスする際に そのアーカイブのファイルシステム上での場所を気にせずにすむようになります。 それ以外の方法としては、Phar が内部的に include を横取りすることを利用したり Phar::interceptFileFuncs() を使って相対パスを利用したりといったものがあります。

パラメータ

alias

このアーカイブを指すときに使用する短い文字列。 phar ストリームラッパーがアクセスする際にこれを使用します。

返り値

エラー / 例外

書き込みアクセスが無効となっている場合に UnexpectedValueException をスローします。 また、そのエイリアスが既に使用済みである場合や 変更をディスクに書き込むときにエラーが発生した場合は PharException をスローします。

例

例1 Phar::setAlias() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->setAlias('myp.phar');
} catch (Exception $e) {
    // エラー処理
}
?>

参考

Phar::setDefaultStub

(Unknown)

Phar::setDefaultStub — Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

説明

bool Phar::setDefaultStub ([ string $index [, string $webindex ]] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドは、 Phar::createDefaultStub() と Phar::setStub() の両方の機能を組み合わせた便利なメソッドです。

パラメータ

index

コマンドラインからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

webindex

ウェブブラウザからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

phar.readonly が php.ini で有効になっている場合に UnexpectedValueException をスローします。 変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 Phar::setDefaultStub() の例

<?php
try {
    $phar = new Phar('myphar.phar');
    $phar->setDefaultStub('cli.php', 'web/index.php');
    // これは、以下と同じ意味です
    // $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
    // エラー処理
}
?>

参考

Phar::setMetadata

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::setMetadata — phar アーカイブのメタデータを設定する

説明

void Phar::setMetadata ( mixed $metadata )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

Phar::setMetadata() は、 phar アーカイブ全体に関する独自の情報を保存する場合に使用します。 ファイル固有のメタデータについては PharFileInfo::setMetadata() を使うようにしましょう。大きなメタデータを使用すると、 phar アーカイブの読み込み時のパフォーマンスが低下します。

メタデータの使用例として考えられるのは、 アーカイブの中で最初に実行するファイルはどれかを指定したり、 » PEAR の package.xml のようなマニフェストの場所を指定したりすることです。 しかし、phar アーカイブに関する有用なデータなら何を保存してもかまいません。

パラメータ

metadata

phar アーカイブについての情報を含む、PHP の変数。

返り値

値を返しません。

例

例1 Phar::setMetadata() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['file.php'] = '<?php echo "hello"';
    $p->setMetadata(array('bootstrap' => 'file.php'));
    var_dump($p->getMetadata());
} catch (Exception $e) {
    echo 'phar の作成/変更ができません:', $e;
}
?>

上の例の出力は以下となります。

array(1) {
  ["bootstrap"]=>
  string(8) "file.php"
}

参考

Phar::setSignatureAlgorithm

(PHP >= 5.3.0, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定して適用する

説明

void Phar::setSignatureAlgorithm ( int $sigtype [, string $privatekey ] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar のシグネチャのアルゴリズムを設定します。 シグネチャのアルゴリズムは Phar::MD5、 Phar::SHA1、Phar::SHA256、 Phar::SHA512 あるいは Phar::OPENSSL のいずれかでなければなりません。

実行可能な phar アーカイブについては、 SHA1 形式のシグネチャが デフォルトで自動的に作成されることに注意しましょう。 データ tar 形式あるいは zip 形式のアーカイブ (PharData クラスで作成したアーカイブ) の場合は、 Phar::setSignatureAlgorithm() で明示的にシグネチャを作成して設定する必要があります。

パラメータ

sigtype

Phar::MD5、 Phar::SHA1、Phar::SHA256、 Phar::SHA512 あるいは Phar::OPENSSL のいずれか。

privatekey

OpenSSL 秘密鍵の中身。証明書あるいは OpenSSL 鍵ファイルから取り出したもの。

<?php
$private = openssl_get_privatekey(file_get_contents('private.pem'));
$pkey = '';
openssl_pkey_export($private, $pkey);
$p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
?>
公開鍵ファイルの名前や置き場所については phar の導入 を参照ください。

返り値

値を返しません。

エラー / 例外

さまざまなエラーが発生した場合に UnexpectedValueException をスローします。 変更内容をディスクに書き込むときにエラーが発生した場合は PharException をスローします。

参考

Phar::setStub

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::setStub — Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

説明

bool Phar::setStub ( string $stub )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用して、新しい Phar アーカイブに PHP 起動ローダスタブを追加します。あるいは、既存の Phar アーカイブのローダスタブを置き換えます。

Phar アーカイブのローダスタブは、 このようにアーカイブを直接インクルードした際に使用されます。

<?php
include 'myphar.phar';
?>

phar ストリームラッパーを使用して次のようにファイルをインクルードした際には、 ローダにはアクセスしません。

<?php
include 'phar://myphar.phar/somefile.php';
?>

パラメータ

stub

文字列あるいはオープンしたストリームハンドル。 この phar アーカイブの実行スタブとして使用します。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

php.ini で phar.readonly が有効になっている場合に UnexpectedValueException がスローされます。 変更をディスクに書き込む際に何らかの問題が発生した場合は PharException がスローされます。

例

例1 Phar::setStub() の例

<?php
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['a.php'] = '<?php var_dump("Hello");';
    $p->setStub('<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
    include 'phar://brandnewphar.phar/a.php';
    var_dump($p->getStub());
    $p['b.php'] = '<?php var_dump("World");';
    $p->setStub('<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
    include 'phar://brandnewphar.phar/b.php';
    var_dump($p->getStub());
} catch (Exception $e) {
    echo 'brandnewphar.phar での書き込み操作に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

string(5) "Hello"
string(82) "<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
string(5) "World"
string(83) "<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"

参考

Phar::startBuffering

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::startBuffering — Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない

説明

void Phar::startBuffering ( void )

技術的には必須ではありませんが、Phar::startBuffering() メソッドを使用すると、大量のファイルを含む Phar アーカイブの作成や変更が非常に高速になります。 通常は、Phar アーカイブ内のファイルが作成あるいは変更されるたびに Phar アーカイブ全体を改めて作り直します。 これによって、アーカイブが常に最新の状態となります。

しかし、単に新しい Phar アーカイブを作りたいときや アーカイブ全体を一度に書き出したいときなどは、これは不要です。 同様に、いくつかの変更を行うときに、 すべての変更がうまくいったことを確認してから実際にディスクに書き込みたい ということもあるでしょう。 これは、ちょうどデータベースのトランザクションの概念と同じようなものです。 Phar::startBuffering()/Phar::stopBuffering() の両メソッドが、このような場合のために用意されています。

Phar の書き込みバッファリングはアーカイブ単位で処理されます。 Phar アーカイブ foo.phar でバッファリングが有効であったとしても、それは Phar アーカイブ bar.phar の変更には影響しません。

返り値

値を返しません。

例

例1 Phar::startBuffering() の例

<?php
// 確実に消しておきます
@unlink('brandnewphar.phar');
try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
} catch (Exception $e) {
    echo 'phar を作成できません:', $e;
}
echo '新しい phar のエントリ数は ' . $p->count() . " です\n";
$p->startBuffering();
$p['file.txt'] = 'hi';
$p['file2.txt'] = 'there';
$p['file2.txt']->setCompressedGZ();
$p['file3.txt'] = 'babyface';
$p['file3.txt']->setMetadata(42);
$p->setStub("<?php
function __autoload($class)
{
    include 'phar://myphar.phar/' . str_replace('_', '/', $class) . '.php';
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER();");
$p->stopBuffering();
?>

参考

  • Phar::stopBuffering() - Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む
  • Phar::isBuffering() - Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

Phar::stopBuffering

(PHP >= 5.3.0, PECL phar >= 1.0.0)

Phar::stopBuffering — Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

説明

void Phar::stopBuffering ( void )

Phar::stopBuffering() は、 Phar::startBuffering() メソッドと組み合わせて使用します。 Phar::startBuffering() メソッドを使用すると、 大量のファイルを含む Phar アーカイブの作成や変更が非常に高速になります。 通常は、Phar アーカイブ内のファイルが作成あるいは変更されるたびに Phar アーカイブ全体を改めて作り直します。 これによって、アーカイブが常に最新の状態となります。

しかし、単に新しい Phar アーカイブを作りたいときや アーカイブ全体を一度に書き出したいときなどは、これは不要です。 同様に、いくつかの変更を行うときに、 すべての変更がうまくいったことを確認してから実際にディスクに書き込みたい ということもあるでしょう。 これは、ちょうどデータベースのトランザクションの概念と同じようなものです。 Phar::startBuffering()/Phar::stopBuffering() の両メソッドが、このような場合のために用意されています。

Phar の書き込みバッファリングはアーカイブ単位で処理されます。 Phar アーカイブ foo.phar でバッファリングが有効であったとしても、それは Phar アーカイブ bar.phar の変更には影響しません。

返り値

値を返しません。

エラー / 例外

変更をディスクに書き出す際に何らかの問題が発生した場合は PharException がスローされます。

例

例1 Phar::stopBuffering() の例

<?php
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file1.txt'] = 'hi';
$p->startBuffering();
var_dump($p->getStub());
$p->setStub("<?php
function __autoload(\$class)
{
    include 'phar://brandnewphar.phar/' . str_replace('_', '/', \$class) . '.php';
}
Phar::mapPhar('brandnewphar.phar');
include 'phar://brandnewphar.phar/startup.php';
__HALT_COMPILER();");
$p->stopBuffering();
var_dump($p->getStub());
?>

上の例の出力は以下となります。

string(24) "<?php __HALT_COMPILER();"
string(195) "<?php
function __autoload($class)
{
    include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('brandnewphar.phar');
include 'phar://brandnewphar.phar/startup.php';
__HALT_COMPILER();"

参考

  • Phar::startBuffering() - Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない
  • Phar::isBuffering() - Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

Phar::uncompressAllFiles

(PECL phar < 2.0.0)

Phar::uncompressAllFiles — 現在の Phar アーカイブ内のすべてのファイルを展開する

説明

bool Phar::uncompressAllFiles ( void )

注意:

このメソッドは、phar 拡張モジュールバージョン 2.0.0 で削除されました。 今後は Phar::compress()、 Phar::decompress()、Phar::compressFiles() および Phar::decompressFiles() をご利用ください。

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドは、Phar アーカイブ内のすべてのファイルを展開します。 gzip で圧縮されているファイルが存在する場合は、それを展開するために zlib 拡張モジュールが有効でなければなりません。 また、bzip2 で圧縮されているファイルが存在する場合は、それを展開するために bzip2 拡張モジュールが有効でなければなりません。 この関数は phar の内容を変更するので、使用するには INI 設定 phar.readonly が off になっていなければなりません。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、bzip2 で圧縮されたファイルがあるのに bzip2 拡張モジュールが使用できない場合、 あるいは gzip で圧縮されたファイルがあるのに zlib 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 Phar::uncompressAllFiles() の例

<?php
try {
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    $p->compressAllFilesGZ();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressedBZIP2());
        var_dump($file->isCompressedGZ());
    }
    $p->uncompressAllFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressedBZIP2());
        var_dump($file->isCompressedGZ());
    }
} catch (Exception $e) {
    echo 'my.phar での書き込み操作に失敗しました: ', $e;
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
bool(true)
bool(false)
bool(true)
string(11) "myfile2.txt"
bool(true)
bool(false)
bool(true)
string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)

参考

Phar::unlinkArchive

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::unlinkArchive — phar アーカイブをディスクとメモリから完全に削除する

説明

bool Phar::unlinkArchive ( string $archive )

phar アーカイブをディスクとメモリから削除します。

パラメータ

archive

ディスク上の phar アーカイブへのパス。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

phar アーカイブがオープンされたままになっている場合や 既存の Phar、PharData PharFileInfo オブジェクトがその phar アーカイブを参照している場合に PharException をスローします。

例

例1 Phar::unlinkArchive() の例

<?php
// シンプルな使用法
Phar::unlinkArchive('/path/to/my.phar');

// より一般的な例
$p = new Phar('my.phar');
$fp = fopen('phar://my.phar/file.txt', 'r');
// これは 'my.phar.gz' を作成します
$gp = $p->compress(Phar::GZ);
// アーカイブへのすべての参照を削除します
unset($p);
fclose($fp);
// そしてアーカイブを完全に削除します
Phar::unlinkArchive('my.phar');
?>

参考

Phar::webPhar

(PHP >= 5.3.0, PECL phar >= 2.0.0)

Phar::webPhar — ウェブベースの phar で使用するフロントコントローラ

説明

void Phar::webPhar ([ string $alias [, string $index = "index.php" [, string $f404 [, array $mimetypes [, array $rewrites ]]]]] )

Phar::mapPhar() は、ウェブベースの phar で使用します。 このメソッドは、 $_SERVER['REQUEST_URI'] をパースして ウェブサーバーからのリクエストを phar アーカイブ内のファイルに転送します。 要は、このメソッド自体がウェブサーバーをシミュレートするということです。 正しいファイルにリクエストを転送し、正しいヘッダを出力し、 必要に応じて PHP ファイルをパースします。 この強力なメソッドがあることで、 既存の PHP アプリケーションを phar アーカイブ化するのが容易になります。 Phar::mungServer() や Phar::interceptFileFuncs() と組み合わせて使用すると、任意のウェブアプリケーションをそのまま phar アーカイブ化することができます。

Phar::webPhar() をコールするのは、 phar アーカイブのスタブ内からのみとしましょう (スタブって何? という方は ここ をごらんください)。

パラメータ

alias

phar:// URL でこのアーカイブを指す際に、 フルパスの代わりに使用するエイリアス。

index

phar の中でディレクトリインデックスとなるファイルの場所。

f404

ファイルが見つからないときに実行するスクリプトの場所。 このスクリプトは HTTP 404 ヘッダを返さなければなりません。

mimetypes

ファイルの拡張子と MIME タイプを関連付けた配列。 デフォルトのマッピングで十分な場合は、空の配列を渡します。 デフォルトで、これらの関連が定義されています。

<?php
$mimes = array(
    'phps' => Phar::PHPS, // highlight_file() に渡します
    'c' => 'text/plain',
    'cc' => 'text/plain',
    'cpp' => 'text/plain',
    'c++' => 'text/plain',
    'dtd' => 'text/plain',
    'h' => 'text/plain',
    'log' => 'text/plain',
    'rng' => 'text/plain',
    'txt' => 'text/plain',
    'xsd' => 'text/plain',
    'php' => Phar::PHP, // PHP としてパースします
    'inc' => Phar::PHP, // PHP としてパースします
    'avi' => 'video/avi',
    'bmp' => 'image/bmp',
    'css' => 'text/css',
    'gif' => 'image/gif',
    'htm' => 'text/html',
    'html' => 'text/html',
    'htmls' => 'text/html',
    'ico' => 'image/x-ico',
    'jpe' => 'image/jpeg',
    'jpg' => 'image/jpeg',
    'jpeg' => 'image/jpeg',
    'js' => 'application/x-javascript',
    'midi' => 'audio/midi',
    'mid' => 'audio/midi',
    'mod' => 'audio/mod',
    'mov' => 'movie/quicktime',
    'mp3' => 'audio/mp3',
    'mpg' => 'video/mpeg',
    'mpeg' => 'video/mpeg',
    'pdf' => 'application/pdf',
    'png' => 'image/png',
    'swf' => 'application/shockwave-flash',
    'tif' => 'image/tiff',
    'tiff' => 'image/tiff',
    'wav' => 'audio/wav',
    'xbm' => 'image/xbm',
    'xml' => 'text/xml',
);
?>

rewrites

URI と内部のファイルを関連付けた配列。apache の mod_rewrite をシミュレートしたものです。 たとえば、次のような配列を定義すると、

<?php
array(
    'myinfo' => 'myinfo.php'
);
?>
http://<host>/myphar.phar/myinfo がコールされた際に phar:///path/to/myphar.phar/myinfo.php に転送します。その際に GET/POST の内容はそのまま維持します。 これは mod_rewrite とまったく同じ挙動になるわけではありません。たとえば http://<host>/myphar.phar/myinfo/another にはマッチしません。

返り値

値を返しません。

エラー / 例外

出力したい内部ファイルのオープンに失敗した場合、 あるいはスタブ以外からコールした場合には PharException をスローします。 無効な配列が mimetypes あるいは rewrites に渡された場合は UnexpectedValueException をスローします。

例

例1 Phar::webPhar() の例

この例で作成した phar は、/myphar.phar/index.php や /myphar.phar をブラウズしたときには Hello World を表示し、 /myphar.phar/index.phps をブラウズしたときには index.phps のソースを表示します。

<?php
// phar アーカイブを作成します
try {
    $phar = new Phar('myphar.phar');
    $phar['index.php'] = '<?php echo "Hello World"; ?>';
    $phar['index.phps'] = '<?php echo "Hello World"; ?>';
    $phar->setStub('<?php
Phar::webPhar();
__HALT_COMPILER(); ?>');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • Phar::mungServer() - 最大 4 つまでの $_SERVER 変数を実行時に変更させる
  • Phar::interceptFileFuncs() - fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる

目次

  • Phar::addEmptyDir — 空のディレクトリを phar アーカイブに追加する
  • Phar::addFile — ファイルシステム上のファイルを phar アーカイブに追加する
  • Phar::addFromString — ファイルシステム上のファイルを phar アーカイブに追加する
  • Phar::apiVersion — API のバージョンを返す
  • Phar::buildFromDirectory — ディレクトリ内のファイルから phar を作成する
  • Phar::buildFromIterator — イテレータから phar アーカイブを作成する
  • Phar::canCompress — phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す
  • Phar::canWrite — phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
  • Phar::compress — Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する
  • Phar::compressAllFilesBZIP2 — 現在の Phar アーカイブ内のすべてのファイルを Bzip2 で圧縮する
  • Phar::compressAllFilesGZ — 現在の Phar アーカイブ内のすべてのファイルを Gzip で圧縮する
  • Phar::compressFiles — 現在の Phar アーカイブ内のすべてのファイルを圧縮する
  • Phar::__construct — Phar アーカイブオブジェクトを作成する
  • Phar::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する
  • Phar::convertToExecutable — phar アーカイブを実行可能な別の phar アーカイブ形式に変換する
  • Phar::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする
  • Phar::count — Phar アーカイブ内のエントリ (ファイル) の数を返す
  • Phar::createDefaultStub — phar ファイルフォーマット用のスタブを作成する
  • Phar::decompress — Phar アーカイブ全体の圧縮を解除する
  • Phar::decompressFiles — 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する
  • Phar::delMetadata — phar のグローバルメタデータを削除する
  • Phar::delete — phar アーカイブ内のファイルを削除する
  • Phar::extractTo — phar アーカイブの内容をディレクトリに展開する
  • Phar::getMetadata — phar アーカイブのメタデータを返す
  • Phar::getModified — phar が変更されているかどうかを返す
  • Phar::getSignature — Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す
  • Phar::getStub — Phar アーカイブの PHP ローダーあるいは起動スタブを返す
  • Phar::getSupportedCompression — サポートする圧縮アルゴリズムの配列を返す
  • Phar::getSupportedSignatures — サポートするシグネチャ型の配列を返す
  • Phar::getVersion — Phar アーカイブのバージョン情報を返す
  • Phar::hasMetadata — ファイルがグローバルなメタデータを持つかどうかを返す
  • Phar::interceptFileFuncs — fopen、file_get_contents、opendir などの stat 関連の関数をすべて phar に横取りさせる
  • Phar::isBuffering — Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる
  • Phar::isCompressed — phar アーカイブ全体が (.tar.gz/tar.bz などで) 圧縮されている場合に Phar::GZ あるいは PHAR::BZ2 を返す
  • Phar::isFileFormat — phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す
  • Phar::isValidPharFilename — 指定したファイル名が正しい形式の phar ファイルかどうかを返す
  • Phar::isWritable — phar アーカイブが変更可能な場合に true を返す
  • Phar::loadPhar — 任意の phar アーカイブを、エイリアスを指定して読み込む
  • Phar::mapPhar — 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する
  • Phar::mount — 外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする
  • Phar::mungServer — 最大 4 つまでの $_SERVER 変数を実行時に変更させる
  • Phar::offsetExists — ファイルが phar 内に存在するかどうかを調べる
  • Phar::offsetGet — 指定したファイルの PharFileInfo オブジェクトを取得する
  • Phar::offsetSet — 内部ファイルに、外部ファイルの内容を設定する
  • Phar::offsetUnset — ファイルを phar から削除する
  • Phar::running — 現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す
  • Phar::setAlias — Phar アーカイブのエイリアスを設定する
  • Phar::setDefaultStub — Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する
  • Phar::setMetadata — phar アーカイブのメタデータを設定する
  • Phar::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定して適用する
  • Phar::setStub — Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する
  • Phar::startBuffering — Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない
  • Phar::stopBuffering — Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む
  • Phar::uncompressAllFiles — 現在の Phar アーカイブ内のすべてのファイルを展開する
  • Phar::unlinkArchive — phar アーカイブをディスクとメモリから完全に削除する
  • Phar::webPhar — ウェブベースの phar で使用するフロントコントローラ

PharData クラス

(バージョン情報なし。おそらく SVN 版にしか存在しないでしょう)

導入

PharData クラスは、実行可能形式でない tar アーカイブや zip アーカイブへのアクセスや作成のための高レベルインターフェイスを提供します。 これらのアーカイブにはスタブが含まれておらず、 phar 拡張モジュールから実行することはできません。 そのため、PharData クラスによる通常の zip および tar ファイルの作成や 操作は php.ini の phar.readonly が 1 であっても可能です。

クラス概要

PharData extends Phar {
/* プロパティ */
/* メソッド */
bool addEmptyDir ( string $dirname )
void Phar::addFile ( string $file [, string $localname ] )
bool addFromString ( string $localname , string $contents )
array Phar::buildFromDirectory ( string $base_dir [, string $regex ] )
array buildFromIterator ( Iterator $iter [, string $base_directory ] )
object compress ( int $compression [, string $extension ] )
bool compressFiles ( int $compression )
__construct ( string $fname [, int $flags [, string $alias [, int $format = Phar::TAR ]]] )
PharData convertToData ([ int $format [, int $compression [, string $extension ]]] )
Phar convertToExecutable ([ int $format [, int $compression [, string $extension ]]] )
bool copy ( string $oldfile , string $newfile )
object decompress ([ string $extension ] )
bool decompressFiles ( void )
bool delMetadata ( void )
bool delete ( string $entry )
bool extractTo ( string $pathto [, string|array $files [, bool $overwrite = false ]] )
bool isWritable ( void )
void offsetSet ( string $offset , string $value )
bool offsetUnset ( string $offset )
bool setAlias ( string $alias )
bool setDefaultStub ([ string $index [, string $webindex ]] )
void Phar::setMetadata ( mixed $metadata )
void Phar::setSignatureAlgorithm ( int $sigtype )
bool setStub ( string $stub )
/* 継承したメソッド */
void Phar::addEmptyDir ( string $dirname )
void Phar::addFile ( string $file [, string $localname ] )
void Phar::addFromString ( string $localname , string $contents )
string Phar::apiVersion ( void )
array Phar::buildFromDirectory ( string $base_dir [, string $regex ] )
array Phar::buildFromIterator ( Iterator $iter [, string $base_directory ] )
bool Phar::canCompress ([ int $type = 0 ] )
bool Phar::canWrite ( void )
object Phar::compress ( int $compression [, string $extension ] )
bool Phar::compressAllFilesBZIP2 ( void )
bool Phar::compressAllFilesGZ ( void )
void Phar::compressFiles ( int $compression )
Phar::__construct ( string $fname [, int $flags [, string $alias ]] )
PharData Phar::convertToData ([ int $format = 9021976 [, int $compression = 9021976 [, string $extension ]]] )
Phar Phar::convertToExecutable ([ int $format = 9021976 [, int $compression = 9021976 [, string $extension ]]] )
bool Phar::copy ( string $oldfile , string $newfile )
int Phar::count ( void )
string Phar::createDefaultStub ([ string $indexfile [, string $webindexfile ]] )
object Phar::decompress ([ string $extension ] )
bool Phar::decompressFiles ( void )
bool Phar::delMetadata ( void )
bool Phar::delete ( string $entry )
bool Phar::extractTo ( string $pathto [, string|array $files [, bool $overwrite = false ]] )
mixed Phar::getMetadata ( void )
bool Phar::getModified ( void )
array Phar::getSignature ( void )
string Phar::getStub ( void )
array Phar::getSupportedCompression ( void )
array Phar::getSupportedSignatures ( void )
string Phar::getVersion ( void )
bool Phar::hasMetadata ( void )
void Phar::interceptFileFuncs ( void )
bool Phar::isBuffering ( void )
mixed Phar::isCompressed ( void )
bool Phar::isFileFormat ( int $format )
bool Phar::isValidPharFilename ( string $filename [, bool $executable = true ] )
bool Phar::isWritable ( void )
bool Phar::loadPhar ( string $filename [, string $alias ] )
bool Phar::mapPhar ([ string $alias [, int $dataoffset = 0 ]] )
void Phar::mount ( string $pharpath , string $externalpath )
void Phar::mungServer ( array $munglist )
bool Phar::offsetExists ( string $offset )
int Phar::offsetGet ( string $offset )
void Phar::offsetSet ( string $offset , string $value )
bool Phar::offsetUnset ( string $offset )
string Phar::running ([ bool $retphar = true ] )
bool Phar::setAlias ( string $alias )
bool Phar::setDefaultStub ([ string $index [, string $webindex ]] )
void Phar::setMetadata ( mixed $metadata )
void Phar::setSignatureAlgorithm ( int $sigtype [, string $privatekey ] )
bool Phar::setStub ( string $stub )
void Phar::startBuffering ( void )
void Phar::stopBuffering ( void )
bool Phar::uncompressAllFiles ( void )
bool Phar::unlinkArchive ( string $archive )
void Phar::webPhar ([ string $alias [, string $index = "index.php" [, string $f404 [, array $mimetypes [, array $rewrites ]]]]] )
}

PharData::addEmptyDir

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::addEmptyDir — 空のディレクトリを tar/zip アーカイブに追加する

説明

bool PharData::addEmptyDir ( string $dirname )

このメソッドを使用すると、空のディレクトリが dirname に作成されます。このメソッドは ZipArchive::addEmptyDir() と同じようなものです。

パラメータ

dirname

phar アーカイブ内に作成する空のディレクトリの名前。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 PharData::addEmptyDir() の例

<?php
try {
    $a = new PharData('/path/to/my.tar');

    $a->addEmptyDir('/full/path/to/file');
    // できあがったファイルを確認します
    $b = $a['full/path/to/file']->isDir();
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

PharData::addFile

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::addFile — ファイルシステム上のファイルを tar/zip アーカイブに追加する

説明

void Phar::addFile ( string $file [, string $localname ] )

このメソッドを使用すると、任意のファイルあるいは URL を tar/zip アーカイブに追加することができます。 オプションの 2 番目のパラメータ localname を指定すると、 ファイルはその名前でアーカイブ内に格納されます。指定しなかった場合は、 file パラメータをアーカイブ内のパスとして使用します。 URL を使用する場合は、localname を指定しないと例外がスローされます。 このメソッドは ZipArchive::addFile() と同じようなものです。

パラメータ

file

phar アーカイブに追加したいディスク上のファイルへのフルパスあるいは相対パス。

localname

ファイルをアーカイブ内に格納するときのパス。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 PharData::addFile() の例

<?php
try {
    $a = new PharData('/path/to/my.tar');

    $a->addFile('/full/path/to/file');
    // 格納したファイルを確認します
    $b = $a['full/path/to/file']->getContent();

    $a->addFile('/full/path/to/file', 'my/file.txt');
    $c = $a['my/file.txt']->getContent();

    // URL の使用例
    $a->addFile('http://www.example.com', 'example.html');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • PharData::offsetSet() - tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する
  • Phar::addFile() - ファイルシステム上のファイルを phar アーカイブに追加する
  • PharData::addFromString() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::addEmptyDir() - 空のディレクトリを tar/zip アーカイブに追加する

PharData::addFromString

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::addFromString — ファイルシステム上のファイルを tar/zip アーカイブに追加する

説明

bool PharData::addFromString ( string $localname , string $contents )

このメソッドを使用すると、任意の文字列を tar/zip アーカイブに追加することができます。 アーカイブ内のファイル名は localname で指定したものとなります。 このメソッドは ZipArchive::addFromString() と同じようなものです。

パラメータ

localname

ファイルをアーカイブ内に格納するときのパス。

contents

ファイルに保存する内容。

返り値

返り値はありません。失敗時には例外をスローします。

例

例1 PharData::addFromString() の例

<?php
try {
    $a = new PharData('/path/to/my.tar');

    $a->addFromString('path/to/file.txt', 'my simple file');
    $b = $a['path/to/file.txt']->getContent();

    // 大きなファイル用にストリームハンドルから追加するには offsetSet() を使用します
    $c = fopen('/path/to/hugefile.bin');
    $a['largefile.bin'] = $c;
    fclose($c);
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

  • PharData::offsetSet() - tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する
  • Phar::addFromString() - ファイルシステム上のファイルを phar アーカイブに追加する
  • PharData::addFile() - ファイルシステム上のファイルを tar/zip アーカイブに追加する
  • PharData::addEmptyDir() - 空のディレクトリを tar/zip アーカイブに追加する

PharData::buildFromDirectory

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::buildFromDirectory — ディレクトリ内のファイルから tar/zip アーカイブを作成する

説明

array Phar::buildFromDirectory ( string $base_dir [, string $regex ] )

ディレクトリの中身をもとに tar/zip アーカイブを作成します。 オプションの 2 番目のパラメータで正規表現 (pcre) を指定すると、特定のファイルを除外することができます。 正規表現にマッチするすべてのファイルがアーカイブに含められ、 それ以外のファイルは除外されます。より詳細に制御するには PharData::buildFromIterator() を使用します。

パラメータ

base_dir

アーカイブに追加するすべてのファイルを含むディレクトリへの フルパスあるいは相対パス。

regex

オプションで指定する pcre 正規表現。 これを使用してファイル一覧をフィルタリングします。 正規表現にマッチするファイルパスのみがアーカイブに追加されます。

返り値

Phar::buildFromDirectory() は、連想配列を返します。これは、 ファイルの内部パスをファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、内部ディレクトリイテレータのインスタンスの作成に失敗したときに BadMethodCallException をスローします。 また、phar アーカイブの保存時にエラーが発生した場合は PharException をスローします。

例

例1 PharData::buildFromDirectory() の例

<?php
$phar = new PharData('project.tar');
// project 内のすべてのファイルを追加します
$phar->buildFromDirectory(dirname(__FILE__) . '/project');

$phar2 = new PharData('project2.zip');
// project 内のファイルのうち、php ファイルだけを追加します
$phar->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
?>

参考

PharData::buildFromIterator

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::buildFromIterator — イテレータから tar あるいは zip アーカイブを作成する

説明

array PharData::buildFromIterator ( Iterator $iter [, string $base_directory ] )

tar あるいは zip アーカイブをイテレータから作成します。 サポートするイテレータは二種類で、 tar/zip 内のファイル名とディスク上の実際のファイル名を対応させたものか、あるいは DirectoryIterator のように SplFileInfo オブジェクトを返すものです。 SplFileInfo オブジェクトを返すイテレータの場合は、2 番目のパラメータが必要となります。

例

例1 SplFileInfo を使用した PharData::buildFromIterator() の例

ほとんどの tar/zip アーカイブは、実際のディレクトリ構造を反映した形式になっています。 このような場合は 2 番目の方式が最適です。 たとえば、次のようなディレクトリ構成のファイルを含む tar/zip アーカイブを作成してみることにしましょう。 

/path/to/project/
                 config/
                        dist.xml
                        debug.xml
                 lib/
                     file1.php
                     file2.php
                 src/
                     processthing.php
                 www/
                     index.php
                 cli/
                     index.php

次のコードを使用すると、これらのファイルを tar アーカイブ "project.tar" に追加します。

<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new RecursiveDirectoryIterator('/path/to/project')),
    '/path/to/project');
?>

これで、ファイル project.tar はすぐに使えるようになります。 PharData::buildFromIterator() は圧縮やメタデータの設定を行いません。 これらは tar/zip アーカイブを作成した後で行うことができます。

興味深いことに、PharData::buildFromIterator() を使用して既存の phar や tar、あるいは zip アーカイブの中身をコピーすることもできます。 というのも PharData オブジェクトは DirectoryIterator を継承しているからです。

<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
    new RecursiveIteratorIterator(
     new Phar('/path/to/anotherphar.phar')),
    'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>

例2 その他のイテレータを使用した PharData::buildFromIterator() の例

それ以外の形式のイテレータでは、 key => value の対応を返すものを使用できます。たとえば ArrayIterator などです。

<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
    new ArrayIterator(
     array(
        'internal/file.php' => dirname(__FILE__) . '/somefile.php',
        'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
     )));
?>

パラメータ

iter

phar ファイルと実際の場所の関連を返すイテレータ、 あるいは SplFileInfo オブジェクトを返すイテレータ。

base_directory

SplFileInfo オブジェクトを返すイテレータを指定した際、 tar/zip アーカイブへの追加時にフルパスから取り除く部分。

返り値

PharData::buildFromIterator() は連想配列を返します。 これは、ファイルの内部パスとファイルシステム上のフルパスを対応させたものです。

エラー / 例外

このメソッドは、イテレータが間違った値 (たとえば文字列キーではなく整数キーなど) を返した場合に UnexpectedValueException を返します。また、SplFileInfo 型のイテレータを渡したときに base_directory を指定しなかった場合は BadMethodCallException を、 phar アーカイブの保存時にエラーが発生した場合は PharException を返します。

参考

PharData::compress

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::compress — tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

説明

object PharData::compress ( int $compression [, string $extension ] )

tar 形式のアーカイブの場合は、 このメソッドはアーカイブ全体を gzip あるいは bzip2 で圧縮します。 できあがったファイルは gunzip/bunzip コマンドで処理することもできますし、 Phar 拡張モジュールで直接透過的に使用することもできます。

zip 形式のアーカイブの場合は、このメソッドは失敗して例外が発生します。 gzip で圧縮するためには zlib 拡張モジュールが、そして bzip2 で圧縮するためには bzip2 拡張モジュールが有効になっていなければなりません。

さらに、このメソッドは自動的にアーカイブの名前を変更し、 .gz あるいは .bz2 を追加します。Phar::NONE を渡して圧縮を解除した場合は拡張子も削除します。 もうひとつの方法として、ファイルの拡張子を 2 番目のパラメータで指定することもできます。

パラメータ

compression

圧縮を行う場合には Phar::GZ あるいは Phar::BZ2、圧縮を解除する場合には Phar::NONE を指定します。

extension

デフォルトでは、tar を圧縮する際の拡張子は .tar.gz あるいは .tar.bz2、伸長する際の拡張子は .tar となります。

返り値

PharData オブジェクトを返します。

エラー / 例外

zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 PharData::compress() の例

<?php
$p = new PharData('/path/to/my.tar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // /path/to/my.phar.gz にコピーします
$p2 = $p->compress(Phar::BZ2); // /path/to/my.phar.bz2 にコピーします
$p3 = $p2->compress(Phar::NONE); // 例外: /path/to/my.phar already exists
?>

参考

  • Phar::compress() - Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

PharData::compressFiles

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::compressFiles — 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する

説明

bool PharData::compressFiles ( int $compression )

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 PharData::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式のアーカイブでは、 このメソッドは Phar アーカイブ内のすべてのファイルを指定した方式で圧縮します。 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。さらに、 もし既に bzip2/zlib で圧縮されているファイルがある場合は、 いったんその圧縮を解除するために対応する拡張モジュールが必要となります。

パラメータ

compression

圧縮を行う場合は Phar::GZ あるいは Phar::BZ2、圧縮を解除するためには Phar::NONE のいずれかを指定しなければなりません。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

INI 設定 phar.readonly が on の場合、zlib 拡張モジュールが有効でない場合、 あるいは既に bzip2 圧縮されているファイルがあるのに bzip2 拡張モジュールが有効でない場合に BadMethodCallException をスローします。

例

例1 PharData::compressFiles() の例

<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)
string(10) "myfile.txt"
int(4096)
bool(false)
bool(true)
string(11) "myfile2.txt"
int(4096)
bool(false)
bool(true)

参考

PharData::__construct

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::__construct — 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する

説明

PharData::__construct ( string $fname [, int $flags [, string $alias [, int $format = Phar::TAR ]]] )

パラメータ

fname

既存の tar/zip アーカイブあるいは作成したいアーカイブへのパス。

flags

親クラス Phar の RecursiveDirectoryIterator に渡すフラグ。

alias

この Phar アーカイブをストリーム機能からコールするときに使うエイリアス。

format

Phar クラスの ファイルフォーマット定数 のいずれか。

エラー / 例外

2 度コールされた場合に BadMethodCallException、 phar アーカイブのオープンに失敗した場合に UnexpectedValueException をスローします。

例

例1 PharData::__construct() の例

<?php
try {
    $p = new PharData('/path/to/my.tar', CURRENT_AS_FILEINFO | KEY_AS_FILENAME);
} catch (UnexpectedValueException $e) {
    die('Could not open my.tar');
} catch (BadMethodCallException $e) {
    echo 'technically, this cannot happen';
}
echo file_get_contents('phar:///path/to/my.tar/example.txt');
?>

PharData::convertToData

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

説明

PharData PharData::convertToData ([ int $format [, int $compression [, string $extension ]]] )

このメソッドは、実行可能でない tar あるいは zip アーカイブを別の実行可能でない形式に変換します。

何も変更しなかった場合、このメソッドは BadMethodCallException をスローします。 このメソッドは、tar アーカイブを zip 形式に変換するか あるいはその逆の変換をする場合に使用するものです。 このメソッドで単に tar アーカイブの圧縮方法だけを変更することもできますが、 その場合は PharData::compress() を使うことをおすすめします。

成功した場合は、このメソッドはディスク上に新しいアーカイブを作成して PharData オブジェクトを返します。 古いアーカイブは削除されずディスク上に残るので、 処理を終えたら手動で削除する必要があります。

パラメータ

format

これは Phar::TAR あるいは Phar::ZIP のいずれかとなります。 NULL を指定すると、現在のファイル形式をそのまま保持します。

compression

アーカイブ全体の圧縮を行わない場合は Phar::NONE、 zlib による圧縮の場合は Phar::GZ、そして bzip による圧縮の場合は Phar::BZ2 のいずれかを指定します。

extension

このパラメータは、変換後のアーカイブのデフォルトのファイル拡張子を変更します。 実行可能でない tar や zip アーカイブのファイル名としては .phar は使用できないことに注意しましょう。

tar 形式の phar アーカイブの場合、デフォルトの拡張子は圧縮形式によって .tar、.tar.gz、 .tar.bz2 のいずれかとなります。 zip 形式のアーカイブの場合、デフォルトの拡張子は .zip となります。

返り値

このメソッドは、成功した場合に PharData オブジェクトを返します。失敗した場合は例外をスローします。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、phar 作成中に何らかの問題が発生した場合に PharException をスローします。

例

例1 PharData::convertToData() の例

PharData::convertToData() の使用法です。

<?php
try {
    $tarphar = new PharData('myphar.tar');
    // myphar.tar は削除 *されない* ことに注意しましょう
    // 実行可能ではない tar 形式に変換し
    // myphar.zip を作成します
    $zip = $tarphar->convertToData(Phar::ZIP);
    // myphar.tbz を作成します
    $tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
    // myphar.phar.tgz を作成します
    $phar = $tarphar->convertToData(Phar::PHAR); // throws exception
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

PharData::convertToExecutable

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::convertToExecutable — 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

説明

Phar PharData::convertToExecutable ([ int $format [, int $compression [, string $extension ]]] )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドは、実行可能でない tar あるいは zip アーカイブを実行可能な phar 形式に変換します。実行可能なファイル形式 3 種類 (phar, tar あるいは zip) のどれでも使用することができ、アーカイブ全体の圧縮も行うことができます。

何も変更しなかった場合、このメソッドは BadMethodCallException をスローします。

成功した場合は、このメソッドはディスク上に新しいアーカイブを作成して Phar オブジェクトを返します。 古いアーカイブは削除されずディスク上に残るので、 処理を終えたら手動で削除する必要があります。

パラメータ

format

これは Phar::PHAR、Phar::TAR あるいは Phar::ZIP のいずれかとなります。 NULL を指定すると、現在のファイル形式をそのまま保持します。

compression

アーカイブ全体の圧縮を行わない場合は Phar::NONE、 zlib による圧縮の場合は Phar::GZ、そして bzip による圧縮の場合は Phar::BZ2 のいずれかを指定します。

extension

このパラメータは、変換後のアーカイブのデフォルトのファイル拡張子を変更します。 実行可能でない tar や zip アーカイブのファイル名としては .phar は使用できないことに注意しましょう。

phar 形式のアーカイブに変換する場合、デフォルトの拡張子は圧縮形式によって .phar、.phar.gz あるいは .phar.bz2 のいずれかとなります。tar 形式のアーカイブの場合、デフォルトの拡張子は .phar.tar、.phar.tar.gz および .phar.tar.bz2 です。zip 形式のアーカイブの場合、 デフォルトの拡張子は .phar.zip となります。

返り値

このメソッドは、成功した場合に Phar オブジェクトを返します。失敗した場合は例外をスローします。

エラー / 例外

圧縮ができない場合や無効な圧縮方式が指定された場合、あるいは Phar::startBuffering() でバッファリングしたまま Phar::stopBuffering() を実行していないアーカイブを処理しようとした場合に BadMethodCallException をスローします。 また、書き込みサポートが無効な場合に UnexpectedValueException、 phar 作成中に何らかの問題が発生した場合に PharException をスローします。

例

例1 PharData::convertToExecutable() の例

PharData::convertToExecutable() の使用例です。

<?php
try {
    $tarphar = new PharData('myphar.tar');
    // phar ファイル形式に変換します
    // myphar.tar は削除 *されない* ことに注意しましょう
    $phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
    $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    // myphar.phar.tgz を作成します
    $compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
} catch (Exception $e) {
    // ここでエラー処理をします
}
?>

参考

PharData::copy

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

説明

bool PharData::copy ( string $oldfile , string $newfile )

phar アーカイブ内のファイルを、そのアーカイブ内で別の新しいファイルとしてコピーします。 これは、phar ストリームラッパーでの copy() と同等の操作をオブジェクト指向で行うものです。

パラメータ

oldfile

newfile

返り値

成功した場合に TRUE を返します。しかし、より安全を期すなら try/catch ブロック内で使用して例外がスローされないことを確認するといいでしょう。

エラー / 例外

コピー元のファイルが存在しない、コピー先のファイルが既に存在する、 書き込みアクセスが無効になっている、どちらかのファイルのオープンに失敗した、 あるいはコピー元のファイルの読み込みに失敗した場合に UnexpectedValueException をスローします。 変更内容の phar への書き込みに失敗した場合は PharException をスローします。

例

例1 PharData::copy() の例

この例は、PharData::copy() の使用法のほかに それと同等の操作をストリームラッパーで行う方法を示すものです。 これらの方式の最大の違いはエラー処理です。 PharData のすべてのメソッドは例外をスローしますが、ストリームラッパーの場合は trigger_error() を使用します。

<?php
try {
    $phar = new PharData('myphar.tar');
    $phar['a'] = 'hi';
    $phar->copy('a', 'b');
    echo $phar['b']; // 出力は "phar://myphar.tar/b"
} catch (Exception $e) {
    // エラー処理
}

// 上のコードと同等の処理をストリームラッパーで行う例。
// エラー時には例外ではなく E_WARNINGS が発生します
copy('phar://myphar.tar/a', 'phar//myphar.tar/c');
echo file_get_contents('phar://myphar.tar/c'); // 出力は "hi"
?>

PharData::decompress

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::decompress — Phar アーカイブ全体の圧縮を解除する

説明

object PharData::decompress ([ string $extension ] )

tar 形式のアーカイブの場合は、 このメソッドはアーカイブ全体の圧縮を解除します。

zip 形式のアーカイブの場合は、このメソッドは失敗して例外が発生します。 gzip で圧縮されたファイルの圧縮を解除するためには zlib 拡張モジュールが、そして bzip2 で圧縮されたファイルの圧縮を解除するためには bzip2 拡張モジュールが有効になっていなければなりません。

さらに、このメソッドは自動的にアーカイブの拡張子を変更し、 .tar をデフォルトで追加します。 もうひとつの方法として、ファイルの拡張子を 2 番目のパラメータで指定することもできます。

パラメータ

extension

圧縮を解除する場合、デフォルトのファイル拡張子は .phar.tar です。 このパラメータを使用すると、別の拡張子を指定することができます。 実行可能な phar アーカイブは、ファイル名に必ず .phar を含まなければならないことに注意しましょう。

返り値

PharData オブジェクトを返します。

エラー / 例外

zlib 拡張モジュールが使用できない場合、あるいは bzip2 拡張モジュールが使用できない場合に BadMethodCallException をスローします。

例

例1 PharData::decompress() の例

<?php
$p = new PharData('/path/to/my.tar', 0, 'my.tar.gz');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p3 = $p2->decompress(); // /path/to/my.tar を作成します
?>

参考

PharData::decompressFiles

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::decompressFiles — 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する

説明

bool PharData::decompressFiles ( void )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 PharData::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式のアーカイブでは、 このメソッドはアーカイブ内のすべてのファイルの圧縮を解除します。 もし bzip2/zlib で圧縮されているファイルがある場合は、 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。

返り値

成功した場合に TRUE を、失敗した場合に FALSE を返します。

エラー / 例外

zlib 拡張モジュールが有効でない場合、 あるいは既に bzip2 圧縮されているファイルがあるのに bzip2 拡張モジュールが有効でない場合に BadMethodCallException をスローします。

例

例1 PharData::decompressFiles() の例

<?php
$p = new PharData('/path/to/my.zip');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($p as $file) {
    var_dump($file->getFileName());
    var_dump($file->isCompressed());
    var_dump($file->isCompressed(Phar::BZ2));
    var_dump($file->isCompressed(Phar::GZ));
}
?>

上の例の出力は以下となります。

string(10) "myfile.txt"
int(4096)
bool(false)
bool(true)
string(11) "myfile2.txt"
int(4096)
bool(false)
bool(true)
string(10) "myfile.txt"
bool(false)
bool(false)
bool(false)
string(11) "myfile2.txt"
bool(false)
bool(false)
bool(false)

参考

PharData::delMetadata

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::delMetadata — zip アーカイブのグローバルメタデータを削除する

説明

bool PharData::delMetadata ( void )

注意:

このメソッドは、php.ini の phar.readonly が 0 でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

zip アーカイブのグローバルメタデータを削除します。

パラメータ

返り値

成功した場合に TRUE を返します。しかし、より安全を期すなら 例外がスローされないことを確認するといいでしょう。

エラー / 例外

変更をディスクに書き戻す際にエラーが発生した場合は PharException をスローします。

例

例1 PharData::delMetaData() の例

<?php
try {
    $phar = new PharData('myphar.zip');
    var_dump($phar->getMetadata());
    $phar->setMetadata("hi there");
    var_dump($phar->getMetadata());
    $phar->delMetadata();
    var_dump($phar->getMetadata());
} catch (Exception $e) {
    // エラー処理
}
?>

上の例の出力は以下となります。

NULL
string(8) "hi there"
NULL

参考

PharData::delete

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::delete — tar/zip アーカイブ内のファイルを削除する

説明

bool PharData::delete ( string $entry )

アーカイブ内のファイルを削除します。 これは、ストリームラッパー上で unlink() をコールするのと同じ意味です。以下に例を示します。

パラメータ

entry

削除したいファイルの、アーカイブ内でのパス。

返り値

成功した場合に TRUE を返します。 しかし、例外がスローされているかどうかを確認したうえで 例外がなければ成功とみなすほうがいいでしょう。

エラー / 例外

変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 PharData::delete() の例

<?php
try {
    $phar = new PharData('myphar.zip');
    $phar->delete('unlink/me.php');
    // これは以下と同じ意味です
    unlink('phar://myphar.phar/unlink/me.php');
} catch (Exception $e) {
    // エラー処理
}
?>

参考

  • Phar::delete() - phar アーカイブ内のファイルを削除する

PharData::extractTo

(PHP >= 5.3.0, PECL phar >= 2.0.0)

PharData::extractTo — tar/zip アーカイブの内容をディレクトリに展開する

説明

bool PharData::extractTo ( string $pathto [, string|array $files [, bool $overwrite = false ]] )

tar/zip アーカイブ内のすべてのファイルをディスクに展開します。 展開されたファイルやディレクトリは、アーカイブに保存されたときのパーミッションを維持しています。 オプションのパラメータを使用すると、どのファイルを展開するかを制御したり 既存のファイルを上書きするかどうかを指定したりすることができます。 2 番目のパラメータ files には、 展開したいファイルやディレクトリの名前、あるいはその配列を指定します。 デフォルトでは、このメソッドは既存のファイルを上書きしません。 3 番目のパラメータを true にすると既存のファイルを上書きさせることができます。 このメソッドは ZipArchive::extractTo() と同じようなものです。

パラメータ

pathto

アーカイブ内のファイルへのパス。

files

展開したいファイル名/ディレクトリ名、あるいはその配列。

overwrite

TRUE にすると既存のファイルを上書きします。

返り値

成功した場合に TRUE を返します。 しかし、例外がスローされているかどうかを確認したうえで 例外がなければ成功とみなすほうがいいでしょう。

エラー / 例外

変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

例

例1 PharData::extractTo() の例

<?php
try {
    $phar = new PharData('myphar.tar');
    $phar->extractTo('/full/path'); // すべてのファイルを展開します
    $phar->extractTo